By Daniel Garcia (cr0hn) | GitHub | Website
Features • Installation • Quick Start • Documentation • Use Cases • What's New • Contributing
- Overview
- Features
- What's New in v2.0
- Installation
- Quick Start
- Usage
- Security Scanners
- Output Formats
- Use Cases
- Comparison
- Architecture
- Contributing
- References
- License
- Author
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.
- ✅ 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
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
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
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)
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
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
- 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)
- ⚡ 10x Faster than Python alternatives
- 🔄 Concurrent Scanning with Go goroutines
- 💾 Low Memory footprint (~50-100MB)
- 📦 Single Binary - No dependencies
DockerScan v2.0 is a complete rewrite from the ground up. Here's what changed from v1.x:
| 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) |
- ✅ 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)
- 🗄️ 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-fileflag - 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
- Performance - Go provides 10x faster scanning with goroutines
- Modern Threats - Incorporates 2024-2025 attack patterns
- Enterprise Ready - SARIF output, exit codes, single binary distribution
- Extensibility - Clean plugin architecture for custom scanners
- Maintainability - Type safety, better error handling, easier to contribute
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
curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-amd64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-linux-arm64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-darwin-amd64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/curl -L https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-darwin-arm64 -o dockerscan
chmod +x dockerscan
sudo mv dockerscan /usr/local/bin/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# 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/dockerscango install github.com/cr0hn/dockerscan/v2/cmd/dockerscan@latestBefore scanning, download the CVE database (updated daily, ~30MB compressed):
# Download latest CVE database from GitHub
dockerscan update-dbTip: The database is updated daily via GitHub Actions. Run
update-dbperiodically to get the latest CVE data.
# 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╔══════════════════════════════════════════════════════════════════════════╗
║ ██████╗ ██████╗ ██████╗██╗ ██╗███████╗██████╗ ███████╗ ██████╗ █████╗ ███╗ ██╗
║ ██╔══██╗██╔═══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗██╔════╝██╔════╝██╔══██╗████╗ ██║
║ ██║ ██║██║ ██║██║ █████╔╝ █████╗ ██████╔╝███████╗██║ ███████║██╔██╗ ██║
║ ██║ ██║██║ ██║██║ ██╔═██╗ ██╔══╝ ██╔══██╗╚════██║██║ ██╔══██║██║╚██╗██║
║ ██████╔╝╚██████╔╝╚██████╗██║ ██╗███████╗██║ ██║███████║╚██████╗██║ ██║██║ ╚████║
║ ║
║ 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
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 Verbose output
Exit Codes:
0 No issues found
1 HIGH severity issues found
2 CRITICAL severity found# 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
# Verbose mode
dockerscan --verbose ubuntu:22.04Automated compliance checking against CIS Docker Benchmark v1.7.0:
dockerscan --scanners cis nginx:latestChecks 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...
Detect real-world supply chain attacks:
dockerscan --scanners supplychain suspicious-image:1.0Detects:
- 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
Find hardcoded secrets:
dockerscan --scanners secrets webapp:prodFinds:
- Cloud credentials (AWS, GCP, Azure)
- API keys (40+ services)
- Private keys and certificates
- Database credentials
- Docker registry auth
- High-entropy strings (potential unknown secrets)
Detect known CVEs:
dockerscan --scanners vulnerabilities node:16Checks for:
- Critical Docker CVEs (2024-2025)
- Container escape vulnerabilities
- BuildKit RCE vulnerabilities
- End-of-life base images
- Vulnerable packages
Audit runtime configurations:
dockerscan --scanners runtime running-containerAnalyzes:
- Linux capabilities (CAP_SYS_ADMIN, etc.)
- Seccomp profiles
- AppArmor/SELinux policies
- Namespace isolation
- Privileged mode usage
{
"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
}
}
}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": [...]
}
]
}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.sarifGitLab 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# 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
}
'# 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# 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/# 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| Feature | DockerScan v2.0 | Trivy | Clair | Snyk | Grype |
|---|---|---|---|---|---|
| CIS Benchmark v1.7 | ✅ Full (80+ checks) | ❌ | ❌ | Partial | ❌ |
| Supply Chain Detection (2024) | ✅ Yes | ❌ | ❌ | ❌ | ❌ |
| Secrets Scanning | ✅ 40+ patterns | Basic | ❌ | ✅ | ❌ |
| CVE Database | ✅ 2024-2025 CVEs | ✅ | ✅ | ✅ | ✅ |
| Runtime Security | ✅ Full | ❌ | ❌ | ❌ | ❌ |
| SARIF Output | ✅ | ✅ | ❌ | ✅ | ✅ |
| Speed (Go) | ⚡ Very Fast | ⚡ Very Fast | 🐌 Slow | ⚡ Fast | ⚡ Very Fast |
| Extensible | ✅ Plugin system | Limited | Limited | ❌ | Limited |
| Exit Codes | ✅ CI/CD ready | ✅ | Partial | ✅ | ✅ |
| Cost | 🆓 Free | 🆓 Free | 🆓 Free | 💰 Paid tiers | 🆓 Free |
| Offline Mode | ✅ | ✅ | ❌ | ❌ | ✅ |
| License | Proprietary Source-Available | Apache-2.0 | Apache-2.0 | Proprietary | Apache-2.0 |
- 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
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
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.
- 🗄️ 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-dbcommand
# 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.sqliteNote: The first time you run
dockerscan, it will prompt you to download the database. After that, you can update it periodically withupdate-db.
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-31nvd2sqlite 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
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())Contributions are welcome! DockerScan is designed to be extensible.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-scanner) - Add your scanner in
internal/scanner/ - Write tests (we maintain 90%+ coverage)
- Commit your changes (
git commit -am 'Add amazing scanner') - Push to the branch (
git push origin feature/amazing-scanner) - Open a Pull Request
# 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 lintWe especially welcome:
- Integration with vulnerability databases (NVD, GitHub Security Advisories)
- Kubernetes security scanning
- Container registry security
- Docker Compose security analysis
- IaC scanning (Dockerfiles)
- CIS Docker Benchmark v1.7.0 - Center for Internet Security
- NIST SP 800-190 - Application Container Security Guide
- OWASP Docker Security Cheat Sheet
- 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
- Trivy - Vulnerability scanner
- Docker Bench Security - CIS benchmark script
- Cosign - Container signing and verification
- SARIF Specification - Static Analysis Results Format
This project is licensed under the DockerScan Proprietary Source-Available License.
✅ 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
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.
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.
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
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: Report vulnerabilities to cr0hn@cr0hn.com
⭐ If you find DockerScan useful, please star the repository! ⭐
Making Docker Security Accessible to Everyone