🚧 DevGuard & this page is under active development. Visit the DevGuard Repo →
How-to GuidesScanningUpload SBOM

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"

Replace sbom.json with the path to your SBOM file. Only CycloneDX-formatted SBOMs (JSON or XML) are supported.

Replace myorg/projects/myproject/assets/myrepo with your repository’s slug. You can copy this from the URL when viewing your repository in the DevGuard UI.

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.

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"

The origin flag helps you track which tools or systems generated your SBOMs. This is useful when you have multiple SBOMs from different sources for the same project.

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

These flags help DevGuard track which branch or tag the scan is associated with. DevGuard will attempt to auto-detect Git information from the current directory if these flags are not specified.

Scan with GitLab CIUpload VEX