Dockerfile 验证器

概览

全面的 Dockerfile 验证工具包，包括语法检查、安全扫描、最佳实践执行和构建优化分析。这项技能使用一个单一的自包含脚本（dockerfile-validate.sh）来处理所有事情：工具安装、验证和清理。

主要特点：

✅ 单一脚本执行 - 不依赖其他脚本
✅ 如果未找到 hadolint 和 Checkov，则自动在 Python 虚拟环境中安装
✅ 运行所有 4 个验证阶段（语法、安全、最佳实践、优化）
✅ 使用 bash trap 在退出时自动清理（成功或失败）
✅ 零配置要求

何时使用这项技能

在以下情况下调用这项技能：

验证 Dockerfile 语法和结构
检查 Dockerfile 中的安全漏洞
优化 Docker 镜像构建性能
确保遵守官方 Docker 最佳实践
调试 Dockerfile 错误或构建问题
对容器镜像进行安全审计
用户要求“验证”、“lint”、“检查”或“优化”Dockerfile
在提交到版本控制之前审查 Dockerfile
分析现有 Dockerfile 以寻求改进

不要为此技能使用

生成新的 Dockerfile（使用 dockerfile-generator）
构建或运行容器（使用 docker build/run 命令）
调试运行中的容器（使用 docker logs, docker exec）
管理 Docker 镜像或注册表

快速开始

单个命令验证任何 Dockerfile：

bash scripts/dockerfile-validate.sh Dockerfile

就是这样！脚本自动：

检查 hadolint 和 Checkov 是否已安装
如果需要，则在 Python 虚拟环境中临时安装它们
运行所有 4 个验证阶段（语法、安全、最佳实践、优化）
在退出时清理临时安装

验证工作流程

dockerfile-validate.sh 脚本运行一个全面的 4 阶段验证：

┌─────────────────────────────────────────────────────────┐
│  Auto-Install (if needed)                               │
│  ├─> Check for hadolint and Checkov                     │
│  ├─> Install in Python venvs if not found               │
│  └─> Set TEMP_INSTALL=true (triggers cleanup on exit)   │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [1/4] 语法验证（hadolint）                     │
│  ├─> Dockerfile 语法检查                         │
│  ├─> 指令验证                             │
│  ├─> Shell 脚本验证（通过 ShellCheck）           │
│  └─> 100+ 内置 linting 规则                        │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [2/4] 安全扫描（Checkov）                          │
│  ├─> 安全策略验证                         │
│  ├─> 硬编码秘密检测                         │
│  ├─> 端口暴露检查                               │
│  ├─> USER 指令验证                          │
│  └─> 50+ 安全策略                              │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [3/4] 最佳实践验证（自定义）               │
│  ├─> 基础镜像标签验证（:latest 检查）          │
│  ├─> USER 指令执行（非 root）              │
│  ├─> HEALTHCHECK 存在                               │
│  ├─> 层效率（RUN 命令计数）               │
│  ├─> 包缓存清理验证                 │
│  ├─> 硬编码秘密检测                        │
│  └─> COPY 排序以提高构建缓存效率           │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  [4/4] 优化分析（自定义）                   │
│  ├─> 基础镜像大小分析（Alpine 建议）      │
│  ├─> 多阶段构建机会                    │
│  ├─> 层计数优化                           │
│  ├─> .dockerignore 文件检查                           │
│  └─> 构建结构建议                    │
└─────────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────────┐
│  Auto-Cleanup (bash trap - always runs)                 │
│  └─> Remove temp venvs if TEMP_INSTALL=true             │
└─────────────────────────────────────────────────────────┘

清理保证： 使用 trap cleanup EXIT INT TERM 确保在以下情况下运行清理：

✅ 正常退出
✅ 验证失败
✅ Ctrl+C（中断）
✅ 脚本错误

核心能力

1. 使用 hadolint 进行语法验证

目的： 在构建之前 lint Dockerfile 语法并捕获常见错误。

工具： hadolint - 一个 Dockerfile linter，使用 ShellCheck 验证指令和嵌入的 bash 命令。

安装：

如果未找到，验证脚本会自动安装工具。如需永久安装：

# macOS
brew install hadolint

# Linux
wget -O ~/.local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
chmod +x ~/.local/bin/hadolint

# Docker（备用选项）
docker pull hadolint/hadolint

工作流程：

# 在 Dockerfile 上运行 hadolint
hadolint Dockerfile

# 运行并输出 JSON 格式以便解析
hadolint --format json Dockerfile

# 运行并忽略特定规则
hadolint --ignore DL3006 --ignore DL3008 Dockerfile

# 如果未安装，则使用 Docker
docker run --rm -i hadolint/hadolint < Dockerfile

常见问题检测：

DL 前缀规则（hadolint 特定）：

DL3000 - 使用绝对 WORKDIR 路径
DL3001 - 对于某些 bash 命令在 Docker 容器中没有意义
DL3002 - 最后一个 USER 不应为 root
DL3003 - 使用 WORKDIR 切换目录
DL3004 - 不要使用 sudo
DL3006 - 总是标记图像版本（避免使用 :latest）
DL3007 - 不建议使用 latest
DL3008 - 在 apt-get install 中固定版本
DL3009 - 安装后删除 apt-cache
DL3013 - 在 pip install 中固定版本
DL3014 - 对于 apt-get 使用 -y 开关
DL3015 - 避免使用 apt-get 的附加包
DL3016 - 在 npm install 中固定版本
DL3018 - 在 apk add 中固定版本
DL3019 - 使用 --no-cache 与 apk add
DL3020 - 使用 COPY 而不是 ADD 用于文件
DL3021 - 从先前阶段复制应通过名称引用
DL3022 - COPY --from 应引用先前定义的 FROM 别名
DL3025 - 对 CMD 和 ENTRYPOINT 使用 JSON 表示法
DL3059 - 多个连续 RUN 指令（组合以提高层效率）

SC 前缀规则（ShellCheck 用于 RUN 命令）：

SC1091 - 不跟随源文件
SC2046 - 引用以防止单词分割
SC2086 - 双引号以防止 globbing
SC2164 - 使用 cd … || exit 进行错误处理

规则严重性级别：

error - 可能会导致构建失败或运行时问题
warning - 违反最佳实践，应该修复
info - 改进建议
style - 代码风格偏好

最佳实践：

在每次 docker build 之前运行 hadolint
集成到 CI/CD 管道中
为项目特定规则配置 .hadolint.yaml
先解决错误再解决警告
谨慎使用内联忽略注释，并提供理由

2. 使用 Checkov 进行安全扫描

目的： 在镜像部署之前检测安全配置错误和漏洞。

工具： Checkov - 一个策略即代码的安全扫描器，内置 50+ Dockerfile 策略。

安装：

如果未找到，验证脚本会自动在隔离的 Python venv 中安装 Checkov。如需永久安装：

# 直接安装
pip3 install checkov

# macOS Homebrew
brew install checkov

# 验证安装
checkov --version

工作流程：

# 扫描 Dockerfile
checkov -f Dockerfile --framework dockerfile

# 扫描目录（查找所有 Dockerfiles）
checkov -d . --framework dockerfile

# 扫描并输出紧凑结果（仅失败）
checkov -f Dockerfile --framework dockerfile --compact

# 扫描并输出 JSON 格式
checkov -f Dockerfile --framework dockerfile -o json

# 跳过特定检查
checkov -f Dockerfile --framework dockerfile --skip-check CKV_DOCKER_2

常见安全检查：

通用安全：

CKV_DOCKER_1 - 确保没有暴露端口 22（SSH）
CKV_DOCKER_2 - 确保存在 HEALTHCHECK 指令
CKV_DOCKER_3 - 确保已创建并使用用户（非 root）
CKV_DOCKER_4 - 确保没有使用 ADD（更喜欢 COPY）
CKV_DOCKER_5 - 确保没有单独使用 update 而不安装
CKV_DOCKER_6 - 确保 SHELL 指令使用 -o pipefail
CKV_DOCKER_7 - 确保基础镜像使用特定版本标签
CKV_DOCKER_8 - 确保最后一个 USER 不是 root
CKV_DOCKER_9 - 确保没有使用 apt-get dist-upgrade
CKV_DOCKER_10 - 确保没有单独使用 yum 更新

包管理：

检查是否缺少包管理器缓存清理
验证安装的包的版本固定
检测 apt-get 使用了 --no-install-recommends

秘密检测：

在 ENV 或 ARG 中扫描潜在的秘密
检测硬编码的凭据
识别暴露的 API 密钥或令牌

输出格式：

cli - 人类可读的控制台输出（默认）
json - JSON 格式，用于程序性解析
sarif - SARIF 格式，用于 IDE 集成
gitlab_sast - GitLab 安全仪表板格式
junitxml - JUnit XML，用于 CI 集成

理解结果：

检查："确保已向容器镜像添加 HEALTHCHECK 指令"
    对于资源 Dockerfile 失败。
    文件：/Dockerfile:1-20
    指南：https://docs.bridgecrew.io/docs/ensure-that-healthcheck-instructions-have-been-added-to-container-images

    1  | FROM node:18
    20 | CMD ["node", "server.js"]

抑制误报：

在内联注释中添加以抑制特定检查：

# checkov:skip=CKV_DOCKER_2:Health check not applicable for this init container
FROM alpine:3.21
...

退出代码：

0 - 所有检查通过
1 - 一个或多个检查失败

最佳实践：

在 hadolint 之后运行 Checkov（先语法，然后安全）
首先解决高严重性问题
用清晰的的理由记录所有抑制
集成到 CI/CD 管道中
定期审查新策略
结合镜像漏洞扫描（例如，trivy, snyk）

3. 最佳实践验证

目的： 确保 Dockerfiles 遵循官方 Docker 最佳实践和当前建议。

自定义验证检查：

1. 基础镜像验证：

# 检查 :latest 标签的使用
grep -E "^FROM.*:latest" Dockerfile

# 推荐特定标签或摘要固定
# 好的：FROM alpine:3.21
# 更好的：FROM alpine:3.21@sha256:digest

2. 多阶段构建检测：

# 计算 FROM 语句的数量
grep -c "^FROM" Dockerfile

# 单个 FROM 暗示可能进行多阶段优化

3. USER 指令检查：

# 确保在 CMD/ENTRYPOINT 之前设置了 USER
# 检查最后一个 USER 是否不是 root
grep "^USER" Dockerfile

4. HEALTHCHECK 存在：

# 验证服务定义了 HEALTHCHECK
grep "^HEALTHCHECK" Dockerfile

5. 层效率：

# 计算 RUN 命令的数量（>5 表示组合机会）
grep -c "^RUN" Dockerfile

# 检查 apt-get 更新是否与安装分开
grep -A1 "^RUN.*apt-get update" Dockerfile

6. 包管理器缓存清理：

# 验证在同一 RUN 层中清理缓存
grep "rm -rf /var/lib/apt/lists" Dockerfile
grep "--no-cache" Dockerfile  # 对于 apk

最佳实践清单：

基础镜像：

✓ 使用特定版本标签，而不是 :latest
✓ 考虑使用 Alpine 变体以减小大小
✓ 固定摘要以实现可复制性
✓ 使用经过验证的发布者提供的官方镜像
✓ 扫描基础镜像以查找漏洞

层优化：

✓ 使用 && 组合相关 RUN 命令
✓ 从最不频繁更改到最频繁更改的顺序排列指令
✓ 在源代码之前复制包文件
✓ 在同一层中清理包管理器缓存
✓ 使用 .dockerignore 排除不必要的文件

安全：

✓ 以非 root 用户身份运行（USER 指令）
✓ 不要安装不必要的包（–no-install-recommends）
✓ 不要硬编码秘密（使用构建秘密或运行时配置）
✓ 使用 COPY 而不是 ADD（除非提取归档）
✓ 避免使用 curl | bash 安装

多阶段构建：

✓ 将构建依赖项与运行时分开
✓ 明确命名阶段（FROM … AS stagename）
✓ 仅复制必要的工件
✓ 使用最小的运行时基础镜像

运行时配置：

✓ 为服务定义 HEALTHCHECK
✓ 对 ENTRYPOINT 和 CMD 使用 exec 形式
✓ 将 WORKDIR 设置为绝对路径
✓ 使用 EXPOSE 文档公开端口
✓ 使用 LABEL 添加元数据

构建性能：

✓ 通过适当的指令顺序利用构建缓存
✓ 使用 BuildKit 功能（–mount=type=cache）
✓ 使用 .dockerignore 减少上下文大小
✓ 在可能的情况下并行化多阶段构建

4. 优化分析

目的： 识别减少镜像大小、构建时间和层数的机会。

优化类别： 1. 镜像大小缩减：

# 差：完整发行版
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl

# 好：最小发行版
FROM alpine:3.21
RUN apk add --no-cache curl

# 更好：多阶段与无发行版
FROM golang:1.21 AS build
WORKDIR /app
COPY . .
RUN go build -o myapp

FROM gcr.io/distroless/base-debian11
COPY --from=build /app/myapp /
ENTRYPOINT ["/myapp"]

2. 层优化：

# 差：单独的 RUN 命令（创建许多层）
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y git
RUN apt-get install -y vim

# 好：组合 RUN（单层）
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    git \
    vim \
    && rm -rf /var/lib/apt/lists/*

3. 构建缓存效率：

# 差：全部复制，然后安装依赖项
COPY . /app
RUN pip install -r requirements.txt

# 好：首先复制依赖文件
COPY requirements.txt /app/
RUN pip install -r requirements.txt
COPY . /app

4. 多阶段构建机会：

# 检测单阶段构建，这些构建可以从分离中受益
# 查看：
# - 安装了构建工具但在运行时不需要
# - 复制了源代码但只需要二进制文件
# - 开发依赖项与运行时混合

优化指标：

层数： 层数越少 = 镜像越小
镜像大小： 最小基础 + 清理 = 下载量越小
构建时间： 缓存命中 + 并行阶段 = 构建速度越快
攻击面： 包越少 = 漏洞越少

参考文档：

加载详细的最佳实践：

references/docker_best_practices.md - 官方 Docker 建议
references/optimization_guide.md - 层和大小优化技术

5. .dockerignore 验证

目的： 确保通过排除不必要的文件来优化构建上下文。

验证检查：

# 检查是否存在 .dockerignore
if [ ! -f .dockerignore ]; then
    echo "WARNING: .dockerignore file not found"
fi

# 应包括的常见模式
.git
.gitignore
README.md
.env
*.log
node_modules
*.md
.dockerignore
Dockerfile*
docker-compose*.yml

.dockerignore 的好处：

减少构建上下文大小
更快的构建（传输的数据更少）
防止意外的秘密泄露
排除仅在开发中使用的文件

最佳实践：

对于非平凡的项目始终创建 .dockerignore
包括 .git 目录
排除本地配置文件（.env, *.local）
除非需要在镜像中使用，否则排除文档
排除测试文件和测试数据
模式语法类似于 .gitignore

工具先决条件

验证脚本如果未找到工具会自动安装。不需要手动安装。

对于永久安装：

# 安装 hadolint
brew install hadolint  # macOS

# 安装 Checkov
pip3 install checkov

最低版本：

hadolint: >= 2.12.0
Checkov: 最新（最新的策略）
Python: >= 3.8（临时安装）
Docker: >= 20.10（可选，用于测试构建）

测试自动安装和清理：

要测试即使工具已安装时的临时安装和清理功能：

# 强制临时安装以进行测试
FORCE_TEMP_INSTALL=true bash scripts/dockerfile-validate.sh Dockerfile

这将：

在临时 Python 虚拟环境中安装 hadolint 和 Checkov
使用临时安装运行所有验证
在退出时清理临时虚拟环境（成功或失败）

处理缺失工具

当验证工具未安装时：

缺少工具的工作流程

检测缺失工具：
- 尝试运行 hadolint 或 Checkov
- 如果命令失败，记录缺少哪个工具
完成可用验证：
- 继续自定义最佳实践检查
- 提供部分验证结果
- 清楚地指明哪些检查被跳过

提示用户安装：

对于 hadolint：

hadolint 未安装。脚本将自动安装它。

对于永久安装：
- macOS: brew install hadolint
- Linux: wget -O ~/.local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 && chmod +x ~/.local/bin/hadolint
- Docker: docker pull hadolint/hadolint

hadolint 提供全面的 Dockerfile 语法检查和最佳实践检查。

对于 Checkov：

Checkov 未安装。是否要安装它？

安装选项：
- 推荐：pip3 install checkov
- macOS: brew install checkov

Checkov 提供 50+ Dockerfile 策略的安全扫描。
安装并重新运行验证？（y/N）

如果用户选择安装：
- 提供安装命令
- 等待完成
- 验证：hadolint --version 或 checkov --version
- 重新运行完整验证
如果用户拒绝：
- 继续部分结果
- 文档跳过的检查
- 建议将来安装以进行验证

工具优先级

必需（始终运行）：

自定义最佳实践验证
文件存在检查

推荐（如果缺失则提供安装）：

hadolint - 语法和最佳实践 linting
Checkov - 安全扫描

可选：

docker - 用于测试构建
trivy - 用于漏洞扫描（补充）

错误故障排除

常见问题和解决方案

错误：FROM 指令必须是第一个非注释指令

解决方案：将定义基础镜像标签的 ARG 移动到 FROM 之前
ARG VERSION=18
FROM node:${VERSION}

错误：未知指令（拼写错误）

解决方案：检查指令拼写（RUN, COPY, FROM 等）
常见拼写错误：RUNS, COPIES, FRUM

错误：链式 RUN 命令失败

解决方案：添加 set -e 或检查各个命令的成功
RUN apt-get update && apt-get install -y package || exit 1

错误：COPY 失败：文件未找到

解决方案：检查文件路径是否相对于构建上下文
验证文件存在且未被 .dockerignore 排除

安全：检测到硬编码的秘密

解决方案：使用构建秘密（BuildKit）
# 而不是：ENV API_KEY=secret123
# 使用：docker build --secret id=api_key,src=api_key.txt

性能：构建缓慢

解决方案：
1. 优化层缓存（首先复制包文件）
2. 使用 .dockerignore 减少上下文
3. 启用 BuildKit：export DOCKER_BUILDKIT=1
4. 使用多阶段构建

资源

scripts/

dockerfile-validate.sh

单一自包含验证脚本
如果需要则自动安装 hadolint 和 Checkov
运行所有 4 个验证阶段（语法、安全、最佳实践、优化）
在退出时自动清理
用法：bash scripts/dockerfile-validate.sh [Dockerfile]

examples/

good-example.Dockerfile - 展示最佳实践和最优结构

bad-example.Dockerfile - 常见错误和反模式

security-issues.Dockerfile - 故意的安全漏洞，用于测试

python-optimized.Dockerfile - Python 特定的优化和多阶段构建

golang-distroless.Dockerfile - 使用无发行版基础镜像的最小 Go 应用程序

.dockerignore.example - 构建上下文优化的示例 .dockerignore

references/

docker_best_practices.md - 官方 Docker 建议和建议

optimization_guide.md - 层优化和镜像大小缩减技术

security_checklist.md - 容器安全最佳实践

强制工作流要求

重要： 使用这项技能时，您必须按顺序遵循以下步骤：

预验证（必需）

首先阅读 Dockerfile - 总是使用阅读工具检查 Dockerfile，然后再运行验证。这有助于您理解上下文并提供更好的建议。

验证（必需）

运行验证脚本 - 执行 bash scripts/dockerfile-validate.sh <Dockerfile> 以运行所有 4 个验证阶段。

后验证（必需）

按严重程度总结发现 - 验证完成后，提供清晰的总结，按以下顺序组织：
- 严重问题（安全漏洞、硬编码秘密）
- 高优先级（缺少 USER、HEALTHCHECK、:latest 标签）
- 中等优先级（层优化、版本固定）
- 低优先级（风格、信息性）
提出具体修复措施 - 对于发现的每个问题，提供具体的代码示例，展示如何修复它。您必须使用阅读工具在提出修复建议之前加载相应的参考文件：
- references/security_checklist.md - 对于与安全相关的修复
- references/optimization_guide.md - 对于性能/大小改进
- references/docker_best_practices.md - 对于一般最佳实践
注意： 即使您事先了解内容，也总是在后验证阶段明确阅读参考文件，以确保修复建议遵循权威模式。
提供应用修复的机会 - 询问用户是否希望您将提出的修复措施应用到他们的 Dockerfile 中。

参考文件使用

重要： 在运行验证后，您必须使用阅读工具明确加载相应的参考文件，然后再提出修复措施。这确保修复建议准确并遵循权威模式。

工作流程：

从验证输出中识别问题类型（安全、优化、最佳实践）
使用阅读工具加载匹配的参考文件
应用参考文件中的模式提出修复措施

问题类型	参考文件	操作
安全问题（秘密、USER、端口）	`references/security_checklist.md`	在提出安全修复之前阅读
尺寸/性能优化	`references/optimization_guide.md`	在提出优化修复之前阅读
一般最佳实践	`references/docker_best_practices.md`	在提出最佳实践修复之前阅读

示例：

# 在验证发现安全问题后：
1. 使用阅读工具：阅读 references/security_checklist.md
2. 应用文件中的修复模式到特定问题
3. 根据参考内容提出代码示例的修复措施

工作流示例

示例 1：验证单个 Dockerfile

用户："验证我的 Dockerfile"

步骤：
1. 使用阅读工具阅读 Dockerfile 以理解结构
2. 运行验证脚本：bash scripts/dockerfile-validate.sh Dockerfile
3. 从所有 4 个阶段（hadolint、Checkov、最佳实践、优化）中查看输出
4. 按严重程度组织发现的总结（关键 → 低）
5. 使用阅读工具加载相关参考文件：
   - 阅读 references/security_checklist.md（如果发现安全问题）
   - 阅读 references/optimization_guide.md（如果发现优化问题）
   - 阅读 references/docker_best_practices.md（如果发现最佳实践问题）
6. 根据参考内容提出具体的代码示例修复措施
7. 询问用户："您希望我应用这些修复措施吗？"
8. 如果用户同意，则应用修复

示例 2：全面的多 Dockerfile 验证

用户："检查我项目中的所有 Dockerfiles"

步骤：
1. 查找所有 Dockerfile* 文件
2. 顺序验证每个文件
3. 聚合结果
4. 识别跨文件的常见问题
5. 提供统一报告
6. 建议项目范围的改进

示例 3：安全审计

用户："对我 Dockerfile 进行安全审计"

步骤：
1. 运行 Checkov 安全扫描
2. 运行 hadolint 安全规则（DL3* 系列）
3. 检查硬编码的秘密
4. 验证 USER 指令
5. 检查基础镜像漏洞
6. 提供以安全为重点的报告
7. 优先考虑关键发现

示例 4：优化审查

用户："如何优化我的 Dockerfile？"

步骤：
1. 分析当前层结构
2. 识别多阶段机会
3. 检查构建缓存效率
4. 建议基础镜像替代品
5. 计算潜在的尺寸节省
6. 提供前后比较
7. 如果批准，则实施优化

与其他技能的集成

这项技能与以下技能很好地结合使用：

dockerfile-generator - 生成优化的 Dockerfiles
k8s-yaml-validator - 验证引用 Docker 镜像的 Kubernetes 部署
helm-validator - 验证带有容器配置的 Helm 图表

注释

总是在构建镜像之前进行验证
在优化之前解决安全问题
在应用修复后测试构建
为可复制性固定基础镜像版本
对于编译语言使用多阶段构建
保持生产镜像最小（无发行版、Alpine）
永远不要提交带有硬编码秘密的 Dockerfiles
用清晰的的理由记录内联抑制
定期更新基础镜像以获取安全补丁
将验证集成到 CI/CD 管道中

来源

这项技能基于来自权威来源的综合研究：

官方 Docker 文档：

安全指南：

最佳实践资源：