Last reviewed: 2026-09-08

Direct answer

Treat a software bill of materials as a merge artifact, not as a decorative attachment. When a coding agent changes a manifest, lockfile, build image, generated bundle, or runtime service declaration, require an SBOM for the exact candidate commit. Compare it with the trusted base, inspect the new components and relationships, run automated dependency checks, and record a human decision before merging.

The Cybersecurity and Infrastructure Security Agency SBOM guidance describes an SBOM as a nested inventory of the ingredients that make up software. That definition matters for agent-authored patches because a small source diff can add a transitive package, alter a build step, or change an external service without making the risk obvious in a code review. An SBOM makes the inventory and its provenance reviewable.

A useful gate has two inputs: the patch and the SBOM generated from that patch. The reviewer should be able to answer five questions:

  1. Does the document describe the same commit and build that will be merged?
  2. Does it include first-party code, direct dependencies, transitive dependencies, and relevant services?
  3. Does the patch explain every new or changed component and relationship?
  4. Have dependency and supply-chain checks completed with results attached to the review?
  5. Are the decision and the evidence retained so a later incident can be traced back to this merge?

Happy path. Start with a baseline SBOM from the protected branch. Ask the agent to list the dependency, build, and service surfaces it expects to touch, then generate a candidate SBOM after tests complete. Normalize both documents to the same format and compare component identifiers, versions, relationships, and completeness. Run the repository’s documented dependency-review check and retain its output with the SBOM diff. Treat the check’s result as one input, not as a substitute for inventory comparison. Run OpenSSF Scorecard or an equivalent check for newly introduced open-source projects. A human reviewer then accepts, requests a narrower patch, or holds the merge. Store the candidate SBOM beside the commit and build record.

Error path. If the SBOM is missing, cannot be tied to the candidate commit, or omits a changed component, stop the merge and ask for a regenerated artifact. If a dependency appears without a corresponding manifest or lockfile change, inspect generated files and build inputs before allowing an exception. If a vulnerability is reported, separate the fact that a component is present from the question of whether the deployed product is affected; record the analysis and any applicable VEX statement. If a check is unavailable, make the missing evidence an explicit review decision rather than silently treating it as a pass.

For a related control, pair this gate with the dependency provenance checks for coding agents . Provenance tells you where a dependency came from; the SBOM shows where it ended up in the candidate.

Use a small, sanitized event record so the workflow is auditable without copying source code or sensitive values into logs:

event: sbom_gate
repository: example/repository
commit: [COMMIT_SHA]
build_id: [BUILD_ID]
format: cyclonedx-json
component_count: 184
new_direct_components: 1
new_transitive_components: 6
dependency_review: passed
scorecard: recorded
vulnerability_status: reviewed
decision: merge

Who this is for

This workflow is for engineering leads who set merge policy, reviewers who approve agent-authored pull requests, release engineers who assemble build artifacts, and security practitioners who need a reproducible dependency inventory. It is especially useful when an agent can edit manifests, generate code, update container definitions, or invoke build tooling. Individual developers can use the same checklist on a single pull request without adopting a large platform.

The process assumes that a person remains accountable for the merge decision. Automation can generate, compare, and flag evidence, but it cannot infer the business context of a new package, decide whether an exception is acceptable, or establish that a vulnerability is irrelevant to a particular deployment.

Key takeaways

  • Generate the SBOM from the exact commit and build that reviewers will merge or ship.
  • Compare a trusted baseline with the candidate instead of inspecting the candidate in isolation.
  • Require identifiers and relationships for direct, transitive, first-party, and service components.
  • Run the repository’s documented dependency-review check and retain its result with the SBOM comparison.
  • Use Scorecard as evidence, not as a substitute for human judgment.
  • Record missing artifacts, exceptions, vulnerability analysis, and the final decision.
  • Keep the stored SBOM immutable or content-addressed so later investigations can reproduce the review.

Sources checked

The CISA Software Bill of Materials resource defines an SBOM as a nested inventory and describes its role in software security and supply-chain risk management. It also explains the relationship between SBOM data and VEX statements, which is useful when a component is present but its exploitability needs separate analysis.

The CycloneDX specification overview documents a modular, machine-readable object model for components, services, dependencies, metadata, vulnerabilities, compositions, and provenance. Its description of direct and transitive relationships supports comparing dependency graphs rather than only counting packages.

The GitHub dependency review documentation is a platform reference for dependency review in pull-request security workflows. Configure the check according to the repository’s current documentation and retain its result with the SBOM comparison.

The OpenSSF Scorecard project describes automated checks across source, build, dependencies, testing, and project maintenance. It reports scores and risk levels and can run automatically on repository changes, making it useful companion evidence when a patch adds or changes an open-source dependency.

Contract details to verify

Artifact identity. Require the repository, commit identifier, build identifier, generation tool, format, and generation time. The commit in the SBOM must match the commit under review. A document generated from a local workspace after uncommitted edits is not evidence for the pull request.

Coverage. Define what the organization means by complete. At minimum, check first-party packages, direct dependencies, transitive dependencies, generated artifacts, container layers if they are part of the release, and external services that the application calls. CycloneDX models services and dependency relationships, so use those fields when a service boundary matters to the change.

Identity quality. Prefer stable package identifiers, supplier information, version data, and provenance. A display name alone is too weak for a diff because two ecosystems can reuse the same name. When a package has no reliable identifier, mark that gap and require a reviewer decision.

Vulnerability context. A finding means that a component matches an advisory; it does not by itself prove that the deployed product is exploitable. Record the affected component, advisory reference, reachable code or feature context when known, and the rationale for remediation, mitigation, or deferral. Use a VEX statement when the project has one, and keep the statement linked to the reviewed product version.

Automation and exceptions. Add a required status check for SBOM generation and the repository’s documented dependency-review workflow. The security scan gates for pull requests provide a complementary pattern for keeping machine-generated findings attached to the review. If an exception is granted, require an owner, scope, expiration date, and replacement evidence rather than a permanent bypass.

Retention. Store the candidate SBOM, its digest, the comparison result, and the decision with the pull request or build record. Do not overwrite an older document when a branch is rebuilt. Retention is what lets an incident responder determine which components were actually present at the time of merge.

Failure modes

The document describes the wrong build. An agent may modify a lockfile, while a CI job generates an SBOM from a cached workspace. Compare the recorded commit and build identifiers before reviewing any component list. Reject mismatches.

A transitive dependency is missing. A manifest diff can look harmless while the resolver selects a new indirect package. Check that the dependency graph contains direct and transitive relationships and that the component count changes are explainable.

Generated or packaged content is outside the inventory. A source-only SBOM can omit a bundled JavaScript package, native library, or container layer. Define the release boundary and generate the inventory at the same boundary that users receive.

A name collision hides a substitution. Two packages can share a human-readable name. Require ecosystem-aware identifiers, supplier data, and version information, then investigate changes in those fields even when the display name is unchanged.

A vulnerability result is treated as a verdict. An alert can be ignored because the vulnerable feature is unreachable, or it can be missed because the component is packaged indirectly. Record the analysis, not just a green or red status, and set a deadline for unresolved findings.

A Scorecard result is over-trusted. A high score does not prove that the new package is suitable for your use case, and a low score does not identify the exact change that introduced risk. Use the individual checks to guide questions about maintenance, review, pinned dependencies, and build controls.

Evidence is lost after merge. If the SBOM is generated only as a transient CI artifact, it may expire before an incident occurs. Preserve it with the commit and record its digest in the review log.

Logs expose more than reviewers need. Avoid copying source files, full dependency paths, or unfiltered tool output into the merge record. Keep counts, identifiers, statuses, and decision fields, and link to access-controlled evidence in the repository system.

FAQ

Is an SBOM enough to approve an agent-authored patch? No. It is an inventory and transparency artifact. It should be reviewed alongside the code diff, tests, dependency policy, vulnerability analysis, and build results.

Should every pull request produce a new SBOM? Generate one whenever the patch can change dependencies, generated packages, build inputs, runtime services, or the shipped artifact. For documentation-only changes, a baseline reference may be sufficient if policy explicitly allows it.

Which SBOM format should a team choose? Choose a machine-readable standard supported by the tools that generate, compare, store, and consume it. CycloneDX is one documented option. Pin the accepted schema version and validate it in CI so format drift is visible.

What should happen when a new component has a vulnerability? First confirm the component identity and affected version. Then determine whether the vulnerable code or service is reachable in the product, consult available remediation or VEX information, and document the decision. A temporary exception needs an owner and expiration date.

Can an agent be allowed to fix a failed SBOM gate automatically? It can prepare a revision, but the revision must regenerate the SBOM from the new commit and rerun the checks. A passing rerun is evidence for review, not an automatic approval.

How do I review a dependency that has no clear provenance? Hold the merge, ask for a canonical identifier and source, and compare the resolved artifact with the lockfile and build output. If the identity cannot be established, treat the component as an unresolved supply-chain risk.

Reader next step

Pick one recent coding agent pull request that changed a dependency or build input. Generate an SBOM for the protected branch and another for the candidate commit. Compare the component and relationship sets, run your dependency review check, and record the sanitized fields shown above. Have a reviewer classify each new component as accepted, revised, or held. Then archive both documents with the pull request and add the gate to the next applicable workflow.

For the surrounding evidence process, use the source verification workflow for coding agent outputs . The immediate goal is simple: every merged agent patch that changes what you ship should leave behind an inventory that another engineer can reproduce and understand.