<div align="center"> [](https://owasp.org/DockSec/) [](https://owasp.org/DockSec/) [](https://owasp.slack.com/archives/C0APXGCUW7M) [](https://github.com/OWASP/DockSec/actions) <br>[](https://www.bestpractices.dev/projects/12939) [](https://github.com/OWASP/DockSec/blob/main/LICENSE) [](https://github.com/OWASP/DockSec/commits/main/) [](https://github.com/OWASP/DockSec/graphs/contributors) [](https://github.com/OWASP/DockSec/network/members) [](https://github.com/OWASP/DockSec/stargazers)  [](https://github.com/OWASP/DockSec/issues) [](https://github.com/OWASP/DockSec/pulls) [](https://github.com/OWASP/DockSec/commit/80664db8935e4b5ab44df5867913e) <picture> <source srcset="https://raw.githubusercontent.com/OWASP/DockSec/main/images/docksec-logo-for-github.png" media="(prefers-color-scheme: dark)"> <img src="https://assets.kitploit.com/production/public/readmes/39487/d30ee74abf3ad22a447ed36ba3010acab606147bc21702a1fb428b8633298caf.png" alt="DockSec Logo" width="600"> </picture><br> <img src="https://assets.kitploit.com/production/public/readmes/39487/009ae678c48ab2738e17c17c238c83cb2481510fbc2bf9d7284ea80ec487feda.png" alt="OWASP Logo" width="300"> # [DockSec](https://owasp.org/DockSec/) **AI 驱动的 Docker 安全扫描器，用通俗易懂的语言解释漏洞** </div> --- ## 什么是 DockSec？ DockSec 是一个 **OWASP 实验室项目**，旨在弥合复杂的安全扫描结果与开发者可执行的修复措施之间的鸿沟。它集成了业界标准的扫描器（Trivy、Hadolint、Docker Scout）与 AI，提供**上下文感知的安全分析**。 DockSec 不会用 200 多个 CVE 的列表让你不知所措，而是： - **优先排序**真正影响你特定容器配置的问题。 - **解释**漏洞时使用通俗易懂的语言，而非仅仅堆砌安全术语。 - **建议**针对你的 Dockerfile 的具体修复方案。 - **生成**专业、可交互的安全报告，供你的团队使用。 所有扫描均在本地进行；唯一离开你机器的内容是你所选择的 AI 提供商收到的（已脱敏的）文件内容——而使用本地模型或仅扫描模式时，则完全不会有任何内容离开。参见[数据流与隐私](#data-flow-and-privacy)。 --- ## 工作原理 <div align="center"> <img src="https://assets.kitploit.com/production/public/readmes/39487/99b4247f599cc8f7a260f285815f8793ca4d2c050ea6656480818a846d590fb0.png" alt="DockSec Workflow" width="800"> <p><em>DockSec 工作流：从扫描到可执行的洞察</em></p> </div> DockSec 遵循五阶段流水线： 1. **扫描**：在你的环境中本地运行 Trivy（镜像漏洞和 Dockerfile 错误配置）、 Hadolint 和 Docker Scout。 2. **优先排序**：根据严重性结合其 [EPSS](https://www.first.org/epss/) 利用可能性对每个 CVE 发现进行排序，因此列表 按应先修复的内容排序，而非按先发现的内容排序。 3. **关联**：检测[利用链](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md)，即多个 独立发现组合成一条攻击路径——一个面向互联网的服务可以访问的带凭据数据库 是一条链，而非两个不相关的发现。 使用 API 密钥时，AI 会基于完整扫描输出进行推理，以排序、解释 并扩展这一过程。 4. **建议**：生成可直接复制运行的修复命令以及具体的 Dockerfile 或 compose 更改，并说明它们能解决多少发现。 5. **报告**：将可执行结果导出为 HTML、PDF、JSON、CSV、Markdown、SARIF 和 CycloneDX SBOM。 --- ## 快速开始 ### 1. 前置条件 DockSec 编排本地扫描器，因此需要： | 要求 | 用途 | 安装 | |---|---|---| | Python 3.12+ | DockSec 本身 | [python.org](https://www.python.org/downloads/) | | Trivy | 所有扫描（必需） | `brew install trivy` 或 [Trivy 文档](https://trivy.dev/latest/getting-started/installation/) | | Hadolint | Dockerfile 检查 | `brew install hadolint` 或 [Hadolint 文档](https://github.com/hadolint/hadolint#install) | | Docker | 镜像扫描（`-i`） | [Docker 文档](https://docs.docker.com/get-docker/) | 或者让 DockSec 为你安装 Trivy 和 Hadolint：```bash python -m docksec.setup_external_tools ``` ### 2. 安装 DockSec```bash # 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 ``` ### 3. 运行你的第一次扫描 本地扫描无需 API 密钥：```bash docksec Dockerfile --scan-only ``` 每次扫描结束时都会生成结果摘要：一个严重性表格、一个 0-100 的安全评分及评级、一个“快速评估”操作块、生成的报告（默认保存到 `~/.docksec/results/`），以及一条建议的下一条命令。 ### 4. 启用 AI 分析 AI 分析会解释发现的问题并建议修复方案。选择一个提供商，设置其 API 密钥，然后运行：```bash # 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 ``` 每个提供商都有合理的默认模型（OpenAI：`gpt-4o`，Anthropic： `claude-haiku-4-5`，Google：`gemini-1.5-pro`，Ollama：`llama3.1`），因此 `--model` 是可选的。为避免重复指定标志，请设置环境变量（或将其放入你运行命令所在目录的 `.env` 文件中——DockSec 会自动加载它）：```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile ``` 在将任何内容发送给 AI 提供商之前，疑似敏感值（密码、令牌、API 密钥、私钥块）会被自动掩码处理。请参阅 [数据流与隐私](#data-flow-and-privacy)。 ### 5. 或者运行容器镜像（无需安装任何内容） 已发布的镜像捆绑了固定版本的 Trivy 和 Hadolint，因此无需安装任何内容，也无需进行任何配置：```bash docker run --rm -v "$PWD:/github/workspace" \ -e INPUT_DOCKERFILE=Dockerfile \ -e INPUT_SCAN_ONLY=true \ ghcr.io/owasp/docksec:latest ``` 每个版本均发布多架构（amd64 和 arm64）镜像。在 CI 中应固定到特定版本（`ghcr.io/owasp/docksec:2026.9.21`）或次要版本系列（`ghcr.io/owasp/docksec:2026.9`），而非使用 `latest`。每个镜像都附带构建来源证明：```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec ``` 该镜像读取与 GitHub Action 相同的 `INPUT_*` 变量，因此任何 Action 输入在此均可用：`INPUT_IMAGE`、`INPUT_COMPOSE`、`INPUT_SEVERITY`、`INPUT_FAIL_ON`、`INPUT_FORMAT`、`INPUT_SARIF`、`INPUT_OUTPUT_DIR`。将报告写入挂载点上的某个位置，以便在容器退出后保留它们：```bash docker run --rm -v "$PWD:/github/workspace" \ -e INPUT_COMPOSE=docker-compose.yml \ -e INPUT_SCAN_ONLY=true \ -e INPUT_FORMAT=json,html \ -e INPUT_OUTPUT_DIR=/github/workspace/docksec-reports \ ghcr.io/owasp/docksec:latest ``` ### 6. 或者使用 GitHub Action```yaml - name: Run DockSec AI Scanner uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' openai_api_key: ${{ secrets.OPENAI_API_KEY }} ``` --- ## 常用命令```bash # 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 # Write a Markdown report for posting directly into a pull request comment docksec Dockerfile --scan-only --format markdown # 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 --scan-only --compact-output # shorter per-finding output docksec Dockerfile --no-color # also honors NO_COLOR # Apply the mechanical Dockerfile fixes (keeps a .bak, re-scans, shows the delta) docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing docksec Dockerfile --scan-only --fix # Rank findings by severity alone, with no EPSS lookup and no network call docksec Dockerfile --scan-only --no-epss # Treat a scan that could not complete as a failure, not a pass docksec Dockerfile --scan-only --fail-on high --incomplete-policy fail ``` --- ## 配置文件 在仓库根目录提交一个 `.docksec.yml`，整个团队——以及每个 CI 任务——都会在同一策略下进行扫描，而不是每个开发者各自传递自己的标志。```yaml # yaml-language-server: $schema=https://owasp.org/DockSec/docksec-config-schema.json severity: CRITICAL,HIGH fail_on: HIGH formats: [json, html] output_dir: ./security-reports rules: disabled: - compose-missing-healthcheck ``` 每个设置都是可选的；任何省略的设置都会回退到环境变量，然后再回退到内置默认值。完整的带注释示例见 [`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml)。 ### 优先级 优先级从高到低：``` CLI flag > environment variable > .docksec.yml > built-in default ``` 因此，提交的 `severity: LOW` 仍会被命令行上的 `--severity CRITICAL` 以及环境变量中的 `DOCKSEC_DEFAULT_SEVERITY` 覆盖。 ### 发现机制 DockSec 会在工作目录中查找 `.docksec.yml`（或 `.docksec.yaml`），然后向上遍历至仓库根目录，因此 monorepo 子目录中的服务会继承顶层提交的策略。搜索会在包含 `.git` 的目录处停止，因此它绝不会拾取仓库之外的文件。 - `--config FILE` 使用指定文件而非进行搜索。 - `--no-config` 忽略任何配置文件，用于可复现的 CI 运行。 生效的配置文件会显示在扫描横幅中，因此始终可以清楚地知道应用了哪个策略。 ### 设置 | 设置 | 等效标志 | 备注 | | --- | --- | --- | | `severity` | `--severity` | 镜像扫描的严重性级别 | | `fail_on` | `--fail-on` | CI 门禁阈值 | | `formats` | `--format` | 列表形式：`[json, html]` | | `output_dir` | `--output-dir` | 报告目标位置 | | `provider` | `--provider` | `openai`、`anthropic`、`google`、`ollama` | | `model` | `--model` | 提供程序的模型名称 | | `offline` | `--offline` | 无网络；跳过 AI 和 Docker Scout | | `skip_ai_scoring` | `--skip-ai-scoring` | 已弃用并被忽略；评分始终是确定性的 | | `no_redact` | `--no-redact` | 在 AI 调用前不遮蔽机密 | | `no_cache` | `--no-cache` | 绕过扫描缓存 | | `ignore_file` | `--ignore-file` | 豁免文件路径 | | `baseline` | `--baseline` | 基线文件路径 | | `rules.disabled` | - | 要完全关闭的规则 ID | 无效的配置文件——未知键、错误的严重性——是硬错误，会以 `2` 退出而非警告，因此损坏的策略文件绝不会导致扫描在团队未提交的规则下运行。 ### 编辑器自动补全 第一行的 `# yaml-language-server:` 注释可在 VS Code 和 JetBrains 编辑器中提供补全和内联验证。该 schema 发布在 [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/main/docs/docksec-config-schema.json)，可通过 `docksec --print-config-schema` 重新生成。 ### 禁用规则 `rules.disabled` 会在所有位置完全关闭某项检查——它会在评分、报告、`--json` 和 `--fail-on` 门禁之前被移除。将其用于不适用于你环境的检查。对于团队已分类并接受的个别发现，请优先使用[豁免文件](#ignoring-findings-waivers)，其条目带有原因和到期日期，因此保持可审计。 --- ## CI/CD 集成 ### 退出码 DockSec 使用对 CI 友好的退出码，以便构建和 shell 可以对结果做出反应： | 代码 | 含义 | |---|---| | `0` | 成功，没有达到或超过 `--fail-on` 的发现 | | `1` | 存在达到或超过 `--fail-on` 阈值的发现 | | `2` | 用法或参数错误 | | `3` | 工具或运行时错误（扫描失败、镜像未找到、缺少工具） | `--fail-on` 会对每个结构化发现进行门禁：镜像漏洞、Dockerfile 错误配置和 compose 错误配置。当 `--fail-on` 低于请求的 `--severity` 时，扫描严重性会自动放宽，以便门禁能够观察到这些发现。 ### 不完整的扫描 如果扫描器无法运行，结果可能缺少发现，而非真正干净。DockSec 会将其报告为 Coverage 块中的检测缺口，并在 `--json` 中的 `scan_info.completeness` 下报告。在这种情况下，使用 `--incomplete-policy fail` 以退出码 `3` 退出，这样 CI 就无法在未完成的扫描上通过：```bash docksec Dockerfile --incomplete-policy fail ``` ### 优先级：先修复什么 每个 CVE 发现都会根据 [EPSS](https://www.first.org/epss/) 进行评分，该评分 估计其在未来 30 天内被利用的概率。将其与严重性结合， 得到四个层级： | 层级 | 含义 | |---|---| | **立即修复** | 严重或高严重性，且在被利用可能性方面位列 CVE 前 10% | | **尽快修复** | 严重或高严重性，但被利用的情况较少见 | | **监控** | 较低严重性，但正被积极利用 | | **低优先级** | 较低严重性，被利用的情况不常见 | 这是 DockSec 在 AI 处理之外进行的唯一网络调用，并且它 刻意保持范围狭窄：**仅发送 CVE ID**——不发送镜像名称、不发送文件内容、 不发送路径。评分会缓存 24 小时。`--offline` 和 `--no-epss` 可将其禁用， 任何失败都会回退到仅按严重性排序，而不会导致扫描失败。 ### 利用链 按服务划分的视图会一次报告一个发现。DockSec 还会报告 多个独立发现组合成单一攻击路径的情况：```text Exploit chains [HIGH] 'web' is internet-facing and can reach 'db' with a committed credential services: web, db combines: compose-plaintext-secret-env, compose-no-network-segmentation 'web' accepts connections from outside the host and shares the default network with 'db'. 'db' is not exposed directly, but its credential is in the compose file, so compromising 'web' yields authenticated access to it. Neither service looks critical on its own. break it: Put 'db' on its own network that 'web' does not join, or move POSTGRES_PASSWORD to a Docker secret. ``` 链检测基于规则，因此可与 `--scan-only` 配合使用、可离线运行，且无需 API 密钥，并且每次运行都返回相同的结果。AI 处理只是对其进行排序和扩展，而非必需环节。链也会出现在 `--json` 输出中的 `exploit_chains` 下。 完整列表请参阅[漏洞利用链指南](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md)，它们组合的每条规则请参阅[compose 规则参考](https://github.com/owasp/docksec/blob/main/docs/rules/README.md)。 ### 修复命令 扫描以具体命令结尾，而不是一列标识符，并附有一句关于它们能解决多少发现项的明确说明：```text Fix commands > apt-get install --only-upgrade -y libgnutls30=3.7.9-2+deb12u7 CRITICAL - 3.7.9-2+deb12u4 -> 3.7.9-2+deb12u7 (CVE-2026-33845 +6) Dockerfile changes - [CRITICAL] Move the secret out of ENV; inject it at runtime (line 4) - [HIGH] Add a non-root USER before CMD/ENTRYPOINT (line 7) Applying all of the above resolves 37 of 93 finding(s); 56 have no mechanical fix yet. ``` ### 机器可读输出 `--json` 会向 stdout 打印单个 JSON 对象（扫描信息、漏洞、严重性计数以及任何 AI 发现），而不是人类可读的摘要，因此可以直接管道传输到其他工具：```bash docksec -i myapp:latest --image-only --json | jq '.severity_counts' ``` 仅使用 `--json` 时，不会写入任何报告文件；将其与 `--format` 结合使用，可在同一次运行中写入文件并打印 JSON。在 `--json` 模式下，所有人类可读的消息都会移至 stderr，因此 stdout 中只会包含 JSON 负载。 ### 报告格式 `--format` 接受以逗号分隔的文件输出列表： | 格式 | 你将获得 | |--------|----------------| | `json` | 一个 `.json` 文件，包含扫描元数据、严重性计数以及完整的漏洞列表（与 `--json` stdout 负载结构相同，但写入磁盘）。 | | `csv` | 一个 `.csv` 发现结果表格（ID、严重性、包、版本、标题及相关字段）。 | | `pdf` | 一份可打印的 PDF 摘要，包含扫描信息、评分和漏洞详情。 | | `html` | 一份带样式的 HTML 报告，可在浏览器中浏览结果。 | | `markdown` | 一份 `.md` 报告，可在拉取请求评论和 CI 作业摘要中原生渲染。需显式启用：除非请求，否则不会写入。 | `json`、`csv`、`pdf` 和 `html` 默认写入；需显式添加 `markdown` 才能获得它。 **零发现结果的 CSV：** 如果扫描未报告任何漏洞，但 `csv` 在你的 `--format` 列表中，DockSec 仍会写入一个仅包含列标题的 CSV 文件。这是有意为之（该导出是有效的，而非写入失败），以便下游工具即使在干净的扫描中也能依赖稳定的模式。 关于 stdout JSON 以及管道传输到其他工具，请参见上文的[机器可读输出](#machine-readable-output)。对于 CI 和 GitHub Code Scanning，请使用 `--sarif`（见下一节）；SARIF 与 `--format` 相互独立，并且在请求时始终会生成。 ### 用于 GitHub Code Scanning 的 SARIF 输出 `--sarif` 会与其他报告格式一起写入一份 SARIF 2.1.0 报告。使用标准的 `github/codeql-action/upload-sarif` 操作上传它，即可直接在拉取请求和 Security 选项卡中看到发现结果的注释：```yaml - name: Run DockSec uses: OWASP/[email protected] 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()` 很重要：没有它，每当 `--fail-on` 导致 DockSec 以非零状态退出时，上传步骤就会被跳过，恰恰在最需要的时候丢失了发现结果。 ### 基线 / 棘轮模式 `--baseline FILE` 让你可以在现有项目上采用 `--fail-on`，而不会被大量预先存在的发现结果阻塞每一次构建。先用 `--update-baseline` 运行一次，对当前的发现结果进行快照，然后提交基线文件；从那时起，`--fail-on` 只会对不在基线中的发现结果进行拦截：```bash # 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 ``` 发现项通过漏洞 ID、目标和包名进行匹配，因此基线在无关发现项出现和消失时仍保持有效。每当你想将当前状态接受为新基线时，使用 `--update-baseline` 重新运行。 ### 忽略发现项（豁免） `--ignore-file FILE` 会抑制团队已分类并接受的单个发现项。与基线（某一时间点的快照）不同，忽略文件是一个显式、可审查的列表，其中每个条目都带有原因和可选的到期日期。 如果当前目录中存在 `.docksec-ignore.yml` 文件，它会被自动读取。```yaml # .docksec-ignore.yml ignores: - id: CVE-2023-45853 # Trivy vulnerability ID or DockSec rule ID reason: "zlib CVE; code path not reachable, vendor fix pending" expires: 2026-12-31 # optional; entry stops applying after this date - id: compose-missing-healthcheck reason: "healthchecks are handled by the orchestrator" ``` 被抑制的发现项在评分、报告、`--json` 输出以及 `--fail-on` 门禁之前会被移除。过期的条目会自动停止生效（并给出警告），而没有原因的条目会被标记，以确保豁免保持可审计。请将该文件提交到版本控制，以便抑制项像其他任何变更一样接受审查。 --- ## 报告 ### 报告格式 默认情况下，每次扫描都会写入四个报告文件；使用 `--format` 选择子集： - **html**：一个交互式、视觉简洁的网页报告：严重性卡片、评分等级、包含修复版本的完整漏洞表，以及完整的 AI 发现项。 - **pdf**：一个便于携带、可直接用于演示的文档。 - **json**：完整的、机器可读的扫描数据（与 `--json` 标准输出格式相同）。 - **csv**：一个可直接用于电子表格的单个漏洞表格。 - **markdown**：一个轻量、易读的报告（严重性摘要 + 包含修复版本的漏洞表），可在拉取请求评论和 CI 作业摘要中原生渲染。需主动启用：将 `markdown` 添加到 `--format`；默认不会写入。 > 关于 CSV 行为的说明：在零漏洞的情况下，DockSec 仍会写入一个仅含表头的 > CSV（列名，无数据行），以便下游自动化永远不会因文件缺失或 > 为空而中断。这是有意为之。 ### CycloneDX SBOM `--sbom` 会写入所扫描镜像的 CycloneDX 软件物料清单（`<image>.cdx.json`）， 列出每个软件包组件以及已知漏洞。该 BOM 由 Trivy 的原生导出器生成（因此符合规范）， DockSec 会将自身信息写入工具元数据。可将其输入到 Dependency-Track、GitHub 的依赖图， 或任何其他 SBOM 消费者：```bash docksec --image-only -i myapp:latest --sbom ``` `--sbom` 需要单个镜像（`-i`），因此在 compose 运行时会被跳过。与 `--sarif` 一样， 它独立于 `--format`。 --- ## 数据流与隐私 DockSec 的设计让你始终清楚什么数据离开了你的机器： - **扫描完全在本地进行。** Trivy、Hadolint 和安全评分都在你的机器上运行。 DockSec 绝不会将镜像内容上传到任何地方。 - **AI 分析仅发送被扫描的文件。** 当 AI 分析运行时，Dockerfile 或 compose 文件的内容（加上用于评分的漏洞数量简短摘要） 会被发送到你配置的 LLM 提供商。除此之外不会传输任何其他内容。 - **敏感信息在离开前会被脱敏。** 文件中看起来像敏感信息的值（密码、 令牌、API 密钥、私钥块）在内容发送到 AI 提供商之前会被遮蔽。键名保持可见， 因此暴露的凭据仍会被标记。使用 `--no-redact` 可选择退出。 - **支持完全本地化的 AI。** 使用 `--provider ollama` 将 AI 分析保留在 你自己的硬件上，或使用 `--scan-only` / `--offline` 完全跳过 AI。 - **无遥测。** DockSec 不收集任何使用数据，也不会向任何地方回传信息。 ### 离线模式 `--offline` 在无网络访问的情况下运行扫描。它使用磁盘上已有的 Trivy 漏洞数据库 （不更新数据库），并跳过 AI 分析和 Docker Scout 高级扫描，这两者都需要网络。 这是在气隙或锁定环境中进行扫描的最简单方式：```bash docksec --image-only -i myapp:latest --offline ``` 确保 Trivy DB 至少已下载过一次（任何先前的在线扫描都会完成此操作），然后再依赖 `--offline`。 ### 扫描结果缓存 镜像扫描结果会被缓存（默认：24 小时，可通过 `DOCKSEC_CACHE_TTL_HOURS` 覆盖），并以镜像的内容摘要为键，因此重新构建的标签 （例如被复用的 `:latest`）始终会获得全新的扫描。使用 `--no-cache`（或 `DOCKSEC_USE_CACHE=false`）可在某次运行中绕过缓存。 ### 拉取本地不存在的镜像 扫描本地不存在的镜像时会先拉取它。一个 compose 栈通常会指定该机器从未拉取过的镜像， 如果没有此功能，这些服务中的每一个都会被报告为未扫描。 设置 `DOCKSEC_PULL_MISSING_IMAGES=false` 可关闭此功能并改为失败，这在 按流量计费的连接或共享 runner 上值得这样做。无论此设置如何，`--offline` 都不会拉取。 --- ## AI 助手技能（`install-skill`） `docksec install-skill` 会将 DockSec 使用说明写入主流 AI 编程助手的知名上下文 文件中，这样在你的仓库中工作的助手就知道如何调用 DockSec：```bash docksec install-skill ``` 这会创建或更新： - `.claude/commands/docksec.md`（Claude Code 斜杠命令 `/docksec`） - `.cursor/rules/docksec.mdc`（Cursor） - `AGENTS.md`（Codex CLI）、`GEMINI.md`（Gemini CLI） - `.github/copilot-instructions.md`（GitHub Copilot） 这些文件是纯文本，你可以审查并提交；不会执行任何内容。重新运行该 命令会就地更新 DockSec 部分，而不是重复添加。 --- ## 功能特性 - **智能分析**：AI 解释漏洞对*你*特定设置意味着什么。 - **多 LLM 支持**：OpenAI、Anthropic Claude、Google Gemini，或通过 Ollama 使用本地模型。 - **隐私优先**：在任何内容到达 AI 提供商之前，敏感值会被脱敏，扫描完全在本地进行，且没有遥测。 - **Docker Compose 扫描**：检测编排层面的错误配置，并扫描 compose 文件中的所有服务。 - **深度集成**：结合 Trivy（漏洞）、Hadolint（代码检查）和 Docker Scout。 - **安全评分**：0-100 分及评级，用于随时间跟踪你的安全态势。 - **丰富格式**：HTML（交互式）、PDF、JSON、CSV、SARIF 和 CycloneDX SBOM。 - **CI/CD 就绪**：`--fail-on` 退出码、基线/棘轮模式、可审计豁免、JSON 输出到 stdout，以及 Marketplace 上的 GitHub Action。 - **离线模式**：使用本地 Trivy 数据库进行完全气隙扫描（`--offline`）。 - **AI 助手技能**：`docksec install-skill` 教会 Claude Code、Cursor、Copilot 等如何在你的仓库中运行 DockSec。 --- ## DockSec 对比 | 能力 | DockSec | Trivy（独立） | Snyk Container | Aikido | |---|---|---|---|---| | 许可证和成本 | 免费、开源（MIT） | 免费、开源（Apache 2.0） | 商业（有限免费层） | 商业（有限免费层） | | 治理 | OWASP Lab 项目，供应商中立 | 开源，由 Aqua 维护 | 单一供应商 | 单一供应商 | | 检测 CVE 和 Dockerfile 错误配置 | 是 | 是 | 是 | 是 | | 用通俗英语解释发现 | 是（AI 编写的上下文和影响） | 否（原始 CVE 数据） | 部分（严重性和修复提示） | 部分（平台中的 AI 摘要） | | 上下文相关的 Dockerfile 修复 | 是（带解释的具体重写） | 否（仅检测） | 是（基础镜像升级建议、修复 PR） | 是（AI AutoFix PR） | | Docker Compose（多服务）扫描 | 是（编排检查和逐服务扫描） | 部分（配置扫描，无逐服务展开） | 部分 | 部分 | | 基线/棘轮模式（仅对新发现失败） | 是 | 否 | 部分（平台策略） | 部分（平台策略） | | 可审计的逐发现豁免，含原因和到期时间 | 是 | 部分（.trivyignore，不强制原因） | 部分（平台策略） | 部分（平台策略） | | CI 原生输出（用于 GitHub Code Scanning 的 SARIF） | 是 | 是 | 是 | 是 | | SBOM 导出（CycloneDX） | 是（`--sbom`） | 是 | 是 | 是 | | AI 助手技能安装（Claude Code、Cursor、Copilot） | 是（`install-skill`） | 否 | 否 | 否 | | 完全离线/气隙运行 | 是（通过 Ollama 使用本地 LLM，仅扫描模式，无 API 密钥） | 仅扫描（无修复层） | 否（云平台） | 否（托管平台） | | 你的镜像数据保留在你的网络中 | 是 | 是 | 否 | 否 | | 自带 LLM/模型选择 | 是（OpenAI、Anthropic、Gemini 或本地 Ollama） | 不适用 | 否（专有 AI） | 否（专有 AI） | | 可自托管，无需平台部署 | 是 | 是 | 否 | 否 | | 供应商锁定 | 无 | 无 | 是 | 是 | | 安全评分（0-100）和多格式报告 | 是 | 部分（机器格式，无修复报告） | 部分（仪表板报告） | 部分（仪表板报告） | DockSec 是其中唯一将上下文相关的 Dockerfile 修复与完全开源、OWASP 治理、可本地运行的 设计相结合的工具。Snyk 和 Aikido 提供强大的 AI 修复，但仅作为商业云平台，会将你的数据发送到 它们的服务。Trivy 是开源且本地的，但止步于检测，不帮助你修复任何内容。DockSec 填补了 开发人员以及受监管或气隙团队的空缺，他们既需要修复指导，又需要完全控制自己的数据，且无需 任何成本。 --- ## 自动应用修复 `--fix` 会应用建议的 Dockerfile 更改中的机械子集， 重新扫描，并报告差异：```bash docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing docksec Dockerfile --scan-only --fix # apply, keeping a .bak ``` ## 工具 - [**AFL++**](https://github.com/AFLplusplus/AFLplusplus) - 基于 AFL 的模糊测试工具，具有许多改进。 - [**Angr**](https://github.com/angr/angr) - 一个强大的二进制分析平台，具有符号执行引擎。 - [**APKLab**](https://github.com/APKLab/APKLab) - 用于逆向工程 Android 应用的 VS Code 扩展。 - [**Apktool**](https://github.com/iBotPeaches/Apktool) - 用于逆向工程 Android APK 文件的工具。 - [**BinDiff**](https://github.com/google/bindiff) - 用于二进制文件的快速差异比较工具。 ``` --- [Read more](https://github.com/owasp/docksec)
