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

每次扫描结束时都会生成结果摘要：一个严重性表格、一个 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

在将任何内容发送给 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

该镜像读取与 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

---

## 常用命令```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

每个设置都是可选的；任何省略的设置都会回退到环境变量，然后再回退到内置默认值。完整的带注释示例见
[`examples/.docksec.yml`](https://github.com/owasp/docksec/blob/main/examples/.docksec.yml)。

### 优先级

优先级从高到低：```
CLI flag  >  environment variable  >  .docksec.yml  >  built-in default

### 优先级：先修复什么

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

### 机器可读输出

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

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

被抑制的发现项在评分、报告、`--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

确保 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

## 工具

- [**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) - 用于二进制文件的快速差异比较工具。
- [**Binwalk**](https://github.com/ReFirmLabs/binwalk) - 用于分析、逆向工程和提取固件映像的工具。
- [**Cutter**](https://github.com/rizinorg/cutter) - 基于 Rizin 构建的逆向工程平台。
- [**decomp2dbg**](https://github.com/mahaloz/decomp2dbg) - 将反编译器与调试器集成，以改善逆向工程工作流程。
- [**dnSpy**](https://github.com/dnSpy/dnSpy) - .NET 调试器和程序集编辑器。
- [**Frida**](https://github.com/frida/frida) - 面向开发人员、逆向工程师和安全研究人员的动态代码插桩工具包。
- [**Ghidra**](https://github.com/NationalSecurityAgency/ghidra) - 由 NSA 研究理事会创建的软件逆向工程（SRE）套件。
- [**GhidraMCP**](https://github.com/LaurieWired/GhidraMCP) - 一个模型上下文协议服务器，允许 LLM 自主逆向工程应用程序。
- [**Hopper**](https://www.hopperapp.com/) - 用于 macOS、Linux 和 Windows 的反汇编器和反编译器。
- [**IDA Pro**](https://hex-rays.com/ida-pro/) - 事实上的标准逆向工程工具。
- [**ImHex**](https://github.com/WerWolv/ImHex) - 面向逆向工程师、程序员以及重视其宝贵时间和视网膜的 24/7 工作人士的十六进制编辑器。
- [**JADX**](https://github.com/skylot/jadx) - 用于从 Android Dex 和 Apk 文件生成 Java 源代码的 Dex 到 Java 反编译器。
- [**Kaitai Struct**](https://github.com/kaitai-io/kaitai_struct) - 一种用于描述二进制数据格式的语言。
- [**LIEF**](https://github.com/lief-project/LIEF) - 用于解析、修改和抽象 ELF、PE 和 MachO 格式的库。
- [**Manticore**](https://github.com/trailofbits/manticore) - 用于分析智能合约和二进制文件的符号执行工具。
- [**Miasm**](https://github.com/cea-sec/miasm) - 逆向工程框架。
- [**PE-bear**](https://github.com/hasherezade/pe-bear) - 用于恶意软件分析的 PE 文件逆向工程工具。
- [**pwndbg**](https://github.com/pwndbg/pwndbg) - 使 GDB 不再令人痛苦的 GDB 插件。
- [**pwntools**](https://github.com/Gallopsled/pwntools) - 用于 CTF 框架和漏洞利用开发的快速利用开发库。
- [**radare2**](https://github.com/radareorg/radare2) - 面向 UNIX 的逆向工程框架和命令行工具集。
- [**Rizin**](https://github.com/rizinorg/rizin) - 一个免费且开源的逆向工程框架。
- [**ROPgadget**](https://github.com/JonathanSalwan/ROPgadget) - 该工具允许你在二进制文件中搜索你的 ROP 利用所需的 gadget。
- [**ropper**](https://github.com/sashs/Ropper) - 显示有关二进制文件的信息，并查找用于构建 ROP 链的 gadget。
- [**Unicorn**](https://github.com/unicorn-engine/unicorn) - 基于 QEMU 的轻量级、多平台、多架构 CPU 模拟器框架。
- [**x64dbg**](https://github.com/x64dbg/x64dbg) - 适用于 Windows 的开源 x64/x32 调试器。```text
Applied 4 change(s)
  - added --no-install-recommends on line(s) 2  [DS029]
  - converted ADD to COPY on line(s) 3  [DL3020]
  - replaced 'USER root' with 'USER appuser' on line 5  [DS002]
  - inserted a placeholder HEALTHCHECK before line 6  [DS026]

Original saved to Dockerfile.bak
Dockerfile findings: 7 -> 2 (5 resolved)