docs: describe the sbom attestation type - #414
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Claude finished @AlexKantor87's task in 3m 28s —— View job Doc quality reviewReviewed the 4 changed files at HEAD ( Sequencing is resolved. Three findings are posted inline. Two more below, on lines the diff does not touch. Improvement —
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| @@ -0,0 +1,122 @@ | |||
| --- | |||
| title: "kosli attest sbom" | |||
| tag: "BETA" | |||
There was a problem hiding this comment.
This is generated from CLI release
There was a problem hiding this comment.
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 <noreply@anthropic.com>
2c05bf0 to
6486dd0
Compare
| 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. |
There was a problem hiding this comment.
Two things a reader needs here that the generated reference page has and this accordion does not.
A gzipped SBOM is rejected, and the size cap is what makes a reader reach for gzip. client_reference/kosli_attest_sbom.md states it plainly: "It must be a single file: it is not compressed, and a gzipped file is rejected, because the format and the summary below are read from it." Line 309 tells the reader their 12 MiB CycloneDX file will be refused and then leaves them to discover by trial that the obvious workaround does not work. One clause — "it must be an uncompressed single file; a gzipped SBOM is rejected" — closes that.
Compliance status is still unstated. "Nothing in the SBOM is checked against the artifact" says what is not checked and never says what status the attestation lands in. This has become load-bearing in this PR rather than optional: the same diff adds sbom to the required-attestation type table in policy-reference/environment_policy.mdx:91, and that rule's must_be_compliant defaults to true (schemas/policy/v1.json). Someone writing must_be_compliant: true against a type that is recorded-as-reported needs to know whether that can ever fail. JUnit, Snyk, Sonar and pull requests all state it; this is the only accordion that does not.
| | `decision` | A recorded decision | | ||
| | `sbom` | A software bill of materials | |
There was a problem hiding this comment.
Both rows match schemas/policy/v1.json, but the sweep stops one file short and decision arrives here with no way to use it.
snippets/policy-builder.jsx was not updated. Its BUILTIN_TYPES (lines 32–39) still lists six types, and its own header comment says "Keep this file in sync with the v1 policy schema." That snippet is the interactive builder on policy-reference/policy_builder.mdx, so a reader who uses the widget rather than this table cannot produce a rule for either new type — while the table three clicks away says both are valid. The two pages now disagree about what a policy can require.
decision has no for_control. The schema field is described as "Control identifier this decision attestation must satisfy. Only valid when type is 'decision'", and for_control appears nowhere in policy-reference/ (grep -rn for_control policy-reference/ is empty). This table is the first place on the site to tell a policy author decision is a valid type; it should not also be the last word on it. decision likewise has no accordion in getting_started/attestations.md "Attestation types" — it is the only type in this table without one.
|
|
||
| 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. |
There was a problem hiding this comment.
Still unaddressed at HEAD: this paragraph redirects SBOM readers away, but the two things that route them here were not updated with it.
title(line 2) is still"Attesting large documents (SBOMs, SARIF, vulnerability reports)".config/navigation.json:97has no label override, so that string is the navigation label and the search result. An SBOM reader clicks the one page whose title promises SBOMs and the first thing it says is that they are in the wrong place.description(line 3) still scopes the page to "large security and compliance reports", with no hint that one report type is now carved out.- Line 22 still offers "an SBOM in JSON format" as the first prerequisite example — the single example this paragraph has just deprecated.
Leading all three with SARIF and vulnerability reports makes the redirection consistent with the page rather than in tension with it.
2 participants
Documents the new
sbomattestation type. Hand-written content only.What changed
getting_started/attestations.mdgains an SBOM entry in the types list. It carries the beta notice and links to the reference page.tutorials/attest_large_documents.mdpoints at it. That tutorial teaches distilling a report into a custom summary. For SBOMs that is now the workaround rather than the approach. It stays correct for SARIF.Two reference pages list allowed types by hand. Both were incomplete. The flow template reference says "one of" and was already missing
decision. Its two descriptions listed different sets, though one schema definition drives both. The environment policy reference had the same gap. Each now matches its own schema.Rebuilt after the release
This branch previously carried the generated reference page, its navigation entry and the schemas. The v2.41.0 release and the schema job landed all three on main. The branch was rebuilt on top of them.
The page I generated locally was byte-identical to the released one.
Where the content came from
The command's long description and the parsed document struct at v2.41.0. That covers the formats, the verifiable checksum, the two annotations Kosli sets, and that nothing is checked against the artifact.
The CLI refuses a file over 9 MiB. That leaves room for the attestation inside the 10 MB the server accepts.
Known and not done
labs/lab-03-build-controls.mdxandunderstand_kosli/glossary.mdalso list built-in types and omitdecisionandsbom.🤖 Generated with Claude Code