From 688561107f8cf0116eb73eebe3f488600dd6ae38 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 07:09:18 +0000 Subject: [PATCH 1/2] docs: describe signed sbom bundles in the sbom attestation type --- getting_started/attestations.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index 85828cd..3865e3a 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -305,9 +305,18 @@ Currently, we support the following types of evidence: 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 + A plain SBOM file is not checked against the artifact. It is recorded as reported, so the attestation says what the SBOM claims, not whether the claim is true. + The SBOM can also arrive inside a signed in-toto attestation, as a Sigstore bundle or a DSSE + envelope. Kosli then uploads and checksums the bundle or envelope, and reads the SPDX or + CycloneDX document from inside it. When the artifact's fingerprint is known, the attestation + must list that artifact as its subject. To verify who signed it, pass `--certificate-identity` + (or `--certificate-identity-regexp`) with `--certificate-oidc-issuer`, or `--key`. Without + those flags the signature is not checked, and the record is annotated with `verified` set to + false. To pick an SBOM or SLSA provenance from a file that holds several attestations, use + [`kosli attest in-toto`](/client_reference/kosli_attest_in-toto/) (beta). + **What you get depends on the tool, not just the format.** Kosli records what the document declares, and tools fill the same fields differently. Three differences catch people out. @@ -324,8 +333,8 @@ Currently, we support the following types of evidence: *A digest that is present is not automatically the artifact's.* The subject identifies what the generator scanned. Point one at a tag and it records whatever that tag resolved to on that machine. For a multi-architecture image that is a single architecture, and it can be a - local image id rather than a registry digest. Kosli does not check the subject against the - artifact, so a digest that is present can still belong to something else. Compare the two + local image id rather than a registry digest. Kosli does not check a plain SBOM's subject + against the artifact, so a digest that is present can still belong to something else. Compare the two only where your pipeline pointed the generator at the exact artifact it attests. Otherwise check it in the pipeline, where the build can fail, rather than in a policy. From 3930db1b007680a78d7f36fc147575711f73b7bc Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 07:15:08 +0000 Subject: [PATCH 2/2] docs: note when a bundled sbom subject is not checked --- getting_started/attestations.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/getting_started/attestations.md b/getting_started/attestations.md index 3865e3a..d7efb68 100644 --- a/getting_started/attestations.md +++ b/getting_started/attestations.md @@ -310,8 +310,10 @@ Currently, we support the following types of evidence: The SBOM can also arrive inside a signed in-toto attestation, as a Sigstore bundle or a DSSE envelope. Kosli then uploads and checksums the bundle or envelope, and reads the SPDX or - CycloneDX document from inside it. When the artifact's fingerprint is known, the attestation - must list that artifact as its subject. To verify who signed it, pass `--certificate-identity` + CycloneDX document from inside it. When the artifact's fingerprint is known, calculated or + given with `--fingerprint`, the attestation must list that artifact as its subject. Attested + to a trail alone, or bound by template name and commit, it has no fingerprint, so the subject + is not checked. To verify who signed it, pass `--certificate-identity` (or `--certificate-identity-regexp`) with `--certificate-oidc-issuer`, or `--key`. Without those flags the signature is not checked, and the record is annotated with `verified` set to false. To pick an SBOM or SLSA provenance from a file that holds several attestations, use