From 18b6157f5ecdeac94c68c9eada08a69dae460211 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 23 Apr 2026 09:47:13 +0200 Subject: [PATCH 1/4] docs: add data flags comparison to attestations getting started page Adds an "Attaching data to attestations" section explaining the difference between --user-data, --attachments, and --attestation-data with a comparison table and usage examples. Closes #171 --- getting_started/attestations.md | 50 +++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index 7a337f1..bcd4edf 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -155,6 +155,56 @@ Along with attestations data, you can attach additional supporting evidence file For `JUnit` attestations (see below), Kosli automatically stores the JUnit XML results files in the Evidence Vault. You can disable this by setting `--upload-results=false` +## Attaching data to attestations + +All `kosli attest` commands support flags for attaching additional data. These flags accept file paths but serve different purposes: + +| Flag | Available on | Purpose | +|------|-------------|---------| +| `--user-data` | All attest commands | Attach structured JSON metadata that is stored and visible alongside the attestation in the Kosli UI | +| `--attachments` | All attest commands | Upload files or directories to the Evidence Vault as compressed archives for later download | +| `--attestation-data` | `attest custom` only | Provide the JSON payload that the custom type's jq rules evaluate to determine compliance | + +### When to use which + +Use **`--user-data`** when you want to store additional context — such as build metadata, environment +variables, or tool versions — that should be visible and queryable in the attestation record. + +```shell +kosli attest generic \ + --name security-scan \ + --user-data scan-metadata.json \ + ... +``` + +Use **`--attachments`** when you want to archive files for audit purposes — such as test reports, +scan output, or policy files — in the Evidence Vault for later retrieval. + +```shell +kosli attest generic \ + --name security-scan \ + --attachments scan-report.html,scan-config.yml \ + ... +``` + +Use **`--attestation-data`** on `kosli attest custom` to provide the JSON data that the custom +attestation type's jq expression evaluates. This is what determines the compliance status of the +attestation. + +```shell +kosli attest custom \ + --type coverage-metrics \ + --name unit-tests \ + --attestation-data coverage-results.json \ + ... +``` + + +These flags can be combined. For example, you can use `--attestation-data` for compliance evaluation, +`--user-data` to store extra metadata, and `--attachments` to archive the full report — all on the +same attestation. + + ## Attestation types Currently, we support the following types of evidence: From 3bd3debc141bfcb80812d8765415308e4fd14075 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 23 Apr 2026 09:49:06 +0200 Subject: [PATCH 2/4] docs: address review feedback on data flags section - Change "All attest commands" to "All evidence attest commands" - Remove "queryable" claim for --user-data - Add --flow and --trail to code examples for consistency - Note comma-separated syntax for --attachments - Add cross-link to Custom attestation type section --- getting_started/attestations.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index bcd4edf..96e075f 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -161,42 +161,46 @@ All `kosli attest` commands support flags for attaching additional data. These f | Flag | Available on | Purpose | |------|-------------|---------| -| `--user-data` | All attest commands | Attach structured JSON metadata that is stored and visible alongside the attestation in the Kosli UI | -| `--attachments` | All attest commands | Upload files or directories to the Evidence Vault as compressed archives for later download | +| `--user-data` | All evidence attest commands | Attach structured JSON metadata that is stored and visible alongside the attestation in the Kosli UI | +| `--attachments` | All evidence attest commands | Upload files or directories to the Evidence Vault as compressed archives for later download | | `--attestation-data` | `attest custom` only | Provide the JSON payload that the custom type's jq rules evaluate to determine compliance | ### When to use which Use **`--user-data`** when you want to store additional context — such as build metadata, environment -variables, or tool versions — that should be visible and queryable in the attestation record. +variables, or tool versions — that is visible alongside the attestation in the Kosli UI. ```shell kosli attest generic \ --name security-scan \ - --user-data scan-metadata.json \ - ... + --flow backend-ci \ + --trail $(git rev-parse HEAD) \ + --user-data scan-metadata.json ``` Use **`--attachments`** when you want to archive files for audit purposes — such as test reports, -scan output, or policy files — in the Evidence Vault for later retrieval. +scan output, or policy files — in the Evidence Vault for later retrieval. Provide multiple paths +as a comma-separated list. ```shell kosli attest generic \ --name security-scan \ - --attachments scan-report.html,scan-config.yml \ - ... + --flow backend-ci \ + --trail $(git rev-parse HEAD) \ + --attachments scan-report.html,scan-config.yml ``` Use **`--attestation-data`** on `kosli attest custom` to provide the JSON data that the custom attestation type's jq expression evaluates. This is what determines the compliance status of the -attestation. +attestation. See the [Custom](#custom) attestation type below for details. ```shell kosli attest custom \ --type coverage-metrics \ --name unit-tests \ - --attestation-data coverage-results.json \ - ... + --flow backend-ci \ + --trail $(git rev-parse HEAD) \ + --attestation-data coverage-results.json ``` From f41cd706e9519da7add512e5984f9d8a169e8ba6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 23 Apr 2026 13:23:45 +0200 Subject: [PATCH 3/4] docs: add 10MB payload size warning to data flags section The server enforces a 10MB limit on all attestation request payloads. This applies to --user-data, --attachments, and --attestation-data combined. Mentions --external-url as the alternative for larger files. --- getting_started/attestations.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index 96e075f..af59713 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -209,6 +209,12 @@ These flags can be combined. For example, you can use `--attestation-data` for c same attestation. + +The total request payload — including all data and attachments — is limited to **10 MB** per attestation. +This applies to `--user-data`, `--attachments`, and `--attestation-data` combined. If you need to +attach larger files, store them externally and use `--external-url` to link to them. + + ## Attestation types Currently, we support the following types of evidence: From 8d115452eeced9954e34b16259cefcc19ecb80f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 23 Apr 2026 13:27:01 +0200 Subject: [PATCH 4/4] fix: remove inaccurate payload size warning The 10MB limit only applies to file uploads (multipart/form-data), not to JSON body fields like --user-data and --attestation-data. Removing rather than documenting incorrect limits. --- getting_started/attestations.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index af59713..96e075f 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -209,12 +209,6 @@ These flags can be combined. For example, you can use `--attestation-data` for c same attestation. - -The total request payload — including all data and attachments — is limited to **10 MB** per attestation. -This applies to `--user-data`, `--attachments`, and `--attestation-data` combined. If you need to -attach larger files, store them externally and use `--external-url` to link to them. - - ## Attestation types Currently, we support the following types of evidence: