Upload SBOM

Upload an existing Software Bill of Materials (SBOM) to DevGuard for vulnerability analysis. This is useful when you already have an SBOM generated by another tool and want DevGuard to scan it against known vulnerabilities.

Prerequisites

Before you begin, ensure you have:

  • Docker installed on your system
  • A personal access token from DevGuard (create one in user settings)
  • A repository created in DevGuard
  • An existing SBOM file in CycloneDX format (JSON)

Upload SBOM File

Upload a CycloneDX SBOM file for vulnerability analysis:

docker run -v "$(PWD):/dev/app" ghcr.io/l3montree-dev/devguard/scanner:main-latest \
  devguard-scanner sbom \
    /dev/app/sbom.json \
    --assetName="myorg/projects/myproject/assets/myrepo" \
    --apiUrl="https://api.devguard.org" \
    --token="YOUR_TOKEN"

What the Scanner Does

  1. Parses SBOM: Reads and validates your CycloneDX SBOM file
  2. Scans Components: Analyzes all software components listed in the SBOM
  3. Checks Vulnerabilities: Cross-references each component against DevGuard's vulnerability database
  4. Reports Findings: Returns detected vulnerabilities with severity scores and remediation guidance
  5. Updates Repository: Syncs findings with your DevGuard repository for tracking

Verify it worked: Navigate to your repository in DevGuard. You'll see detected vulnerabilities listed with affected components and fix recommendations.

Scan Without Authentication

You can upload an SBOM and scan it without a token or asset name to get vulnerability results without saving them to DevGuard.

docker run -v "$(PWD):/dev/app" ghcr.io/l3montree-dev/devguard/scanner:main-latest \
  devguard-scanner sbom /dev/app/sbom.json

When no --token and --assetName are provided, the scanner will print a warning and return results without persisting them:

Warning: You are scanning without saving the results. Provide --token and --assetName to save results to DevGuard.

Merge and Scan Multiple SBOMs

Use merge-sboms to combine multiple CycloneDX SBOMs and pipe the result directly into the sbom command for scanning. Pass - as the file argument to read from stdin:

devguard-scanner merge-sboms config.json | devguard-scanner sbom -

The merge config file specifies the target purl and the list of SBOM files to merge:

{ "purl": "pkg:foo/bar@1.2.3", "sboms": ["a.json", "b.json"] }

To save the merged scan results to DevGuard, add authentication flags:

devguard-scanner merge-sboms config.json | devguard-scanner sbom - \
  --assetName="myorg/projects/myproject/assets/myrepo" \
  --token="YOUR_TOKEN"

CI/CD Integration

For automated SBOM uploads in CI/CD pipelines, DevGuard provides ready-to-use integrations:

Advanced Options

Fail the command based on risk level:

--failOnRisk=critical  # Options: low, medium, high, critical (default: critical)
--failOnCVSS=critical  # Options: low, medium, high, critical (default: critical)

Specify which artifact this SBOM represents:

--artifactName="pkg:devguard/orgSlug/projectSlug/repoSlug"  # Default is based on your asset

Set a custom origin to track where the SBOM came from:

--origin="sbom-file-upload"  # Default is "sbom-file-upload"

Specify Git reference information:

--ref="v1.2.3"                 # Git reference (branch, tag, or commit)
--defaultRef="main"            # Default Git reference to use
--isTag=true                   # Indicates if the reference is a tag