Signing documents

How cdx --sign and bom enrich --sign sign a CycloneDX document with the runner's own OIDC identity through Fulcio and Rekor, the sidecar files they write, and what happens where there is no identity.

Two commands take --sign:

vulnetix cdx --sign
vulnetix bom enrich vendor.cdx.json --out enriched.cdx.json --sign

The signature uses the identity of the machine running the command: a workflow reference in CI. It is not a Vulnetix credential. A scan run in your pipeline is better attested by you than by the tool vendor, and the result verifies with cosign verify-blob against public Sigstore.

Where the identity comes from

Order	Source	Notes
1	`SIGSTORE_ID_TOKEN`	Any OIDC token Fulcio accepts. Use this on GitLab CI, mapping an `id_tokens` entry with `aud: sigstore` into it.
2	The GitHub Actions OIDC token	Only present when the job has `permissions: id-token: write`

With neither, signing is skipped with the reason no OIDC identity in this environment, so there is nothing to sign as. The document is still written and the command still succeeds: losing an SBOM over a missing signature would be worse than an unsigned SBOM.

Endpoints

Variable	Default	Effect
`SIGSTORE_FULCIO_URL`	`https://fulcio.sigstore.dev`	Certificate authority
`SIGSTORE_REKOR_URL`	`https://rekor.sigstore.dev`	Transparency log. `-` skips logging.

Point both at a private Sigstore to keep signatures off the public log, and give verifiers its root with --trusted-root (see Trust roots and signer pinning).

Files written

File	Contents
`<file>`	The document, with an embedded JSF signature. The detached signatures cover these bytes.
`<file>.sig`	Base64 signature
`<file>.pem`	The short-lived Fulcio certificate binding the signature to the identity
`<file>.intoto.jsonl`	The same claim as a DSSE envelope

These are the names cosign verify-blob expects and the names the Vulnetix release workflows publish.

Verifying

vulnetix attest verify .vulnetix/sbom.cdx.json

Or with cosign:

cosign verify-blob \
  --certificate-identity "https://github.com/acme/repo/.github/workflows/release.yml@refs/heads/main" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --bundle .vulnetix/sbom.cdx.json.intoto.jsonl \
  .vulnetix/sbom.cdx.json

Enriching a signed document

bom enrich --sign signs the output with this machine’s identity, because this machine made the new claims. A signature that was on the input is kept as vulnetix:bom/original-signature, since it still attests the input. See Enrich an SBOM.