DockSec - AI-powered Docker security scanner that explains v

项目说明

<di="center">

![OWASP]() ![OWASP]() ![project-docksec]() ![Build Status]()
<br>![OpenSSF Best Practices]()

![License]() ![Last Commit]() ![Contributors]()

![Forks]() ![Stars]() !PyPI Downloads

![Issues]() ![Pull Requests]()

![CREATED]()

<picture>
<source srcset=" media="(prefers-color-scheme: dark)">
<img src=" alt="DockSec Logo" width="600">
</picture><br>
<img src=" alt="OWASP Logo" width="300">

DockSec

AI-powered Docker security scanner that explains in plain English

</div>

---

What is DockSec?

DockSec is an OWASP Lab Project that bridges the gap between complex security scan results and actionable de fixes. It integrates industry-standard scanners (Tri, Docker Scout) with AI to provide context-aware security analysis.

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

Prioritizes what actually affects your specific container setup.

Explains in plain English, not just security jargon.

Suggests specific fixes for your Dockerfile.

Generates professional, interacti reports for your team.

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

How It Works

<di="center">
<img src=" alt="DockSec Workflow" width="800">
<p><em>DockSec workflow: from scanning to actionable insights</em></p>
</div>

DockSec follows a fi pipeline:

1. Scan: Runs Tri and Dockerfile misconfigurations),
Hadolint, and Docker Scout locally on your en.
2. Prioritize: Ranks every C by se combined with its
EPSS exploitation likelihood, so the list is
ordered by what to fix first rather than by what was found first.
3. Correlate: Detects exploit chains where separate
findings combine into one attack path - a credentialed database that an
internet-facing service can reach is a chain, not two unrelated findings.
With an API key, an AI pass reasons over the full scan output to rank, explain,
and extend this.
4. Recommend: Produces copy-and-run fix commands and concrete Dockerfile or
compose changes, and states how many findings they resolve.
5. Report: Exports actionable results as HTML, PDF, JSON, CS, SARIF, and CycloneDX SBOM.

---

Getting Started

1. Prerequisites

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:

2. Install DockSec

3. Run your first scan

No API key needed for local scanning:

Every scan ends with a result summary: a se 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.

4. Enable AI analysis

AI analysis explains findings and suggests fixes. Pick a provider, set its API key, and run:

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 en (or put them in a .env
file in the directory you run from - DockSec loads it automatically):

Before any content is sent to an AI provider, secret-looking (passwords, tokens,
API keys, private key blocks) are masked automatically. See
Data flow and privacy.

5. Or run the container image (nothing to install)

The published image bundles pinned of Trivy and Hadolint, so there is
nothing to install and nothing to configure:

Also published to Docker Hub as owasp/docksec:

Published multi-arch (amd64 and arm64) on every release, to both registries
from the same build. Pin to a specific (ghcr.io/owasp/docksec:2026.9.21,
owasp/docksec:2026.9.21) or a minor series (ghcr.io/owasp/docksec:2026.9)
rather than latest in CI. Every GHCR image carries a build pro
attestation:

The image reads the same INPUT_* as the GitHub Action, so any Action
input works here: INPUT_IMAGE, INPUT_COMPOSE, INPUT_SE,
INPUT_FAIL_ON, INPUT_FORMAT, INPUT_SARIF, INPUT_OUTPUT_DIR. Write reports
somewhere on the mount to keep them after the container exits:

6. Or use the GitHub Action

---

Common Commands

---

Configuration file

Commit a .docksec.yml at the root of your repository and the whole team - and
every CI job - scans under the same policy, instead of each de passing
their own flags.

Every setting is optional; anything you leave out falls back to the en
and then to the built-in default. A full annotated example is in
examples/.docksec.yml.

Precedence

Highest priority first:

So a committed se: LOW is still o by --se CRITICAL on
the command line, and by DOCKSEC_DEFAULT_SE in the en.

Discovery

DockSec looks for .docksec.yml (or .docksec.yaml) in the working directory
and then walks up to the repository root, so a service in a monorepo
subdirectory inherits the policy committed at the top level. The search stops at
the directory containing .git, so it ne up a file from outside the
repository.

--config FILE uses a specific file instead of searching.

--no-config ignores any config file, for reproducible CI runs.

The config file in force is shown in the scan banner, so it is always clear
which policy was applied.

Settings

| Setting | Equi flag | Notes |
| --- | --- | --- |
| se | --se | Se levels for the image scan |
| fail_on | --fail-on | CI gate threshold |
| formats | --format | List form: [json, html] |
| output_dir | --output-dir | Report destination |
| provider | --provider | openai, anthropic, google, ollama |
| model | --model | Model name for the provider |
| offline | --offline | No network; skips AI and Docker Scout |
| skip_ai_scoring | --skip-ai-scoring | Deprecated and ignored; scoring is always deterministic |
| no_redact | --no-redact | Do not mask secrets before the AI call |
| no_cache | --no-cache | Bypass the scan cache |
| ignore_file | --ignore-file | Waiver file path |
| baseline | --baseline | Baseline file path |
| rules.disabled | - | Rule IDs to switch off entirely |

An invalid config file - an unknown key, a bad se - is a hard error that
exits 2 rather than a warning, so a broken policy file can ne a scan
to run under rules the team did not commit.

Editor autocomplete

The # yaml-language-server: comment on the first line gi and
inline in VS Code and JetBrains editors. The schema is published at
docs/docksec-config-schema.json and can be
regenerated with docksec --print-config-schema.

Disabling rules

rules.disabled switches a check off entirely, e - it is removed
before scoring, reports, --json, and the --fail-on gate. Use it for checks
that do not apply to your en. For indi findings your team has
triaged and accepted, prefer the waiver file,
whose entries carry a reason and an expiry date and so stay auditable.

---

CI/CD Integration

Exit codes

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 every structured finding: image , Dockerfile
misconfigurations, and compose misconfigurations. When --fail-on is below the
requested --se, the scan se is widened automatically so the gate can
obser findings.

Incomplete scans

If a scanner cannot run, results may be missing findings rather than genuinely
clean. DockSec reports that as a detection gap in the Co block and in
--json under scan_info.completeness. Use --incomplete-policy fail to exit 3
in that case, so CI cannot pass on a scan that did not finish:

Priority: what to fix first

Every C is scored against EPSS, which
estimates the probability it will be exploited in the next 30 days. Combining that
with se gives four tiers:

| Tier | Meaning |
|---|---|
| Fix Now | Critical or high se, and in the top 10% of CVEs by exploitation likelihood |
| Fix Soon | Critical or high se, but exploitation is less common |
| Monitor | Lower se, but actively exploited |
| Low Priority | Lower se, exploitation uncommon |

This is the only network call DockSec makes outside the AI pass, and it is
deliberately narrow: only CVE IDs are sent - no image names, no file contents,
no paths. Scores are cached for 24 hours. --offline and --no-epss disable it,
and any failure falls back to se ranking rather than failing the scan.

Exploit chains

A per-service view reports findings one at a time. DockSec also reports where
separate findings combine into a single attack path:

Chain detection is rule-based, so it works with --scan-only, offline, and with
no API key, and returns the same answer every run. The AI pass ranks and extends
it rather than being required for it. Chains also appear in --json under
exploit_chains.

See the exploit chains guide for the full list and the
compose rule reference for every rule they combine.

Fix commands

Scans end with concrete commands rather than a list of identifiers, and a plain
statement of how many findings they resolve:

Machine-readable output

--json prints a single JSON object to stdout (scan info, , se
counts, and any AI findings) instead of the human-readable summary, so it can be piped
straight into other tools:

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 e the JSON payload.

Report formats

--format accepts a comma-separated list of file outputs:

| Format | What you get |
|--------|----------------|
| json | A .json file with scan metadata, se counts, and the full list (same shape as the --json stdout payload, but written to disk). |
| csv | A .csv table of findings (ID, se, package, , title, and related fields). |
| pdf | A printable PDF summary with scan info, scores, and details. |
| html | A styled HTML report for browsing results in a browser. |
| markdown | A .md report that renders natively in pull request comments and CI job summaries. Opt-in: not written unless requested. |

json, csv, pdf, and html are written by default; add markdown explicitly to
get it.

CSV with zero findings: if a scan reports no but csv is in your
--format list, DockSec still writes a CSV file containing only the column headers.
That is intentional (the export is valid, not a failed write) so downstream tools can
rely on a stable schema even on clean scans.

For stdout JSON and piping into other tools, see Machine-readable output
above. For CI and GitHub Code Scanning, use --sarif (see the next section); SARIF is
separate from --format and is always emitted when requested.

SARIF output for GitHub Code Scanning

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

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

Baseline / ratchet mode

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

Findings are matched by 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.

Ignoring findings (waivers)

--ignore-file FILE suppresses indi findings a team has triaged and accepted.
Unlike the baseline (a point-in-time snapshot), the ignore file is an explicit,
re list where every entry carries a reason and an optional expiry date.
If a .docksec-ignore.yml file exists in the current directory, it is picked up
automatically.

Suppressed findings are remo scoring, reports, --json output, and the
--fail-on gate. Expired entries stop applying automatically (with a warning), and
entries without a reason are flagged so waivers stay auditable. Commit the file to
control so suppressions are re like any other change.

---

Reports

Report formats

By default every scan writes four report files; use --format to pick a subset:

html: An interacti clean web report: se cards, score rating, full table with fixed , and the complete AI findings.

pdf: A portable, presentation-ready document.

json: Full, machine-readable scan data (same shape as --json stdout output).

csv: A spreadsheet-ready table of indi .

markdown: A lightweight, readable report (se summary + table with fixed ) that renders natively in pull request comments and CI job summaries. Opt-in: add markdown to --format; it is not written by default.

> Note on CS: with zero , DockSec still writes a header-only
> CS names, no rows) so downstream automation ne on a missing or
> empty file. This is intentional.

CycloneDX SBOM

--sbom writes a CycloneDX software bill of materials (<image>.cdx.json) of the
scanned image, listing every package component plus known . The BOM is
produced by Trivy's nati (so it is spec-compliant) and DockSec stamps itself
into the tool metadata. Feed it into Dependency-Track, GitHub's dependency graph, or any
other SBOM consumer:

--sbom needs a single image (-i), so it is skipped for compose runs. Like --sarif,
it is independent of --format.

---

Data flow and privacy

DockSec is designed so you always know what leaves your machine:

Scanning is fully local. Tri, and the security score run on your

machine. Image contents are ne anywhere by DockSec.

AI analysis sends only the scanned file. When the AI pass runs, the Dockerfile

or compose file content (plus a short summary of counts for scoring)
is sent to the LLM provider you configured. Nothing else is transmitted.

Secrets are redacted before they leave. Secret-looking (passwords,

tokens, API keys, private key blocks) in the file are masked before the content is
sent to the AI provider. Key names stay so exposed credentials are still
flagged. Use --no-redact to opt out.

Fully local AI is supported. Use --provider ollama to keep the AI analysis on

your own hardware, or --scan-only / --offline to skip AI entirely.

No telemetry. DockSec collects no usage data and phones home to nothing.

Offline mode

--offline runs a scan with no network access. It uses the Tri database
already on disk (no DB update) and skips the AI analysis and the Docker Scout ad
scan, both of which require network. This is the simplest way to scan in an air-gapped or
locked-down en:

Make sure the Trivy DB has been downloaded at least once (any prior online scan does
this) before relying on --offline.

Scan results cache

Image scan results are cached (default: 24 hours, o with
DOCKSEC_CACHE_TTL_HOURS) and keyed by the image's content digest, so a rebuilt tag
such as a reused :latest always gets a fresh scan. Use --no-cache (or
DOCKSEC_USE_CACHE=false) to bypass the cache for a run.

Pulling images that are not local

Scanning an image that is not present locally pulls it first. A compose stack
routinely names images the machine has ne, and without this every one
of those services is reported as unscanned.

Set DOCKSEC_PULL_MISSING_IMAGES=false to turn this off and fail instead, which
is worth doing on a metered connection or a shared runner. --offline never
pulls, regardless of this setting.

---

AI-assistant skills (install-skill)

docksec install-skill writes DockSec usage instructions into the well-known context
files for popular AI coding assistants, so an assistant working in your repo knows how to
invoke DockSec:

This creates or updates:

.claude/commands/docksec.md (Claude Code slash command /docksec)

.cursor/rules/docksec.mdc (Cursor)

AGENTS.md (Codex CLI), GEMINI.md (Gemini CLI)

.github/copilot-instructions.md (GitHub Copilot)

The files are plain text you can review and commit; nothing is executed. Re-running the
command updates the DockSec section in place instead of duplicating it.

---

Features

Smart Analysis: AI explains what mean for *your* specific setup.

Multi-LLM Support: OpenAI, Anthropic Claude, Google Gemini, or local models .

Privacy First: Secret are redacted before any content reaches an AI provider, scanning is fully local, and there is no telemetry.

Docker Compose Scanning: Detect orchestration-le and scan all services in a compose file.

Deep Integration: Combines Tri), 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, CS, 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 Tri.

AI-Assistant Skills: docksec install-skill teaches Claude Code, Cursor, Copilot, and others how to run DockSec in your repo.

---

How DockSec Compares

| Capability | DockSec | Tri) | Snyk Container | Aikido |
|---|---|---|---|---|
| License and cost | Free, open source (MIT) | Free, open source (Apache 2.0) | Commercial (limited free tier) | Commercial (limited free tier) |
| Go | OWASP Lab Project, neutral | Open source, maintained by Aqua | Single | Single |
| Detects CVEs and Dockerfile misconfigurations | Yes | Yes | Yes | Yes |
| Explains findings in plain English | Yes (AI-written context and impact) | No (raw CVE data) | Partial (se and fix hints) | Partial (AI summaries in platform) |
| Contextual Dockerfile remediation | Yes (specific rewrites with explanation) | No (detection only) | Yes (base image upgrade advice, fix PRs) | Yes (AI AutoFix PRs) |
| Docker Compose (multi-service) scanning | Yes (orchestration checks and per-service scan) | Partial (config scan, no per-service fan-out) | Partial | Partial |
| Baseline / ratchet mode (fail only on new findings) | Yes | No | Partial (platform policies) | Partial (platform policies) |
| Auditable per-finding waivers with reasons and expiry | Yes | Partial (.tri, no reasons enforced) | Partial (platform policies) | Partial (platform policies) |
| CI-nati (SARIF for GitHub Code Scanning) | Yes | Yes | Yes | Yes |
| SBOM export (CycloneDX) | Yes (--sbom) | Yes | Yes | Yes |
| AI-assistant skill install (Claude Code, Cursor, Copilot) | Yes (install-skill) | No | No | No |
| Runs fully offline / air-gapped | Yes (local LLM , scan-only mode, no API key) | Scanning only (no remediation layer) | No (cloud platform) | No (hosted platform) |
| Your image data stays on your network | Yes | Yes | No | No |
| Bring your own LLM / model choice | Yes (OpenAI, Anthropic, Gemini, or local Ollama) | Not applicable | No (proprietary AI) | No (proprietary AI) |
| Self-hostable, no platform deployment | Yes | Yes | No | No |
| lock-in | None | None | Yes | Yes |
| Security score (0-100) and multi-format reports | Yes | Partial (machine formats, no remediation report) | Partial (dashboard reports) | Partial (dashboard reports) |

DockSec is the only one of these that pairs contextual Dockerfile remediation with a fully open source, OWASP-go, 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 de and for regulated or air-gapped teams who need both the fix guidance and full control of their data, at no cost.

---

Applying fixes automatically

--fix applies the mechanical subset of the suggested Dockerfile changes,
re-scans, and reports the delta:

It is deliberately conser. It will not choose a base image , move a
secret, convert an ADD that fetches a URL or unpacks an archive, or edit a
compose file - those are reported under "Needs review" instead. It also refuses
to edit a file with uncommitted changes unless --force is given, so git is
always in a position to undo the change.

Documentation

| Guide | What it covers |
| --- | --- |
| E guide | 15-minute assessment, including what DockSec does *not* do |
| Exploit chains | Cross-service attack paths, and their limits |
| Compose rule reference | All 17 rules: what each catches, and when keeping it is reasonable |
| CI integration | Jenkins, GitLab, Azure Pipelines, pre-commit |
| Examples | Ten Dockerfiles and compose stacks with their expected findings |
| Case studies | Real scans of official images, with the numbers |

Roadmap

See ROADMAP.md for where DockSec is heading: registry scanning without a
local Docker daemon, a repo-le config file, Jenkins/GitLab/Azure DevOps
templates, an official container image, Kubernetes and Helm scanning, and more. Feedback
and votes on priorities are welcome in
issues and on
OWASP Slack.

---

Contributing

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

Code Contributions: Fix bugs or add new features.

Documentation: Impro 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.

---

Leaders and Community

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

Advait Patel - Project Lead

Arkadii Yakovets - Project Co-lead

Find us here:

OWASP Project Page: owasp.org/DockSec/

OWASP Slack: #project-docksec

PyPI: pypi.org/project/docksec/

Issues: Report a bug

Changelog: CHANGELOG.md

---

<di="center">
<strong>If DockSec helps you, star the repo to help others discover it.</strong><br>
Built by <a href=" Patel</a> and the OWASP community.
</div>

项目信息

开发语言：Python

Star 数：495

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕AI-powered Docker security scanner that explains vulnerabilities in plain English. An OWASP Lab Project.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。