Dock Sec

Abstract

1. Introduction

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.

Everything scans locally. When enabled, DockSec sends only the data required for EPSS lookups or AI analysis, with secrets redacted before AI requests. With a local model, scan-only mode, or offline mode, no scan data leaves your machine. See Data flow and privacy.

DockSec workflow: from scanning to actionable insights

2. Objective

AI-powered Docker security scanner that explains vulnerabilities in plain English. An OWASP Lab Project.

This project demonstrates how Python can be applied to a real-world Cybersecurity & Ethical Hacking problem.

3. Key Features / Modules

• Smart Analysis: AI explains what vulnerabilities mean for your specific setup.
• Multi-LLM Support: OpenAI, Anthropic Claude, Google Gemini, or local models via Ollama.
• Privacy First: Secret values are redacted before any content reaches an AI provider, scanning is fully local, and there is no telemetry.
• 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: A 0-100 score with a rating to track your security posture over time.
• Rich Formats: HTML (interactive), PDF, JSON, CSV, SARIF, and CycloneDX SBOM.
• CI/CD Ready: --fail-on exit codes, baseline/ratchet mode, auditable waivers, JSON-to-stdout, and a GitHub Action on the Marketplace.
• Offline Mode: Scan fully air-gapped (--offline) using the local Trivy database.
• AI-Assistant Skills: docksec install-skill teaches Claude Code, Cursor, Copilot, and others how to run DockSec in your repo.

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Python 3.8 or later
• pip / virtualenv for dependencies
• VS Code, PyCharm or Jupyter Notebook
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/OWASP/DockSec.git
cd DockSec

1. .claude/commands/docksec.md (Claude Code slash command /docksec)
2. .cursor/rules/docksec.mdc (Cursor)
3. AGENTS.md (Codex CLI), GEMINI.md (Gemini CLI)
4. .github/copilot-instructions.md (GitHub Copilot)

# 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

docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_DOCKERFILE=Dockerfile \
  -e INPUT_SCAN_ONLY=true \
  ghcr.io/owasp/docksec:latest

docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_DOCKERFILE=Dockerfile \
  -e INPUT_SCAN_ONLY=true \
  owasp/docksec:latest

gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add logging and alert notifications (email / Telegram)
• Write a threat model document for the tool
• Package it with Docker for safe lab testing

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which threat or attack does this project defend against?
2. What detection or protection technique is used and what are its limits?
3. How are false positives and false negatives handled?
4. Which cryptographic algorithms or security standards are involved?
5. What legal and ethical rules apply when testing a tool like this?

9. Source Code & License

This project is developed by OWASP and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.