Scan OCI Images

Scan container images for known vulnerabilities and generate a Software Bill of Materials (SBOM).

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

Scan Container Images

docker run ghcr.io/l3montree-dev/devguard/scanner:main-latest \
  devguard-scanner container-scanning \
    --image ghcr.io/org/image:tag \
    --assetName="myorg/projects/myproject/assets/myrepo" \
    --apiUrl="https://api.devguard.org" \
    --token="YOUR_TOKEN"

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

docker run ghcr.io/l3montree-dev/devguard/scanner:main-latest \
  sh -c "devguard-scanner login -u USERNAME -p PASSWORD registry.example.com && \
  devguard-scanner container-scanning \
    --image registry.example.com/org/image:tag \
    --assetName='myorg/projects/myproject/assets/myrepo' \
    --apiUrl='https://api.devguard.org' \
    --token='YOUR_TOKEN'"

What the Scanner Does

1. Generates SBOM: Creates a complete inventory of all software components in your container
2. Discovers Attestations: Automatically extracts relevant attestations (e.g., VEX documents) from base images
3. Uploads Data: Sends the SBOM and discovered attestations to DevGuard
4. Server-Side Scanning: DevGuard analyzes all components against its vulnerability database and returns results

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

CI/CD Integration

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

• GitHub Actions: See Scan with GitHub Actions for setup instructions
• GitLab CI: See Scan with GitLab CI for setup instructions

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)

Skip attestation discovery from the container image:

--ignoreUpstreamAttestations  # Ignores attestations from the scanned container image

Ignore external references in attestations:

--ignoreExternalReferences  # Ignores external links in VEX documents

Specify an artifact name (useful for tracking multiple artifacts like a oci image with a CLI and one with the App per repository):

--artifactName="pkg:oci/orgSlug/projectSlug/repoSlug"  # Default is "pkg:oci/{orgSlug}/{projectSlug}/{repoSlug}"

Set a custom origin to track scan source:

--origin="my-custom-origin"  # Default is "DEFAULT"

Specify Git reference information:

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