dockerfile-validator

Dockerfile 验证器

通过确定性的执行阶段、清晰的严重性报告，以及在工具或网络访问受限时明确的回退方案来验证 Dockerfile。

触发语句

用户提出以下任务时使用此技能：

• “验证这个 Dockerfile”
• “检查／校验我的 Dockerfile”
• “对 Dockerfile 进行安全扫描”
• “优化 Docker 镜像大小／构建时间”
• “合并前审查 Dockerfile”
• “查找 Dockerfile.prod/Dockerfile.dev 中的问题”

使用／不使用

以下情况使用此技能：

• 语法和 lint 验证
• 安全和机密信息检查
• 最佳实践和性能审查
• 在 CI/CD 或生产环境中使用前加固 Dockerfile

以下情况不要使用此技能：

• 从零生成新的 Dockerfile（使用 dockerfile-generator）
• 运行容器、调试运行时行为或操作镜像仓库

此技能中的本地文件

• 验证脚本：scripts/dockerfile-validate.sh
• 参考资料：
  • references/security_checklist.md
  • references/optimization_guide.md
  • references/docker_best_practices.md
• Dockerfile 示例：examples/*.Dockerfile

确定性执行流程（必需）

按顺序运行以下步骤。除非适用已说明的回退分支，否则不得跳过步骤。

1. 预检和路径设置

假设仓库根目录为工作目录：

cd /path/to/repo
SKILL_DIR="devops-skills-plugin/skills/dockerfile-validator"
TARGET_DOCKERFILE="Dockerfile"   # replace when user provides a path

运行工具前验证输入：

test -f "$SKILL_DIR/scripts/dockerfile-validate.sh"
test -f "$TARGET_DOCKERFILE"

如果任一检查失败，请停止并报告确切的缺失路径。

2. 明确读取目标 Dockerfile

使用明确的文件读取命令（不要使用抽象的“读取工具”表述）：

sed -n '1,220p' "$TARGET_DOCKERFILE"

长文件必要时：

sed -n '220,440p' "$TARGET_DOCKERFILE"

3. 运行验证脚本

主要命令：

bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE"

用于结构化报告的可选捕获运行：

bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE" | tee /tmp/dockerfile-validator.out

4. 按严重性对发现进行分类（标准）

使用以下标准严重性模型：

• Critical
  • 硬编码的机密信息／凭据
  • 高风险上下文中的显式 root 运行时
  • 影响重大的安全策略违规
• High
  • Checkov 容器加固检查失败
  • 可能导致构建不安全／不可靠的 hadolint 错误
  • 缺少或不安全的运行时用户配置（USER）
• Medium
  • :latest 镜像标签、缺少版本固定、缓存清理遗漏
  • 构建缓存效率低下和分层安装反模式
• Low
  • 样式／信息提示及不阻塞的优化建议

5. 无问题快速路径（必需）

如果验证没有发现可采取行动的问题：

• 返回简洁的通过摘要。
• 不要打开参考文件。
• 不要生成修复差异。

满足以下所有条件时使用快速路径：

• 脚本报告整体通过。
• 没有安全检查失败。
• 没有需要用户采取行动的错误／警告发现。

6. 参考资料加载规则（仅在存在发现时）

只读取与实际发现相匹配的参考资料。每个所需文件只读取一次。

问题与参考资料的对应关系：

问题类别	触发示例	读取此文件
机密信息、root 用户、暴露的敏感端口、加固缺陷	CKV_DOCKER_*、硬编码令牌／密码、root 运行时	references/security_checklist.md
镜像大小、层数、多阶段构建机会、缓存效率、.dockerignore 缺陷	RUN 过多、单阶段构建且包含构建依赖、缓存未命中	references/optimization_guide.md
标签版本固定、指令用法、COPY 与 ADD、WORKDIR/CMD/ENTRYPOINT 约定	:latest、未固定版本的软件包、指令级最佳实践	references/docker_best_practices.md

明确的读取命令：

sed -n '1,220p' "$SKILL_DIR/references/security_checklist.md"
sed -n '1,220p' "$SKILL_DIR/references/optimization_guide.md"
sed -n '1,220p' "$SKILL_DIR/references/docker_best_practices.md"

定向提取：

rg -n "USER|secrets|EXPOSE|HEALTHCHECK" "$SKILL_DIR/references/security_checklist.md"
rg -n "multi-stage|cache|layer|dockerignore" "$SKILL_DIR/references/optimization_guide.md"
rg -n "FROM|COPY|ADD|WORKDIR|CMD|ENTRYPOINT|latest" "$SKILL_DIR/references/docker_best_practices.md"

7. 生成标准报告输出

每次非快速路径运行均使用此模板：

## Dockerfile Validation Report
- Target: <path>
- Command: `bash <skill-script> <target>`
- Overall result: PASS | FAIL | PARTIAL (fallback)

### Critical
- <issue or `None`>

### High
- <issue or `None`>

### Medium
- <issue or `None`>

### Low
- <issue or `None`>

### Recommended Fixes
- <specific code-level fix per actionable issue>

### References Used
- <list only files actually read>

### Fallbacks Used
- `None` or exact fallback branch + reason

8. 提供应用修复的选项

报告完成后：

• 询问用户是否应用修复。
• 如果用户同意，修改 Dockerfile 并重新运行验证。

回退行为（明确）

主要脚本无法完成时，使用确定性的回退分支并报告所用分支。

回退方案 A：Python/工具安装受限

条件：

• 脚本因工具安装失败而退出（例如缺少 Python、软件包安装受阻或环境受限）。

操作：

1. 说明主要故障及原因。
2. 执行最低限度的手动检查：

# Basic syntax signal (if Docker is available)
DOCKERFILE_DIR="$(dirname "$TARGET_DOCKERFILE")"
docker build --no-cache -f "$TARGET_DOCKERFILE" "$DOCKERFILE_DIR"

# High-value static checks
grep -nEi "^[[:space:]]*FROM[[:space:]]+.*:latest" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*(ENV|ARG)[[:space:]].*(password|secret|token|api[_-]?key)[[:space:]]*=" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*USER[[:space:]]+(root|0(:0)?)$" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*HEALTHCHECK[[:space:]]+" "$TARGET_DOCKERFILE" || true

3. 将结果归类为 PARTIAL，并明确标出跳过的检查。

回退方案 B：无法使用 hadolint，但 Docker 可用

使用 hadolint 容器镜像：

docker run --rm -i hadolint/hadolint < "$TARGET_DOCKERFILE"

回退方案 C：没有 Docker、hadolint 或 checkov

仅运行手动正则表达式检查（回退方案 A 的第 2 步），明确标记为 PARTIAL，并说明跳过了哪些扫描器。

快速命令集

验证一个 Dockerfile

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile

验证备用文件

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile.prod

验证 skill 示例

cd /path/to/repo/devops-skills-plugin/skills/dockerfile-validator
bash scripts/dockerfile-validate.sh examples/good-example.Dockerfile
bash scripts/dockerfile-validate.sh examples/security-issues.Dockerfile

运行回归检查（CI 入口点）

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh

适用于必须强制执行 ShellCheck 的 CI 环境的可选严格模式：

STRICT_SHELLCHECK=true bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh

渐进式披露规则

• 始终先读取目标 Dockerfile。
• 除非检查结果需要，否则不要读取任何参考文件。
• 只读取与问题到参考资料映射相匹配的参考文件。
• 除非出现新的问题类别，否则不要重复读取同一参考文件。

完成标准

只有满足以下所有条件，才认为此技能执行已完成：

• 触发条件与 Dockerfile 验证、lint、安全或优化请求相符。
• 已明确验证目标 Dockerfile 路径。
• 已执行验证命令（或明确说明采用了回退方案）。
• 已按严重性级别（Critical、High、Medium、Low）报告检查结果。
• 参考资料的使用与问题类别相符，并已明确列出。
• 无问题的快速路径跳过了不必要的参考文件读取。
• 如果已应用修复，已重新运行验证并报告最终状态。

资源

• 脚本：scripts/dockerfile-validate.sh
• CI/回归入口点：scripts/test_validate.sh
• 安全参考资料：references/security_checklist.md
• 优化参考资料：references/optimization_guide.md
• 最佳实践参考资料：references/docker_best_practices.md
• 示例：examples/good-example.Dockerfile、examples/bad-example.Dockerfile、examples/security-issues.Dockerfile、examples/python-optimized.Dockerfile、examples/golang-distroless.Dockerfile

来源链接

• Docker 构建最佳实践
• Dockerfile 参考
• Checkov Dockerfile 扫描
• hadolint