Loading repository data…
OWASP / repository
AI-powered Docker security scanner that explains vulnerabilities in plain English. An OWASP Lab Project.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
AI-powered Docker security scanner that explains vulnerabilities in plain English
DockSec is an OWASP Lab Project that bridges the gap between complex security scan results and actionable developer fixes. It integrates industry-standard scanners (Trivy, Hadolint, Docker Scout) with AI to provide context-aware security analysis.
Instead of overwhelming you with a list of 200+ CVEs, DockSec:
Everything scans locally; the only thing that ever leaves your machine is the (secret-redacted) file content sent to the AI provider you choose - and with a local model or scan-only mode, nothing leaves at all. See Data flow and privacy.
DockSec follows a four-stage pipeline:
DockSec orchestrates local scanners, so it needs:
| Requirement | Needed for | Install |
|---|---|---|
| Python 3.12+ | DockSec itself | python.org |
| Trivy | All scans (required) | brew install trivy or Trivy docs |
| Hadolint | Dockerfile linting | brew install hadolint or Hadolint docs |
| Docker | Image scans (-i) | Docker docs |
Or let DockSec install Trivy and Hadolint for you:
python -m docksec.setup_external_tools
# Full install with AI analysis support (recommended)
pip install "docksec[ai]"
# Or the slim, scan-only core (no LLM dependencies, no API key needed)
pip install docksec
No API key needed for local scanning:
docksec Dockerfile --scan-only
Every scan ends with a result summary: a severity table, a 0-100 security score with a
rating, a "Quick take" action block, the generated reports (saved to
~/.docksec/results/ by default), and a suggested next command.
AI analysis explains findings and suggests fixes. Pick a provider, set its API key, and run:
# OpenAI (default provider)
export OPENAI_API_KEY="sk-..."
docksec Dockerfile
# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
docksec Dockerfile --ai-only --provider anthropic --model claude-sonnet-5
# Google Gemini
export GOOGLE_API_KEY="..."
docksec Dockerfile --ai-only --provider google
# Ollama (fully local, no API key, data never leaves your machine)
docksec Dockerfile --ai-only --provider ollama --model llama3.1
Each provider has a sensible default model (OpenAI: gpt-4o, Anthropic:
claude-haiku-4-5, Google: gemini-1.5-pro, Ollama: llama3.1), so --model is
optional. To avoid repeating flags, set environment variables (or put them in a .env
file in the directory you run from - DockSec loads it automatically):
export LLM_PROVIDER=anthropic
export LLM_MODEL=claude-sonnet-5
docksec Dockerfile
Before any content is sent to an AI provider, secret-looking values (passwords, tokens, API keys, private key blocks) are masked automatically. See Data flow and privacy.
- name: Run DockSec AI Scanner
uses: OWASP/DockSec@v2026.7.5
with:
dockerfile: 'Dockerfile'
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
# Scan Dockerfile + Docker image (AI + scanners)
docksec Dockerfile -i myapp:latest
# Scan a Docker Compose file and all its services
docksec --compose docker-compose.yml
# Scan only a Docker image
docksec --image-only -i myapp:latest
# Fast local scan, no AI, no API key
docksec Dockerfile --scan-only
# Choose which severity levels the image scan reports (default: CRITICAL,HIGH)
docksec -i myapp:latest --image-only --severity CRITICAL,HIGH,MEDIUM
# Fail the build (exit 1) if any finding is HIGH or above
docksec -i myapp:latest --image-only --fail-on high
# Write only the report formats you want, to a directory of your choice
docksec Dockerfile --scan-only --format json,html --output-dir ./reports
# Print results as JSON to stdout for scripts and CI pipelines
docksec -i myapp:latest --image-only --json
# Write a SARIF report for GitHub Code Scanning
docksec Dockerfile --scan-only --sarif
# Write a CycloneDX SBOM of an image for supply-chain tooling
docksec --image-only -i myapp:latest --sbom
# Fully offline scan: local Trivy DB, no network, no AI
docksec --image-only -i myapp:latest --offline
# Save today's findings as a baseline, then only gate on new findings later
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high
# Suppress triaged findings with an auditable ignore file
docksec -i myapp:latest --image-only --ignore-file .docksec-ignore.yml
# Force a fresh scan, bypassing the results cache
docksec -i myapp:latest --image-only --no-cache
# Install AI-assistant skill files (Claude Code, Cursor, Copilot, and more)
docksec install-skill
# Output control
docksec Dockerfile --scan-only --quiet # warnings, errors, summary only
docksec Dockerfile --scan-only --verbose # INFO-level diagnostics on stderr
docksec Dockerfile --scan-only --verbose --log-file logs/docksec.log
docksec Dockerfile --no-color # also honors NO_COLOR
DockSec uses CI-friendly exit codes so builds and shells can react to results:
| Code | Meaning |
|---|---|
0 | Success, no findings at or above --fail-on |
1 | Findings at or above the --fail-on threshold |
2 | Usage or argument error |
3 | Tool or runtime error (scan failed, image not found, missing tools) |
--fail-on gates on the structured findings (image vulnerabilities and compose
misconfigurations). When --fail-on is below the requested --severity, the scan
severity is widened automatically so the gate can observe those findings.
--json prints a single JSON object to stdout (scan info, vulnerabilities, severity
counts, and any AI findings) instead of the human-readable summary, so it can be piped
straight into other tools:
docksec -i myapp:latest --image-only --json | jq '.severity_counts'
With --json alone, no report files are written; combine it with --format to write
files and print JSON in the same run. All human-readable messages move to stderr in
--json mode, so stdout only ever contains the JSON payload.
--sarif writes a SARIF 2.1.0 report alongside the other report formats. Upload it
with the standard github/codeql-action/upload-sarif action to see findings annotated
directly on pull requests and in the Security tab:
- name: Run DockSec
uses: OWASP/DockSec@v2026.7.5
with:
dockerfile: 'Dockerfile'
sarif: 'true'
- name: Upload SARIF to GitHub Code Scanning
uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: ~/.docksec/results
if: always()is important: without it, the upload step is skipped whenever--fail-oncauses DockSec to exit non-zero, losing the findings exactly when they matter most.
--baseline FILE lets you adopt --fail-on on an existing project without a wall of
pre-existing findings blocking every build. Run once with --update-baseline to snapshot
today's findings, then commit the baseline file; from then on, --fail-on only gates on
findings that aren't already in the baseline:
# Snapshot current findings (does not gate)
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline
# Later runs only fail on NEW findings above the threshold
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high
Findings are matched by vulnerability ID, target, and package name, so the baseline stays
valid as unrelated findings come and go. Re-run with --update-baseline whenever you want
to accept the current state as the new baseline.
--ignore-file FILE suppresses individual findings a team has triaged and accepted.
Unlike the baseline (a point-in-time snapshot), the ignore file is an explicit,
reviewable list where every entry carries a reason and an optional expiry date.
If a .docksec-ignore.yml file exists in the current directory, it
Selected from shared topics, language and repository description—not editorial ratings.
Bazil-27 /
AI-Powered DevSecOps Security Scanner — Automatically detects secrets, Docker CVEs, and vulnerabilities using Python, Trivy, and Groq AI
49/100 health