Quickstart

In a GitHub workflow (recommended)

The most common way to run bomdrift is the composite Action — drop it into a pull_request workflow and let the action handle checkout, Syft install, SBOM generation, diffing, and PR-comment posting:

# .github/workflows/sbom-diff.yml
name: SBOM diff
on: pull_request
permissions:
  contents: read
  pull-requests: write       # to upsert the diff comment
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: Metbcy/bomdrift@v1
        # Optional:
        # with:
        #   fail-on: critical-cve   # exit 2 on HIGH/CRITICAL advisories
        #   path: services/api      # scan a monorepo subdirectory

The @v1 mutable tag tracks the latest v0.x release. Pin to a specific version (@v0.9.9) if you prefer reproducible builds. See GitHub Action for every input.

If you prefer a checked-in policy file, install the binary and run bomdrift init once. It writes .bomdrift.toml plus the SBOM-diff and comment-suppression workflows, so future policy tweaks happen in TOML instead of workflow YAML.

Locally with the binary

Three install paths are supported.

Via cargo (v0.9.9+)

cargo install --locked bomdrift
bomdrift --version

Via Docker / OCI (v0.9.9+)

docker run --rm ghcr.io/metbcy/bomdrift:latest --version
# Pin to a specific version for reproducible CI:
docker run --rm ghcr.io/metbcy/bomdrift:v0.9.9 --version

The image is multi-arch (linux/amd64, linux/arm64), distroless (gcr.io/distroless/cc-debian13:nonroot), and runs as a non-root user. Verify the inline SLSA attestation with gh attestation verify --owner Metbcy oci://ghcr.io/metbcy/bomdrift:v0.9.9.

Via release archive (cosign-signed)

Pre-built binaries cover Linux x86_64 + aarch64, macOS aarch64, and Windows x86_64. Each archive is cosign-signed via Sigstore + GitHub OIDC and ships a SLSA build provenance attestation (v0.9.9+).

VERSION=v0.9.9
TARGET=x86_64-unknown-linux-gnu
curl -sSL -o bomdrift.tar.gz \
  "https://github.com/Metbcy/bomdrift/releases/download/${VERSION}/bomdrift-${VERSION}-${TARGET}.tar.gz"
tar -xzf bomdrift.tar.gz
./bomdrift-${VERSION}-${TARGET}/bomdrift --version

# Diff two SBOMs
./bomdrift-${VERSION}-${TARGET}/bomdrift diff before.json after.json

# Emit SARIF to a file (no fragile YAML > redirection)
./bomdrift-${VERSION}-${TARGET}/bomdrift diff before.json after.json \
    --output sarif --output-file bomdrift.sarif

To verify the archive’s signature before you trust the binary, see Release signing.

From source

cargo install --locked --git https://github.com/Metbcy/bomdrift --tag v0.9.9 bomdrift

Requires Rust 1.85+ (the project uses edition 2024). Prefer cargo install bomdrift (above) unless you specifically want to track an unreleased commit.

First diff

The repository ships four runnable example scenarios under examples/. After cloning + cargo build --release:

./target/release/bomdrift diff \
  examples/axios-incident/before.json \
  examples/axios-incident/after.json \
  --no-osv --no-maintainer-age

The output is GitHub-Flavored Markdown ready for PR-comment posting.

What’s next?

Wire it up: GitHub Action · GitLab CI · Bitbucket · Azure DevOps.
Reference: CLI reference · every flag with introduced-in annotations · Output formats · SARIF + Code Scanning.
Suppress noise: Baseline & suppression lets a team adopt bomdrift on a project with pre-existing findings without drowning the first PR.
License gating: License policy — SPDX expression evaluation with allow/deny + per-exception granularity.
VEX: VEX — record exploitability decisions in OpenVEX 0.2.0 / CycloneDX VEX 1.6, suppress on subsequent diffs.
Advanced (v0.9.6+): OCI attestation · Plugins for custom rules.
Internals: Architecture · Contributing.

Keyboard shortcuts

bomdrift