Applied AI-Accelerated Government Development

The Build Ships Its Own SBOM and Evidence

Updated

Intermediate

What you'll learn

~50 min
  • Generate a CycloneDX SBOM (software bill of materials, the machine-readable ingredient list of a build) for the Next.js app inside the pipeline
  • Write a verify-sbom gate that fails the build and names the missing CISA 2026 minimum element
  • Bind the SBOM and test evidence to the container image digest in a hashed manifest that the deploy step re-checks
  • Explain why an agency request for an SBOM is optional under OMB M-26-05 and why shipping one anyway answers it in minutes

The case-intake office’s agency has just asked, in an email, what is inside the new intake application. If the answer is a week of someone reading lockfiles, the build is missing a step. If the answer is a file the pipeline already attached to the release, you reply in minutes. This lesson builds that file and the gate that keeps it honest.

DevOps Foundations (a separate training in this series) already taught the idea. DevOps Foundations 5.2, Provenance and SBOM covers why SBOMs outlived the memo that pushed them, the split between signing tools, and platform-native build provenance. Nothing there is repeated here. This lesson adds two pieces only: generating the app-level SBOM for this stack, and a failure gate that refuses a build whose SBOM is missing a required field.

Before the detail — Artifact: sbom.cdx.json, a verify-sbom script, and evidence-manifest.json binding both to the image digest, all produced by the SBOM stage, scripts/ci/sbom.sh, that follows the build image stage in lesson 19’s pipeline stages. Acceptance test: delete one required field from the SBOM and the build fails, naming that field. Status of what follows: reusable engineering practice; the field list is guidance, not a mandate.

What the policy does and does not ask

OMB memo M-26-05 (January 23, 2026) rescinds the earlier software-security memos M-22-18 and M-23-16. It makes the secure software development attestation form and SBOM requests an agency choice: agencies “may choose” to use the form, and “may also choose to adopt contractual terms” that require a software producer to provide a current SBOM upon request. It sets no deadline and mandates no SBOM. What it keeps is the agency’s duty to maintain a complete inventory of software and hardware. Source: OMB M-26-05.

So this is not a lesson about meeting a requirement. It is a lesson about being the team that can answer when its agency, or its contract, asks.

What is not equivalent: the memo’s footnote says that for a cloud platform, an agency adopting such a term should specify an SBOM of the runtime production environment. The app-level SBOM you build here lists the application’s packages. It is not an inventory of the platform it runs on, and it should not be offered as one.

Which tool, and why

The generator is @cyclonedx/cyclonedx-npm, from the CycloneDX project, which maintains the CycloneDX format. It is Apache-2.0 licensed, built for npm projects, and reads the installed dependency tree (or, with a flag, only the lockfile). The CycloneDX project’s Node meta-package points npm projects to exactly this tool and says to depend on the actual tool, not the meta-package. Alternatives exist, including a polyglot generator from the same ecosystem and image-level scanners; this lesson stays with the npm tool because the reference platform is an npm project, and because its flags are small enough to read in one sitting. The container image’s operating-system packages need an image-level generator, which is outside this lesson.

The flags used here come from the tool’s own --help on 2026-11-04:

FlagWhat it doesWhy it is here
--omit devLeaves development-only packages out of the treeThe SBOM describes what ships, not what built it
--mc-type applicationMarks the main component as an applicationThe root component is the app, not a library
--of JSONOutput formatThe gate parses JSON
-o <file>Output fileWritten into the evidence directory
--sv <version>Pins the CycloneDX spec versionThe tool defaults to 1.6; pin it so a tool upgrade cannot change the format silently
--package-lock-onlyUses only the lockfile, ignoring node_modulesAn option when you want lockfile truth and no install; the default reads what is installed

One flag to leave out: --output-reproducible. It makes the output stable between runs by dropping time- and random-based values, which includes the timestamp. The CISA minimum elements want a timestamp, so the gate below would rightly fail. Reproducibility and a timestamp pull in opposite directions; this lesson takes the timestamp.

Pin the generator itself, so a tool upgrade is a reviewed change:

Terminal window
npm install --save-dev --save-exact @cyclonedx/cyclonedx-npm@6.0.1

The minimum elements, and where each lives

CISA’s 2026 Minimum Elements for an SBOM (July 29, 2026, a joint product of CISA, NSA, FBI and international partners) lists 17 data fields: nine about the SBOM itself and eight about each component. It states that the elements “do not create new requirements; they refine how organizations should generate and request SBOMs.” Source: 2026 Minimum Elements for an SBOM. A gate built on it is therefore a quality bar you choose, in line with what an agency is likely to ask for.

The document defines the fields, not where each one lives in CycloneDX. The mapping below is this lesson’s own choice for CycloneDX 1.6. Check it against whatever mapping your agency or its assessor publishes.

CISA elementCycloneDX 1.6 location (this lesson’s mapping)Who fills it
SBOM Authormetadata.authors[].namefinalize-sbom step
SBOM Author Signaturesignature, or a detached <file>.sig beside it. The gate checks only that this artifact is presentThe signing step
SBOM Data Format Name / VersionbomFormat / specVersionGenerator
SBOM Generation Contextmetadata.lifecycles[].phasefinalize-sbom step (build)
SBOM Timestampmetadata.timestampGenerator
SBOM Tool Name / Versionmetadata.tools.components[]Generator
SBOM VersionversionGenerator
Component Name / Versionname / versionGenerator
Component Producerauthor, supplier.name or publisherGenerator, when the package declares one
Component Identifierspurl (or cpe)Generator
Component Licenselicenses[]Generator, when the package declares one
Component Hash Algorithm / Valuehashes[], or the hashes on a distribution externalReferences entryGenerator
Component Dependency Relationshipthe component’s bom-ref appearing in dependencies[].refGenerator

The signature row needs a caveat. verify-sbom can only tell you that a signature artifact is present; it does not check that the signature is valid, so it reports that element as “signature artifact present” and never as “signed”. Real verification means running your signing tool’s verify command against the SBOM with the public key or identity you trust, ideally in a stage the build cannot rewrite; the signing step from DevOps Foundations 5.2 is where that choice is made.

On a one-dependency test project on 2026-11-04, the generator filled everything except the author, the generation context, and the signature. Your real tree will show more gaps, usually a package with no declared license. That is the gate doing its work. For each gap you choose: fix it upstream, supply a reviewed override, or record an exception with an owner and an expiry. What you do not do is loosen the gate.

Plan the change with your agent

Open your agent in the project root and switch to Plan mode (Shift+Tab, /plan, or the mode picker in your desktop app). Ask it to plan the SBOM finalizer and completeness verifier scripts against the mapping table above:

We need two zero-dependency Node scripts in scripts/sbom/: one to stamp author and build lifecycle metadata on a CycloneDX SBOM, and one to verify the 17 CISA minimum elements. Ask me anything unclear before writing code.

What to check in the plan before you approve

  • scripts/sbom/finalize-sbom.mjs writes only metadata.authors and metadata.lifecycles (phase: 'build') into the CycloneDX 1.6 JSON file and does not touch any other generator output.
  • scripts/sbom/verify-sbom.mjs checks all 17 CISA 2026 minimum elements using the CycloneDX 1.6 locations from the mapping table above, exiting 1 if anything is missing and 0 otherwise.
  • Each missing element prints verify-sbom: FAIL <element name> (<where it should be>) and, for component elements, lists up to five offending name@version items.
  • A --pre-sign flag skips only the signature check and says so in its output; without --pre-sign, the signature check verifies artifact presence (signature or <file>.sig) and notes that cryptographic validity is checked separately.

If the agent’s first plan offers to default or guess missing component licenses during finalization, correct it before approving:

Do not fill in missing component licenses in finalize-sbom. Leave the generator output untouched except for authors and lifecycles, then proceed.

Keeping the finalizer narrow stops the agent from “helping” by filling a missing license with a guess. A gate whose input the agent can quietly improve is not a gate.

What you get

Here is the reference implementation from gov-dev-reference-app for scripts/sbom/finalize-sbom.mjs (for comparison with what your agent writes; you do not type or paste it by hand):

scripts/sbom/finalize-sbom.mjs
// Adds the fields the generator does not know: who authored the SBOM and in which phase.
import { readFileSync, writeFileSync } from 'node:fs';
const [file, author] = process.argv.slice(2);
if (!file || !author) {
console.error('usage: finalize-sbom.mjs <sbom.json> "<author name>"');
process.exit(2);
}
const bom = JSON.parse(readFileSync(file, 'utf8'));
bom.metadata.authors = [{ name: author }];
bom.metadata.lifecycles = [{ phase: 'build' }];
writeFileSync(file, JSON.stringify(bom, null, 2) + '\n');
console.log(`finalize-sbom: wrote authors + lifecycles into ${file}`);
REFERENCE CODE scripts/sbom/verify-sbom.mjs: CISA 2026 minimum-element completeness gate open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
scripts/sbom/verify-sbom.mjs
import { existsSync, readFileSync } from 'node:fs';
const args = process.argv.slice(2);
const file = args.find((a) => !a.startsWith('--'));
const preSign = args.includes('--pre-sign'); // signature is added by a later step
if (!file) { console.error('usage: verify-sbom.mjs <sbom.json> [--pre-sign]'); process.exit(2); }
const bom = JSON.parse(readFileSync(file, 'utf8'));
const md = bom.metadata ?? {};
const tools = md.tools?.components ?? [];
const missing = []; // { element, where, who? }
const need = (ok, element, where) => { if (!ok) missing.push({ element, where }); };
need(md.authors?.some((a) => a.name), 'SBOM Author', 'metadata.authors[].name');
if (preSign) console.log('verify-sbom: skipped SBOM Author Signature (--pre-sign; the signing step adds it)');
else {
// Presence only: this does NOT verify the signature cryptographically.
need(bom.signature || existsSync(`${file}.sig`), 'SBOM Author Signature (artifact present)', `signature, or ${file}.sig`);
console.log('verify-sbom: signature artifact present is checked; validity is not (verify with your signing tool)');
}
need(bom.bomFormat === 'CycloneDX', 'SBOM Data Format Name', 'bomFormat');
need(bom.specVersion, 'SBOM Data Format Version', 'specVersion');
need(md.lifecycles?.some((l) => l.phase), 'SBOM Generation Context', 'metadata.lifecycles[].phase');
need(md.timestamp, 'SBOM Timestamp', 'metadata.timestamp');
need(tools.some((t) => t.name), 'SBOM Tool Name', 'metadata.tools.components[].name');
need(tools.some((t) => t.version), 'SBOM Tool Version', 'metadata.tools.components[].version');
need(bom.version, 'SBOM Version', 'version');
const depRefs = new Set((bom.dependencies ?? []).map((d) => d.ref));
const hashesOf = (c) => [...(c.hashes ?? []), ...(c.externalReferences ?? []).flatMap((r) => r.hashes ?? [])];
for (const c of bom.components ?? []) {
const id = `${c.name}@${c.version ?? '?'}`;
const miss = (element, where) => missing.push({ element, where, who: id });
if (!c.name) miss('Component Name', 'name');
if (!c.version) miss('Component Version', 'version');
if (!(c.author || c.supplier?.name || c.publisher)) miss('Component Producer', 'author | supplier.name | publisher');
if (!c.purl && !c.cpe) miss('Component Identifiers', 'purl | cpe');
if (!c.licenses?.length) miss('Component License', 'licenses');
const h = hashesOf(c);
if (!h.some((x) => x.content)) miss('Component Hash Value', 'hashes[].content');
if (!h.some((x) => x.alg)) miss('Component Hash Algorithm', 'hashes[].alg');
if (!depRefs.has(c['bom-ref'])) miss('Component Dependency Relationship', 'dependencies[].ref');
}
need((bom.components ?? []).length > 0, 'Component Name', 'components is empty');
if (missing.length === 0) {
console.log(`verify-sbom: PASS ${(bom.components ?? []).length} components, all minimum elements present`);
process.exit(0);
}
const byElement = Map.groupBy(missing, (m) => m.element);
for (const [element, list] of byElement) {
const who = list.filter((m) => m.who).map((m) => m.who);
const names = who.length ? ` ${who.length} component(s): ${who.slice(0, 5).join(', ')}${who.length > 5 ? ', ...' : ''}` : '';
console.log(`verify-sbom: FAIL ${element} (${list[0].where})${names}`);
}
process.exit(1);

Evidence, bound to the image digest

An SBOM that is not tied to a specific build answers the wrong question. The binding key is the container image digest, the content hash the registry assigns when you push. A tag can move; a digest cannot. The manifest records that digest next to a SHA-256 hash of every evidence file, and the deploy stage re-runs the check before its first deploy command and stops if either side differs (the exact steps are under “Wire it into the pipeline”). The hash-at-build, verify-at-every-hop idea is the one DevOps Foundations 5.1 taught; here it is applied to evidence files, and the manifest is deliberately small.

REFERENCE CODE scripts/sbom/evidence-manifest.mjs: bind and verify evidence hashes against the image digest open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
scripts/sbom/evidence-manifest.mjs
// write: evidence-manifest.mjs write <out.json> <sha256:image-digest> <file>...
// verify: evidence-manifest.mjs verify <manifest.json> <sha256:image-digest-being-deployed>
// Files are stored as paths relative to the manifest's directory and resolved the same way on verify,
// so the manifest still verifies after the evidence directory is published, downloaded or moved.
import { createHash } from 'node:crypto';
import { lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
import { dirname, isAbsolute, relative, resolve, sep, win32 } from 'node:path';
const sha256 = (f) => 'sha256:' + createHash('sha256').update(readFileSync(f)).digest('hex');
const [mode, target, digest, ...files] = process.argv.slice(2);
const DIGEST = /^sha256:[0-9a-f]{64}$/;
if (mode === 'write') {
if (!DIGEST.test(digest ?? '')) { console.error('evidence: image digest must be sha256:<64 hex>'); process.exit(2); }
const base = dirname(resolve(target));
const rel = (f) => relative(base, resolve(f)).split(sep).join('/');
const outside = files.filter((f) => rel(f).startsWith('..'));
if (outside.length) { console.error(`evidence: files must sit under the manifest directory: ${outside.join(', ')}`); process.exit(2); }
const manifest = { image: { digest }, files: Object.fromEntries(files.map((f) => [rel(f), sha256(f)])) };
writeFileSync(target, JSON.stringify(manifest, null, 2) + '\n');
console.log(`evidence: wrote ${target} for ${digest.slice(0, 19)}... (${files.length} files)`);
} else if (mode === 'verify') {
const m = JSON.parse(readFileSync(target, 'utf8'));
const base = dirname(resolve(target));
let bad = 0;
if (!DIGEST.test(digest ?? '')) { console.log('evidence: FAIL the digest being deployed is not sha256:<64 hex>'); bad++; }
if (m.image?.digest !== digest) { console.log(`evidence: FAIL manifest is for ${m.image?.digest}, deploying ${digest}`); bad++; }
const isObj = m.files !== null && typeof m.files === 'object' && !Array.isArray(m.files);
const entries = isObj ? Object.entries(m.files) : [];
// An empty manifest would "match" vacuously and prove nothing, so it fails.
if (entries.length === 0) { console.log('evidence: FAIL manifest lists no files'); bad++; }
for (const [f, h] of entries) {
// A manifest is input the verifier must not trust: it may only name files inside its own directory.
const full = resolve(base, f);
if (isAbsolute(f) || win32.isAbsolute(f) || f.split(/[\\/]/).includes('..') || !full.startsWith(base + sep)) {
console.log(`evidence: FAIL ${f} is not a path inside the manifest directory`); bad++; continue;
}
// The lexical check above cannot see symlinks: a link inside the directory can point anywhere.
// Refuse links outright, and compare canonical (realpath) locations for anything else.
let real = null;
try {
if (lstatSync(full).isSymbolicLink()) { console.log(`evidence: FAIL ${f} is a symlink; evidence must be regular files`); bad++; continue; }
real = realpathSync(full);
} catch { /* missing file: the hash comparison below reports it */ }
if (real && !real.startsWith(realpathSync(base) + sep)) {
console.log(`evidence: FAIL ${f} resolves outside the manifest directory`); bad++; continue;
}
let now = null;
try { now = sha256(full); } catch { /* missing file counts as changed */ }
if (now !== h) { console.log(`evidence: FAIL ${f} changed (or is missing) since the manifest was written`); bad++; }
}
if (!bad) console.log(`evidence: PASS ${entries.length} files match the manifest for ${digest.slice(0, 19)}...`);
process.exit(bad ? 1 : 0);
} else { console.error('usage: evidence-manifest.mjs write|verify ...'); process.exit(2); }

One honest limit: a manifest the same pipeline wrote protects against mistakes and drift, not against a compromised build. Detecting a rewrite by the build system itself needs a signature checked outside the pipeline, which is the signing step from DevOps Foundations 5.2.

Wire it into the pipeline

The SBOM stage is one script, scripts/ci/sbom.sh, called after lesson 19’s build-image.sh has written the image digest to ci-out/image-digest. Because it is a plain script, the same file runs in GitHub Actions, GitLab CI, Azure Pipelines or Bitbucket Pipelines, and on a laptop; Lesson 37 shows each dialect calling it and carrying ci-out/ to the deploy stage. The deploy stage reads ci-out/evidence/evidence-manifest.json, so a pipeline without this stage has no manifest and does not deploy.

REFERENCE CODE scripts/ci/sbom.sh: CI stage script for SBOM generation, gates, and evidence manifest open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
scripts/ci/sbom.sh
#!/usr/bin/env bash
set -euo pipefail
OUT=ci-out/evidence
DIGEST="$(cat ci-out/image-digest)"
mkdir -p "$OUT"
# Install exactly what the lockfile says, then generate and finalize the SBOM.
npm ci
npx cyclonedx-npm --omit dev --mc-type application --of JSON --sv 1.6 -o "$OUT/sbom.cdx.json"
node scripts/sbom/finalize-sbom.mjs "$OUT/sbom.cdx.json" "$(basename "$PWD") build pipeline"
# Gate 1: minimum elements present (pre-signing).
node scripts/sbom/verify-sbom.mjs "$OUT/sbom.cdx.json" --pre-sign
# Sign the SBOM. Put your signing command here; it must write sbom.cdx.json.sig beside the SBOM.
# Until it does, the next line fails the stage, so an unsigned SBOM cannot reach the manifest.
test -s "$OUT/sbom.cdx.json.sig"
# Gate 2: post-sign, all elements including the signature artifact.
node scripts/sbom/verify-sbom.mjs "$OUT/sbom.cdx.json"
# Bind evidence to the image digest; paths are stored relative to the manifest.
node scripts/sbom/evidence-manifest.mjs write "$OUT/evidence-manifest.json" "$DIGEST" \
"$OUT/sbom.cdx.json" "$OUT/sbom.cdx.json.sig"

ci-out/image-digest is the value lesson 19’s build image stage takes from the digest the registry reports for the pushed tag, and the deploy stage reads the same file, so the manifest and the deploy name one value.

Gates 1 and 2 stop the SBOM stage, and because deploy runs only after it succeeds, a failure in either one means nothing deploys. The deploy side then adds checks of its own, in this order, before its first deploy command. They are the first lines of lesson 19’s deploy.sh, and a non-zero exit from any of them fails the stage:

  1. The ci-out/evidence folder must have reached the deploy stage as a CI artifact; a missing manifest is a failure, not a skip.
  2. node scripts/sbom/evidence-manifest.mjs verify <manifest> "$IMAGE_DIGEST": every listed file must hash to its recorded value, the manifest must list at least one file, every path must stay inside the manifest’s directory, and the manifest’s image digest must equal the digest being deployed.
  3. A separate assertion that the manifest’s image.digest equals the digest in ci-out/image-digest, written without the verifier so a defect in one check does not silence the other.

The manifest stores file paths relative to its own directory, so verify works on the downloaded artifact wherever it lands.

The SBOM gate runs twice on purpose (Gate 1 and Gate 2 above). Before signing it skips only the signature element and prints that it did; after signing it runs in full. A gate that quietly skipped a field would be the failure it exists to prevent. Gate 2 checks that a signature artifact is present, as the table above says; it does not verify the signature.

See it work

SESSION SBOM gate: generate, break, bind
  1. Typed in the terminal: claude
  2. Mode:Plan mode
  3. You type in the session: We need two zero-dependency Node scripts in scripts/sbom/: one to stamp author and build lifecycle metadata on a CycloneDX SBOM, and one to verify the 17 CISA minimum elements. Ask me anything unclear before writing code.
  4. The tool replies: I will plan scripts/sbom/finalize-sbom.mjs and scripts/sbom/verify-sbom.mjs using only node:fs. Two questions before I write the plan: should verify-sbom support a flag to run before the signing step, and should the post-sign check run a cryptographic verify command or only check that the signature artifact exists?
  5. You type in the session: Add --pre-sign to skip only the signature check with a log line. Post-sign checks signature artifact presence only. Approved to implement.
  6. The tool replies: Wrote scripts/sbom/finalize-sbom.mjs and scripts/sbom/verify-sbom.mjs.
  7. You type in the session: Generate the SBOM for fixtures/mini-app (a one-dependency copy of our package.json), finalize it, and run verify-sbom with --pre-sign.
  8. The tool replies: $ npx cyclonedx-npm --omit dev --mc-type application --of JSON --sv 1.6 -o sbom.json $ node scripts/sbom/finalize-sbom.mjs sbom.json "intake build pipeline" finalize-sbom: wrote authors + lifecycles into sbom.json $ node scripts/sbom/verify-sbom.mjs sbom.json --pre-sign verify-sbom: skipped SBOM Author Signature (--pre-sign; the signing step adds it) verify-sbom: PASS 1 components, all minimum elements present The generator filled the timestamp, tool name and version, the component's purl, license, producer, hash and dependency entry. The author and generation context came from finalize-sbom. The signature element is still open and the output says so.
  9. You type in the session: Delete the license from the dependency and run the gate again. I want to see the failure name it.
  10. The tool replies: $ node scripts/sbom/verify-sbom.mjs sbom.json --pre-sign verify-sbom: skipped SBOM Author Signature (--pre-sign; the signing step adds it) verify-sbom: FAIL Component License (licenses) 1 component(s): <package>@<version> exit code 1 The failure names the element, where it should be, and the component. In the real tree a missing license is usually a package that does not declare one. Your choices are an upstream fix, a reviewed override, or an exception with an owner and an expiry; do not edit the gate.
  11. You type in the session: Now remove metadata.timestamp instead and show me that the build stops.
  12. The tool replies: $ node scripts/sbom/verify-sbom.mjs sbom.json --pre-sign verify-sbom: skipped SBOM Author Signature (--pre-sign; the signing step adds it) verify-sbom: FAIL SBOM Timestamp (metadata.timestamp) exit code 1 The pipeline step returns a non-zero code, so the stage fails and nothing downstream of it, including the image promotion, runs.
  13. You type in the session: Restore the SBOM, then write the evidence manifest for the image digest in $IMAGE_DIGEST and verify it. Then append a newline to sbom.json and verify again.
  14. The tool replies: $ node scripts/sbom/evidence-manifest.mjs write evidence-manifest.json sha256:2d71...bcce8 sbom.json evidence: wrote evidence-manifest.json for sha256:2d711642b726... (1 files) $ node scripts/sbom/evidence-manifest.mjs verify evidence-manifest.json sha256:2d71...bcce8 evidence: PASS 1 files match the manifest for sha256:2d711642b726... $ echo >> sbom.json $ node scripts/sbom/evidence-manifest.mjs verify evidence-manifest.json sha256:2d71...bcce8 evidence: FAIL sbom.json changed since the manifest was written exit code 1 One appended byte is enough. (In your run, pass the full 64-character digest; the shortened form here is for the page.)

Illustrative session; exact output varies by tool and agency configuration.

Prove it

Run this against a small fixture project first (a package.json with one dependency and its lockfile), so the output is short enough to read.

Terminal window
npm ci
npx cyclonedx-npm --omit dev --mc-type application --of JSON --sv 1.6 -o sbom.cdx.json
node scripts/sbom/finalize-sbom.mjs sbom.cdx.json "intake build pipeline"
node scripts/sbom/verify-sbom.mjs sbom.cdx.json --pre-sign # expect PASS, exit 0

Then plant the fault. Delete one required field and run the gate again:

Terminal window
node -e 'const f="sbom.cdx.json",b=JSON.parse(require("fs").readFileSync(f));delete b.metadata.timestamp;require("fs").writeFileSync(f,JSON.stringify(b))'
node scripts/sbom/verify-sbom.mjs sbom.cdx.json --pre-sign # expect FAIL naming SBOM Timestamp, exit 1

The proof is that the failure names the field. A gate that fails with “SBOM invalid” sends the next person into the file to find out why. Then test the manifest verifier’s refusals. Each of these must exit 1; a verifier that accepts any of them can be handed a manifest that proves nothing:

Terminal window
T=$(mktemp -d); mkdir "$T/ev"
D=sha256:$(printf 'a%.0s' $(seq 64)) # a well-formed digest
echo outside > "$T/outside.txt"
H=sha256:$(sha256sum "$T/outside.txt" | cut -d' ' -f1) # the real hash of a file OUTSIDE ev/
printf '{"image":{"digest":"%s"},"files":{}}' "$D" > "$T/ev/empty.json"
printf '{"image":{"digest":"%s"},"files":{"../outside.txt":"%s"}}' "$D" "$H" > "$T/ev/traversal.json"
printf '{"image":{"digest":"%s"},"files":{"%s":"%s"}}' "$D" "$T/outside.txt" "$H" > "$T/ev/absolute.json"
ln -s ../outside.txt "$T/ev/link.txt" # a link INSIDE ev/ that points outside it
printf '{"image":{"digest":"%s"},"files":{"link.txt":"%s"}}' "$D" "$H" > "$T/ev/symlink.json"
for m in empty traversal absolute symlink; do
node scripts/sbom/evidence-manifest.mjs verify "$T/ev/$m.json" "$D" && echo "UNEXPECTED PASS: $m" || echo "refused: $m"
done

Expect four refused: lines: manifest lists no files for the empty one, is not a path inside the manifest directory for traversal and absolute, and is a symlink for the last. The hashes are correct on purpose, so only the path checks can stop them. The symlink case is the one a purely lexical check misses: link.txt looks like it sits inside ev/, and only the lstat/realpath check sees where it leads. Remove a check from verify and its line must turn into UNEXPECTED PASS.

Then run the same four commands on the real application, and expect to find components with no declared license: handle each as an upstream fix, a reviewed override, or an exception with an owner and an expiry.

ℹStatus checked 2026-11-04

Availability, authorization, agency approval, region support, and price are five separate facts. This box holds the dated facts for this lesson.

  • OMB M-26-05, dated January 23, 2026, rescinds M-22-18 and M-23-16; the attestation form and SBOM contract terms are optional (“may choose”); agencies keep the duty to maintain a software and hardware inventory. Source: OMB M-26-05.
  • CISA 2026 Minimum Elements for an SBOM, published July 29, 2026: 17 data fields, of which 10 are new compared with the 2021 list. Read from the FBI-hosted copy of the joint product, not from cisa.gov: Minimum Elements.
  • NIST SP 800-218 version 1.1 (February 2022) is the current final Secure Software Development Framework; Rev. 1 is an initial public draft (December 17, 2025; comment period closed January 30, 2026). Sources: SP 800-218 and Rev. 1 draft.
  • Tool: @cyclonedx/cyclonedx-npm (the exact pin is in the install command above), Apache-2.0, checked on 2026-11-04 on npm and via its --help; its default CycloneDX spec version is 1.6. Source: CycloneDX Node module and tool list.

Recheck the cited source and your agency’s authorization boundary before you rely on any of it.

KNOWLEDGE CHECK

Your agency has not asked for SBOMs, and OMB M-26-05 makes SBOM requests optional for agencies. What is the strongest reason to keep generating one in the pipeline?

KNOWLEDGE CHECK

verify-sbom fails because one dependency has no declared license. What is the right fix?

Practice status — how established each pattern is across agencies and contractors

PracticeStatusAlso called
SBOM generated per buildcommon baselineSBOM at build
Failing the build on missing minimum elementsemergingSBOM completeness gate, SBOM linting
Evidence hashed and bound to the image digeststrong optionalevidence manifest, release evidence bundle
Signed SBOMstrong optionalSBOM attestation
Providing an SBOM on request under M-26-05strong optionalSBOM-on-request contract term

Note: the last row is an agency choice under M-26-05, not a mandate; the signed-SBOM row means a signature checked with a verify command, which this lesson’s gate does not do.

Scale: required | common baseline | strong optional | reference-shop (seen only at organizations that publish their own practice) | emerging

Key takeaway

The SBOM is a build output, and the gate is what makes it trustworthy. Generate it from the lockfile-resolved install, add the fields the generator cannot know, fail the build naming any missing minimum element, and tie the file to the image digest so the evidence describes one specific build. M-26-05 makes the request optional for agencies; the pipeline makes the answer cheap.

LEADERSHIP DECISION
Treat the SBOM and its evidence manifest as standing pipeline outputs, so an agency request is answered from the last build.
PRACTITIONER ACTION
Add the generate, finalize, verify and manifest steps to the pipeline and run the delete-a-field test once.
SUCCESS MEASURE
Calendar time: an SBOM request is answered from the release artifact in minutes instead of a manual lockfile review.

Legend: LEADERSHIP DECISION = what a leader decides · PRACTITIONER ACTION = what the engineer does next · SUCCESS MEASURE = how you know, in calendar time, assessor-hours or cost, contract or revenue risk, or audit finding avoided

Search lessons