cr0hn/dockerscanThe Most Comprehensive Docker Security Scanner
<div align="center">
<img src="https://assets.kitploit.com/production/public/readmes/1309/3345979faae1cdabbe2912dfcaf46221df5cb53697630a8e8dcc5eebf814e949.png" alt="DockerScan Logo" width="200">
# DockerScan v2.0
### *The Most Comprehensive Docker Security Scanner*
[](LICENSE)
[](https://golang.org/)
[](https://github.com/cr0hn/dockerscan/releases)
[](https://github.com/cr0hn/dockerscan/actions/workflows/dockerscan.yml)
[](https://github.com/cr0hn/dockerscan)
[](https://goreportcard.com/report/github.com/cr0hn/dockerscan)
[](https://github.com/cr0hn/dockerscan/releases)
**By [Daniel Garcia (cr0hn)](https://cr0hn.com)** | [GitHub](https://github.com/cr0hn/dockerscan) | [Website](https://cr0hn.com)
---
[Features](#-features) •
[Installation](#-installation) •
[Quick Start](#-quick-start) •
[Documentation](#-documentation) •
[Use Cases](#-use-cases) •
[What's New](#-whats-new-in-v20) •
[Contributing](#-contributing)
</div>
---
## 📑 Table of Contents
- [Overview](#-overview)
- [Features](#-features)
- [What's New in v2.0](#-whats-new-in-v20)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Usage](#-usage)
- [Private Registry Authentication](#-private-registry-authentication)
- [Security Scanners](#-security-scanners)
- [Output Formats](#-output-formats)
- [Use Cases](#-use-cases)
- [Comparison](#-comparison-with-other-tools)
- [Architecture](#-architecture)
- [Contributing](#-contributing)
- [References](#-references)
- [License](#-license)
- [Author](#-author)
---
## 🎯 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
| 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)
```bash
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)
```bash
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)
```bash
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)
```bash
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)
```powershell
Invoke-WebRequest -Uri "https://github.com/cr0hn/dockerscan/releases/latest/download/dockerscan-windows-amd64.exe" -OutFile "dockerscan.exe"
```
#### Verify Download (Optional but Recommended)
```bash
# 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
```bash
# 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
```bash
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):
```bash
# 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
```bash
# 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
```bash
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
```bash
# 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:
```bash
# 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:
```json
{
"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:
```bash
# 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):**
```yaml
- 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):
```bash
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)
```bash
# 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)
```bash
# 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)
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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**
```bash
# 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"**
```bash
# 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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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
```json
{
"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:
```json
{
"$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:**
```yaml
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:**
```yaml
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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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) | ❌ | ❌ | 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 |
### 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
```bash
# Download latest database from GitHub (recommended)
dockerscan update-db
```
---
[Read more](https://github.com/cr0hn/dockerscan)