---

什么是 DockSec？

DockSec 是一个 OWASP 实验室项目，旨在弥合复杂的安全扫描结果与开发者可执行的修复措施之间的鸿沟。它集成了业界标准的扫描器（Trivy、Hadolint、Docker Scout）与 AI，提供上下文感知的安全分析。

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

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

所有扫描均在本地进行；唯一离开你机器的内容是你所选择的 AI 提供商收到的（已脱敏的）文件内容——而使用本地模型或仅扫描模式时，则完全不会有任何内容离开。参见数据流与隐私。

---

工作原理

DockSec 遵循五阶段流水线：

1. 扫描：在你的环境中本地运行 Trivy（镜像漏洞和 Dockerfile 错误配置）、 Hadolint 和 Docker Scout。
2. 优先排序：根据严重性结合其 EPSS 利用可能性对每个 CVE 发现进行排序，因此列表 按应先修复的内容排序，而非按先发现的内容排序。
3. 关联：检测利用链，即多个 独立发现组合成一条攻击路径——一个面向互联网的服务可以访问的带凭据数据库 是一条链，而非两个不相关的发现。 使用 API 密钥时，AI 会基于完整扫描输出进行推理，以排序、解释 并扩展这一过程。
4. 建议：生成可直接复制运行的修复命令以及具体的 Dockerfile 或 compose 更改，并说明它们能解决多少发现。
5. 报告：将可执行结果导出为 HTML、PDF、JSON、CSV、Markdown、SARIF 和 CycloneDX SBOM。

---

快速开始

1. 前置条件

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

要求	用途	安装
Python 3.12+	DockSec 本身	python.org
Trivy	所有扫描（必需）	brew install trivy 或 Trivy 文档
Hadolint	Dockerfile 检查	brew install hadolint 或 Hadolint 文档
Docker	镜像扫描（-i）	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