The Build Ships Its Own SBOM and Evidence
Updated
IntermediateWhat 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:
| Flag | What it does | Why it is here |
|---|---|---|
--omit dev | Leaves development-only packages out of the tree | The SBOM describes what ships, not what built it |
--mc-type application | Marks the main component as an application | The root component is the app, not a library |
--of JSON | Output format | The gate parses JSON |
-o <file> | Output file | Written into the evidence directory |
--sv <version> | Pins the CycloneDX spec version | The tool defaults to 1.6; pin it so a tool upgrade cannot change the format silently |
--package-lock-only | Uses only the lockfile, ignoring node_modules | An 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:
npm install --save-dev --save-exact @cyclonedx/cyclonedx-npm@6.0.1The 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 element | CycloneDX 1.6 location (this lesson’s mapping) | Who fills it |
|---|---|---|
| SBOM Author | metadata.authors[].name | finalize-sbom step |
| SBOM Author Signature | signature, or a detached <file>.sig beside it. The gate checks only that this artifact is present | The signing step |
| SBOM Data Format Name / Version | bomFormat / specVersion | Generator |
| SBOM Generation Context | metadata.lifecycles[].phase | finalize-sbom step (build) |
| SBOM Timestamp | metadata.timestamp | Generator |
| SBOM Tool Name / Version | metadata.tools.components[] | Generator |
| SBOM Version | version | Generator |
| Component Name / Version | name / version | Generator |
| Component Producer | author, supplier.name or publisher | Generator, when the package declares one |
| Component Identifiers | purl (or cpe) | Generator |
| Component License | licenses[] | Generator, when the package declares one |
| Component Hash Algorithm / Value | hashes[], or the hashes on a distribution externalReferences entry | Generator |
| Component Dependency Relationship | the component’s bom-ref appearing in dependencies[].ref | Generator |
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.mjswrites onlymetadata.authorsandmetadata.lifecycles(phase: 'build') into the CycloneDX 1.6 JSON file and does not touch any other generator output.scripts/sbom/verify-sbom.mjschecks all 17 CISA 2026 minimum elements using the CycloneDX 1.6 locations from the mapping table above, exiting1if anything is missing and0otherwise.- Each missing element prints
verify-sbom: FAIL <element name> (<where it should be>)and, for component elements, lists up to five offendingname@versionitems. - A
--pre-signflag skips only the signature check and says so in its output; without--pre-sign, the signature check verifies artifact presence (signatureor<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):
// 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.
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 stepif (!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.
// 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.
#!/usr/bin/env bashset -euo pipefailOUT=ci-out/evidenceDIGEST="$(cat ci-out/image-digest)"mkdir -p "$OUT"
# Install exactly what the lockfile says, then generate and finalize the SBOM.npm cinpx 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:
- The
ci-out/evidencefolder must have reached the deploy stage as a CI artifact; a missing manifest is a failure, not a skip. 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.- A separate assertion that the manifest’s
image.digestequals the digest inci-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
- Typed in the terminal:
claude - Mode:Plan mode
- 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.
- 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?
- 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.
- The tool replies: Wrote scripts/sbom/finalize-sbom.mjs and scripts/sbom/verify-sbom.mjs.
- 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.
- 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.
- You type in the session: Delete the license from the dependency and run the gate again. I want to see the failure name it.
- 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.
- You type in the session: Now remove metadata.timestamp instead and show me that the build stops.
- 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.
- 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.
- 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.
npm cinpx cyclonedx-npm --omit dev --mc-type application --of JSON --sv 1.6 -o sbom.cdx.jsonnode 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 0Then plant the fault. Delete one required field and run the gate again:
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 1The 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:
T=$(mktemp -d); mkdir "$T/ev"D=sha256:$(printf 'a%.0s' $(seq 64)) # a well-formed digestecho 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 itprintf '{"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"doneExpect 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.
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.
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?
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
| Practice | Status | Also called |
|---|---|---|
| SBOM generated per build | common baseline | SBOM at build |
| Failing the build on missing minimum elements | emerging | SBOM completeness gate, SBOM linting |
| Evidence hashed and bound to the image digest | strong optional | evidence manifest, release evidence bundle |
| Signed SBOM | strong optional | SBOM attestation |
| Providing an SBOM on request under M-26-05 | strong optional | SBOM-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