DockerScan v2.0

June 11, 2026 · View on GitHub

DockerScan Logo

DockerScan v2.0

The Most Comprehensive Docker Security Scanner

License Go Version Version CI/CD Test Coverage Go Report Card Downloads

By Daniel Garcia (cr0hn) | GitHub | Website

Features • Installation • Quick Start • Documentation • Use Cases • What's New • Contributing

📑 Table of Contents

🎯 Overview

DockerScan v2.0 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.0?

  • ✅ 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
  • ✅ Free & Open Source: BSD-3 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.0?

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

Major Changes

Featurev1.x (Python)v2.0 (Go)
LanguagePython 3.5+Go 1.21+
Performance~500 images/hour~5000 images/hour
Memory Usage200-500 MB50-100 MB
Distributionpip install + depsSingle binary
Security Scanners2 modules5 modules
CIS BenchmarkPartialFull v1.7.0 (80+ checks)
Supply Chain❌ Not available✅ Based on 2024 research
Secret Patterns10 patterns40+ patterns
CVE DetectionBasic2024-2025 CVEs
Runtime Security❌ Not available✅ Full capabilities audit
SARIF Output❌ Not available✅ Full support
CI/CD IntegrationManualNative (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

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"

# 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:

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.

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 }}

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

FeatureDockerScan v2.0TrivyClairSnykGrype
CIS Benchmark v1.7✅ Full (80+ checks)❌❌Partial❌
Supply Chain Detection (2024)✅ Yes❌❌❌❌
Secrets Scanning✅ 40+ patternsBasic❌✅❌
CVE Database✅ 2024-2025 CVEs✅✅✅✅
Runtime Security✅ Full❌❌❌❌
SARIF Output✅✅❌✅✅
Speed (Go)⚡ Very Fast⚡ Very Fast🐌 Slow⚡ Fast⚡ Very Fast
Extensible✅ Plugin systemLimitedLimited❌Limited
Exit Codes✅ CI/CD ready✅Partial✅✅
Cost🆓 Free🆓 Free🆓 Free💰 Paid tiers🆓 Free
Offline Mode✅✅❌❌✅
LicenseProprietary Source-AvailableApache-2.0Apache-2.0ProprietaryApache-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 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.

Database Features

  • 🗄️ Pre-built database - Ready to use, no manual setup required
  • 🔄 Daily updates - GitHub Action updates the database every day at 00:00 UTC
  • 📅 2.5 years of CVE data - Covers CVEs from mid-2022 to present
  • ⚡ Fast lookups - SQLite with optimized indexes
  • 🌐 Hosted on GitHub - Downloaded automatically with 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)

For advanced users, you can build the CVE database from NVD directly:

# Build the tool
make build  # Builds both dockerscan and nvd2sqlite

# Download CVEs (last 2.5 years by default)
./bin/nvd2sqlite --output data/cve-db.sqlite --verbose

# With NVD API key (10x faster - 50 req/30sec vs 5 req/30sec)
NVD_API_KEY=your-key ./bin/nvd2sqlite --output data/cve-db.sqlite --verbose

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

nvd2sqlite features:

  • ⚡ 4 parallel download workers for faster downloads
  • 🔄 Automatic retry with exponential backoff for rate limiting (HTTP 429)
  • 📦 Downloads to temp directory, then processes sequentially
  • 🗄️ SQLite output with indexed tables for fast lookups

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

Research & CVEs

Tools & Projects

📄 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

Daniel Garcia (cr0hn)

Website GitHub Twitter

Security Researcher | Open Source Developer | Docker Security Expert

🙏 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

⭐ If you find DockerScan useful, please star the repository! ⭐

Making Docker Security Accessible to Everyone

⬆ Back to Top