From 6486dd00ecde0bea806cd5d400a97329f8b36ff0 Mon Sep 17 00:00:00 2001 From: Alex Kantor Date: Tue, 15 Sep 2026 11:14:56 +0100 Subject: [PATCH] docs: describe the sbom attestation type Adds an SBOM entry to the attestation types list, points the large-documents tutorial at it, and completes two hand-written type tables that the new type made incomplete. The tutorial teaches distilling a report into a custom summary and attaching the original. For SBOMs that is now the workaround rather than the approach, so it says so while staying correct for SARIF and anything else Kosli does not parse. Two reference pages list the allowed types by hand, and both were wrong. The flow template reference says "one of" and was already missing decision, and its trail-level and artifact-level descriptions listed different sets despite the schema using one shared Attestation definition for both. The environment policy reference had the same gap in its table. Each now names every value its schema allows, checked against schemas/flow-template/v1.json and schemas/policy/v1.json rather than by eye. Content is taken from the command's own long description and the parsed document struct: the supported formats, that the file is uploaded as supplied so its checksum is verifiable by hand, that Kosli sets the sbom_format and sbom_sha256 annotations, that nothing is checked against the artifact, and that the CLI refuses a file over 9 MiB to leave room for the attestation inside the 10 MB the server accepts. The reference page, its navigation entry and the regenerated schemas are no longer here. The v2.41.0 release and the schema job landed all three, so the branch is rebuilt on those and carries only what is written by hand. search: grep for pages enumerating attestation types found flow_template.md, environment_policy.mdx, understand_kosli/glossary.md and labs/lab-03-build-controls.mdx. The first two are exhaustive and are fixed. The glossary says "include" rather than listing all, so it is not wrong. The lab is teaching material and is left alone. mutation: not applicable, prose Co-Authored-By: Claude Opus 5 --- getting_started/attestations.md | 23 +++++++++++++++++++++++ policy-reference/environment_policy.mdx | 2 ++ template-reference/flow_template.md | 4 ++-- tutorials/attest_large_documents.md | 2 ++ 4 files changed, 29 insertions(+), 2 deletions(-) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index 1652d1d5..bc32029e 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -4,6 +4,8 @@ description: "Learn how to make attestations to Kosli to prove compliance in you icon: "receipt" --- +import CliBetaNotice from "/snippets/cli-beta-notice.mdx"; + Attestations are how you record the facts you care about in your software supply chain. They are the evidence that you have performed certain activities, such as running tests, security scans, or ensuring that a certain requirement is met. @@ -288,6 +290,27 @@ Currently, we support the following types of evidence: See [attest Snyk results to an artifact or a trail](/client_reference/kosli_attest_snyk/) for usage details and examples. + + + + + You can attest a software bill of materials in CycloneDX (JSON or XML) or SPDX (JSON or + tag-value) format. Kosli reads the format, the creation time, the tools that produced it, + the subject it describes and how many packages it lists, and records those alongside the + file itself in the [Evidence Vault](#evidence-vault). + + The file is uploaded as supplied, so the checksum Kosli records is the checksum of your + file and you can verify it by hand. Kosli sets the `sbom_format` and `sbom_sha256` + annotations for you; you do not pass them with `--annotate`. + + Nothing in the SBOM is checked against the artifact. It is recorded as reported, so the + attestation says what the SBOM claims, not whether the claim is true. + + The CLI refuses an SBOM file larger than 9 MiB, which leaves room for the attestation + itself within the 10 MB the server accepts. We are working on raising this. + + See [attest an SBOM to an artifact or a trail](/client_reference/kosli_attest_sbom/) for usage details and examples. + You can use the Jira attestation to verify that a git commit or branch contains a reference to a Jira issue and that an issue with the same reference does exist in Jira. diff --git a/policy-reference/environment_policy.mdx b/policy-reference/environment_policy.mdx index 3b2baedf..8d8ecc9f 100644 --- a/policy-reference/environment_policy.mdx +++ b/policy-reference/environment_policy.mdx @@ -87,6 +87,8 @@ An environment policy is a YAML file that declares compliance requirements for a | `pull_request` | Pull request evidence | | `jira` | Jira ticket reference | | `sonar` | SonarQube analysis | +| `decision` | A recorded decision | +| `sbom` | A software bill of materials | | `*` | Matches any built-in or custom type | | `custom:` | A [custom attestation type](/client_reference/kosli_create_attestation-type) (e.g., `custom:coverage-metrics`) | diff --git a/template-reference/flow_template.md b/template-reference/flow_template.md index b4b46c94..2c01f2a0 100644 --- a/template-reference/flow_template.md +++ b/template-reference/flow_template.md @@ -24,7 +24,7 @@ A flow template defines what attestations are required for a trail and its artif - The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, `*` (matches any type). + The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, `decision`, `sbom`, `custom:` for [custom attestation types](/client_reference/kosli_create_attestation-type), or `*` to match any type. @@ -46,7 +46,7 @@ A flow template defines what attestations are required for a trail and its artif - The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, or `custom:` for [custom attestation types](/client_reference/kosli_create_attestation-type). + The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, `decision`, `sbom`, `custom:` for [custom attestation types](/client_reference/kosli_create_attestation-type), or `*` to match any type. diff --git a/tutorials/attest_large_documents.md b/tutorials/attest_large_documents.md index 513837f3..2b898dfb 100644 --- a/tutorials/attest_large_documents.md +++ b/tutorials/attest_large_documents.md @@ -8,6 +8,8 @@ By the end, you will have a Kosli attestation that captures the key facts from y This two-part approach keeps attestation payloads focused on what compliance rules need to evaluate, while ensuring the raw evidence remains available. +For SBOMs there is now a dedicated type, `kosli attest sbom`, which reads the format, tools, subject and package count from the file for you. It is in beta. This tutorial remains the approach for any report Kosli does not parse, such as SARIF. + The `--attestation-data` JSON payload sent by `kosli attest custom` is limited to 1 MB — exceeding it returns a 400 error. Distill larger reports into a summary and attach the full document with `--attachments`, as described below.