container-hadolintSkill container-hadolint

container-hadolint

概述

Hadolint 是一个 Dockerfile 静态代码分析工具，它使用 100 多条内置规则，根据 CIS Docker 基准测试来验证容器构建文件的安全性和最佳实践。使用场景包括：(1) 分析 Dockerfile 以查找安全配置错误和反模式，(2) 在 CI/CD 管道中强制执行容器镜像安全最佳实践，(3) 在容器构建中检测硬编码的秘密和凭证，(4) 验证 CIS Docker 基准测试要求的合规性，(5) 将左移容器安全性整合到开发人员工作流程中，(6) 为不安全的 Dockerfile 指令提供补救指导。

快速开始

安装 Hadolint

# macOS 通过 Homebrew 安装
brew install hadolint

# Linux 通过二进制文件安装
wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
chmod +x /usr/local/bin/hadolint

# 通过 Docker 安装
docker pull hadolint/hadolint

扫描 Dockerfile

# 扫描当前目录下的 Dockerfile
hadolint Dockerfile

# 扫描特定路径下的 Dockerfile
hadolint path/to/Dockerfile

# 使用 Docker 扫描
docker run --rm -i hadolint/hadolint < Dockerfile

生成报告

# 为自动化输出 JSON 格式
hadolint -f json Dockerfile > hadolint-report.json

# 为 GitLab Code Quality 格式
hadolint -f gitlab_codeclimate Dockerfile > hadolint-codeclimate.json

# 为 CI 集成输出 Checkstyle 格式
hadolint -f checkstyle Dockerfile > hadolint-checkstyle.xml

核心工作流程

1. 本地开发扫描

在开发过程中验证 Dockerfile：

# 基本扫描，带彩色输出
hadolint Dockerfile

# 扫描并设置特定严重性阈值
hadolint --failure-threshold error Dockerfile

# 只显示警告和错误
hadolint --no-color --format tty Dockerfile | grep -E "^(warning|error)"

# 详细输出，包括规则 ID
hadolint -t style -t warning -t error Dockerfile

输出格式：

Dockerfile:3 DL3008 警告：在 apt-get install 中固定版本
Dockerfile:7 DL3025 错误：使用 JSON 表示法对 CMD 和 ENTRYPOINT
Dockerfile:12 DL3059 信息：检测到多个 RUN 指令

何时使用： 开发者工作站，预提交验证，迭代 Dockerfile 开发。

2. CI/CD 管道集成

在构建管道中自动化 Dockerfile 验证：

GitHub Actions

name: Hadolint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Hadolint Dockerfile
        uses: hadolint/hadolint-action@v3.1.0
        with:
          dockerfile: Dockerfile
          failure-threshold: warning
          format: sarif
          output-file: hadolint.sarif

      - name: 上传 SARIF 到 GitHub Security
        if: always()
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: hadolint.sarif

GitLab CI

hadolint:
  image: hadolint/hadolint:latest-debian
  stage: lint
  script:
    - hadolint -f gitlab_codeclimate Dockerfile > hadolint-report.json
  artifacts:
    reports:
      codequality: hadolint-report.json
    when: always

何时使用： 自动化安全门禁，拉取请求检查，部署验证。

3. 配置自定义

创建 .hadolint.yaml 来自定义规则：

# .hadolint.yaml
failure-threshold: warning
ignored:
  - DL3008  # 允许未固定的 apt-get 包（首先评估风险）
  - DL3059  # 允许多个 RUN 指令

trustedRegistries:
  - docker.io/library  # 官方 Docker Hub 镜像
  - gcr.io/distroless  # Google distroless 镜像
  - registry.access.redhat.com  # Red Hat 注册表

override:
  error:
    - DL3001  # 强制：永远不要在没有版本固定的情况下使用 yum/dnf/zypper
  warning:
    - DL3015  # 警告：使用 apt-get 时使用 --no-install-recommends
  info:
    - DL3059  # 信息：多个 RUN 指令减少层缓存

label-schema:
  maintainer: text
  org.opencontainers.image.vendor: text
  org.opencontainers.image.version: semver

使用 assets/ 中的捆绑模板：

• assets/hadolint-strict.yaml - 严格的安全执行（仅 CRITICAL/HIGH）
• assets/hadolint-balanced.yaml - 平衡验证（推荐）
• assets/hadolint-permissive.yaml - 宽松的旧 Dockerfile 迁移 何时使用： 减少误报，组织标准，旧 Dockerfile 迁移。

4. 安全重点验证

强制执行关键安全规则：

# 仅在安全问题上失败（错误严重性）
hadolint --failure-threshold error Dockerfile

# 检查特定安全规则
hadolint --trusted-registry docker.io/library Dockerfile

# 扫描项目中的所有 Dockerfile
find . -name "Dockerfile*" -exec hadolint {} \;

# 生成仅包含错误的安全报告
hadolint -f json Dockerfile | jq '.[] | select(.level == "error")'

关键安全规则：

• DL3000: 使用绝对 WORKDIR（防止目录遍历）
• DL3001: 总是使用包管理器的版本固定
• DL3002: 永远不要在 Dockerfile 中切换到 root USER
• DL3020: 使用 COPY 而不是 ADD（防止任意 URL 获取）
• DL3025: 使用 JSON 表示法对 CMD/ENTRYPOINT（防止 shell 注入） 查看 references/security_rules.md 了解完整的安全规则目录和 CIS 映射。

5. 多阶段构建验证

扫描复杂的多阶段 Dockerfile：

# 验证所有阶段
hadolint Dockerfile

# 特定阶段验证（使用自定义脚本）
./scripts/hadolint_multistage.py Dockerfile

常见多阶段问题：

• 在构建和运行时阶段使用相同的用户
• 将不必要的构建工具复制到生产镜像
• 最后阶段缺少安全加固
• 构建阶段中的秘密传播到运行时 何时使用： 复杂构建，安全加固镜像，生产容器化。

6. 预提交钩子集成

防止不安全的 Dockerfile 被提交：

# 使用捆绑脚本安装预提交钩子
./scripts/install_precommit.sh

# 或手动创建钩子
cat << 'EOF' > .git/hooks/pre-commit
#!/bin/bash
for dockerfile in $(git diff --cached --name-only | grep -E 'Dockerfile'); do
  hadolint --failure-threshold warning "$dockerfile" || exit 1
done
EOF

chmod +x .git/hooks/pre-commit

何时使用： 开发者工作站，团队入职，强制安全控制。

安全考虑

敏感数据处理

• 秘密检测: Hadolint 标记 ENV、ARG、LABEL 指令中硬编码的秘密
• 构建秘密: 使用 Docker BuildKit 秘密（RUN --mount=type=secret）而不是 ARG 用于凭证
• 多阶段安全: 确保构建阶段的秘密不会泄露到最终镜像
• 镜像扫描: Hadolint 验证 Dockerfile - 结合镜像扫描（Trivy, Grype）进行运行时安全

访问控制

• CI/CD 权限: Hadolint 扫描需要读取 Dockerfile 和构建上下文的权限
• 报告存储: 将扫描报告视为内部文档 - 可能揭示安全实践
• 受信任的注册表: 配置 trustedRegistries 以强制批准的基础镜像源

审计日志

记录以下内容以符合合规性和安全审计：

• 扫描执行的时间戳和 Dockerfile 路径
• 按严重性（错误、警告、信息）的规则违规
• 被抑制的规则及其理由
• 基础镜像注册表验证结果
• 补救行动和时间表

合规性要求

• CIS Docker 基准测试 1.6: Hadolint 规则映射到 CIS 控制（见 references/cis_mapping.md）
  • 4.1: 为容器创建用户（DL3002）
  • 4.6: 添加 HEALTHCHECK 指令（DL3025）
  • 4.7: 不要在 Dockerfile 中单独使用更新（DL3009）
  • 4.9: 使用 COPY 而不是 ADD（DL3020）
• OWASP Docker 安全: 验证 OWASP 容器安全最佳实践
• NIST SP 800-190: 应用程序容器安全指南

捆绑资源

脚本（scripts/）

• hadolint_scan.py - 综合扫描多个 Dockerfiles 和输出格式
• hadolint_multistage.py - 多阶段 Dockerfile 分析，具有特定阶段验证
• install_precommit.sh - 自动化预提交钩子安装
• ci_integration.sh - 多个平台的 CI/CD 集成示例

参考（references/）

• security_rules.md - 完整的 Hadolint 安全规则与 CIS 基准测试映射
• cis_mapping.md - 详细的 CIS Docker 基准测试控制映射
• remediation_guide.md - 逐条规则的补救指导，带有安全示例
• shellcheck_integration.md - 用于 RUN 指令验证的 ShellCheck 规则

资产（assets/）

• hadolint-strict.yaml - 严格的安全配置
• hadolint-balanced.yaml - 生产就绪配置（推荐）
• hadolint-permissive.yaml - 旧 Dockerfile 迁移配置
• github-actions.yml - 完整的 GitHub Actions 工作流
• gitlab-ci.yml - 完整的 GitLab CI 管道
• precommit-config.yaml - 预提交框架配置

常见模式

模式 1: 初始 Dockerfile 安全审计

首次安全评估：

# 1. 查找所有 Dockerfiles
find . -type f -name "Dockerfile*" > dockerfile-list.txt

# 2. 将所有 Dockerfiles 扫描输出为 JSON
mkdir -p security-reports
while read dockerfile; do
  output_file="security-reports/$(echo $dockerfile | tr '/' '_').json"
  hadolint -f json "$dockerfile" > "$output_file" 2>&1
done < dockerfile-list.txt

# 3. 生成摘要报告
./scripts/hadolint_scan.py --input-dir . --output summary-report.html

# 4. 查看关键/高发现
cat security-reports/*.json | jq '.[] | select(.level == "error")' > critical-findings.json

模式 2: 渐进式补救

逐步安全加固：

# 第一阶段：基线（尚未使构建失败）
hadolint --failure-threshold none -f json Dockerfile > baseline.json

# 第二阶段：修复关键问题（仅在错误时失败）
hadolint --failure-threshold error Dockerfile

# 第三阶段：解决警告
hadolint --failure-threshold warning Dockerfile

# 第四阶段：完全合规（包括风格/信息）
hadolint Dockerfile

模式 3: 安全加固的生产镜像

构建以安全为先的容器镜像：

# 遵循 Hadolint 最佳实践的示例安全 Dockerfile

# 使用来自受信任注册表的特定基础镜像版本
FROM docker.io/library/node:18.19.0-alpine3.19

# 安装带有版本固定的软件包并清理
RUN apk add --no-cache \
    dumb-init=1.2.5-r2 \
    && rm -rf /var/cache/apk/*

# 创建非 root 用户
RUN addgroup -g 1001 -S appuser && \
    adduser -S -u 1001 -G appuser appuser

# 设置工作目录
WORKDIR /app

# 复制应用程序文件（使用 COPY 而不是 ADD）
COPY --chown=appuser:appuser package*.json ./
COPY --chown=appuser:appuser . .

# 安装依赖项
RUN npm ci --only=production && \
    npm cache clean --force

# 切换到非 root 用户
USER appuser

# 暴露端口（仅文档，不是安全控制）
EXPOSE 3000

# 添加健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node healthcheck.js || exit 1

# 使用 JSON 表示法对 entrypoint/cmd
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["node", "server.js"]

用 Hadolint 验证：

hadolint Dockerfile  # 应该没有错误通过

模式 4: CI/CD 与自动补救建议

在拉取请求中提供可操作的反馈：

# 在 CI 管道中
hadolint -f json Dockerfile > hadolint.json

# 生成补救建议
./scripts/hadolint_scan.py \
  --input hadolint.json \
  --format markdown \
  --output pr-comment.md

# 发布到 PR 评论（使用 gh CLI）
gh pr comment --body-file pr-comment.md

集成点

CI/CD 集成

• GitHub Actions: 原生 hadolint-action 支持 SARIF 格式，用于安全标签
• GitLab CI: GitLab Code Quality 格式集成
• Jenkins: Checkstyle 格式用于 Jenkins Warnings 插件
• CircleCI: 基于 Docker 的执行器与工件保留
• Azure Pipelines: 任务集成与结果发布

安全工具生态系统

• 镜像扫描: 结合 Trivy, Grype, Clair 进行运行时漏洞扫描
• 秘密扫描: 与 Gitleaks, TruffleHog 集成进行全面的秘密检测
• IaC 安全: 与 Checkov 链式结合，用于 Kubernetes/Terraform 验证
• SBOM 生成: 将结果与 Syft/Trivy SBOM 报告一起导出
• 安全仪表板: 导出 JSON 到 Grafana, Kibana, Datadog 进行集中监控

SDLC 集成

• 开发: 预提交钩子提供即时反馈
• 代码审查: PR 检查防止不安全的 Dockerfiles 合并
• 测试: 扫描测试环境 Dockerfiles
• 暂存: 在生产推广前验证门禁
• 生产: 定期审计部署的容器配置

故障排除

问题：太多误报

症状: 合法模式被标记（旧 Dockerfiles，特定用例） 解决方案:

# 创建 .hadolint.yaml
ignored:
  - DL3059  # 多个 RUN 指令（对于复杂构建有效）

# 或使用内联忽略
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y curl

参考 references/remediation_guide.md 了解特定规则的指导。

问题：基础镜像注册表不受信任

症状: 即使对于合法镜像，也会出现关于不受信任注册表的错误 解决方案:

# 添加到 .hadolint.yaml
trustedRegistries:
  - mycompany.azurecr.io
  - gcr.io/my-project
  - docker.io/library

问题：RUN 指令中的 ShellCheck 警告

症状: SC2086, SC2046 来自 ShellCheck 集成的警告 解决方案:

# 不好：未引用变量
RUN echo $MY_VAR > file.txt

# 好：引用变量
RUN echo "$MY_VAR" > file.txt

# 或禁用特定 ShellCheck 规则
# hadolint ignore=DL4006
RUN echo $MY_VAR > file.txt

查看 references/shellcheck_integration.md 了解完整的 ShellCheck 指导。

问题：多阶段构建未被识别

症状: 尽管正确设置多阶段，仍然出现缺少 USER 指令的错误 解决方案:

# 确保每个阶段都有适当的 USER
FROM node:18 AS builder
# 构建操作...

FROM node:18-alpine AS runtime
USER node  # 在最后阶段添加 USER
CMD ["node", "app.js"]

问题：CI 管道因警告而失败

症状: 构建因低严重性问题而失败 解决方案:

# 在 CI 中调整失败阈值
hadolint --failure-threshold error Dockerfile

# 或按环境配置
if [ "$CI_ENVIRONMENT" == "production" ]; then
  hadolint --failure-threshold warning Dockerfile
else
  hadolint --failure-threshold error Dockerfile
fi

高级配置

自定义规则严重性覆盖

# .hadolint.yaml
override:
  error:
    - DL3001  # 包版本控制至关重要
    - DL3020  # COPY 与 ADD 的安全性至关重要
  warning:
    - DL3059  # 多个 RUN 为警告，不是信息
  info:
    - DL3008  # 将 apt-get 固定降级为信息，适用于开发镜像

内联抑制

# 抑制单个指令的单个规则
# hadolint ignore=DL3018
RUN apk add --no-cache curl

# 抑制多个规则
# hadolint ignore=DL3003,DL3009
WORKDIR /tmp
RUN apt-get update && apt-get install -y wget

# 全局抑制（慎用）
# hadolint global ignore=DL3059

受信任的注册表强制执行

# .hadolint.yaml
trustedRegistries:
  - docker.io/library      # 仅限官方镜像
  - gcr.io/distroless      # Google distroless
  - cgr.dev/chainguard     # Chainguard 镜像

# 这将对以下内容报错：
# FROM nginx:latest                    ❌ (docker.io/nginx)
# FROM docker.io/library/nginx:latest  ✅ （受信任）

标签模式验证

# .hadolint.yaml
label-schema:
  maintainer: text
  org.opencontainers.image.created: rfc3339
  org.opencontainers.image.version: semver
  org.opencontainers.image.vendor: text

确保 Dockerfile LABELs 符合 OCI 镜像规范。

参考

• Hadolint GitHub 仓库
• CIS Docker 基准测试
• Docker 最佳实践
• ShellCheck 文档
• OCI 镜像规范