Table of Contents

• Overview
• Features
• What's New in v2.1.0
• What's New in v2.0
• Installation
• Quick Start
• Usage
  • Private Registry Authentication
• Security Scanners
• Output Formats
• Use Cases
• Comparison
• Architecture
• Contributing
• References
• License
• Author

[!WARNING] Versions 2.0.6 and earlier silently report zero package CVEs. A query bug made the package vulnerability check fail on every scan and discard the error, so older binaries always show 0 package CVE findings regardless of the image or the database. Upgrading to v2.1.0 or later is strongly recommended — it is the first version where package CVE detection actually works.

Overview

DockerScan v2 is a next-generation security scanner for Docker containers and images, completely rewritten in Go. It combines multiple security scanning techniques based on the latest 2024-2025 research, industry standards (CIS Benchmark, NIST SP 800-190), and real-world attack patterns discovered in production environments.

Why DockerScan v2?

• Most Comprehensive: Combines 5+ security scanning techniques in one tool
• Latest Research: Based on 2024-2025 supply chain attacks and CVEs
• Production Ready: SARIF output for CI/CD, exit codes for automation
• Blazing Fast: Written in Go with concurrent scanning
• Extensible: Plugin architecture for custom scanners
• Source-Available: Free for internal, educational, research, and non-competing commercial use (see License)

Features

Security Scanning Modules

1. CIS Docker Benchmark v1.7.0

Complete compliance checking with 80+ automated controls:

• Host configuration security (13 checks)
• Docker daemon hardening (18 checks)
• File & directory permissions (9 checks)
• Container image best practices (13 checks)
• Runtime security validation (31+ checks)
• Security operations compliance

2. Supply Chain Attack Detection

Based on real 2024 attack campaigns:

• Imageless Container Detection - Identifies malicious containers with no actual layers (4M+ found on Docker Hub)
• Cryptocurrency Miner Detection - Detects mining malware (120K+ malicious image pulls detected)
• Backdoored Library Detection - Catches compromised dependencies (xz-utils, liblzma incidents)
• Image Signature Verification - Validates signatures using Notary/Cosign
• Phishing Content Detection - Scans documentation for social engineering
• Malicious Network Destinations - Identifies C2 servers, mining pools, Tor nodes

3. Advanced Secrets Detection

40+ secret patterns including modern APIs (2024 update):

• Cloud Providers: AWS, GCP, Azure credentials
• Version Control: GitHub, GitLab, Bitbucket tokens
• AI/ML APIs: OpenAI, Anthropic, Hugging Face keys
• Payment: Stripe, PayPal, Square keys
• Communication: Slack, SendGrid, Twilio, Mailchimp
• Authentication: JWT tokens, OAuth tokens
• Crypto: Private keys (RSA, SSH, PGP, EC, DSA), certificates
• Databases: PostgreSQL, MySQL, MongoDB connection strings
• Docker: Registry authentication tokens
• Entropy Analysis: Shannon entropy calculation for unknown secrets (>4.5 threshold)

4. CVE & Vulnerability Scanning

Critical 2024-2025 CVE detection:

• CVE-2024-21626 - runc container escape (CVSS 8.6)
• CVE-2024-23651 - BuildKit cache poisoning RCE (CVSS 9.1)
• CVE-2024-23652 - BuildKit race condition (CVSS 7.5)
• CVE-2024-23653 - BuildKit privilege escalation
• CVE-2024-8695/8696 - Docker Desktop RCE (CVSS 8.8)
• CVE-2025-9074 - Docker Desktop local access vulnerability
• End-of-life base image detection
• Known vulnerable package scanning

5. Runtime Security Analysis

Container runtime hardening checks:

• Linux Capabilities Auditing - Detects dangerous capabilities (CAP_SYS_ADMIN, CAP_NET_ADMIN, etc.)
• Seccomp Profile Validation - Ensures syscall filtering is enabled
• AppArmor/SELinux Checks - Mandatory access control verification
• Privileged Container Detection - Identifies containers with full host access
• Namespace Isolation - PID, IPC, network, user namespace checks
• Container Escape Indicators - Detects common escape techniques

Reporting & Integration

• JSON - Machine-readable output for automation
• SARIF - Native integration with:
  • GitHub Security tab
  • Azure DevOps
  • VS Code extensions
  • GitLab security dashboards
• Beautiful CLI - Color-coded severity levels with emojis
• Exit Codes - CI/CD friendly (0=clean, 1=warnings, 2=critical)

Performance

• 10x Faster than Python alternatives
• Concurrent Scanning with Go goroutines
• Low Memory footprint (~50-100MB)
• Single Binary - No dependencies

What's New in v2.1.0

Version 2.1.0 (released 2026-07-13) overhauls the CVE data pipeline and package vulnerability matching:

• CVE database built from MITRE cvelistV5 - The database is now generated from the official MITRE cvelistV5 daily snapshots instead of the NVD API. No NVD API dependency, no API keys, and no rate limits.
• Package CVE detection fixed end-to-end - Package-to-CVE matching was rewritten around a dpkg-style version comparator (Debian Policy 5.6.12), with per-(vendor, product) version ranges for accurate matching.
• Vendor-verified alias matching - Matches now carry vendor_verified finding metadata. Name-only matches are flagged as such and include remediation caveats, so you can tell a vendor-verified match from a heuristic one.
• Derived fix information - FixedVersion is derived from the matched version ranges, and backport disclosure metadata (match_basis, distro_revision) is included so distro-backported fixes are not reported as vulnerable.
• Optional CVSS enrichment from NVD - A best-effort enrichment step can pull CVSS scores from the NVD API via --enrich-from-nvd, --enrich-only, and --enrich-timeout. It is non-blocking and safe to skip in CI (it never fails the build).

What's New in v2.0?

DockerScan v2.0 was a complete rewrite from the ground up. Here's what changed from v1.x:

Major Changes

Feature	v1.x (Python)	v2.0 (Go)
Language	Python 3.5+	Go 1.21+
Performance	~500 images/hour	~5000 images/hour
Memory Usage	200-500 MB	50-100 MB
Distribution	pip install + deps	Single binary
Security Scanners	2 modules	5 modules
CIS Benchmark	Partial	Full v1.7.0 (80+ checks)
Supply Chain	Not available	Based on 2024 research
Secret Patterns	10 patterns	40+ patterns
CVE Detection	Basic	2024-2025 CVEs
Runtime Security	Not available	Full capabilities audit
SARIF Output	Not available	Full support
CI/CD Integration	Manual	Native (exit codes, SARIF)

What's Preserved from v1.x

• Offensive Tools - Image trojanization capabilities (coming soon in v2.1)
• Registry Operations - Push, pull, delete operations (coming soon in v2.1)
• Network Scanning - Docker registry discovery (coming soon in v2.1)

New in v2.0.5

• Private Registry Authentication - Full support for scanning images from private registries (fixes #24)
• Multi-Registry Support - Docker Hub, GHCR, ECR, GCR, ACR, GitLab, and self-hosted registries
• Multiple Auth Methods - Environment variables (CI/CD), CLI flags (testing), Docker config file (seamless)
• Smart Auth Priority - CLI flags > ENV vars > Docker config (automatic selection)
• Enhanced Error Messages - Registry-specific hints (ECR token expiration, rate limits, certificates)
• Comprehensive Testing - 64 test cases, 91.2% coverage, tested with real private registry
• Complete Documentation - Examples for all major cloud registries and authentication methods

New in v2.0.4

• CVE Database Integration - Local SQLite database with NVD data (2.5 years of CVEs)
• Daily Auto-Updates - GitHub Action updates the CVE database every day
• Parallel CVE Downloads - 4 workers for faster database builds (nvd2sqlite)
• Retry with Backoff - Automatic retry for rate-limited NVD API requests
• --from-file flag - Install CVE database from local file (offline/air-gapped)
• Quiet mode (-q) - Suppress banner for CI/CD pipelines
• Reduced false positives - Improved secrets detection with entropy filtering

Why the Rewrite?

1. Performance - Go provides 10x faster scanning with goroutines
2. Modern Threats - Incorporates 2024-2025 attack patterns
3. Enterprise Ready - SARIF output, exit codes, single binary distribution
4. Extensibility - Clean plugin architecture for custom scanners
5. Maintainability - Type safety, better error handling, easier to contribute

Installation

Option 1: Download Pre-built Binary (Recommended)

Pre-compiled binaries are automatically built and released via GitHub Actions for every version tag.

Supported Platforms:

• Linux: amd64, arm64, 386
• macOS: amd64 (Intel), arm64 (Apple Silicon)
• Windows: amd64, arm64, 386
• FreeBSD: amd64

Linux (amd64)

curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/

Linux (arm64)

curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-arm64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/

macOS (Intel)

curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-darwin-amd64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/

macOS (Apple Silicon)

curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-darwin-arm64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/

Windows (PowerShell)

Invoke-WebRequest -Uri "https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-windows-amd64.exe" -OutFile "dockerscan.exe"

Verify Download (Optional but Recommended)

# Download checksums
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/checksums.txt -o checksums.txt

# Verify (Linux/macOS)
sha256sum -c checksums.txt --ignore-missing

Option 2: Build from Source

# Clone repository
git clone https://github.com/cr0hn/dockerscan
cd dockerscan/dockerscan-v2

# Build
make build

# Install
sudo make install

# Or build manually
go build -o bin/dockerscan ./cmd/dockerscan

Option 3: Go Install

go install github.com/cr0hn/dockerscan/v2/cmd/dockerscan@latest

Quick Start

First-Time Setup

Before scanning, download the CVE database (updated daily, ~30MB compressed):

# Download latest CVE database from GitHub
dockerscan update-db

Tip: The database is updated daily via GitHub Actions. Run update-db periodically to get the latest CVE data.

Basic Scan

# Scan a Docker image
dockerscan nginx:latest

# Scan with specific scanners
dockerscan --scanners cis,secrets ubuntu:22.04

# Scan and save reports
dockerscan alpine:latest --output /tmp/reports

# Quiet mode (suppress banner)
dockerscan -q nginx:latest

Example Output

╔══════════════════════════════════════════════════════════════════════════╗
║   ██████╗  ██████╗  ██████╗██╗  ██╗███████╗██████╗ ███████╗ ██████╗ █████╗ ███╗   ██╗
║   ██╔══██╗██╔═══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗██╔════╝██╔════╝██╔══██╗████╗  ██║
║   ██║  ██║██║   ██║██║     █████╔╝ █████╗  ██████╔╝███████╗██║     ███████║██╔██╗ ██║
║   ██║  ██║██║   ██║██║     ██╔═██╗ ██╔══╝  ██╔══██╗╚════██║██║     ██╔══██║██║╚██╗██║
║   ██████╔╝╚██████╔╝╚██████╗██║  ██╗███████╗██║  ██║███████║╚██████╗██║  ██║██║ ╚████║
║                                                                                        ║
║                Advanced Docker Security Scanner v2.0.0                                ║
║                                                                                        ║
║   Author:     Daniel Garcia (cr0hn)                                                   ║
║   Website:    https://cr0hn.com                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════╝

🔍 Scanning image: nginx:latest

═══════════════════════════════════════════════════════════════════
                         SCAN RESULTS
═══════════════════════════════════════════════════════════════════

📊 Summary:
   Total Findings: 47
   Duration: 2.3s

🔴 By Severity:
   Critical: 8
   High:     15
   Medium:   18
   Low:      6

📁 By Category:
   CIS-Benchmark:      12
   Secrets:            8
   Supply-Chain:       5
   Vulnerability:      10
   Runtime-Security:   12

📄 JSON report saved to: dockerscan-report.json
📄 SARIF report saved to: dockerscan-report.sarif

Usage

Command Line Options

dockerscan [COMMAND] [OPTIONS] <IMAGE>

Commands:
  scan        Scan a Docker image (default)
  update-db   Download or update the CVE database
              Options: --from-file <path>  Install from local SQLite file
  version     Show version information
  help        Show help message

Options:
  -h, --help              Show help message
  -v, --version           Show version
  -q, --quiet             Suppress banner output (quiet mode)
  --scanners SCANNERS     Comma-separated list of scanners to run
                          (default: all)
                          Options: cis,secrets,supplychain,vulnerabilities,runtime
  --output DIR            Output directory for reports (default: .)
  --only-critical         Show only critical/high severity findings
  --verbose, -v           Show scan progress (scanner names, findings count, image pull status). Output to stderr.
  --debug                 Show verbose output plus internal errors and technical details. Output to stderr.

Authentication (for private registries):
  --registry-user <username>       Registry username
  --registry-password <password>   Registry password (not recommended, use env vars)
  --registry <url>                 Registry URL (optional, auto-detected from image)
  --docker-config <path>           Path to Docker config file (default: ~/.docker/config.json)

  Environment variables (recommended for CI/CD):
    DOCKER_USERNAME or REGISTRY_USERNAME     Registry username
    DOCKER_PASSWORD or REGISTRY_PASSWORD     Registry password or token
    DOCKER_REGISTRY or REGISTRY             Registry URL (optional)

Exit Codes:
  0   No issues found
  1   HIGH severity issues found
  2   CRITICAL severity found

Examples

# Scan with all scanners (default)
dockerscan myapp:latest

# Only run specific scanners
dockerscan --scanners secrets,supplychain redis:7

# Save reports to specific directory
dockerscan --output /var/reports postgres:14

# Only show critical issues
dockerscan --only-critical production-app:v1.0

# Ver progreso del scan (scanner names, findings count, image pull status)
dockerscan --verbose ubuntu:22.04

# Debug detallado (errores internos, detalles técnicos)
dockerscan --debug ubuntu:22.04

# Scan private registry images (see Authentication section below)
dockerscan ghcr.io/myorg/private-app:v1.0

Private Registry Authentication

DockerScan supports three methods for authenticating with private registries:

Method 1: Docker Config File (Recommended for Local Use)

The most convenient method - uses your existing Docker credentials:

# First, authenticate with your registry using Docker
docker login ghcr.io
# Username: your-username
# Password: ghp_your-token-here

# Now DockerScan can use these credentials automatically
dockerscan ghcr.io/myorg/private-app:latest

DockerScan automatically reads credentials from ~/.docker/config.json. This works with all registries you've logged into with docker login.

Credential helpers are fully supported. DockerScan natively resolves credentials through:

• credsStore — global credential helper (e.g. osxkeychain on macOS with Docker Desktop, wincred on Windows, pass on Linux)
• credHelpers — per-registry credential helpers (takes precedence over credsStore)
• Automatic fallback — if the specified helper binary is not installed, DockerScan falls back to the plaintext auths block in config.json

On macOS with Docker Desktop, this works out of the box with no extra configuration:

{
  "credsStore": "osxkeychain"
}

DockerScan will call docker-credential-osxkeychain transparently to retrieve tokens, so you never need to pass credentials explicitly.

Method 2: Environment Variables (Recommended for CI/CD)

Best for automated environments and CI/CD pipelines:

# Set environment variables
export DOCKER_USERNAME=myusername
export DOCKER_PASSWORD=mytoken

# Scan private image
dockerscan ghcr.io/myorg/private-app:latest

# Or use alternative variable names
export REGISTRY_USERNAME=myusername
export REGISTRY_PASSWORD=mytoken
dockerscan myregistry.example.com/app:v1.0

CI/CD Example (GitHub Actions):

- name: Scan private image
  env:
    DOCKER_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
    DOCKER_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
  run: dockerscan ghcr.io/${{ github.repository }}:${{ github.sha }}

Method 3: Command-Line Flags (Not Recommended)

For quick testing only (credentials visible in process list):

dockerscan --registry-user myuser --registry-password mytoken ghcr.io/myorg/app:v1

Security Warning: This method exposes credentials in your shell history and process list. Use environment variables or Docker config instead.

Registry-Specific Examples

Docker Hub (Private Repositories)

# Using Docker config
docker login docker.io
dockerscan myusername/private-repo:latest

# Using environment variables
export DOCKER_USERNAME=myusername
export DOCKER_PASSWORD=dckr_pat_XXXXXXXXXXXXX
dockerscan myusername/private-repo:latest

GitHub Container Registry (GHCR)

# Using Docker config
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
dockerscan ghcr.io/myorg/myapp:v1.0

# Using environment variables
export DOCKER_USERNAME=myusername
export DOCKER_PASSWORD=ghp_XXXXXXXXXXXXXXXXXXXX
dockerscan ghcr.io/myorg/myapp:v1.0

AWS Elastic Container Registry (ECR)

# Get login credentials from AWS
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

# Scan ECR image
dockerscan 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

# Or use environment variables with ECR credentials
export DOCKER_USERNAME=AWS
export DOCKER_PASSWORD=$(aws ecr get-login-password --region us-east-1)
dockerscan 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

Google Container Registry (GCR) / Artifact Registry

# Authenticate with gcloud
gcloud auth configure-docker gcr.io

# Scan GCR image
dockerscan gcr.io/my-project/myapp:latest

# For Artifact Registry
gcloud auth configure-docker us-docker.pkg.dev
dockerscan us-docker.pkg.dev/my-project/my-repo/myapp:latest

# Or use service account JSON key
export DOCKER_USERNAME=_json_key
export DOCKER_PASSWORD="$(cat service-account-key.json)"
dockerscan gcr.io/my-project/myapp:latest

Azure Container Registry (ACR)

# Login with Azure CLI
az acr login --name myregistry

# Scan ACR image
dockerscan myregistry.azurecr.io/myapp:v1.0

# Or use service principal credentials
export DOCKER_USERNAME=<service-principal-id>
export DOCKER_PASSWORD=<service-principal-password>
dockerscan myregistry.azurecr.io/myapp:v1.0

GitLab Container Registry

# Using Docker config
docker login registry.gitlab.com
dockerscan registry.gitlab.com/mygroup/myproject/myapp:latest

# Using environment variables with deploy token
export DOCKER_USERNAME=gitlab+deploy-token-1
export DOCKER_PASSWORD=DEPLOY_TOKEN_HERE
dockerscan registry.gitlab.com/mygroup/myproject/myapp:latest

Self-Hosted/Private Registries

# Standard authentication
docker login myregistry.example.com:5000
dockerscan myregistry.example.com:5000/myapp:latest

# With environment variables
export DOCKER_USERNAME=admin
export DOCKER_PASSWORD=secret
dockerscan myregistry.example.com:5000/myapp:latest

# Insecure registries (not recommended for production)
# Add to Docker daemon config: /etc/docker/daemon.json
# {
#   "insecure-registries": ["myregistry.example.com:5000"]
# }

Troubleshooting Authentication

Common Issues

1. "authentication required" error

# Make sure you're logged in
docker login <registry>

# Or set environment variables
export DOCKER_USERNAME=your-username
export DOCKER_PASSWORD=your-token

2. "unauthorized: authentication failed" error

• Verify your credentials are correct
• Check if your token has expired (especially for cloud providers)
• Ensure your account has pull permissions for the image

3. AWS ECR "authorization token has expired"

# ECR tokens expire after 12 hours - refresh them
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

4. Rate limiting on Docker Hub

• Authenticate to increase rate limits (200 pulls/6 hours for free accounts)
• Consider using a Docker Hub Pro account for higher limits

5. Certificate errors with self-signed certificates

• Add the CA certificate to your system trust store
• Or configure Docker to trust the registry (see Docker documentation)

Security Scanners

CIS Docker Benchmark

Automated compliance checking against CIS Docker Benchmark v1.7.0:

dockerscan --scanners cis nginx:latest

Checks include:

• Container user is not root
• No unnecessary packages installed
• HEALTHCHECK instruction present
• Specific version tags (not :latest)
• Minimal exposed ports
• No privileged containers
• Linux capabilities restricted
• Seccomp/AppArmor profiles applied
• Read-only root filesystem
• And 70+ more checks...

Supply Chain Security

Detect real-world supply chain attacks:

dockerscan --scanners supplychain suspicious-image:1.0

Detects:

• Imageless containers (documentation-only attacks)
• Cryptocurrency miners (xmrig, claymore, etc.)
• Backdoored libraries (xz-utils case)
• Unsigned/unverified images
• Phishing attempts in docs
• Connections to mining pools, C2 servers

Secrets Detection

Find hardcoded secrets:

dockerscan --scanners secrets webapp:prod

Finds:

• Cloud credentials (AWS, GCP, Azure)
• API keys (40+ services)
• Private keys and certificates
• Database credentials
• Docker registry auth
• High-entropy strings (potential unknown secrets)

Vulnerability Scanning

Detect known CVEs:

dockerscan --scanners vulnerabilities node:16

Checks for:

• Critical Docker CVEs (2024-2025)
• Container escape vulnerabilities
• BuildKit RCE vulnerabilities
• End-of-life base images
• Vulnerable packages

Runtime Security

Audit runtime configurations:

dockerscan --scanners runtime running-container

Analyzes:

• Linux capabilities (CAP_SYS_ADMIN, etc.)
• Seccomp profiles
• AppArmor/SELinux policies
• Namespace isolation
• Privileged mode usage

Output Formats

JSON Output

{
  "target": {
    "image_name": "nginx:latest"
  },
  "start_time": "2024-11-22T10:30:00Z",
  "findings": [
    {
      "id": "CIS-4.1",
      "title": "Container should not run as root",
      "severity": "HIGH",
      "category": "CIS-Benchmark",
      "description": "Running containers as root increases attack surface...",
      "remediation": "Use USER instruction in Dockerfile..."
    }
  ],
  "summary": {
    "total_findings": 47,
    "by_severity": {
      "CRITICAL": 8,
      "HIGH": 15
    }
  }
}

SARIF Output

Compatible with GitHub Security, Azure DevOps, VS Code:

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "DockerScan",
          "version": "2.0.0"
        }
      },
      "results": [...]
    }
  ]
}

Use Cases

1. CI/CD Pipeline Integration

GitHub Actions:

name: Docker Security Scan

on: [push]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Install DockerScan
        run: |
          curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -o dockerscan
          chmod +x dockerscan

      - name: Update CVE Database
        run: ./dockerscan update-db

      - name: Run Security Scan
        run: ./dockerscan -q myapp:${{ github.sha }}

      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: dockerscan-report.sarif

GitLab CI:

docker-security-scan:
  stage: test
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - wget https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -O dockerscan
    - chmod +x dockerscan
    - ./dockerscan update-db
    - ./dockerscan -q $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  artifacts:
    reports:
      sast: dockerscan-report.sarif

2. Security Audits

# Comprehensive audit of production images
for image in $(docker images --format "{{.Repository}}:{{.Tag}}"); do
  echo "Scanning $image..."
  dockerscan $image --output /audit-reports/
done

# Generate summary report
cat /audit-reports/*.json | jq -s '
  {
    total_images: length,
    total_findings: map(.summary.total_findings) | add,
    critical_findings: map(.summary.by_severity.CRITICAL // 0) | add
  }
'

3. Pre-deployment Validation

# Fail deployment if critical issues found
dockerscan production-app:v2.0
exit_code=$?

if [ $exit_code -eq 2 ]; then
  echo "❌ Critical vulnerabilities found. Deployment blocked."
  exit 1
elif [ $exit_code -eq 1 ]; then
  echo "⚠️  High severity issues found. Manual review required."
  # Send notification...
else
  echo "✅ No critical issues. Proceeding with deployment."
fi

4. Compliance Reporting

# Generate CIS compliance report
dockerscan --scanners cis --only-critical all-production-images:* > cis-compliance-report.txt

# Weekly security scan for compliance
0 0 * * 0 /usr/local/bin/dockerscan --scanners cis,vulnerabilities production-images:latest --output /compliance/weekly/

5. Developer Workflow

# Pre-commit hook
#!/bin/bash
# .git/hooks/pre-commit

docker build -t local-test:latest .
dockerscan --only-critical local-test:latest

if [ $? -ne 0 ]; then
  echo "❌ Docker security scan failed. Fix issues before committing."
  exit 1
fi

Comparison with Other Tools

Feature	DockerScan v2.0	Trivy	Clair	Snyk	Grype
CIS Benchmark v1.7	Full (80+ checks)	No	No	Partial	No
Supply Chain Detection (2024)	Yes	No	No	No	No
Secrets Scanning	40+ patterns	Basic	No	Yes	No
CVE Database	2024-2025 CVEs	Yes	Yes	Yes	Yes
Runtime Security	Full	No	No	No	No
SARIF Output	Yes	Yes	No	Yes	Yes
Speed (Go)	Very Fast	Very Fast	Slow	Fast	Very Fast
Extensible	Plugin system	Limited	Limited	No	Limited
Exit Codes	CI/CD ready	Yes	Partial	Yes	Yes
Cost	Free	Free	Free	Paid tiers	Free
Offline Mode	Yes	Yes	No	No	Yes
License	Proprietary Source-Available	Apache-2.0	Apache-2.0	Proprietary	Apache-2.0

Why Choose DockerScan?

• Most Comprehensive: Only tool combining CIS + Supply Chain + Secrets + CVE + Runtime
• Latest Research: Based on 2024-2025 real-world attacks
• Zero Configuration: Works out of the box
• Developer Friendly: Beautiful CLI output with actionable remediation
• Enterprise Ready: SARIF + exit codes + JSON output

Architecture

Project Structure

dockerscan/
├── logo.png                 # Project logo
├── cmd/
│   ├── dockerscan/          # Main CLI application
│   │   └── main.go
│   └── nvd2sqlite/          # CVE database builder tool
│       └── main.go
├── data/                    # CVE database (auto-updated daily)
│   ├── latest.db.gz         # Compressed SQLite database
│   └── metadata.json        # Database version info
├── internal/
│   ├── scanner/             # Extensible scanner framework
│   │   ├── scanner.go       # Scanner interface & registry
│   │   ├── cis/             # CIS Benchmark implementation
│   │   ├── secrets/         # Secrets detection
│   │   ├── supplychain/     # Supply chain attacks
│   │   ├── vulnerabilities/ # CVE scanning
│   │   └── runtime/         # Runtime security
│   ├── report/              # Report generators
│   │   ├── json.go          # JSON reporter
│   │   └── sarif.go         # SARIF reporter
│   ├── models/              # Data models
│   │   └── models.go        # Findings, scan results, etc.
│   └── config/              # Configuration
│       └── config.go        # App config & banner
└── pkg/docker/              # Docker client wrapper
    └── client.go

CVE Database & nvd2sqlite-cvelistV5 Tool

DockerScan uses a local SQLite database for CVE lookups. The database is automatically updated daily via GitHub Actions and hosted in the repository, so you always have access to the latest CVE data.

The database is built from the MITRE cvelistV5 dataset (the official CVE List, published as a daily snapshot on GitHub). Unlike the NVD API, this source has no rate limits, no API keys and no availability problems: the full snapshot is a single ~525 MB zip served by GitHub's CDN.

Database Features

• Pre-built database - Ready to use, no manual setup required
• Daily updates - A GitHub Action rebuilds the full database every day at 06:47 UTC from the MITRE cvelistV5 midnight snapshot
• 30-month window - ~125,000 CVEs and ~432,000 affected-product rows (schema_version 2)
• Fast lookups - SQLite with optimized indexes
• Hosted on GitHub - Downloaded automatically with the update-db command

Updating the Database

# Download latest database from GitHub (recommended)
dockerscan update-db

# Install from local file (for air-gapped/offline environments)
dockerscan update-db --from-file /path/to/cve-db.sqlite

Note: The first time you run dockerscan, it will prompt you to download the database. After that, you can update it periodically with update-db.

Building the Database Manually (nvd2sqlite-cvelistV5)

For advanced users, you can build the CVE database from the MITRE cvelistV5 snapshot directly:

# Build the tool
go build -o bin/nvd2sqlite-cvelistV5 ./cmd/nvd2sqlite-cvelistV5

# Download the latest snapshot and build the database (last 30 months by default)
./bin/nvd2sqlite-cvelistV5 --output data/cve-db.sqlite --verbose

# Optionally enrich CVSS scores from the NVD API (best-effort, non-blocking)
./bin/nvd2sqlite-cvelistV5 --output data/cve-db.sqlite --enrich-from-nvd

# Custom date range
./bin/nvd2sqlite-cvelistV5 --output data/cve-db.sqlite \
  --start-date 2023-01-01 \
  --end-date 2024-12-31

# From an already-downloaded snapshot zip (offline / air-gapped)
./bin/nvd2sqlite-cvelistV5 --output data/cve-db.sqlite \
  --input 2026-07-13_all_CVEs_at_midnight.zip.zip

nvd2sqlite-cvelistV5 features:

• No API keys, no rate limits - single zip download from GitHub's CDN
• Parallel parsing - one worker per CPU core, ~300k CVE records in minutes
• Version-range normalization - free-text CNA ranges (>=1.0, <2.0, comma lists, v prefixes) converted to proper ranges
• Optional CVSS enrichment - best-effort NVD lookup via --enrich-from-nvd / --enrich-only / --enrich-timeout
• SQLite output with indexed tables for fast lookups

Deprecated: the previous cmd/nvd2sqlite tool (NVD API 2.0 source) is kept for reference but is no longer used or maintained. The NVD API's rate limits and frequent 503s/timeouts made daily automated builds unreliable.

Extensibility

Adding a new scanner is simple:

package myscan

import (
    "context"
    "github.com/cr0hn/dockerscan/v2/internal/models"
    "github.com/cr0hn/dockerscan/v2/internal/scanner"
)

type MyScanner struct {
    scanner.BaseScanner
}

func NewMyScanner() *MyScanner {
    return &MyScanner{
        BaseScanner: scanner.NewBaseScanner(
            "my-scanner",
            "Description of my scanner",
            true, // enabled
        ),
    }
}

func (s *MyScanner) Scan(ctx context.Context, target models.ScanTarget) ([]models.Finding, error) {
    var findings []models.Finding

    // Your scanning logic here...

    return findings, nil
}

// Register in main.go:
// registry.Register(myscan.NewMyScanner())

Contributing

Contributions are welcome! DockerScan is designed to be extensible.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-scanner)
3. Add your scanner in internal/scanner/
4. Write tests (we maintain 90%+ coverage)
5. Commit your changes (git commit -am 'Add amazing scanner')
6. Push to the branch (git push origin feature/amazing-scanner)
7. Open a Pull Request

Development

# Clone and setup
git clone https://github.com/cr0hn/dockerscan
cd dockerscan/dockerscan-v2

# Install dependencies
make deps

# Run tests
make test

# Run with coverage
make coverage

# Build
make build

# Format code
make fmt

# Lint
make lint

Adding New Scanners

We especially welcome:

• Integration with vulnerability databases (NVD, GitHub Security Advisories)
• Kubernetes security scanning
• Container registry security
• Docker Compose security analysis
• IaC scanning (Dockerfiles)

References

Standards & Benchmarks

• CIS Docker Benchmark v1.7.0 - Center for Internet Security
• NIST SP 800-190 - Application Container Security Guide
• OWASP Docker Security Cheat Sheet

Research & CVEs

• 4M Malicious Imageless Containers - The Hacker News, April 2024
• Supply Chain Attacks Using Container Images - Aqua Security
• CVE-2024-21626: runc Container Escape - NIST NVD
• CVE-2024-23651: BuildKit RCE - NIST NVD
• xz-utils Backdoor (March 2024) - OpenWall

Tools & Projects

• Trivy - Vulnerability scanner
• Docker Bench Security - CIS benchmark script
• Cosign - Container signing and verification
• SARIF Specification - Static Analysis Results Format

---

License

This project is licensed under the DockerScan Proprietary Source-Available License.

What This Means

You CAN (Free of Charge):

• Use DockerScan for free for internal security scanning
• Use it in your CI/CD pipelines and security workflows
• Modify, fork, and contribute back to the community
• Use it for educational and research purposes
• Use it as a tool in professional services (consulting, security audits, pentesting)
• Integrate it into other products where it's an ancillary component

You CANNOT (without express written permission or commercial license):

• Offer Docker scanning as a commercial SaaS
• Sell hosted instances of DockerScan
• Build a commercial platform primarily based on DockerScan
• Create a paid managed service where DockerScan is the primary offering

Why This License?

This license protects the project's sustainability by:

• Granting freedom to use the software for legitimate purposes
• Preventing harmful free-riding where companies profit from offering it as a service without contributing back
• Ensuring the project remains sustainable through commercial licensing for competing uses
• Keeping the source code available for transparency and community contributions

This is NOT open source - it's source-available with restrictions on commercial competitive use.

Commercial Licensing

Required for:

• SaaS or hosted offerings
• Commercial platforms using DockerScan as a primary feature
• Reselling or redistributing as a commercial product
• Managed services where DockerScan is the core offering

Contact for commercial licensing:

Email: cr0hn [at] cr0hn.com Website: https://cr0hn.com Flexible licensing terms available for enterprise and startups

See the LICENSE file for complete legal terms.

Author

Acknowledgments

Special thanks to:

• The Docker security community
• CIS for the Docker Benchmark
• NIST for SP 800-190
• Security researchers who discovered the 2024 supply chain attacks
• All contributors and users of DockerScan

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Report vulnerabilities to cr0hn@cr0hn.com

---