Skip to main content

Generate an SBOM and audit dependencies

Generate a project SBOM and audit dependencies against selected vulnerability sources. Inspect the findings and export a SARIF report.

User Guides

An SBOM is an inventory of software components that you can attach to a release or share with the security team. It shows third-party packages and helps match dependencies to vulnerability reports. CodeGraph exports CycloneDX or SPDX inventories and produces audit reports in JSON, SARIF, Markdown or GOST format.

Start with the inventory: generate the file, inspect component names and versions, and retain it with the source revision. Then run the audit and triage its findings before updating dependencies. The command reads project dependency files and matches package versions against the selected sources. A security reviewer triages the findings for the release configuration.

Prerequisites and complete example

Install Python 3.11 or later and CodeGraph dependencies using the prerequisites in the CLI guide. This example uses PowerShell and a source checkout for local development. Start in the CodeGraph repository root. Use a new sbom-demo directory; the commands create example files.

$env:PYTHONPATH = (Get-Location).Path
New-Item -ItemType Directory -Path sbom-demo
@'
{
  "name": "sbom-demo",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "packages": {
    "": {"name": "sbom-demo", "version": "1.0.0"},
    "node_modules/lodash": {"version": "4.17.20"}
  }
}
'@ | Set-Content sbom-demo/package-lock.json -Encoding utf8
Set-Content sbom-demo/config.yaml "security:`n  local_cli_enabled: true" -Encoding utf8
Push-Location sbom-demo
try {
  python -m src.cli sbom generate --format cyclonedx --output sbom.json
  $sbom = Get-Content sbom.json -Raw | ConvertFrom-Json
  $sbom.components | Select-Object name, version
  Get-FileHash sbom.json -Algorithm SHA256
} finally {
  Pop-Location
}

Expected output: SBOM written to sbom.json (cyclonedx, 1 components). The file sbom-demo/sbom.json contains bomFormat: CycloneDX, specVersion: 1.5, and a lodash component with version 4.17.20 and bom-ref: pkg:lodash@4.17.20. This is a teaching lockfile with a fixed version; use the lockfile from the revision being checked for your own project. You do not need to install the package: the command reads its dependency declaration. security.local_cli_enabled enables the CLI for local development. Without it, the CLI reports that it is disabled and stops before generation. After the command, check the created file and its contents.

Generate the inventory

python -m src.cli sbom generate --project "<project>" --format cyclonedx --output "<sbom.json>"

Replace <project> with a registered project name and <sbom.json> with the output path. Keep quotes around values containing spaces. Without --project, the command scans the current directory. If the project name cannot be resolved, the implementation also uses the current directory. Check which source files it contains before running the command.

Format choices are --format {cyclonedx,spdx}; the default is cyclonedx. Retain the source revision, command, output file, and SHA-256 digest. No dependencies found. returns 0 without creating an SBOM. Check the directory and dependency file formats: the command includes components from the files it recognizes.

Audit vulnerabilities

sbom audit scans the selected project manifests again and checks the resulting dependency graph through the chosen sources. Generate the SBOM and run the audit against the same revision to match components to findings.

python -m src.cli sbom audit `
  --project "<project>" `
  --format sarif `
  --fail-on high `
  --output "<sca.sarif>"

Audit the directory from the complete example and inspect the findings:

Push-Location sbom-demo
try {
  python -m src.cli sbom audit --sources osv --format sarif --fail-on high --output sca.sarif
  $report = Get-Content sca.sarif -Raw | ConvertFrom-Json
  $report.runs[0].results | Select-Object ruleId, level
  $report.runs[0].tool.driver.rules | Select-Object id, properties
} finally {
  Pop-Location
}

Report formats are --format {sarif,json,markdown,gost}; the default is json. Set sources with --sources osv,nvd,bdu_fstec; the default is osv. --fail-on {critical,high,medium,low} returns 1 when a finding reaches or exceeds the selected severity. No severity threshold applies when this option is omitted. Findings with unknown severity stay in the report and are excluded from the --fail-on threshold comparison. In SARIF, inspect tool.driver.rules[].properties.severity and match each rule to results[].ruleId. Review those findings against the source advisory to assign severity and choose a fix. Exit code 2 indicates an error handled by the command. Check the report file, its contents, and source error messages before using the result in CI.

python -m src.cli sbom sync --sources osv,nvd,bdu_fstec records a synchronization marker for the listed sources and prints local cache statistics. Vulnerability lookups run through sbom audit. Retain the report, source messages and check time with the project revision; if a source fails, restore access and repeat the audit.

Retrieve results through the REST API

Project-scoped SCA operations are under /api/v1/security/sca. Check the REST reference of your deployed CodeGraph instance for exact operations and request schemas. See the dependency analysis scenario for registered-project preparation and the principal routes.

Triage

  1. Confirm package name, version, ecosystem, and dependency path.
  2. Check advisory source and cache freshness.
  3. Assess whether the vulnerable code is reachable in the deployed profile.
  4. Prefer an upgrade or removal; document compensating controls and expiry for exceptions.
  5. Regenerate both SBOM and audit evidence after remediation.
Report a documentation issue