Supply-Chain Attestations

This page is for the first time you’re asked to sign an artifact and you’re not sure what any of the acronyms mean. It covers four things chant attaches to a build, in plain language, then walks through doing it for real with the sign and verify capabilities.

Want to just run something?

examples/supply-chain is a complete, clone-and-run project: npm install && npm run supply-chain produces a real SBOM and a real config-BOM with no external tool installed — see Generating an SBOM tool-free below for the same walkthrough inline. The tool-gated sign/verify/vuln-gate steps this page covers are also in that example, clearly marked as needing cosign/syft/grype.

Glossary

Term	What it actually is
SBOM (Software Bill of Materials)	A list of every package/library in the artifact — name, version, license. Answers “what’s in this thing,” the same way a food label answers “what’s in this can.”
SLSA provenance	A signed statement of where the artifact came from and how it was built — source commit, builder identity, build timestamp. Answers “who built this and from what,” not “what’s in it.”
Signature	Cryptographic proof that a specific identity (a person or a CI workflow) produced this exact artifact, plus a public record that the signature happened. Answers “who vouches for these exact bytes.”
VEX / CVE	A CVE is a known vulnerability in some package. VEX is a statement about whether a given CVE actually affects this artifact the way it’s used. Answers “of everything the SBOM lists, what actually matters.”

An SBOM tells you what’s inside. Provenance tells you where it came from. A signature tells you who’s vouching for it. None of the three answers the other two — that’s why chant attaches all three separately, to the same artifact, rather than treating any one as a stand-in for the others.

What each capability needs to run

vuln-gate is real: it scans an SBOM for known CVEs, applies VEX suppression, evaluates a license policy, and throws VulnGateFailedError on a policy violation — see VEX/CVE gating below. The scanner it registers by default auto-detects a real backend at scan time — grype if present, else trivy — and throws only when neither is on PATH. Signing and provenance are real end-to-end once cosign is on PATH. See the Prerequisites table below for the full tool surface.

Prerequisites

What each capability needs installed. The dir/zip/jar SBOM path is the only one that runs with nothing external installed.

Capability	External tool	Tool-free?
generate-sbom — dir / zip / jar	none (pure-TypeScript lockfile backend)	Yes
generate-sbom — image	syft or docker buildx (#610)	No
sign / attest-provenance / verify	cosign	No
vuln-gate	grype or trivy (auto-detected at scan time)	No

Generating an SBOM tool-free

Before any of the signing/provenance material below, there’s a step that needs no external tool at all: generate-sbom. Every artifact type it supports (dir, zip, jar — not image, see the aside below) defaults to lockfileSbomGenerator (packages/core/src/components/verbs/lockfile-sbom-generator.ts), a pure-TypeScript backend that parses a package-lock.json/pom.xml already on disk and emits a real SPDX/CycloneDX document. No syft, no network, no Docker.

a config-only/producer component's build phase

import { phase, type Component } from "@intentius/chant/components/component";

export const myLib: Component = {
  name: "my-lib",
  archetype: "producer-library",
  dependsOn: [],
  deploy: [
    phase("Sbom", [
      { kind: "generate-sbom", artifactType: "dir", path: ".", format: "spdx" },
    ]),
  ],
};

Run it:

chant run --components my-lib --env local

That writes sbom.spdx.json next to the scanned package-lock.json (lockfileSbomGenerator’s default outDir) and folds an sbom-kind entry into the component’s build-archive manifest. examples/supply-chain is this exact pattern, plus a second, structural BOM over a synthesized IaC template via extract-config-bom — clone it and run npm install && npm run supply-chain to see both artifacts land on disk.

forImage is the one exception

An image’s dependency surface includes its base layers, which no lockfile enumerates — generate-sbom with artifactType: "image" still throws SbomGeneratorNotImplementedError by default. That path needs the real deep-scan tool backend (syft/docker buildx --sbom/cyclonedx-maven/cdxgen, tracked in #610) — inject toolSbomGenerator (packages/core/src/components/verbs/tool-sbom-generator.ts) explicitly once that tool is available. dir/zip/jar never had this problem: their dependency surface is the lockfile.

Why keyless signing

The obvious way to sign something is a private key: generate a keypair, sign with the private half, publish the public half for verification. That works, but it hands a beginner a new hazard — a key file that can leak, that can be lost (taking your ability to sign with it), and that someone has to remember to rotate.

Keyless signing removes the key file entirely. Instead of a long-lived secret, cosign asks an OIDC identity provider you already use — your CI system’s built-in token, or a browser login — “prove who you are,” and gets back a short-lived certificate good for a few minutes. It signs with that, and logs the signature to a public transparency log (Rekor) so anyone can later confirm a signature really was issued at that time for that identity. The certificate expires almost immediately; there’s nothing left to steal afterward.

This is why chant’s sign capability defaults to keyless with no configuration: there’s no key to generate before your first signature, and nothing to rotate afterward. Key-based signing still exists as an explicit opt-in (key config) for teams with an existing KMS policy, but it is never what a new project reaches for first.

The one thing you must set: an OIDC identity

Signing needs no setup — cosign detects ambient OIDC automatically in GitHub Actions, GitLab CI, and most CI providers, and falls back to an interactive browser login locally. Verifying does need one thing from you: telling verify which identity is allowed to have signed.

Without this, “verify” would only mean “some signature exists” — which any keyless signer, including an attacker who can also complete an OIDC login, can produce. Naming the expected issuer and identity is what turns “a signature exists” into “the identity I trust signed this.”

Set it in two places that must agree:

chant.config.ts

export default {
  signing: {
    oidcIssuer: "https://token.actions.githubusercontent.com",
    identity: "https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main",
  },
};

a component's verify step

import { verify } from "@intentius/chant/components/verbs/verify";

await verify.run(ctx, {
  imageRef: "@Sign.imageRef",
  policy: {
    expectedIssuer: "https://token.actions.githubusercontent.com",
    expectedIdentity: "https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main",
  },
});

resolveSigningDefaults() (packages/core/src/config.ts) reads the signing block from chant.config.ts so a component’s verify step doesn’t have to repeat the issuer/identity literally — it resolves project-wide defaults a per-call policy can still override.

For GitHub Actions and GitLab CI, oidcIssuer is the provider’s fixed token endpoint and identity is your own workflow’s ref — both values you can read straight off the provider’s own OIDC docs, not something chant invents. Locally, signing falls back to an interactive Sigstore login (a browser tab), and identity becomes the email cosign’s certificate records for that login.

identityIsRegexp: true treats identity as a pattern instead of a literal match, for teams whose workflow ref varies by branch or tag and don’t want to enumerate every one.

Both fields are required, on purpose

IdentityPolicy has no “verify but accept any identity” mode. An identity-less verify would defeat the entire point of keyless signing — anyone’s Rekor-logged signature would pass. expectedIssuer and expectedIdentity are both required fields, not an optional pair a beginner could forget to set.

Why digest, not tag

A tag like myapp:latest is a pointer that can move — the next push retargets it to different bytes without changing the tag. Signing a tag would only ever mean “something with this name was signed at some point,” which says nothing about what a docker pull actually resolves to by the time someone runs it.

A digest (myapp@sha256:...) is the artifact’s own content hash. It cannot be reassigned to different bytes; a signature on a digest is a signature on those exact bytes, forever.

sign and attest-provenance enforce this structurally: both throw SignTargetNotDigestError before ever invoking cosign if the reference isn’t digest-qualified. In practice you never construct that digest by hand — it comes from a prior publish step’s output ("@Publish.uri", itself repo@sha256:...; see Build Archive).

First-signing walkthrough

One digest carries all three attestations — SBOM, provenance, and signature — and verify checks that digest before a deploy is allowed to proceed.

This walkthrough's SBOM step needs a scanner

The Sbom phase below uses artifactType: "image", which throws SbomGeneratorNotImplementedError by default until a scanner backend is wired in (#610) — see the Prerequisites table. For a first run that needs no external tool at all, start from Generating an SBOM tool-free (dir/zip/jar artifacts), then layer on the sign/verify steps shown here once cosign is installed.

SBOM, provenance, and signature all attach to one artifact digest. Verify gates apply on that digest.

The composition below is the real authoring shape — a Component built from phase()/Step (packages/core/src/components/component.ts), the exact shape chant run --components dispatches, not a paraphrase. It’s written here as { kind: … } literals to keep every field visible; each step also has a typed builder (sign({ … }), verify({ … })) — see Component Contract:

deploy-with-attestations.component.ts

import { phase, type Component } from "@intentius/chant/components/component";

export const webService: Component = {
  name: "web-service",
  archetype: "service",
  dependsOn: [],
  build: { kind: "docker-build", context: "." },
  deploy: [
    phase("Build", [
      { kind: "docker-build", context: ".", into: "web-service.tar", sourceRef: "$env.GIT_SHA" },
    ]),
    phase("Publish", [
      // "@Build.digest" reads the prior "Build" phase's docker-build output —
      // publish-image's own output, "@Publish.uri", is what every step below wires from.
      { kind: "publish-image", from: "archive:web-service.tar", to: "123.dkr.ecr.us-east-1.amazonaws.com/web-service" },
    ]),
    phase("Sbom", [
      { kind: "generate-sbom", artifactType: "image", path: "archive:web-service.tar", digest: "@Build.digest" },
    ]),
    phase("Attest", [
      {
        kind: "attest-provenance",
        imageRef: "@Publish.uri",
        // { sourceRef, artifactDigest } — the same link docker-build folded into the archive manifest (#614)
        provenance: { sourceRef: "$env.GIT_SHA", artifactDigest: "@Build.digest" },
        builderId: "https://github.com/actions/runner",
      },
    ]),
    phase("Sign", [
      { kind: "sign", imageRef: "@Publish.uri" }, // keyless — no key config needed
    ]),
    phase("Verify", [
      {
        kind: "verify",
        imageRef: "@Publish.uri",
        policy: {
          expectedIssuer: "https://token.actions.githubusercontent.com",
          expectedIdentity: "https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main",
        },
      },
    ]),
    phase("Apply", [
      { kind: "cfn-deploy", template: "archive:web-service.template.json" }, // only runs if Verify passed
    ]),
  ],
};

Run it: chant run --components web-service --env prod. Every step from Sbom onward takes the same "@Publish.uri" digest (or "@Build.digest", threaded from the Build phase) — build once, attest three times, verify once, all against bytes that never change underneath you.

“Done right” here means: the digest deployed is the digest that was signed, and verify ran and passed before apply — not signed-and-forgotten, and not a signature that gets checked manually after the fact if someone remembers. Put verify before the Apply phase in the composition and a failed check throws, halting the deploy the same way any other thrown capability error does (see Orchestration) — an unsigned or wrongly-signed artifact never reaches apply.

verify also checks provenance by default — sign alone is not enough

VerifyInput.requireProvenance defaults to true (packages/core/src/components/verbs/verify.ts), so verify runs cosign verify-attestation --type slsaprovenance1 alongside the signature check unless you explicitly pass requireProvenance: false. That means the composition above needs both sign and attest-provenance to have already run against the same digest — verify on a digest that was only signed (no provenance attested) throws VerificationFailedError on the provenance check, not just the signature one.

cosign must be installed

sign/attest-provenance/verify all shell out to the real cosign binary. If it’s missing, you get a clear ToolNotAvailableError naming the missing tool and what was being attempted — never a silent skip or a fake pass. Install cosign from docs.sigstore.dev/cosign/system_config/installation and it’s on PATH for every environment that runs these three capabilities, including CI. generate-sbom above needs no such install for dir/zip/jar artifacts (see Generating an SBOM tool-free) — only artifactType: "image", as used here, needs a real scanner backend (#610).

chant.config.ts fills these in for you (#629)

Repeating signing/vulnPolicy on every step is only necessary if you want a per-step override. chant run --components resolves chant.config.ts’s sbom/signing/vulnPolicy sections and fills them into any generate-sbom/sign/attest-provenance/verify/vuln-gate step that didn’t already set the field itself (packages/core/src/components/config-defaults.ts’s applyConfigDefaults, called from runComponents before dispatch). With a project-wide signing block set, the Verify phase above can shrink to { kind: "verify", imageRef: "@Publish.uri", policy: {} } — see examples/supply-chain’s chant.config.ts for a working example of both.

VEX/CVE gating with vuln-gate

vuln-gate scans an SBOM for known CVEs, suppresses the ones a VEX document says don’t actually apply, checks a license policy, and throws VulnGateFailedError on a violation — the same throw-to-halt mechanism as verify:

a Gate phase, composed after Sbom

phase("VulnGate", [
  {
    kind: "vuln-gate",
    sbom: "@Sbom.sbom", // wired from the generate-sbom step's output, same phase-output convention as "@Publish.uri"
    policy: {}, // filled from chant.config.ts's vulnPolicy section (#629) when left empty
  },
]),

The default policy (DEFAULT_VULN_POLICY, packages/core/src/components/verbs/vuln-gate.ts) is beginner-safe: block only critical + fixable + not-VEX-suppressed findings; warn on high; license findings are report-only unless failOnLicense: true.

vuln-gate needs grype or trivy installed

vuln-gate scans via an injectable VulnScanner. The capability chant run --components registers by default auto-detects a real backend at scan time — grype if present, else trivy (autoDetectVulnScanner, packages/core/src/components/verbs/vuln-scan.ts) — so the gate works the moment either tool is on PATH, no code wiring (#634, the vuln-side analog of the hermetic-by-default SBOM generator). When neither is installed it throws a ToolNotAvailableError naming what to install, not a silent empty scan. To pin a specific tool or inject a mock, construct your own registry with createVulnGateCapability(createToolVulnScanner("grype")) (see RunComponentsOptions.registry, packages/core/src/components/cli-support.ts), or supply findings directly from a prior scan-vulnerabilities step. Unlike the SBOM step there is no hermetic fallback — a scan needs a real vuln database, so a scanner is genuinely required.

Read next

• Build Archive — how the SBOM is generated and where the digest sign/verify operate on comes from.
• Observability — the build ledger’s referrer discovery, which can surface a digest’s signature/provenance/SBOM referrers after the fact.
• Orchestration — how a thrown VerificationFailedError halts a composition before apply runs.
• examples/supply-chain — the runnable version of this page: npm install && npm run supply-chain produces a real SBOM + config-BOM tool-free, plus the tool-gated steps above as a separate, clearly-marked component.