DockSec

AI 驱动的 Docker 安全扫描器，用通俗易懂的语言解释漏洞

什么是 DockSec？

DockSec 是一个 OWASP 实验室项目，旨在弥合复杂安全扫描结果与可操作的开发者修复方案之间的鸿沟。它将行业标准扫描器（Trivy、Hadolint、Docker Scout）与 AI 相结合，提供具有上下文感知能力的安全分析。

DockSec 不会用 200 多个 CVE 的列表让你不知所措，而是：

• 按优先级排序，只关注真正影响你特定容器配置的问题。
• 用通俗易懂的语言解释漏洞，而非仅仅堆砌安全术语。
• 针对你的 Dockerfile 提出具体的修复建议。
• 为你的团队生成专业、交互式的安全报告。

所有扫描均在本地进行；唯一会离开你机器的内容，是发送给你所选 AI 提供商的（已脱敏处理秘密信息的）文件内容——而如果使用本地模型或仅扫描模式，则任何内容都不会离开你的机器。请参阅数据流与隐私。

工作原理

DockSec 工作流程：从扫描到可操作的洞察

DockSec 遵循四阶段流水线：

1. 扫描：在你的环境中本地运行 Trivy、Hadolint 和 Docker Scout。
2. 分析：AI 关联所有扫描器的发现结果，以去除噪音并评估真实世界影响。
3. 建议：生成人类可读的解释和具体的修复步骤。
4. 报告：将可操作的结果导出为 HTML、PDF、JSON、CSV、SARIF 和 CycloneDX SBOM。

快速开始

1. 前提条件

DockSec 负责编排本地扫描器，因此需要：

或者让 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. 或使用 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

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 --no-color # also honors NO_COLOR

---

## 配置文件

在仓库根目录提交一个 `.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。

优先级

优先级从高到低：``` 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` 基于结构化发现项（镜像漏洞和 compose 配置错误）进行门禁。当 `--fail-on` 低于所请求的 `--severity` 时，扫描严重性会自动放宽，以便门禁能观察到这些发现项。

### 机器可读输出

`--json` 会将单个 JSON 对象打印到标准输出（扫描信息、漏洞、严重性计数以及任何 AI 发现项），而非人类可读的摘要，因此可直接通过管道传递给其他工具：```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

单独使用 --json 时不会写入任何报告文件；可将其与 --format 结合使用，以便在同一次运行中既写入文件又输出 JSON。在 --json 模式下，所有面向人类阅读的消息都会移至 stderr，因此 stdout 只会包含 JSON 数据。

用于 GitHub 代码扫描的 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**：一份适合电子表格处理的单个漏洞表。

> 关于 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`）可在单次运行中绕过缓存。

---

## 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（lint 检查）和 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 是这些工具中唯一将上下文相关的 Dockerfile 修复与完全开源、由 OWASP 治理、可本地运行的设计相结合的方案。Snyk 和 Aikido 提供强大的 AI 修复能力，但仅限于商业云平台，需要将你的数据发送到其服务。Trivy 是开源且本地的，但止步于检测，不会帮你修复任何问题。DockSec 填补了这一空白，为开发者以及受监管或隔离网络的团队提供修复指导和数据的完全控制权，且完全免费。

路线图

有关 DockSec 的未来方向，请参阅 ROADMAP.md：无需本地 Docker 守护进程的镜像仓库扫描、仓库级策略配置文件、Jenkins/GitLab/Azure DevOps 模板、官方容器镜像、Kubernetes 和 Helm 扫描等。欢迎在 issues 和 OWASP Slack 中提供反馈并投票确定优先级。

参与贡献

DockSec 的发展离不开社区贡献。无论你是开发者、设计师还是安全爱好者，都有很多参与方式：

• 代码贡献：修复 bug 或添加新功能。
• 文档：改进指南或创建教程。
• 问题报告：识别并报告 bug。
• 反馈：分享你的经验和建议。

要开始，请查看我们的贡献指南、行为准则和赞助指南。

领导团队与社区

DockSec 由一支致力于让容器安全更易用的专职团队领导：

• Advait Patel - 项目负责人
• Arkadii Yakovets - 项目联合负责人

在这里找到我们：

• OWASP 项目页面：owasp.org/DockSec/
• OWASP Slack：#project-docksec
• PyPI：pypi.org/project/docksec/
• Issues：报告 bug
• 变更日志：CHANGELOG.md