DockSec is an OWASP Lab project that orchestrates Trivy, Hadolint, and Docker Scout locally, then layers AI explanation and EPSS-based prioritization on top for authorized DevSecOps workflows.
| Tool | OWASP/DockSec — AI-assisted Docker security scanner that explains and prioritizes container vulnerabilities in plain English |
| Category | Container image and Dockerfile security scanning / vulnerability triage |
| Primary Use | Prioritizing CVE findings from Trivy and Hadolint via EPSS, explaining them in plain English, and generating fix suggestions and reports (HTML, SARIF, CycloneDX SBOM) for authorized CI/CD pipelines |
| Safe Use | Defensive analysis of containers you own or are authorized to assess; scans run locally, and scan-only or Ollama modes keep all data on your machine |
| Telemetry Note | Purely defensive tooling; it leaves reports under ~/.docksec/results/ and optionally calls out for EPSS lookups or AI providers, with secrets masked before any AI request |
DockSec is an OWASP Lab Project, written in Python (requiring 3.12+) and MIT-licensed, that attacks one of the most persistent problems in container security: the 200-CVE wall. Rather than producing yet another raw scanner dump, it orchestrates three established engines — Trivy for image vulnerabilities and Dockerfile misconfigurations, Hadolint for Dockerfile linting, and Docker Scout — and then applies a reasoning layer that ranks, explains, and correlates findings. With roughly 486 stars and an active build pipeline on main, it sits in the growing niche of AI-assisted triage tools that try to convert scanner output into something a developer will actually act on. The framing is unambiguously defensive: this is a DevSecOps gate for your own images and Dockerfiles, not an attack tool.
The architecture is a five-stage pipeline, and the README is unusually explicit about each stage. The Scan stage runs all three external scanners locally on your environment. The Prioritize stage ranks every CVE by severity combined with its EPSS exploitation-likelihood score from FIRST, so ordering reflects what to fix first rather than what the scanner happened to emit first. The Correlate stage is the most interesting piece conceptually: it detects exploit chains where separate findings combine into a single attack path — the README's example is a credentialed database reachable from an internet-facing service being treated as a chain, not two disconnected findings. With an API key, an AI pass reasons over the full scan output to rank, explain, and extend that correlation.
The remaining stages handle remediation and reporting. Recommend produces copy-and-run fix commands and concrete Dockerfile or compose changes, and — a detail worth appreciating — it states how many findings each suggestion resolves, which forces the tool to be accountable for its advice. Report exports results in HTML, PDF, JSON, CSV, Markdown, SARIF, and CycloneDX SBOM, which covers the format needs of pull-request comments, GitHub Code Scanning via --sarif, and supply-chain tooling via --sbom. That breadth of export targets tells you the project is designed for pipeline integration, not just interactive use.
Installation is straightforward and comes in two flavors: pip install "docksec[ai]" for the full LLM-enabled build, or pip install docksec for a slim scan-only core with no LLM dependencies and no API key required. Because DockSec orchestrates external binaries, it expects Trivy (mandatory for all scans) and Hadolint on the path, plus Docker for image scans invoked with -i; python -m docksec.setup_external_tools will install the first two for you if they are missing. There is also a prebuilt container image published multi-arch (amd64 and arm64) to both ghcr.io/owasp/docksec and Docker Hub's owasp/docksec, bundling pinned versions of the scanners — nothing to install, nothing to configure, and GHCR images carry build provenance attestations verifiable with gh attestation verify.
The first scan needs no key at all: docksec Dockerfile --scan-only performs a fully local pass, and every scan terminates with a result summary containing a severity table, a 0-100 security score with a rating, a "Quick take" action block, the generated report paths (under ~/.docksec/results/ by default), and a suggested next command. Enabling AI analysis means picking a provider and exporting its key: OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY, or — the option privacy-conscious teams will gravitate toward — Ollama, which runs the reasoning pass fully locally with models like llama3.1 so that no scan data ever leaves the machine. Sensible default models per provider (gpt-4o, claude-haiku-4-5, gemini-1.5-pro) mean --model is optional, and provider/model can be pinned via LLM_PROVIDER and LLM_MODEL environment variables or a .env file DockSec loads automatically.
The privacy posture in the README is better documented than most tools in this category. Everything scans locally; when AI is enabled, only the data required for EPSS lookups or AI analysis is sent, and secret-looking values — passwords, tokens, API keys, private key blocks — are masked automatically before any content reaches a provider. Three configurations achieve full data locality: a local model via Ollama, scan-only mode, and a fully offline mode using --offline with a local Trivy DB, no network, and no AI. For defenders reviewing this tool for adoption, that triage of egress paths is exactly the kind of disclosure you want to see, and it makes the tool viable even in air-gapped or heavily regulated environments.
The command surface is dense with genuinely operational features. --compose docker-compose.yml scans a compose file across all its services; --image-only -i myapp:latest restricts to image analysis; --severity and --fail-on high let you tune reporting levels and gate CI with an exit 1 on HIGH-or-above findings. The baseline workflow stands out for mature teams: record today's findings with --baseline .docksec-baseline.json --update-baseline, then gate only on new findings later — the difference-based approach that distinguishes pragmatic pipelines from ones that fail on inherited debt nobody will ever fix. An auditable --ignore-file .docksec-ignore.yml handles deliberately triaged suppressions, and --no-cache forces a fresh scan past the results cache.
Automation hooks round out the picture. A committed .docksec.yml configuration file, schema-validated against a published JSON schema, lets the whole team and every CI job scan under one policy rather than per-developer flag archaeology. A GitHub Action (uses: OWASP/DockSec@v2026.9.21) wraps the same functionality with inputs like dockerfile and openai_api_key from secrets, and the container image reads the identical INPUT_* variables — INPUT_IMAGE, INPUT_COMPOSE, INPUT_SEVERITY, INPUT_FAIL_ON, INPUT_FORMAT, INPUT_SARIF, INPUT_OUTPUT_DIR — so any Action input works with plain docker run. There is even an install-skill command that deploys AI-assistant skill files for Claude Code, Cursor, and Copilot, an acknowledgment of where developer workflows are heading.
Two operational details deserve emphasis from a code-review perspective. First, the --fix flag applies mechanical Dockerfile fixes automatically — keeping a .bak of the original, re-scanning, and showing the delta — with --dry-run printing the diff without changing anything; treating automated mutation of build files with backup-plus-diff discipline is the right design. Second, --incomplete-policy fail makes a scan that could not complete count as a failure rather than a silent pass, closing the classic CI gap where a broken scanner becomes a green checkmark. Smaller ergonomic touches like --no-epss for no-network severity-only ranking, --quiet/--verbose/--log-file, and --no-color honoring NO_COLOR indicate a project that has thought about scripting contexts.
Where does this fit in an authorized workflow? DockSec is a shift-left triage layer: it does not replace Trivy or Hadolint, it consumes them, and its value-add is the correlation and explanation layer that turns their output into prioritized, explainable work items. The EPSS integration addresses the well-known failure mode of severity-only ranking, where a wall of CRITICALs with negligible exploitation probability burns out a team while the actively exploited MEDIUM goes unnoticed. The exploit-chain correlation is conceptually adjacent to how attackers actually reason about containers — chaining weak findings rather than hunting silver bullets — which is precisely why it belongs in a defensive review rather than an offensive one.
Caveats worth noting before adoption: AI-generated explanations and fix suggestions remain probabilistic, so the "states how many findings they resolve" accounting is a useful check but not a substitute for human review of suggested Dockerfile changes, ideally through the --dry-run diff. Sending scan output — even secret-masked — to a third-party LLM provider is a data-governance decision each organization must make explicitly; the Ollama and --offline paths exist precisely for teams that answer no. For blue teams and platform engineers who own their container estate and are drowning in scanner noise, though, DockSec represents one of the more thoughtfully engineered attempts to make container vulnerability triage actionable, and its OWASP Lab affiliation, MIT license, and provenance-attested images lower the institutional barriers to giving it a run.
OWASP/DockSec.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.