Checkov Binary Store 镜像文档

1. 镜像概述和主要用途

Checkov Binary Store 镜像是一个预打包了 Checkov 二进制文件的容器镜像，专为基础设施即代码（IaC）静态分析工具 Checkov 设计。该镜像提供开箱即用的 Checkov 可执行环境，旨在简化 Checkov 的部署与使用，确保在不同环境中（如开发机、CI/CD 流水线）的版本一致性和运行稳定性。其核心用途是作为 IaC CLI 工具的二进制存储载体，支持对 Terraform、CloudFormation、Kubernetes 等 IaC 配置文件进行自动化安全合规检查。

2. 核心功能和特性

• 预打包二进制文件：内置 Checkov 稳定版本的可执行文件，无需手动下载或编译依赖。
• 版本一致性：通过镜像标签（如 :2.3.45）固定 Checkov 版本，避免团队或环境间版本差异导致的分析结果不一致。
• 轻量级基础：基于 Alpine 或 Distroless 等轻量级镜像构建，减少镜像体积（通常 <100MB），加速部署和启动。
• 多 IaC 格式支持：原生支持 Terraform、CloudFormation、ARM Template、Kubernetes、Dockerfile 等主流 IaC/配置文件格式的分析。
• 离线可用：二进制文件本地存储，无需在线下载依赖，适用于受限网络或离线环境。

3. 使用场景和适用范围

• CI/CD 流水线集成：在 Jenkins、GitLab CI、GitHub Actions 等流水线中，作为自动化步骤执行 IaC 配置的安全合规检查。
• 本地开发验证：开发人员在本地环境快速验证 IaC 配置（如 Terraform 代码）的安全性，无需手动安装 Checkov。
• 团队协作环境：统一团队内 Checkov 版本，确保所有人使用相同规则集和分析逻辑。
• 离线/受限网络环境：在无法访问外部包管理器（如 PyPI）的环境中，通过本地镜像提供 Checkov 运行能力。

4. 详细使用方法和配置说明

4.1 基本使用（docker run 命令）

通过 docker run 直接启动容器，并挂载本地 IaC 文件目录，执行 Checkov 分析。

语法：

docker run --rm \
  -v [本地IaC文件目录]:/iac \  # 挂载本地IaC文件到容器内的 /iac 目录
  [镜像名称]:[标签] \          # 如 checkov-binary-store:2.3.45
  checkov [Checkov参数]         # 传递给 Checkov 的命令行参数

示例 1：分析本地 Terraform 目录

假设本地 ./terraform 目录包含 Terraform 代码，执行基础安全检查：

docker run --rm \
  -v $(pwd)/terraform:/iac \
  checkov-binary-store:2.3.45 \
  checkov --directory /iac --output table

示例 2：指定输出格式并导出结果

将分析结果以 JSON 格式输出到本地文件：

docker run --rm \
  -v $(pwd)/terraform:/iac \
  -v $(pwd)/reports:/reports \  # 挂载本地目录存储报告
  checkov-binary-store:2.3.45 \
  checkov --directory /iac --output json --output-file /reports/checkov-results.json

4.2 Docker Compose 配置示例

对于需要持久化配置（如自定义规则集、忽略文件）的场景，可通过 docker-compose.yml 简化管理：

version: '3'
services:
  checkov:
    image: checkov-binary-store:2.3.45
    volumes:
      - ./terraform:/iac                   # 挂载IaC代码目录
      - ./checkov-config:/config           # 挂载自定义配置（如.checkov.yaml）
      - ./reports:/reports                 # 挂载报告输出目录
    command: >
      checkov 
      --directory /iac 
      --config-file /config/.checkov.yaml  # 使用自定义配置
      --output sarif 
      --output-file /reports/checkov.sarif # 输出SARIF格式报告（适配GitHub Code Scanning）

启动命令：

docker-compose run --rm checkov

4.3 配置参数说明

4.3.1 Checkov 命令行参数

容器运行时，可通过 checkov [参数] 传递 Checkov 原生参数，常用参数如下：

4.3.2 环境变量

镜像支持通过环境变量调整运行行为（需在 docker run 中通过 -e 指定）：

4.4 数据卷挂载说明

为使容器能访问本地 IaC 文件、配置或输出报告，需挂载以下目录（通过 -v 参数）：

5. 注意事项

• 版本选择：通过镜像标签（如 :2.3.45）指定 Checkov 版本，建议使用固定版本标签而非 latest，确保稳定性。
• 文件权限：挂载本地目录时，若容器内用户（通常为 root 或 checkov）无读取权限，需通过 --user $(id -u):$(id -g) 调整权限（如 docker run --user $(id -u):$(id -g) ...）。
• 离线规则更新：默认情况下，Checkov 会定期在线更新规则库。若需完全离线使用，可通过 --no-update 参数禁用规则更新（需确保镜像内置规则库满足需求）。
• 自定义规则：如需添加自定义检查规则，可将规则文件（Python 脚本）挂载到容器内的 /checkov/custom_rules 目录，并通过 --external-checks-dir /checkov/custom_rules 参数指定。