Skip to content

docs: describe the sbom attestation type #414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexKantor87 merged 1 commit into from
Sep 15, 2026
+29 −2
Merged

docs: describe the sbom attestation type #414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions getting_started/attestations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.
</Accordion>
<Accordion title="SBOM" icon="list-tree">

<CliBetaNotice />

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.
Comment thread
AlexKantor87 marked this conversation as resolved.
Comment on lines +306 to +310

@claude claude Bot Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Fix this →


See [attest an SBOM to an artifact or a trail](/client_reference/kosli_attest_sbom/) for usage details and examples.
</Accordion>
<Accordion title="Jira issues" icon="clipboard-list-check">

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.
Expand Down
2 changes: 2 additions & 0 deletions policy-reference/environment_policy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Comment on lines +90 to +91

@claude claude Bot Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Fix this →

| `*` | Matches any built-in or custom type |
| `custom:<name>` | A [custom attestation type](/client_reference/kosli_create_attestation-type) (e.g., `custom:coverage-metrics`) |

Expand Down
4 changes: 2 additions & 2 deletions template-reference/flow_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ A flow template defines what attestations are required for a trail and its artif
</ParamField>

<ParamField path="trail.attestations[].type" type="string" required>
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:<custom-type-name>` for [custom attestation types](/client_reference/kosli_create_attestation-type), or `*` to match any type.
</ParamField>
</Expandable>
</ParamField>
Expand All @@ -46,7 +46,7 @@ A flow template defines what attestations are required for a trail and its artif
</ParamField>

<ParamField path="trail.artifacts[].attestations[].type" type="string" required>
The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, or `custom:<custom-type-name>` 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:<custom-type-name>` for [custom attestation types](/client_reference/kosli_create_attestation-type), or `*` to match any type.
</ParamField>
</Expandable>
</ParamField>
Expand Down
2 changes: 2 additions & 0 deletions tutorials/attest_large_documents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
AlexKantor87 marked this conversation as resolved.

@claude claude Bot Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:97 has 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.

Fix this →


<Note>
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.
</Note>
Comment thread
AlexKantor87 marked this conversation as resolved.
Expand Down