vg sbom

Overview

The vg sbom command family provides supply-chain evidence — Software Bill of Materials (SBOM) export, dependency deltas, and OpenVEX exploitability statements — for compliance, audit, and supply chain security workflows.

Usage

# Export SBOM from scan artifact
vg sbom export [options]

# Compare dependencies between two scans
vg sbom delta --from <file> --to <file> [options]

# Generate an OpenVEX document
vg sbom vex [options]

sbom export

Options

Supported Formats

Examples

# Export CycloneDX SBOM
vg sbom export --format cyclonedx --out sbom.cdx.json

# Export SPDX SBOM
vg sbom export --format spdx --out sbom.spdx.json

# Export from specific artifact
vg sbom export --in ./archive/scan-q1.json --out sbom-q1.cdx.json

Component identity

Match a component on its package URL (purl). That string is the primary identity in vg sbom export. vg scan --format json and .vibgrate/scan_result.json use the same coordinates and do not repeat the purl string.

projects[].type is the project kind (java, node, python). The vulnerability block uses the advisory ecosystem (maven, npm, pypi). vg sbom export turns those coordinates into the purl type (pkg:maven, pkg:npm, pkg:pypi).

These documents have no CPE field. The CLI does not write one, including when a name has several segments (a Maven group:artifact, an npm scope, a Go module path). A missing CPE is the normal record. Leave it missing. If a file from another cataloger carries a cpe property, keep the purl as the identity you match. A CPE does not replace a purl, rank above it, or stand in for a purl that was omitted.

When a name cannot be a package URL, the component stays in the SBOM and purl is omitted. CycloneDX sets vibgrate:purlStatus to unavailable. That row still has no CPE.

Local advisory matching uses the same coordinates. vg scan --vulns --offline --package-manifest package-versions.json reads vulns under the ecosystem and the package name in that file. Matches land on extended.vulnerabilities.packages[]. Join an advisory of your own on the purl, or on ecosystem + package name + version.

vg scan --vulns --offline --package-manifest package-versions.json --format json --out scan.json
vg sbom export --in scan.json --format cyclonedx --out sbom.cdx.json

For com.google.code.gson:gson at 2.11.0 in a Java project, read these fields. They are shown together so the join is visible. vg writes them in scan.json and sbom.cdx.json, not in one object. The advisory object is present when --vulns records a match for that package.

{
  "scanDependency": {
    "projectType": "java",
    "package": "com.google.code.gson:gson",
    "resolvedVersion": "2.11.0"
  },
  "scanAdvisory": {
    "ecosystem": "maven",
    "package": "com.google.code.gson:gson",
    "version": "2.11.0"
  },
  "cyclonedx": {
    "name": "com.google.code.gson:gson",
    "version": "2.11.0",
    "purl": "pkg:maven/com.google.code.gson/gson@2.11.0",
    "bom-ref": "pkg:maven/com.google.code.gson/gson@2.11.0"
  }
}

Key the join on pkg:maven/com.google.code.gson/gson@2.11.0, or on maven + com.google.code.gson:gson + 2.11.0. The group com.google.code.gson is the purl namespace. SPDX stores the same purl on externalRefs[].referenceLocator.

sbom delta

Options

Example

vg sbom delta \
  --from .vibgrate/baseline.json \
  --to .vibgrate/scan_result.json \
  --out dependency-changes.json

Delta Output

{
  "summary": {
    "added": 5,
    "removed": 2,
    "changed": 12,
    "driftDelta": -8
  },
  "changes": [
    {
      "package": "lodash",
      "type": "upgraded",
      "from": "4.17.19",
      "to": "4.17.21"
    },
    {
      "package": "moment",
      "type": "removed",
      "note": "Replaced with date-fns"
    }
  ]
}

sbom vex

Generate a spec-compliant OpenVEX document stating the exploitability of components, ready to attach as a signed attestation. The generator is input-agnostic — it assembles a complete document from the statements you supply, so it works regardless of which scanner flagged the components. A zero-statement document is valid and honest: it asserts no known affected components.

Options

Example

# Generate VEX and attest it to a signed image
vg sbom vex --product "$IMAGE_REF" \
  --statement '{"vulnerability":"CVE-2024-1","status":"not_affected","justification":"vulnerable_code_not_present"}' \
  --out openvex.json
cosign attest --yes --type openvex --predicate openvex.json "$IMAGE_REF"

Use Cases

Integrations

Dependency-Track

# Export and upload to Dependency-Track
vg sbom export --format cyclonedx --out sbom.cdx.json
curl -X POST "https://dtrack.example.com/api/v1/bom" \
  -H "X-Api-Key: $DTRACK_API_KEY" \
  -F "bom=@sbom.cdx.json"

Grype Vulnerability Scanning

# Export and scan with Grype
vg sbom export --format spdx --out sbom.spdx.json
grype sbom:sbom.spdx.json

Related Commands

• vg scan — Generate scan artifacts
• vg baseline — Create baseline for delta comparison
• Supply Chain Security — Security best practices