checkov:基于 IaC 和 SCA 的静态代码分析工具项目

Checkov 是一款针对基础设施即代码（IaC）的静态代码分析工具，同时也是一款针对镜像和开源软件包的软件成分分析（SCA）工具。

它能够扫描使用 Terraform、Terraform plan、Cloudformation、AWS SAM、Kubernetes、Helm charts、Kustomize、Dockerfile、Serverless、Bicep、OpenAPI、ARM Templates 或 OpenTofu 配置的云基础设施，并通过基于图谱的扫描方式检测其中的安全与合规性配置错误。

它还能执行 软件成分分析（SCA）扫描，即对开源软件包和镜像进行常见漏洞与暴露（CVE）的扫描。

Checkov 同时也是 Prisma Cloud 应用安全 的核心驱动力。Prisma Cloud 是一个以开发者为中心的平台，旨在通过开发周期将云安全实践代码化并加以简化。该平台能够识别、修复并预防云资源和基础设施即代码文件中的配置错误。

目录

• 功能特性
• 截图展示
• 快速开始
• 免责声明
• 支持与帮助
• 从 v2 迁移到 v3

功能特性

• 超过 1000 条内置策略，涵盖 AWS、Azure 和 Google Cloud 的安全与合规最佳实践。
• 扫描 Terraform、Terraform Plan、Terraform JSON、CloudFormation、AWS SAM、Kubernetes、Helm、Kustomize、Dockerfile、Serverless 框架、Ansible、Bicep、ARM 和 OpenTofu 模板文件。
• 扫描 Argo Workflows、Azure Pipelines、BitBucket Pipelines、Circle CI Pipelines、GitHub Actions 和 GitLab CI 工作流文件。
• 支持基于内存图扫描的上下文感知策略。
• 支持 Python 格式的属性策略，以及 YAML 格式的属性策略和复合策略。
• 检测 EC2 Userdata、Lambda 环境变量和 Terraform 提供程序中的 AWS 凭证。
• 使用正则表达式、关键字和基于熵的检测识别密钥。
• 评估 Terraform Provider 设置，以规范通过 Terraform 创建、管理和更新 IaaS、PaaS 或 SaaS 的行为。
• 策略支持将变量计算为其可选默认值。
• 支持对已接受风险或误报进行行内抑制，以减少重复的扫描失败。还支持通过 CLI 进行全局跳过。
• 目前支持的输出格式包括 CLI、CycloneDX、JSON、JUnit XML、CSV、SARIF 和 GitHub Markdown，并提供指向修复指南的链接。

截图

命令行界面中的扫描结果

Jenkins 中的定时扫描结果

快速开始

环境要求

• Python >= 3.9，<=3.12
• Terraform >= 0.12

安装步骤

如需安装 pip，请参阅官方文档

pip3 install checkov

某些环境（例如 Debian 12）可能要求您在虚拟环境中安装 Checkov。

# Create and activate a virtual environment
python3 -m venv /path/to/venv/checkov
cd /path/to/venv/checkov
source ./bin/activate

# Install Checkov with pip
pip install checkov

# Optional: Create a symlink for easy access
sudo ln -s /path/to/venv/checkov/bin/checkov /usr/local/bin/checkov

或使用 Homebrew（适用于 macOS 或 Linux）

brew install checkov

启用 bash 自动补全

source <(register-python-argcomplete checkov)

升级

如果您使用 pip3 安装了 checkov

pip3 install -U checkov

或使用 Homebrew

brew upgrade checkov

配置输入文件夹或文件

checkov --directory /user/path/to/iac/code

或者特定的一个或多个文件

checkov --file /user/tf/example.tf

或

checkov -f /user/cloudformation/example1.yml -f /user/cloudformation/example2.yml

或者一个 JSON 格式的 terraform 计划文件

terraform init
terraform plan -out tf.plan
terraform show -json tf.plan  > tf.json
checkov -f tf.json

注意：terraform show 的输出文件 tf.json 会是单行格式。因此，Checkov 会将所有发现的问题都报告为行号 0。

check: CKV_AWS_21: "Ensure all data stored in the S3 bucket have versioning enabled"
	FAILED for resource: aws_s3_bucket.customer
	File: /tf/tf.json:0-0
	Guide: https://docs.prismacloud.io/en/enterprise-edition/policy-reference/aws-policies/s3-policies/s3-16-enable-versioning

如果你已安装 jq，可以使用以下命令将 json 文件转换为多行格式：

terraform show -json tf.plan | jq '.' > tf.json

扫描结果会更加用户友好。

checkov -f tf.json
Check: CKV_AWS_21: "Ensure all data stored in the S3 bucket have versioning enabled"
	FAILED for resource: aws_s3_bucket.customer
	File: /tf/tf1.json:224-268
	Guide: https://docs.prismacloud.io/en/enterprise-edition/policy-reference/aws-policies/s3-policies/s3-16-enable-versioning

		225 |               "values": {
		226 |                 "acceleration_status": "",
		227 |                 "acl": "private",
		228 |                 "arn": "arn:aws:s3:::mybucket",

或者，使用 --repo-root-for-plan-enrichment 标志指定用于生成计划文件的 hcl 文件的仓库根目录，以便用资源的适当文件路径、行号和代码块丰富输出内容。这样做的额外好处是 checkov 抑制规则将得到相应处理。

checkov -f tf.json --repo-root-for-plan-enrichment /user/path/to/iac/code

扫描结果示例（CLI）

Passed Checks: 1, Failed Checks: 1, Suppressed Checks: 0
Check: "Ensure all data stored in the S3 bucket is securely encrypted at rest"
/main.tf:
	 Passed for resource: aws_s3_bucket.template_bucket
Check: "Ensure all data stored in the S3 bucket is securely encrypted at rest"
/../regionStack/main.tf:
	 Failed for resource: aws_s3_bucket.sls_deployment_bucket_name

开始使用 Checkov，请阅读 快速入门 页面。

使用 Docker

docker pull bridgecrew/checkov
docker run --tty --rm --volume /user/tf:/tf --workdir /tf bridgecrew/checkov --directory /tf

注意：如果您使用的是 Python 3.6（Ubuntu 18.04 中的默认版本），checkov 将无法正常工作，并会失败并显示 ModuleNotFoundError: No module named 'dataclasses' 错误消息。在这种情况下，您可以改用 docker 版本。

请注意，在某些情况下，将 docker run --tty 的输出重定向到文件（例如，如果您想将 Checkov JUnit 输出保存到文件）会导致打印额外的控制字符。这可能会破坏文件解析。如果遇到此问题，请移除 --tty 标志。

--workdir /tf 标志是可选的，用于将工作目录更改为挂载的卷。如果您使用 SARIF 输出 -o sarif，这会将 results.sarif 文件输出到挂载的卷（在上面的示例中为 /user/tf）。如果不包含该标志，工作目录将为 "/"。

运行或跳过检查

通过使用命令行标志，您可以指定仅运行命名检查（允许列表）或运行除列出的检查之外的所有检查（拒绝列表）。如果您通过 API 密钥使用平台集成，您还可以指定要跳过和/或包含的严重性阈值。 此外，由于 json 文件不能包含注释，因此可以传递正则表达式模式来跳过 json 文件的密钥扫描。

有关这些标志如何协同工作的更多详细信息，请参阅文档。

示例

仅允许运行两个指定的检查：

checkov --directory . --check CKV_AWS_20,CKV_AWS_57

运行所有检查，但排除指定的检查项：

checkov -d . --skip-check CKV_AWS_20

运行所有检查，但排除具有指定模式的检查：

checkov -d . --skip-check CKV_AWS*

运行所有严重级别为中或更高的检查（需要 API 密钥）：

checkov -d . --check MEDIUM --bc-api-key ...

运行所有严重级别为中（MEDIUM）或更高的检查，以及检查 CKV_123（假设这是一个低（LOW）严重级别检查）：

checkov -d . --check MEDIUM,CKV_123 --bc-api-key ...

跳过所有严重级别为 MEDIUM 或更低的检查：

checkov -d . --skip-check MEDIUM --bc-api-key ...

跳过所有严重级别为中或更低的检查，以及检查 CKV_789（假设这是一项高严重级别检查）：

checkov -d . --skip-check MEDIUM,CKV_789 --bc-api-key ...

运行所有严重级别为 MEDIUM 及以上的检查，但跳过检查 CKV_123（假设这是一个 MEDIUM 或更高级别的检查）：

checkov -d . --check MEDIUM --skip-check CKV_123 --bc-api-key ...

运行检查 CKV_789，但如果其风险等级为中（medium），则跳过该检查（--check 逻辑始终在 --skip-check 之前应用）

checkov -d . --skip-check MEDIUM --check CKV_789 --bc-api-key ...

对于 Kubernetes 工作负载，您还可以使用允许/拒绝命名空间功能。例如，不对 kube-system 命名空间报告任何结果：

checkov -d . --skip-check kube-system

运行容器镜像扫描。首先拉取或构建镜像，然后通过哈希、ID 或 name:tag 引用它：

checkov --framework sca_image --docker-image sha256:1234example --dockerfile-path /Users/path/to/Dockerfile --repo-id ... --bc-api-key ...

checkov --docker-image <image-name>:tag --dockerfile-path /User/path/to/Dockerfile --repo-id ... --bc-api-key ...

你也可以使用 --image 标志来扫描容器镜像，以替代 --docker-image，使命令更简洁：

checkov --image <image-name>:tag --dockerfile-path /User/path/to/Dockerfile --repo-id ... --bc-api-key ...

对仓库中的包运行 SCA 扫描：

checkov -d . --framework sca_package --bc-api-key ... --repo-id <repo_id(arbitrary)>

对包含环境变量的目录运行扫描，移除缓冲并添加调试级日志：

PYTHONUNBUFFERED=1 LOG_LEVEL=DEBUG checkov -d .

或者为多次运行启用环境变量

export PYTHONUNBUFFERED=1 LOG_LEVEL=DEBUG
checkov -d .

对 MyDirectory 中的所有文件运行密钥扫描。对后缀为 DontScan 的 json 文件跳过 CKV_SECRET_6 检查。

checkov -d /MyDirectory --framework secrets --repo-id ... --bc-api-key ... --skip-check CKV_SECRET_6:.*DontScan.json$

对 MyDirectory 中的所有文件运行密钥扫描。对路径中包含 "skip_test" 的 json 文件跳过 CKV_SECRET_6 检查

checkov -d /MyDirectory --framework secrets --repo-id ... --bc-api-key ... --skip-check CKV_SECRET_6:.*skip_test.*json$

可以通过提供包含 mask 条目的配置文件（使用 --config-file 标志）来屏蔽扫描结果中的值。 屏蔽可应用于资源和值（或多个值，用逗号分隔）。 示例：

mask:
- aws_instance:user_data
- azurerm_key_vault_secret:admin_password,user_passwords

在上面的示例中，以下值将被屏蔽：

• aws_instance 资源的 user_data
• azurerm_key_vault_secret 的 admin_password 和 user_passwords

抑制/忽略检查

与任何静态分析工具一样，其分析范围是有限的。 例如，如果某个资源是手动管理的，或者使用后续的配置管理工具进行管理，可以通过简单的代码注释来插入抑制信息。

抑制注释格式

要在给定的 Terraform 定义块或 CloudFormation 资源上跳过检查，请在其范围内应用以下注释模式：

checkov:skip=<check_id>:<suppression_comment>

• <check_id> 是 [可用检查扫描器](docs/5.Policy Index/all.md) 之一
• <suppression_comment> 是可选的抑制原因，将包含在输出中

示例

以下注释会在标识符为 foo-bucket 的资源上跳过 CKV_AWS_20 检查，该扫描用于检查 AWS S3 存储桶是否为私有。 在此示例中，存储桶配置为具有公共读取权限；添加抑制注释将跳过相应的检查，而不是导致检查失败。

resource "aws_s3_bucket" "foo-bucket" {
  region        = var.region
    #checkov:skip=CKV_AWS_20:The bucket is a public static content host
  bucket        = local.bucket_name
  force_destroy = true
  acl           = "public-read"
}

现在输出将包含一个 SKIPPED 检查结果条目：

...
...
Check: "S3 Bucket has an ACL defined which allows public access."
	SKIPPED for resource: aws_s3_bucket.foo-bucket
	Suppress comment: The bucket is a public static content host
	File: /example_skip_acl.tf:1-25

...

要跳过多个检查，请将每个检查作为新行添加。

  #checkov:skip=CKV2_AWS_6
  #checkov:skip=CKV_AWS_20:The bucket is a public static content host

要在 Kubernetes 清单中忽略检查，需使用以下格式的注解： checkov.io/skip#: <check_id>=<suppression_comment>

例如：

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  annotations:
    checkov.io/skip1: CKV_K8S_20=I don't care about Privilege Escalation :-O
    checkov.io/skip2: CKV_K8S_14
    checkov.io/skip3: CKV_K8S_11=I have not set CPU limits as I want BestEffort QoS
spec:
  containers:
...

日志记录

若要将详细日志输出到标准输出（stdout），请将环境变量 LOG_LEVEL 设置为 DEBUG。

默认日志级别为 LOG_LEVEL=WARNING。

跳过目录

如需跳过文件或目录，可使用 --skip-path 参数，该参数可多次指定。此参数接受相对于当前工作目录的路径正则表达式，可用于跳过整个目录和/或特定文件。

默认情况下，所有名为 node_modules、.terraform 和 .serverless 的目录，以及任何以 . 开头的文件或目录都会被跳过。 若要取消跳过以 . 开头的目录，可覆盖环境变量 CKV_IGNORE_HIDDEN_DIRECTORIES，执行 export CKV_IGNORE_HIDDEN_DIRECTORIES=false。

您可以通过设置环境变量 CKV_IGNORED_DIRECTORIES 来覆盖默认的跳过目录集。 请注意，如果您希望保留默认列表并添加新目录，必须包含这些默认值。例如，CKV_IGNORED_DIRECTORIES=mynewdir 将仅跳过该目录，而不会跳过上述其他目录。此变量为遗留功能，建议使用 --skip-file 标志。

控制台输出

控制台输出默认带有颜色，若要切换为单色输出，请设置环境变量： ANSI_COLORS_DISABLED

VS Code 扩展

如果您想在 VS Code 中使用 Checkov，不妨尝试 Prisma Cloud 扩展。

使用配置文件进行配置

Checkov 可以通过 YAML 配置文件进行配置。默认情况下，Checkov 会按以下优先级顺序查找 .checkov.yaml 或 .checkov.yml 文件：

• 运行 checkov 时指定的目标目录（--directory）。
• 调用 checkov 时的当前工作目录。
• 用户的主目录。

注意：最佳实践是从由已验证身份组成的可信来源加载 checkov 配置文件，以确保扫描的文件、检查 ID 和加载的自定义检查符合预期。

用户也可以通过命令行传入配置文件的路径。在这种情况下，其他配置文件将被忽略。例如：

checkov --config-file path/to/config.yaml

用户还可以使用 --create-config 命令创建配置文件，该命令会获取当前的命令行参数并将其写入指定路径。例如：

checkov --compact --directory test-dir --docker-image sample-image --dockerfile-path Dockerfile --download-external-modules True --external-checks-dir sample-dir --quiet --repo-id prisma-cloud/sample-repo --skip-check CKV_DOCKER_3,CKV_DOCKER_2 --skip-framework dockerfile secrets --soft-fail --branch develop --check CKV_DOCKER_1 --create-config /Users/sample/config.yml

将创建一个如下所示的 config.yaml 文件：

branch: develop
check:
  - CKV_DOCKER_1
compact: true
directory:
  - test-dir
docker-image: sample-image
dockerfile-path: Dockerfile
download-external-modules: true
evaluate-variables: true
external-checks-dir:
  - sample-dir
external-modules-download-path: .external_modules
framework:
  - all 
output: cli 
quiet: true 
repo-id: prisma-cloud/sample-repo 
skip-check: 
  - CKV_DOCKER_3 
  - CKV_DOCKER_2 
skip-framework:
  - dockerfile
  - secrets
soft-fail: true

用户还可以使用 --show-config 标志查看所有参数和设置，以及它们的来源（即命令行、配置文件、环境变量或默认值）。例如：

checkov --show-config

将显示：

Command Line Args:   --show-config
Environment Variables:
  BC_API_KEY:        your-api-key
Config File (/Users/sample/.checkov.yml):
  soft-fail:         False
  branch:            master
  skip-check:        ['CKV_DOCKER_3', 'CKV_DOCKER_2']
Defaults:
  --output:          cli
  --framework:       ['all']
  --download-external-modules:False
  --external-modules-download-path:.external_modules
  --evaluate-variables:True

贡献指南

我们欢迎您的贡献！

首先，请查阅贡献指南。之后，您可以浏览适合新手的任务。

您甚至可以通过以下链接，一键在浏览器中通过 Gitpod 启动开发环境：

想要贡献新的检查规则？请在此处学习如何编写新的检查规则（也称为策略）。

免责声明

checkov 不会保存、发布或与任何人分享任何可识别的客户信息。
查询 Prisma Cloud 的公开指南时，不会使用任何可识别的客户信息。
checkov 使用 Prisma Cloud 的 API 来丰富结果，提供指向修复指南的链接。
如需跳过此 API 调用，请使用标志 --skip-download。

支持

Prisma Cloud 构建并维护 Checkov，旨在让策略即代码变得简单易用。

您可以从我们的文档开始，获取快速教程和示例。

Python 版本支持

我们遵循 Python 的官方支持周期，并对受支持的 Python 版本进行自动化测试。 这意味着我们目前支持 Python 3.9 至 3.13（含首尾版本）。 请注意，Python 3.8 已于 2024 年 10 月停止支持（EOL），Python 3.9 将于 2025 年 10 月停止支持。 如果您在任何非 EOL 的 Python 版本上遇到问题，请提交 Issue。