SBOM and Dependency Scanning Workflow: Track Open-Source Risk Across Releases

Overview

A software bill of materials, or SBOM, is an inventory of the components included in a software product. Depending on the project, those components may come from language package managers, operating-system packages, build tools, plugins, or container base images. An SBOM does not make software safe by itself. Its value comes from connecting component inventory with vulnerability and license analysis, release records, and an owner who can act on the findings.

The most reliable approach is to scan at more than one stage. Scan dependency manifests during pull requests so developers receive feedback before a change is merged. Scan the resolved dependency set after installation or compilation so the result reflects what the build actually uses. If the application is shipped as a container, generate or collect an SBOM for the image and scan the image separately. Finally, retain the SBOM and scan results with the release artifact.

Use a format your tools and downstream users can process consistently. CycloneDX and SPDX are common choices, but the practical decision is less about selecting a fashionable format and more about choosing one that records package identifiers, versions, relationships, licenses where available, and enough metadata to connect the document to a commit or release. Record the format and generator version in the project documentation so future comparisons remain meaningful.

This workflow fits hosted repositories and self-hosted CI/CD systems. Teams using a self-hosted CI/CD runner should pay particular attention to runner permissions, network access, and where reports are stored. Teams that deploy directly from Git can connect the same checks to their repository-to-deployment workflow.

Checklist by scenario

1. Pull request or merge request scanning

• Identify every supported package manifest and lockfile in the repository.
• Run a scanner against the manifest and lockfile, not only against source-code text.
• Use lockfiles where the ecosystem supports them so the check evaluates resolved versions.
• Report the dependency path that introduces a finding, including whether it is direct or transitive.
• Set a clear failure rule, such as blocking a new high-confidence, high-severity issue while allowing existing findings to be tracked separately.
• Make the result visible in the pull request and link to the remediation guidance or issue.

Pull-request checks should be fast enough to support normal development. They are best used for change detection: what did this contribution add, upgrade, or remove? A separate scheduled scan can identify newly disclosed vulnerabilities in unchanged dependencies.

2. Main-branch and scheduled scanning

• Scan the default branch after dependency installation or build resolution.
• Schedule a recurring scan because vulnerability databases and affected-version ranges change independently of repository commits.
• Compare results with the previous successful run to distinguish new findings from an existing backlog.
• Export machine-readable results as well as a concise human-readable summary.
• Create or update a ticket with the affected component, reachable package path when available, severity, evidence, owner, and target review date.

Do not assume that a clean pull request means the branch will remain clean. A new advisory can affect a version already present in production. Scheduled scanning closes that gap.

3. Container image scanning

• Build the image using the same Dockerfile and build arguments used for release candidates.
• Generate an SBOM from the image or from the build process, depending on the capabilities of the selected tool.
• Scan operating-system packages as well as application dependencies embedded in the image.
• Record the image digest, base image reference, source commit, build timestamp, and scanner or generator version.
• Run the check before pushing a release image and, where practical, rescan stored images on a schedule.

Manifest scanning and image scanning answer different questions. A manifest can show intended application dependencies, while an image scan can reveal packages introduced by the base image, build environment, or runtime layer. Use both when containers are part of the delivery path.

4. Release and artifact storage

• Generate an SBOM for the exact artifact being released rather than for a nearby development build.
• Store the SBOM beside the release artifact with a stable filename and documented format.
• Keep the scan result, tool configuration, commit identifier, and artifact digest together.
• Restrict modification rights for release evidence and define how long it should be retained.
• Make the artifact discoverable to maintainers, incident responders, and approved downstream users.

Evidence is useful only when it can be found and interpreted later. A repository maintenance process should include the release records and security findings alongside issues, change notes, and ownership. The open-source repository maintenance checklist provides a useful companion process for that broader work.

Tool-selection table

Choose based on coverage and workflow fit rather than the number of integrations listed on a product page. Test representative repositories, including private packages, monorepos, generated code, multiple lockfiles, and the final production image.

What to double-check

Severity and exploitability

Severity is a prioritization input, not a complete risk decision. Confirm the affected component and version, whether the vulnerable code is present in the shipped artifact, whether the affected function is reachable in your deployment, and whether a fixed version is available. A critical label may deserve immediate review, but a lower-severity issue in an exposed service can also require prompt action.

Define actions for each severity band before the first finding appears. For example, a team might require immediate triage for the highest category, a planned upgrade for lower categories, and documented acceptance for findings that cannot currently be remediated. The exact thresholds should reflect the application, exposure, and release process.

Direct versus transitive dependencies

Direct dependencies can usually be upgraded by changing a manifest. Transitive dependencies may require upgrading a parent package, changing resolution constraints, or waiting for an upstream fix. Ask the scanner to show the dependency path and verify that the proposed remediation does not introduce incompatible changes.

License findings

Keep license review distinct from vulnerability review, even when one tool reports both. Confirm the detected license against package metadata and project notices, then apply the project’s documented policy. Unknown or conflicting metadata should lead to human review, not an automatic conclusion.

False positives, exceptions, and suppression

Every exception should include a reason, owner, scope, expiration or review date, and reference to the evidence considered. Prefer narrow suppressions tied to a package version, image, or finding identifier. Avoid repository-wide exclusions that hide future occurrences of the same issue.

Reproducibility and provenance

Check that CI uses the intended lockfile, registry configuration, build arguments, and base image. If development and production resolve different dependency sets, scan both where the difference affects risk. For repeatable local environments, connect the pipeline configuration with a documented development setup such as the Dev Containers workflow.

Common mistakes

• Generating an SBOM only once: An inventory becomes stale when dependencies, images, or vulnerability intelligence change. Generate it for each release and rescan on a schedule.
• Scanning only manifests: This can miss operating-system packages and dependencies installed during image construction. Inspect the shipped image when containers are involved.
• Blocking every finding immediately: A hard gate without baseline handling can encourage rushed suppressions. Establish a process for new findings, existing findings, and documented exceptions.
• Ignoring failed or incomplete scans: A tool error is not the same as a clean result. Make unavailable data visible and decide whether the affected stage should fail closed or require manual approval.
• Storing reports without context: An SBOM without a commit, image digest, format, or generator version is difficult to trust during later review.
• Assigning findings to nobody: Security teams can coordinate the process, but the owner of the dependency or service should have a clear remediation responsibility.
• Treating an upgrade as automatically safe: Test the fix, review its dependency changes, and verify that the resulting artifact is the one that will be deployed.

When to revisit

Review this workflow before seasonal planning cycles, after a major change to the CI/CD platform, and whenever the project adds a package ecosystem, container image, deployment target, or private registry. Revisit it after changing scanner configuration, SBOM format, vulnerability data sources, retention rules, or release approvals.

Maintainers should also check the workflow for every dependency update, release, and newly reported vulnerability. A practical monthly review can confirm that scanners still support the repository’s package managers, databases are updating as expected, scheduled jobs are succeeding, exceptions have not expired unnoticed, and stored reports can still be retrieved.

Before the next release, use this short action list:

1. List the manifests, lockfiles, build outputs, and container images included in the release.
2. Run dependency and image scans against the exact release candidate.
3. Generate the chosen SBOM format and verify its component count and metadata.
4. Review new vulnerability and license findings, including dependency paths and available fixes.
5. Assign owners and due dates, or document narrowly scoped exceptions with review dates.
6. Store the SBOM and scan evidence with the release artifact and record the commit or image digest.
7. Confirm that the next scheduled scan and alert path are enabled.

For API-heavy projects, keep the dependency workflow alongside the specification and testing process described in this OpenAPI documentation workflow. For deployment teams, pair it with a documented self-hosted CI/CD pipeline so security checks remain part of delivery rather than a separate manual task. The result is a repeatable record of what was shipped, what was found, and who is responsible for the next decision.