DockSec

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 advanced AI to provide context-aware security analysis.

Instead of overwhelming you with a list of 200+ CVEs, DockSec:

• Prioritizes what actually affects your specific container setup.
• Explains vulnerabilities in plain English, not just security jargon.
• Suggests specific, line-by-line fixes for your Dockerfile.
• Generates professional, interactive security reports for your team.

Think of it as having a security expert sitting right next to you, reviewing your Dockerfiles in real-time.

DockSec workflow: From scanning to actionable insights

DockSec follows a robust four-stage pipeline:

1. Scan: Runs Trivy, Hadolint, and Docker Scout locally on your environment.
2. Analyze: AI correlates findings across all scanners to remove noise and assess real-world impact.
3. Recommend: Generates human-readable explanations and specific remediation steps.
4. Report: Exports actionable results in JSON, PDF, HTML, or Markdown formats.

DockSec is led by a dedicated team committed to making container security accessible.

• Advait Patel - Project Lead
• Arkadii Yakovets - Project Co-lead

For questions or discussions, please join the #project-docksec channel on OWASP Slack.

Integrate DockSec into your GitHub Actions workflow:

- name: Run DockSec AI Scanner
  uses: OWASP/DockSec@main
  with:
    dockerfile: 'Dockerfile'
    openai_api_key: ${{ secrets.OPENAI_API_KEY }}

# Install DockSec
pip install docksec

# Scan a Dockerfile (AI-powered)
# Reports will be saved to ~/.docksec/results/
docksec Dockerfile

# Scan Dockerfile + Docker image
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 scan only (no AI)
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

# 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

# Reduce output to warnings, errors, and the result summary
docksec Dockerfile --scan-only --quiet

# Disable colored output (also honors the NO_COLOR env var)
docksec Dockerfile --no-color

Every scan ends with a result summary: a severity table, the security score with a rating, a "Quick take" action block, the generated reports, and a suggested next command. Use --quiet for a compact result and --no-color for plain output.

--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 (info, warnings, errors) 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@main
  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-on causes DockSec to exit non-zero, losing the findings exactly when they matter most.

--sarif is independent of --format: it always writes a .sarif file regardless of which report formats you've selected, since it targets CI/Code Scanning rather than local reading.

--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 (e.g. after triaging and deciding to defer a finding).

DockSec uses CI-friendly exit codes so builds and shells can react to results:

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

• Smart Analysis: AI explains what vulnerabilities mean for your specific setup.
• Multi-LLM Support: Use OpenAI, Anthropic Claude (4.x), Google Gemini (1.5+), or local models via Ollama.
• Docker Compose Scanning: Detect orchestration-level misconfigurations and scan all services in a compose file.
• Deep Integration: Combines Trivy (vulnerabilities), Hadolint (linting), and Docker Scout.
• Security Scoring: Get a 0-100 score to track your security posture over time.
• Centralized Reporting: All reports are neatly organized in ~/.docksec/results/ by default.
• Rich Formats: Professional exports in HTML (interactive), PDF, JSON, and CSV.
• CI/CD Ready: Designed for easy integration into GitHub Actions and build pipelines.
• GitHub Action: Available on the GitHub Marketplace for automated security scans.

Here is a comparison of how DockSec relates to other container security tools.

DockSec is the only one of these that pairs contextual, line level Dockerfile remediation with a fully open source, OWASP governed, locally runnable design. Snyk and Aikido offer capable AI remediation, but only as commercial cloud platforms that send your data to their service. Trivy is open source and local but stops at detection and does not help you fix anything. DockSec fills the gap for developers and for regulated or air gapped teams who need both the fix guidance and full control of their data, at no cost.

DockSec thrives on community contributions. Whether you are a developer, designer, or security enthusiast, there are many ways to get involved:

• Code Contributions: Fix bugs or add new features.
• Documentation: Improve guides or create tutorials.
• Issue Reporting: Identify and report bugs.
• Feedback: Share your experience and suggestions.

To get started, check out our Contributing Guidelines, Code of Conduct, and Sponsorship Guide.

• OWASP Project Page: owasp.org/DockSec/
• OWASP Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• Issues: Report a bug