# https://github.com/bridgecrewio/checkov 项目说明书 生成时间：2026-06-20 17:20:39 UTC ## 目录 - [Overview, Installation & Quick Start](#page-1) - [Core Architecture: Runners, Registries & Graph Engine](#page-2) - [IaC Framework Scanners (Terraform, CloudFormation, ARM/Bicep, Kubernetes, Helm, Kustomize)](#page-3) - [Pipelines, VCS, OpenAPI & Cross-Platform Scanners](#page-4) - [Custom Policies: YAML & Python Authoring](#page-5) - [Output Formats, Reporting & CI/CD Integrations](#page-6) - [Secrets, SCA & SAST Scanning](#page-7) - [Configuration, Suppression, External Modules & Troubleshooting](#page-8) ## Overview, Installation & Quick Start ### 相关页面 相关主题：[Core Architecture: Runners, Registries & Graph Engine](#page-2), [Configuration, Suppression, External Modules & Troubleshooting](#page-8)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py)
# Checkov 概览、安装与快速开始 ## 项目概览 Checkov 是 Bridgecrew（现为 Prisma Cloud 团队）维护的一款开源静态代码分析与软件成分分析（SCA）工具，主要用于扫描基础设施即代码（IaC）模板与容器镜像中的安全与合规违规项。它支持 Terraform、Terraform Plan、CloudFormation、AWS SAM、Kubernetes、Helm、Kustomize、Dockerfile、Serverless 框架、Ansible、Bicep、ARM 以及 OpenTofu 等多种模板语言 资料来源：[README.md:1-20]()。 Checkov 内置了 1000+ 条策略，覆盖 AWS、Azure、Google Cloud 的安全与合规最佳实践，并可通过 SCA 功能扫描开源包和镜像中的已知 CVE 漏洞 资料来源：[README.md:46-58]()。项目使用官方 Python 支持周期，当前兼容 Python 3.9 - 3.13（含），Python 3.8 已于 2024 年 10 月 EOL 资料来源：[README.md:80-88]()。 ## 安装方式 Checkov 提供多种安装与运行方式，便于不同场景下的使用： | 安装方式 | 命令 | 适用场景 | | --- | --- | --- | | pip | `pip install checkov` | 通用 Python 环境、CI/CD 流水线 | | Docker | `docker pull bridgecrew/checkov` | 容器化运行，避免依赖冲突 | | Homebrew | `brew install checkov` | macOS 本地开发 | | Gitpod | 通过 README 徽章一键启动 | 浏览器内贡献与测试 资料来源：[README.md:60-78]() | > ⚠️ **社区提示**：通过 Homebrew 安装时，`CKV2` 检查可能不会运行，而通过 pip 安装时正常执行，这会导致本地与 CI（如 GitHub Actions）结果不一致，建议在 CI 环境中统一使用 pip 安装 资料来源：[community issue #6645]()。 ## 快速开始 ### 基本扫描 安装完成后，可直接对包含 IaC 模板的目录执行扫描： ```bash checkov -d /path/to/iac/code ``` 常用参数包括 `--framework`（限定框架）、`--output`（输出格式，例如 cli、json、sarif）、`--skip-check`（按检查 ID 跳过）、`--soft-fail` 与 `--hard-fail-on`（按严重度控制退出码）等 资料来源：[README.md:34-44]()。 通过 `checkov --show-config` 可以查看当前生效的配置来源（命令行、环境变量、配置文件或默认值），便于排查配置优先级问题 资料来源：[README.md:96-108]()。 ### 镜像与 SCA 扫描 除 IaC 模板外，Checkov 还可对容器镜像进行 SCA 扫描，识别开源组件中的已知漏洞。 ```bash checkov --framework sca_image --image ``` 最新版本（3.3.1）新增了 `serverless` 框架的 `disable vars opt out` 配置项 资料来源：[community release 3.3.1]()。 ## 架构概览：模块加载与检查执行 Checkov 的 Terraform 扫描在解析本地模板时，会通过一组可插拔的 **ModuleLoader** 拉取外部模块（Git、Registry、HTTP 归档等）。下面是模块加载与检查执行的简化流程： ```mermaid flowchart LR A[Terraform 源码] --> B[ModuleParams] B --> C{Loader 匹配} C -- git:: 协议 --> D[GenericGitLoader] C -- github.com --> E[GithubLoader] C -- bitbucket.org --> F[BitbucketLoader] C -- registry --> G[RegistryLoader] D & E & F --> H[拉取/检出模块] G --> I[解析版本约束] I --> J[下载归档] H & J --> K[BaseResourceCheck 扫描] K --> L[cloudsplaining IAM 分析] L --> M[CheckResult PASSED/FAILED/UNKNOWN] ``` `GenericGitLoader` 处理 `git:://...` 形式的通用 Git 仓库源，支持 `git::https://`、`git::ssh://` 以及 `git@host:org/repo` 简写，并可通过 `VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` 环境变量对接私有 Git 服务 资料来源：[checkov/terraform/module_loading/loaders/git_loader.py:1-80]()。 `RegistryLoader` 用于从 Terraform Registry（默认 `registry.terraform.io`，可通过 `TF_HOST_NAME` 覆盖）下载模块，先通过 `versions_parser` 解析版本约束，再根据 `MODULE_ARCHIVE_EXTENSIONS`（`zip`、`tar.bz2`、`tar.gz`、`tgz`、`tar.xz`、`txz`）判断归档格式 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py:1-40]()。 `VersionConstraint` 实现了 `=`、`!=`、`>`、`>=`、`<`、`<=`、`~>` 七种操作符的版本比较逻辑，`~>` 会被展开为「同一主版本下小于下一主版本」的区间 资料来源：[checkov/terraform/module_loading/loaders/versions_parser.py:1-40]()。 针对访问受限的 VCS，`GithubAccessTokenLoader` 与 `BitbucketAccessTokenLoader` 会通过环境变量（如 `GITHUB_PAT`、`BITBUCKET_USERNAME`/`BITBUCKET_APP_PASSWORD`）将私有仓库源改写为带凭据的 URL 资料来源：[checkov/terraform/module_loading/loaders/github_access_token_loader.py:1-20]()；[checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py:1-16]()。 ## 常见问题与故障排查 | 现象 | 可能原因 | 参考 | | --- | --- | --- | | `checkov --version` 抛出 `AttributeError: module 'pycares' has no attribute 'ares_query_a_result'` | 依赖冲突（如 `uv` 虚拟环境与系统包版本不一致） | [community issue #7398]() | | 部分 AWS/GCP 检查误报（如 `CKV_AWS_86`、`CKV_GCP_62/63/93/123`） | 检查实现未覆盖 v2 logging、undetermined 值、多密钥等场景 | [community issues #7385 #7402 #7406 #7473]() | | 使用 `--hard-fail-on`/`--soft-fail-on` 等按严重度参数无效果 | 未配置 `BC_API_KEY`（Prisma Cloud API） | [community issue #7379]() | | Bicep 模板扫描报 `extension` 关键字解析错误 | pycep 解析器尚未支持 `extension` 关键字 | [community issue #7364]() | | Kubernetes 清单含 `${VAR}` 占位符时静默跳过 | 框架未对占位符模板做告警 | [community issue #7210]() | | 3.2.517 版本依赖含已知 CVE（urllib3、asteval、ply） | 传递依赖未及时升级 | [community issue #7504]() | ## 后续建议 - 查看官方 [Quick Start](https://www.checkov.io/1.Welcome/Quick%20Start.html) 与 `docs/` 目录下的扫描示例以深入特定框架。 - 在 CI 中固定 Checkov 版本并通过 `--download-external-modules true` 控制外部模块行为，避免流水线结果漂移。 - 需要自定义检查时，可继承 `BaseResourceCheck` 或基于 `BaseTerraformCloudsplainingIAMScanner` 实现 IAM 策略扫描 资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:1-30]()。 ## 参见 - Terraform 模块加载详解 - 自定义策略开发指南 - 与 Prisma Cloud 平台集成 --- ## Core Architecture: Runners, Registries & Graph Engine ### 相关页面 相关主题：[Overview, Installation & Quick Start](#page-1), [IaC Framework Scanners (Terraform, CloudFormation, ARM/Bicep, Kubernetes, Helm, Kustomize)](#page-3), [Custom Policies: YAML & Python Authoring](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md)
# 核心架构：Runner、Registry 与图引擎 ## 概述 Checkov 是一个面向基础设施即代码（IaC）的静态代码分析与软件成分分析（SCA）工具，支持 Terraform、CloudFormation、Kubernetes、Helm、Bicep、ARM、OpenAPI 等多种框架 资料来源：[README.md]() 。其核心架构围绕三类协作组件展开：**Runner（执行器）** 负责调度整个扫描流程；**Registry（注册表/加载器）** 负责注册和发现各类检查策略以及外部模块源；**Graph Engine（图引擎）** 则在更高层对资源之间的引用关系进行图遍历。 在仓库中可直接观察到的"Registry"层有两个主要体现：一是 **Check 注册表**（按框架动态加载检查类），二是 **Terraform 模块加载器注册表**（通过链式匹配获取外部模块）。本页面重点说明后者以及它与检查执行体系的衔接，并标注在本次检索范围内未直接获取到的 Runner 主循环与 Graph Builder 源码模块的占位说明。 ## 模块加载器注册表（Module Loader Registry） Checkov 在扫描 Terraform 代码时，会先识别 `module "x" { source = "..." }` 块中的 `source` 字段，并通过一组 **模块加载器**（`ModuleLoader` 子类）来解析、下载并展开外部模块。每个具体加载器在文件末尾以单例形式暴露： ```python # 资料来源：checkov/terraform/module_loading/loaders/registry_loader.py loader = RegistryLoader() ``` ```python # 资料来源：checkov/terraform/module_loading/loaders/git_loader.py loader = GenericGitLoader() ``` ```python # 资料来源：checkov/terraform/module_loading/loaders/github_loader.py loader = GithubLoader() ``` 加载器通过 `_is_matching_loader(module_params)` 判定自身是否适配当前模块源，并通过 `discover(module_params)` 注入环境变量（`TF_HOST_NAME`、`TF_REGISTRY_TOKEN`、`VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` 等）。这种"先匹配、后注入、再下载"的设计避免了强制下载无关模块，并使私有仓库能够通过环境令牌透明地访问。 ### 加载器类型 下表总结本次检索到的加载器职责与匹配规则。 | 加载器 | 文件 | 匹配前缀/协议 | 关键行为 | | --- | --- | --- | --- | | `RegistryLoader` | `registry_loader.py` | Terraform Registry API | 调用 `tf_modules_versions_endpoint` 获取版本列表，归一化下载 URL | | `GenericGitLoader` | `git_loader.py` | `git::`、`git@`、自定义 `VCS_BASE_URL` | 解析 `ModuleSource` 数据类，处理 inner-module 路径，调用 `GitGetter` | | `GithubLoader` | `github_loader.py` | `github.com`、`git@github.com:`、`git::git@github.com:` | 将简写形式重写为 `git::https://` 或 `git::ssh://` 形式 | | `GithubAccessTokenLoader` | `github_access_token_loader.py` | 含 `username`/`token` 的 GitHub 源 | 注入凭据重写为 `https://user:token@host/...` | ### 版本约束解析 `versions_parser.py` 提供了 `VersionConstraint` 类与 `VERSION_REGEX`，支持 `=`, `!=`, `>`, `>=`, `<`, `<=`, `~>` 等 Terraform 语义版本操作符。`get_max_version_for_most_specific_segment()` 与 `~>` 配合使用以实现"锁住次要版本、放开补丁版本"的语义。`order_versions_in_descending_order` 协助 Registry 端点选择最新可用版本。 ```python # 资料来源：checkov/terraform/module_loading/loaders/versions_parser.py VERSION_REGEX = re.compile(r"^(?P=|!=|>=|>|<=|<|~>)?\s*(?P[\d.]+-?\w*)$") ``` > 社区提示：外部模块的跳过逻辑（例如 `${VAR}` 占位符的 Kubernetes 清单被静默跳过，见 issue #7210）会与模块加载器在解析阶段协同工作；当无法展开时，对应模块将退化为未扫描状态。 ## 检查注册与执行（Check Registry 与扫描流程） 在 `checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py` 中，可以观察到 Check 检查的最小执行单元形态： ```python # 资料来源：checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py policy_document_cache: Dict[str, PolicyDocument] = {} # noqa: CCE003 def scan_conf(self, conf: Dict[str, List[Any]]) -> CheckResult: if self.should_scan_conf(conf): try: if self.cache_key not in BaseTerraformCloudsplainingIAMScanner.policy_document_cache.keys(): policy = self.convert_to_iam_policy(conf) BaseTerraformCloudsplainingIAMScanner.policy_document_cache[self.cache_key] = policy ... if violations: return CheckResult.FAILED except Exception: return CheckResult.UNKNOWN return CheckResult.PASSED ``` 该基类揭示了 Check 体系的关键约定： 1. **类级缓存** —— `policy_document_cache` 在类层面共享，避免对同一 IAM 策略重复构造昂贵的 `PolicyDocument`。 2. **三态结果** —— `CheckResult.PASSED` / `FAILED` / `UNKNOWN`，其中 `UNKNOWN` 用于模板化或异常策略，提升了在真实 IaC 中容错性。 3. **命中即短路** —— 命中违规后立即返回 `FAILED`，并通过 `cloudsplaining_enrich_evaluated_keys` 增强结果可追溯性。 > 社区提示：这种 `UNKNOWN` 状态与"对未解析的占位符静默跳过"（issue #7210、`CKV_GCP_62/63` 出现 `undetermined` 值，见 issue #7473）的现象相关，提示用户：在流水线中应将 `UNKNOWN` 与 `PASSED` 区分对待，避免漏报。 ## 数据流概览 下图描绘了从 CLI 入口到检查执行的总体数据流（基于本次检索到的源码片段，Runner 主循环与 Graph Builder 内部细节未在范围内，下图中以虚线表示）： ```mermaid flowchart LR A[CLI 入口] --> B[Runner Registry] B --> C[框架 Runner] C --> D[Module Loader 注册表] D --> D1[RegistryLoader] D --> D2[GenericGitLoader] D --> D3[GithubLoader] D --> D4[GithubAccessTokenLoader] C --> E[Check Registry] E --> F[BaseCheck / BaseCloudsplainingIAMScanner] F --> G{图引擎 Graph Builder} G -->|引用关系| F F --> H[CheckResult PASSED/FAILED/UNKNOWN] ``` ## 配置与常见问题 - **环境变量优先级**：`TF_HOST_NAME`、`TF_REGISTRY_TOKEN`、`VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` 在 `discover()` 阶段被读取，未设置时回退到默认值 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py]()、[checkov/terraform/module_loading/loaders/git_loader.py]() 。 - **代理下载**：`RegistryLoader` 通过 `call_http_request_with_proxy` 调用 `requests`，超时由 `DEFAULT_TIMEOUT` 控制 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py]() 。 - **凭据注入顺序**：`GithubAccessTokenLoader` 必须先于 `GithubLoader` 匹配，否则已重写过的 `git::https://user:token@...` 不会再匹配 `github.com` 前缀 资料来源：[checkov/terraform/module_loading/loaders/github_access_token_loader.py]() 。 - **缓存与重启**：类级 `policy_document_cache` 不会自动失效，长时间运行的进程需注意内存增长 资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py]() 。 - **未知结果处置**：`CheckResult.UNKNOWN` 在 CI 中若被忽略，可能与 issue #7210、#7473 描述的"静默跳过/未确定值"叠加，造成安全盲区；建议在流水线中显式 fail-on UNKNOWN。 ## See Also - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) — Checkov 总体特性与安装使用 - [docs/5.Policy Index/all.md](https://github.com/bridgecrewio/checkov/blob/main/docs/5.Policy%20Index/all.md) — 内置策略索引 - [docs/6.Contribution/Contribution Overview.md](https://github.com/bridgecrewio/checkov/blob/main/docs/6.Contribution/Contribution%20Overview.md) — 如何编写新检查 - [docs/1.Welcome/Migration.md](https://github.com/bridgecrewio/checkov/blob/main/docs/1.Welcome/Migration.md) — v2 到 v3 迁移指南 - [checkov/terraform/module_loading/](https://github.com/bridgecrewio/checkov/tree/main/checkov/terraform/module_loading) — 模块加载与解析源码目录 --- ## IaC Framework Scanners (Terraform, CloudFormation, ARM/Bicep, Kubernetes, Helm, Kustomize) ### 相关页面 相关主题：[Core Architecture: Runners, Registries & Graph Engine](#page-2), [Pipelines, VCS, OpenAPI & Cross-Platform Scanners](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py) - [checkov/terraform/checks/utils/iam_terraform_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/iam_terraform_document_to_policy_converter.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/local_path_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/local_path_loader.py)
# IaC 框架扫描器 (Terraform、CloudFormation、ARM/Bicep、Kubernetes、Helm、Kustomize) ## 概述 Checkov 是一款针对基础设施即代码（IaC）以及容器镜像与开源依赖进行静态分析的安全扫描工具。其核心能力由一组按目标 IaC 框架组织的"扫描器（Runner）"承担，每种扫描器负责解析一种特定格式的清单文件并执行与之对应的策略集合。 根据 [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) 中的描述，Checkov 当前支持的 IaC 框架包括 Terraform、Terraform Plan、CloudFormation、AWS SAM、Kubernetes、Helm、Kustomize、Dockerfile、Serverless 框架、Ansible、Bicep、ARM 模板以及 OpenTofu。除资源级扫描外，Checkov 还支持 Argo Workflows、Azure Pipelines、BitBucket Pipelines、CircleCI Pipelines、GitHub Actions 和 GitLab CI 等流水线文件的扫描，并通过基于内存图的"上下文感知"策略进行跨资源关联分析。 ## 通用扫描流程 所有 IaC 框架扫描器在执行阶段共享相同的调用契约：发现目标文件 → 解析为内部表示 → 匹配适用的 Check → 收集结果。下图展示了 Checkov 的整体数据流。 ```mermaid flowchart LR A[IaC 源文件] --> B[框架 Runner] B --> C[解析器/语法树] C --> D[注册中心: BaseRegistry] D --> E[属性检查与图检查] E --> F[结果: PASSED/FAILED/UNKNOWN] F --> G[报告与抑制处理] ``` 不同框架的 Runner 之间的差异主要体现在"解析器"和"图构建器"两个阶段，例如 Terraform 走 `terraform` 子模块的 graph_manager，而 CloudFormation 与 ARM/Bicep 走各自原生的解析路径。 ## Terraform 扫描器 Terraform 是 Checkov 支持最完善的框架，覆盖 HCL、JSON 计划文件以及 OpenTofu 语法。其代码组织在 `checkov/terraform/` 子包中，包括 `runner.py`、`plan_runner.py`、`graph_manager.py` 等。 ### 模块加载机制 Terraform 扫描器在扫描过程中会递归地解析 `module` 块并下载其源代码。`checkov/terraform/module_loading/loaders/` 目录实现了一套基于策略的模块加载器链： | 加载器 | 来源前缀 | 鉴权机制 | | --- | --- | --- | | `LocalPathLoader` | `./`、`../`、绝对路径 | 无 | | `RegistryLoader` | Terraform Registry / 私有 Registry | `TF_REGISTRY_TOKEN`、`TF_HOST_NAME` | | `GenericGitLoader` | `git::https://` | `VCS_USERNAME` / `VCS_TOKEN` | | `GithubLoader` | `github.com` | SSH / HTTPS | | `GithubAccessTokenLoader` | `github.com` (有 `GITHUB_PAT`) | `GITHUB_PAT` | | `BitbucketLoader` | `bitbucket.org` | SSH | | `BitbucketAccessTokenLoader` | `bitbucket.org` | `BITBUCKET_USERNAME` / `BITBUCKET_APP_PASSWORD` / `BITBUCKET_TOKEN` | 各加载器从 `git_loader.py` 的 `GenericGitLoader` 派生，并通过 `discover()` 方法读取环境变量。资料来源：[checkov/terraform/module_loading/loaders/github_access_token_loader.py:11-30]() 显示，当 `GITHUB_PAT` 被设置时，模块源会自动重写为 `git::https://x-access-token:@github.com/...`。`registry_loader.py` 则会调用 Terraform Registry API 来解析版本约束并下载归档。 ### IAM 策略与图检查 Terraform 扫描器内置了 `cloudsplaining` 集成用于检测过度宽松的 IAM 权限。`base_cloudsplaining_iam_scanner.py` 中的 `scan_conf()` 会先将 HCL 配置通过 `iam_terraform_document_to_policy_converter.py` 转换为标准 IAM 策略 JSON 文档，再交由 `cloudsplaining` 评估。资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:18-44]() 表明该类在类级别维护 `policy_document_cache`，以避免重复创建昂贵的 `PolicyDocument` 对象。 ## CloudFormation 扫描器 CloudFormation 扫描器位于 `checkov/cloudformation/`，支持 YAML/JSON 模板以及嵌套 Stack。其 IAM 策略转换由 [checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py) 提供，函数 `convert_cloudformation_conf_to_iam_policy()` 将模板中的 `Statement`（首字母大写）格式归一化为标准 IAM 文档结构，例如把 `Action` 列表取首项转为字符串、把 `Resource` 转为字符串并补齐 `Effect` 默认值。 由于 CloudFormation 的 `Intrinsic` 函数（`!Ref`、`!Sub`、`!GetAtt` 等）可能让值在扫描时不可解析，转换器在出现异常时会被上游包装并以 `CheckResult.UNKNOWN` 回退，避免产生误报。 ## ARM / Bicep、Kubernetes、Helm、Kustomize 扫描器 - **ARM 模板**：使用 `checkov/arm/` 下的 Runner，将 JSON 模板解析为内部字典结构后运行资源检查。 - **Bicep**：先通过外部 Bicep CLI 生成 ARM JSON，再复用 ARM Runner。Bicep 解析依赖的 `pycep` 库存在一些尚未覆盖的语法，例如 [issue #7364](https://github.com/bridgecrewio/checkov/issues/7364) 报告的 `extension` 关键字，会直接抛出解析错误并终止该文件扫描。 - **Kubernetes**：扫描 `.yaml`/`.yml` 清单，需要文件能被 `yaml.safe_load` 解析。若清单中存在未渲染的占位符（如 `${K8S_APP_NAME}`），解析可能失败并被静默跳过，参见 [issue #7210](https://github.com/bridgecrewio/checkov/issues/7210)。 - **Helm**：先 `helm template` 渲染 chart，再以 Kubernetes 清单的形式送入检查器。 - **Kustomize**：执行 `kustomize build` 后同样转换为 Kubernetes 清单后再扫描。 这些框架与 Terraform、CloudFormation 共享同一套"注册中心 → 检查器 → 报告器"管线，因此新增一类 IaC 框架的主要工作是实现其特定的"输入解析 + 图构建"步骤。 ## 常见问题与社区反馈 - **依赖与打包**：[issue #6950](https://github.com/bridgecrewio/checkov/issues/6950) 反馈 Python 包名空间仍停留在 23.x，导致与较新依赖共同构建时产生版本冲突。 - **依赖 CVE**：[issue #7504](https://github.com/bridgecrewio/checkov/issues/7504) 指出 Checkov 3.2.517 打包的 `urllib3`、`asteval`、`ply` 存在多个高危 CVE，需要在发行版中升级。 - **Pulumi 支持**：[issue #568](https://github.com/bridgecrewio/checkov/issues/568) 长期跟踪 Pulumi IaC 的支持请求，是社区关注度最高的扩展方向之一。 - **.tfvars 解析**：[issue #386](https://github.com/bridgecrewio/checkov/issues/386) 讨论 `.tfvars` 变量文件在 Checkov 中尚无原生支持，影响变量展开与变量相关策略的准确性。 - **外部模块中的抑制**：[issue #4366](https://github.com/bridgecrewio/checkov/issues/4366) 指出 `checkov:skip` 元数据在外部模块内的资源上未生效。 - **CKV2 行为差异**：[issue #6645](https://github.com/bridgecrewio/checkov/issues/6645) 报告通过 Homebrew 安装的 Checkov 在某些场景下不会运行 CKV2 检查，与 pip 安装行为不一致。 - **最新版本**：3.3.1 发布说明中新增了 `serverless: disable vars opt out`（[#7574](https://github.com/bridgecrewio/checkov/pull/7574)），调整了 Serverless 框架的变量解析默认行为。 ## See Also - Terraform Plan 扫描与图查询：见 [checkov/terraform/graph_manager.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/graph_manager.py) - 通用 Runner 与 CLI 入口：见 [checkov/main.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/main.py) - 资源检查注册中心：见 [checkov/common/checks/base_check_registry.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/checks/base_check_registry.py) - 抑制与跳过策略：见 [checkov/common/runner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/runner.py) --- ## Pipelines, VCS, OpenAPI & Cross-Platform Scanners ### 相关页面 相关主题：[IaC Framework Scanners (Terraform, CloudFormation, ARM/Bicep, Kubernetes, Helm, Kustomize)](#page-3), [Output Formats, Reporting & CI/CD Integrations](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py) - [checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [cdk_integration_tests/src/python/CloudtrailMultiRegion/pass.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/CloudtrailMultiRegion/pass.py) - [cdk_integration_tests/src/python/CloudtrailMultiRegion/fail__1__.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/CloudtrailMultiRegion/fail__1__.py)
# Pipelines、VCS、OpenAPI 与跨平台扫描器 ## 概述 Checkov 是一款面向基础设施即代码 (IaC) 与软件成分分析 (SCA) 的静态扫描工具。README 中明确列出其支持 Terraform、Terraform Plan、CloudFormation、AWS SAM、Kubernetes、Helm、Kustomize、Dockerfile、Serverless、Bicep、OpenAPI 与 ARM 等多种来源 资料来源：[README.md:1-15]()。 在企业实践中，Checkov 常被嵌入到 GitHub Actions、GitLab CI、Azure Pipelines 等流水线中运行；其扫描的 IaC 既包括手写 Terraform，也包括由 AWS CDK、Pulumi 等上层工具综合而成的产物。本页聚焦于**支撑这些跨平台、VCS 来源扫描的底层机制**：Terraform 模块加载链、版本约束解析、跨平台扫描样例。 ## Terraform 模块加载器体系 ### 加载器继承层次 Checkov 的模块加载器采用继承式设计，根类 `ModuleLoader` 定义 `discover()` 与 `_is_matching_loader()` 接口；各具体加载器按源类型进行识别与接管 资料来源：[checkov/terraform/module_loading/loaders/git_loader.py:1-44]()。 ```mermaid graph TD A[ModuleLoader 根类] --> B[RegistryLoader] A --> C[GenericGitLoader] C --> D[GithubLoader] C --> E[BitbucketLoader] C --> F[GithubAccessTokenLoader] C --> G[BitbucketAccessTokenLoader] ``` ### Registry 加载器 `RegistryLoader` 负责解析 Terraform 公共/私有 Registry 源。`discover()` 读取环境变量 `TF_HOST_NAME`（默认取自常量 `TFC_HOST_NAME`）与 `TF_REGISTRY_TOKEN`；若设置了 `TFC_TOKEN`，则发出弃用警告 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py:33-45]()。 URL 归一化逻辑会把无 netloc 的下载地址补全为 `https://{tf_host_name}{path}` 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py:62-65]()。`_get_archive_extension` 静态方法识别 `zip / tar.bz2 / tar.gz / tgz / tar.xz / txz` 等压缩格式，并兼容 URL 查询串中的 `archive=` 参数 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py:67-77]()。 ### GitHub / Bitbucket 加载器 - `GithubLoader` 将 `github.com/...`、`git@github.com:...`、`git::git@github.com:...` 三种写法分别转换为 `git::https://` 或 `git::ssh://` URL 资料来源：[checkov/terraform/module_loading/loaders/github_loader.py:13-30]()。 - `GithubAccessTokenLoader` 在 `discover()` 中设置 `module_source_prefix`，按三种前缀形式注入 `username:token` 凭据 资料来源：[checkov/terraform/module_loading/loaders/github_access_token_loader.py:1-30]()。 - `BitbucketLoader` 仅设置 `module_source_prefix = "bitbucket.org"`，其余逻辑由父类 `GenericGitLoader` 提供 资料来源：[checkov/terraform/module_loading/loaders/bitbucket_loader.py:1-15]()。 - `BitbucketAccessTokenLoader` 读取 `BITBUCKET_USERNAME`、`BITBUCKET_APP_PASSWORD`、`BITBUCKET_TOKEN`；若提供 token，则将用户名改写为 `x-token-auth` 以匹配 Bitbucket 的 Token Auth 协议 资料来源：[checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py:1-20]()。 ### 版本约束解析 `VersionConstraint` 封装单一约束，`VERSION_REGEX` 把字符串解析为 `{"version": "v1.2.3", "operator": ">="}` 结构 资料来源：[checkov/terraform/module_loading/loaders/versions_parser.py:1-15]()。支持的运算符包括 `= != > >= < <= ~>`，其中 `~>` 通过 `get_max_version_for_most_specific_segment()` 映射为"低于下一主版本"的区间上限 资料来源：[checkov/terraform/module_loading/loaders/versions_parser.py:17-35]()。该机制是 Registry 加载器正确挑选可下载 tarball 版本的依据。 ## 跨平台扫描与图扫描支撑 ### AWS CDK 集成样例 Checkov 不只扫描原生 Terraform，还能扫描由 AWS CDK（Python 写法的 `aws_cdk`）综合出的等效配置。仓库根目录下的 `cdk_integration_tests/` 提供对照样例： - 通过样例：`is_multi_region_trail=True`，Checkov 将得到 PASS 资料来源：[cdk_integration_tests/src/python/CloudtrailMultiRegion/pass.py:1-19]()。 - 失败样例：`is_multi_region_trail=False`，将触发对应 CKV 规则并产生 FAILED 资源记录 资料来源：[cdk_integration_tests/src/python/CloudtrailMultiRegion/fail__1__.py:1-19]()。 这种"上层语言 → Terraform Plan JSON → Checkov 扫描"的链条体现了 Checkov 的跨平台扫描能力：任何能输出符合 Terraform Plan JSON Schema 的工具（如 CDK、pulumi-terraform-bridge 等）都可以被纳入扫描流水线。 ### IAM 策略与图扫描基类 `BaseTerraformCloudsplainingIAMScanner` 是被具体 AWS IAM 检查复用的基类。它在**类级别**缓存 `PolicyDocument`，避免在每次 `scan_resource_conf` 调用中重复构造对象 资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:1-22]()。当策略处于模板化、ARN 尚未填充的状态时，方法会捕获异常并返回 `CheckResult.UNKNOWN`，与 PASS / FAILED 形成三态区分 资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:28-39]()。该模式被 CloudFront、IAM 角色、信任策略等多条 CKV_AWS_* 规则共享。 ## 已知限制与社区反馈 README 标明 Checkov 当前支持 Python 3.9–3.13 资料来源：[README.md:150-155]()。与本节相关的社区反馈摘录如下： - `terraform show -json` 单行输出时，所有 finding 都会落到 0 行；建议用 `jq '.'` 重新格式化 资料来源：[README.md:90-110]()。 - Bicep 解析器尚不支持 `extension` 关键字 ([#7364](https://github.com/bridgecrewio/checkov/issues/7364))。 - Kubernetes 清单中的 `${VAR}` 占位符会被静默跳过 ([#7210](https://github.com/bridgecrewio/checkov/issues/7210))。 - Checkov 3.2.517 报告 urllib3 / asteval / ply 存在 CVE，建议升级依赖 ([#7504](https://github.com/bridgecrewio/checkov/issues/7504))。 - Homebrew 安装时 CKV2 检查未运行，与 pip 安装行为不一致 ([#6645](https://github.com/bridgecrewio/checkov/issues/6645))。 ## 参见 - Terraform Plan 扫描用法：[README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - 贡献新检查（Policy）：[Contribution Overview](https://github.com/bridgecrewio/checkov/blob/main/docs/6.Contribution/Contribution%20Overview.md) - 社区问题索引：[checkov issues](https://github.com/bridgecrewio/checkov/issues) --- ## Custom Policies: YAML & Python Authoring ### 相关页面 相关主题：[Core Architecture: Runners, Registries & Graph Engine](#page-2), [Output Formats, Reporting & CI/CD Integrations](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/checks/utils/iam_terraform_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/iam_terraform_document_to_policy_converter.py) - [checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py) - [cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/fail__1__.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/fail__1__.py) - [cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/pass.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/pass.py) - [cdk_integration_tests/src/python/SNSTopicEncryption/fail.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/SNSTopicEncryption/fail.py) - [cdk_integration_tests/src/python/CodeBuildProjectEncryption/pass.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/CodeBuildProjectEncryption/pass.py) - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md)
# 自定义策略：YAML 与 Python 编写 ## 概述 Checkov 是一个面向基础设施即代码（IaC）以及软件成分分析（SCA）的静态分析工具（资料来源：[README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md)）。除了内置检查外，用户可编写自定义策略来扩展检测能力。自定义策略主要通过两种形式落地：声明式的 YAML 策略文件，以及基于 Python 的检查类。本页从源码层面说明 Python 编写模式、模块加载对外部模块扫描的影响，以及 CDK 集成测试的约定。 ## Python 编写模式的常用工具 ### IAM 配置转换器 自定义 IAM 类检查通常需要把 HCL 或 CloudFormation 风格的配置转换为标准 IAM Policy Document。Checkov 提供两个无状态转换工具： - `convert_terraform_conf_to_iam_policy` 将 Terraform 中的小写字段（`statement`、`actions`、`resources`、`effect`、`condition`）映射为大写标准字段（`Statement`、`Action`、`Resource`、`Effect`、`Condition`），并在 effect 缺省时填入 `"Allow"`（资料来源：[checkov/terraform/checks/utils/iam_terraform_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/iam_terraform_document_to_policy_converter.py)）。 - `convert_cloudformation_conf_to_iam_policy` 处理大写字段名 `Statement`、`Action`、`Resource`、`NotAction`、`NotResource`、`Effect`，对列表型 Resource 取首元素，同样在缺省时填入 `"Allow"`（资料来源：[checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/cloudformation/checks/utils/iam_cloudformation_document_to_policy_converter.py)）。 二者均通过 `pickle_deepcopy` 避免污染原始配置，自定义 Python 检查可直接复用而无需自行解析 HCL/JSON。 ### Cloudsplaining IAM 扫描基类 `BaseTerraformCloudsplainingIAMScanner` 是为 Python 自定义 IAM 检查提供的基类，封装了与 Cloudsplaining 引擎的集成。它在类级维护 `policy_document_cache` 以缓存生成的 `PolicyDocument`，避免重复计算；`scan_conf` 方法调用子类实现的 `convert_to_iam_policy`、`cloudsplaining_analysis` 与 `cloudsplaining_enrich_evaluated_keys`。检测到违规时返回 `CheckResult.FAILED`，无违规返回 `CheckResult.PASSED`，遇到模板 ARN 未填充等异常则返回 `CheckResult.UNKNOWN`（资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py)）。该基类是 YAML 难以表达的复杂 IAM 规则（如 privilege escalation 检测）在 Python 端的典型落地方式。 ## Terraform 模块加载与外部模块扫描 自定义策略扫描 Terraform 代码时，模块加载器决定如何发现并下载外部模块。Checkov 通过多种 `ModuleLoader` 子类协同工作： - **RegistryLoader**：通过 Terraform Registry 的 versions API 解析模块版本，使用 `versions_parser.py` 中的 `VERSION_REGEX` 解析约束，并调用 `order_versions_in_descending_order` 与 `get_version_constraints` 选择合适版本（资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py)、[checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py)）。 - **GenericGitLoader**：匹配 `git::://` 形式的通用 Git 仓库，从环境变量 `VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` 读取凭据；`_process_generic_git_repo` 解析协议、用户名、inner_module 与 ref（资料来源：[checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py)）。 - **GithubLoader**：专用于 `github.com/...` 源码，将 `git@github.com:org/repo` 改写为 `git::https://` 或 `git::ssh://` 形式（资料来源：[checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py)）。 - **GithubAccessTokenLoader**：在已配置 `username` 与 `token` 时将 GitHub URL 转为带凭据的 HTTPS 形式（资料来源：[checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py)）。 下表归纳主要加载器的匹配规则与凭据来源： | 加载器 | URL 形式 | 凭据来源 | |---|---|---| | RegistryLoader | Terraform Registry API | `TF_HOST_NAME`、`TF_REGISTRY_TOKEN`、`TFC_TOKEN` | | GenericGitLoader | `git::://...` | `VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` | | GithubLoader | `github.com/...`、`git@github.com:...` | `GITHUB_PAT` 环境变量 | | GithubAccessTokenLoader | 同 GithubLoader（带 Token） | 已注入的 `username` + `token` | 自定义策略在扫描外部模块时受 `loader.discover` 与 `_is_matching_loader` 行为影响——若加载器在 `discover` 阶段未匹配上对应环境变量，可能直接进入"跳过"分支，相关讨论见 issue #4366。 ## CDK Python 集成测试夹具约定 Checkov 通过 CDK 集成测试验证自定义检查对 AWS CDK 合成产物的检测能力。测试夹具遵循 `pass.py` 与 `fail.py` / `fail____.py` 的命名约定，框架据此自动识别预期结果。例如： - `IAMPolicyAttachedToGroupOrRoles/fail__1__.py` 创建 `iam.Policy` 时将 `users=["a"]` 直接挂到用户，违反"策略不应直接附加到用户"类检查；对应 `pass.py` 未附加到任何用户（资料来源：[cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/fail__1__.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/fail__1__.py)、[cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/pass.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/IAMPolicyAttachedToGroupOrRoles/pass.py)）。 - `SNSTopicEncryption/fail.py` 创建一个未启用加密的 `sns.Topic`，用于测试 SNS 加密类自定义检查的反例（资料来源：[cdk_integration_tests/src/python/SNSTopicEncryption/fail.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/SNSTopicEncryption/fail.py)）。 - `CodeBuildProjectEncryption/pass.py` 中的 Artifacts 设置 `encryption_disabled=True`，也是相关加密类检查的测试用例（资料来源：[cdk_integration_tests/src/python/CodeBuildProjectEncryption/pass.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/CodeBuildProjectEncryption/pass.py)）。 在为 Python 自定义检查编写回归用例时，建议沿用此命名与目录结构，便于 Checkov 测试运行器自动发现。 ## 常见失败模式 社区中与自定义策略相关的反馈集中在以下几类： - 外部模块抑制失效：`checkov:skip` 在外部模块中可能不生效，扫描器需要正确加载外部模块才会触达抑制注释（[issue #4366](https://github.com/bridgecrewio/checkov/issues/4366)）。 - Kubernetes 占位符被静默跳过：含 `${VAR}` 占位符的清单不会被扫描，自定义策略需显式处理这种边界（[issue #7210](https://github.com/bridgecrewio/checkov/issues/7210)）。 - Homebrew 与 pip 安装行为不一致：CKV2 检查在 Homebrew 安装时不会运行，与 pip 安装差异显著，建议 CI 中固定使用 pip（[issue #6645](https://github.com/bridgecrewio/checkov/issues/6645)）。 - Python 包版本冲突：`checkov` 仍受限于 `23.x`，与使用 `>=24` 的项目存在依赖冲突（[issue #6950](https://github.com/bridgecrewio/checkov/issues/6950)）。 - 传递依赖 CVE：`urllib3`、`asteval`、`ply` 等存在已知漏洞，建议升级或使用 `--skip-download`（[issue #7504](https://github.com/bridgecrewio/checkov/issues/7504)）。 ## 另请参阅 - [Checkov 官方快速入门文档](https://www.checkov.io/1.Welcome/Quick%20Start.html) - [Checkov 贡献指南（CONTRIBUTING.md）](https://github.com/bridgecrewio/checkov/blob/main/CONTRIBUTING.md) - [Terraform 模块加载源码目录](https://github.com/bridgecrewio/checkov/tree/main/checkov/terraform/module_loading) - [Cloudsplaining 项目](https://github.com/salesforce/cloudsplaining) - 相关 GitHub Issues：#6950、#7504、#7210、#6645、#4366 --- ## Output Formats, Reporting & CI/CD Integrations ### 相关页面 相关主题：[Overview, Installation & Quick Start](#page-1), [Pipelines, VCS, OpenAPI & Cross-Platform Scanners](#page-4), [Secrets, SCA & SAST Scanning](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [checkov/common/output/report.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/output/report.py) - [checkov/common/output/record.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/output/record.py) - [checkov/common/output/sarif.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/output/sarif.py) - [checkov/common/output/cyclonedx.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/output/cyclonedx.py) - [checkov/common/output/junit.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/output/junit.py) - [checkov/common/output/csv.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/output/csv.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py)
# Output Formats, Reporting & CI/CD Integrations ## 一、概述与设计目标 Checkov 的输出与报告子系统承担两项核心职责：将多框架（Terraform、CloudFormation、Kubernetes、Bicep、ARM 等）扫描得到的检查结果（CheckResult）序列化为可被外部系统消费的格式，以及提供与 CI/CD 流水线对接的退出码、抑制与过滤机制。Checkov 本身定位为静态代码分析工具与软件成分分析（SCA）工具的结合体，因此其报告层既要服务于人工阅读（CLI 富文本、表格），也要服务于自动化系统（JUnit、SARIF、CycloneDX、CSV 等） 资料来源：[README.md:1-40]()。 报告模块的统一抽象由 `checkov/common/output/report.py` 承担，单条检查结果通过 `Record` 描述（位于 `record.py`），多种序列化器（`sarif.py`、`junit.py`、`cyclonedx.py`、`csv.py` 等）将记录集合转换为不同标准格式 资料来源：[checkov/common/output/report.py]()、[checkov/common/output/record.py]()。 ## 二、支持的输出格式矩阵 下表汇总了 Checkov 在报告层对外暴露的主要输出格式及其典型使用场景： | 输出格式 | 实现模块 | 主要使用场景 | | --- | --- | --- | | `cli` | `report.py`（默认） | 本地终端交互阅读、CI 日志直接打印 | | `json` | `report.py` | 程序化消费、聚合多框架结果 | | `junitxml` | `checkov/common/output/junit.py` | CI 系统（GitHub Actions、Jenkins、GitLab CI）解析测试报告 | | `sarif` | `checkov/common/output/sarif.py` | GitHub Code Scanning、IDE/安全平台集成 | | `cyclonedx` | `checkov/common/output/cyclonedx.py` | SCA、SBoM 工具链（Dependency-Track 等） | | `csv` | `checkov/common/output/csv.py` | 离线审计、Excel/电子表格分析 | | `cli` + `BcApi` | `report.py` + Prisma Cloud API | 富文本报告，并通过 API 富化指南链接 | 通过 `--output` 参数可指定一个或多个目标格式，Checkov 会并发生成对应的报告文件 资料来源：[README.md:88-110]()、`[checkov/common/output/report.py]()`。 ## 三、运行流程与数据流 Checkov 一次完整扫描到输出的处理流水线可概括为下图： ```mermaid flowchart LR A[IaC 源码
Terraform/CloudFormation/K8s/Bicep] --> B[Runner & Parser] B --> C[Check 注册表
CKV_* 与 CKV2_*] C --> D[Record 集合
record.py] D --> E[Report 聚合
report.py] E --> F1[cli] E --> F2[junit] E --> F3[sarif] E --> F4[cyclonedx] E --> F5[csv] E --> G[退出码 &
严重度过滤] G --> H[CI/CD 流水线] ``` 要点说明： 1. **资源级缓存**：诸如 `BaseTerraformCloudsplainingIAMScanner` 之类的检查器在类级别维护 `policy_document_cache`，避免重复解析同一 IAM 策略，提升多格式输出阶段性能 资料来源：[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:8-18]()`。 2. **外部模块解析**：当扫描 Terraform 时遇到 registry、git、GitHub 源模块，`registry_loader.py` 等 Loader 会先拉取远端内容再注入到同一报告流程 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py]()`。 3. **退出码控制**：`--hard-fail-on` / `--soft-fail-on` 与严重度过滤结合，决定扫描在 CI 中以何种状态码失败，相关参数需要 API key 才能生效，社区多次反馈缺乏 API key 时缺少明确警告（参考 issue #7379） 资料来源：[community_context #7379]()。 ## 四、CI/CD 集成与配置管理 ### 4.1 配置文件与命令行优先级 Checkov 支持四层配置来源（优先级递减）： 1. 命令行参数 2. 环境变量（如 `BC_API_KEY`、`TF_REGISTRY_TOKEN`、`VCS_TOKEN` 等） 3. 配置文件（默认 `~/.checkov.yml`） 4. 内置默认值 通过 `checkov --show-config` 可一次性查看所有生效配置及其来源，例如 README 给出如下示例 资料来源：[README.md:180-200]()： ```sh 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 ``` ### 4.2 典型 CI 集成片段 ```yaml # GitHub Actions 示例 - name: Run Checkov env: BC_API_KEY: ${{ secrets.BC_API_KEY }} run: | checkov -d . \ --output cli --output junitxml --output sarif \ --output-file-path ./reports,cli,./reports/junit.xml,./reports/results.sarif \ --soft-fail - name: Upload SARIF uses: github/codeql-action/upload-sarif@v3 with: sarif_file: ./reports/results.sarif ``` ### 4.3 已知的集成陷阱 - **Homebrew vs pip 行为差异**：社区报告通过 Homebrew 安装时 CKV2 检查不会运行（issue #6645），导致本地与 CI 结果不一致；建议在 CI 中固定使用 `pip` 安装并锁定版本 资料来源：[community_context #6645]()。 - **依赖漏洞**：Checkov 3.2.517 中 `urllib3`、`asteval`、`ply` 等传递依赖存在 CVE（issue #7504），在长期 CI 流水线中需定期升级基础镜像或锁定依赖版本 资料来源：[community_context #7504]()。 - **Kubernetes 模板占位符**：包含 `${VAR}` 的 K8s 清单会被静默跳过（issue #7210），CI 任务可能在缺少这些文件时仍显示成功，建议在 pre-step 中校验或显式 fail-on 静默跳过 资料来源：[community_context #7210]()。 - **Bicep/ARM 限制**：Bicep 解析器缺少 `extension` 关键字支持（issue #7364），对真实 Azure 项目的扫描覆盖率与官方文档期望不一致（issue #7394），CI 中可加 `--skip-framework bicep` 或等待上游 pycep 合并修复 资料来源：[community_context #7364]()、[community_context #7394]()。 ## 五、报告富化与 API 调用 Checkov 在生成报告时会调用 Prisma Cloud 公共 API 为每条检查结果追加修复指南链接（Guide URL）。若不希望上传元数据，可使用 `--skip-download` 完全跳过该调用 资料来源：[README.md:225-235]()`。该行为在受合规约束的 CI 环境（离线或严格数据出境限制）中尤为重要，建议在内部管道中默认开启。 ## See Also - [CKV2 检查与外部模块抑制增强](issue #4366) - [Pulumi 支持请求](issue #568) - [严重度控制与报告](issue #884) - [Terraform Plan 变量暴露](issue #7396) - [3.3.1 发布说明（serverless: disable vars opt out）](https://github.com/bridgecrewio/checkov/releases/tag/3.3.1) --- ## Secrets, SCA & SAST Scanning ### 相关页面 相关主题：[IaC Framework Scanners (Terraform, CloudFormation, ARM/Bicep, Kubernetes, Helm, Kustomize)](#page-3), [Output Formats, Reporting & CI/CD Integrations](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [checkov/common/models/consts.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/models/consts.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [cdk_integration_tests/src/typescript/GlueSecurityConfiguration/fail.ts](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/typescript/GlueSecurityConfiguration/fail.ts) - [cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts) - [cdk_integration_tests/src/python/BackupVaultEncrypted/fail__1__.py](https://github.com/bridgecrewio/checkov/blob/main/cdk_integration_tests/src/python/BackupVaultEncrypted/fail__1__.py)
# Secrets, SCA & SAST 扫描 ## 项目能力概览 Checkov 是一个面向基础设施即代码 (IaC) 的静态代码分析工具，并兼有软件成分分析 (SCA) 能力。资料来源：[README.md:14-25]() 明确指出："它会执行 SCA 扫描，对开源软件包与镜像进行通用漏洞披露 (CVE) 检测"。这意味着除 IaC 之外，Checkov 还在镜像、开放源软件包与源码层面提供安全扫描，覆盖 secrets 扫描、SCA 与 SAST 三个维度。 ## Secrets 凭据检测 `checkov/common/models/consts.py` 中预置了凭据识别的正则常量。资料来源：[checkov/common/models/consts.py:36-38]() 定义了 `access_key_pattern`，用于匹配形如 AWS Access Key 的 20 位大写字母数字串（`[A-Z0-9]{20}`）。检测器在源码、IaC 文件、配置文件中匹配该模式，识别被无意提交的长期凭据。同时 `checkov/common/models/consts.py:32-33` 中 `SUPPORTED_FILE_EXTENSIONS` 限定了 secrets 扫描的输入文件范围，包括 `.tf`、`.yml`、`.json`、`.template`、`.bicep`、`.hcl` 等。 ## SCA 软件成分分析 ### 支持的包文件类型 `checkov/common/models/consts.py` 中以集合形式声明了 Checkov 识别的清单与依赖锁文件。资料来源：[checkov/common/models/consts.py:6-17]() 中的 `SUPPORTED_PACKAGE_FILES` 涵盖 `bower.json`、`package.json`、`package-lock.json`、`npm-shrinkwrap.json`、`pom.xml`、`requirements.txt`、`Pipfile`、`Pipfile.lock`、`build.gradle`、`build.gradle.kts`、`go.sum`、`METADATA` 等；`[checkov/common/models/consts.py:19-21]()` 的 `DEPENDENCY_TREE_SUPPORTED_FILES` 包含 `yarn.lock`、`Gemfile`、`Gemfile.lock`、`go.mod`、`paket.dependencies`、`paket.lock`、`packages.config`、`composer.json`、`composer.lock`。两组常量共同驱动 SCA 引擎解析依赖并比对已知漏洞库。 ### SCA 支持目标一览 | 类别 | 示例 | |------|------| | 包清单文件 | `package.json`、`pom.xml`、`requirements.txt`、`Pipfile` | | 依赖树锁文件 | `yarn.lock`、`go.sum`、`Gemfile.lock`、`composer.lock` | | 容器镜像 | Dockerfile 中 `FROM` 引用的镜像 CVE 比对 | | 特殊扩展 | `.csproj`（由 `SCANNABLE_PACKAGE_FILES_EXTENSIONS` 处理） | ## SAST 静态应用安全测试 ### 支持的语言与文件扩展名 `checkov/common/models/consts.py` 通过 `SAST_SUPPORTED_FILE_EXTENSIONS` 字典声明 SAST 引擎可识别的源码扩展名。资料来源：[checkov/common/models/consts.py:27-35]() 覆盖五种语言：Java (`.java`)、JavaScript (`.js`)、TypeScript (`.ts`)、Python (`.py`)、Golang (`.go`)。Checkov 在执行扫描时通过这些扩展名发现源码文件并对其运行安全规则评估，例如 `BaseTerraformCloudsplainingIAMScanner` 等基于 AST 的检查（见 `[checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py:11-20]()`）。 ## 扫描引擎的基础设施支撑 ### 模块加载与私有仓库适配 虽然 SCA/SAST 各自独立，但 Checkov 在执行 IaC 扫描时常需解析外部模块。资料来源：[checkov/terraform/module_loading/loaders/git_loader.py:42-50]() 中的 `GenericGitLoader` 通过 `VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` 环境变量支持私有 VCS；`[checkov/terraform/module_loading/loaders/github_loader.py:11-15]()` 与 `[checkov/terraform/module_loading/loaders/github_access_token_loader.py:1-12]()` 提供 GitHub 风格仓库的访问令牌注入；`[checkov/terraform/module_loading/loaders/registry_loader.py:18-23]()` 的 `MODULE_ARCHIVE_EXTENSIONS` 与 `tf_modules_endpoint` 处理 Terraform Registry 下载；`[checkov/terraform/module_loading/loaders/versions_parser.py:7-15]()` 的 `VersionConstraint` 类负责解析 `=`、`!=`、`>=`、`<=`、`~>` 等语义化版本约束。这一基础设施使 Checkov 在受限网络下也能完成扫描。 ### CDK 集成测试覆盖多语言 `cdk_integration_tests/` 目录下的样例验证了 Checkov 对 AWS CDK 多语言场景的检查能力。资料来源：[cdk_integration_tests/src/typescript/GlueSecurityConfiguration/fail.ts:1-10]() 与 `[cdk_integration_tests/src/typescript/SNSTopicEncryption/fail.ts:1-12]()` 分别覆盖 Glue 安全配置与 SNS 加密；`[cdk_integration_tests/src/python/BackupVaultEncrypted/fail__1__.py:1-12]()` 展示 Python CDK 的备份保险库加密检查。这些失败用例与 SAST 规则库共同验证多语言扫描的可靠性。 ## 已知限制与社区反馈 - **间接依赖漏洞**：社区 Issue #7504 报告 Checkov 3.2.517 的间接依赖 `urllib3`、`asteval`、`ply` 存在已知 CVE（如 CVE-2026-21441，CVSS 8.9）。这表明 SCA 引擎自身的依赖治理同样需要持续跟进。 - **跨模块抑制不完整**：Issue #4366 等社区问题反映外部模块下的 `checkov:skip` 抑制机制尚不完整，会影响 secrets/SCA/SAST 跨模块的检测覆盖面。 - **Kubernetes 模板静默跳过**：Issue #7210 指出当 K8s 清单含 `${VAR}` 占位符时会被静默跳过，缺乏告警。 ## See Also - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [checkov/common/models/consts.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/common/models/consts.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) --- ## Configuration, Suppression, External Modules & Troubleshooting ### 相关页面 相关主题：[Overview, Installation & Quick Start](#page-1), [IaC Framework Scanners (Terraform, CloudFormation, ARM/Bicep, Kubernetes, Helm, Kustomize)](#page-3), [Custom Policies: YAML & Python Authoring](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [checkov/terraform/module_loading/loaders/versions_parser.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/versions_parser.py) - [checkov/terraform/module_loading/loaders/git_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/git_loader.py) - [checkov/terraform/module_loading/loaders/registry_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/registry_loader.py) - [checkov/terraform/module_loading/loaders/github_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_access_token_loader.py) - [checkov/terraform/module_loading/loaders/github_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/github_loader.py) - [checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/bitbucket_access_token_loader.py) - [checkov/terraform/module_loading/loaders/local_path_loader.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/module_loading/loaders/local_path_loader.py) - [checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py](https://github.com/bridgecrewio/checkov/blob/main/checkov/terraform/checks/utils/base_cloudsplaining_iam_scanner.py) - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md)
# 配置、抑制、外部模块与故障排除 ## 配置机制与配置文件优先级 Checkov 支持多层级配置：命令行参数、环境变量、`.checkov.yml` 配置文件以及默认值。可通过 `checkov --show-config` 查看当前生效的配置来源及其优先级，输出会按"命令行 → 环境变量 → 配置文件 → 默认值"的顺序逐项展示 资料来源：[README.md:43-62]()。 社区实践中常见的一个痛点是：使用 `--hard-fail-on` / `--soft-fail-on` 按严重级别（`HIGH`、`CRITICAL` 等）过滤时，若未设置 `BC_API_KEY`，相关参数会静默失效，从而造成本地与 CI 行为不一致 资料来源：[#7379]()。建议在 CI 中始终显式注入 API 密钥，或改用基于检查 ID 的过滤策略（如 `--skip-check` / `--check`）。 ## 外部模块加载体系 Checkov 通过一组 `ModuleLoader` 实现对 Terraform `module` 块不同来源的解析。核心抽象位于 `checkov/terraform/module_loading/loaders/`，并由分发器按 `module_source` 前缀选择匹配的 loader 资料来源：[checkov/terraform/module_loading/loaders/git_loader.py:27-50]()。 下表概括当前支持的加载器： | Loader | 适用源 | 关键环境变量 | 备注 | |---|---|---|---| | `RegistryLoader` | Terraform Registry 及 HTTP 归档 | `TF_HOST_NAME`、`TF_REGISTRY_TOKEN`、`TFC_TOKEN` | 通过 `tf_modules_versions_endpoint` 查询版本列表 | | `GenericGitLoader` | `git::` 通用 Git 仓库 | `VCS_BASE_URL`、`VCS_USERNAME`、`VCS_TOKEN` | 默认前缀 `git::https://` | | `GithubLoader` / `GithubAccessTokenLoader` | `github.com/org/repo` 短格式 | `GITHUB_PAT` | 自动转换为 `git::https://` 形式 | | `BitbucketAccessTokenLoader` | `bitbucket.org` 源 | `BITBUCKET_USERNAME`、`BITBUCKET_APP_PASSWORD`、`BITBUCKET_TOKEN` | 当仅提供 `BITBUCKET_TOKEN` 时使用 `x-token-auth` 用户名 | | `LocalPathLoader` | 本地相对/绝对路径 | 无 | 路径不存在时抛出 `FileNotFoundError` | 对于 Registry 源，`RegistryLoader._get_archive_extension` 依据 `MODULE_ARCHIVE_EXTENSIONS = ["zip", "tar.bz2", "tar.gz", "tgz", "tar.xz", "txz"]` 识别归档类型，并使用 `VERSION_REGEX` 解析 `=`、`!=`、`>=`、`<=`、`~>` 等运算符约束版本 资料来源：[checkov/terraform/module_loading/loaders/registry_loader.py:33-49]()、[checkov/terraform/module_loading/loaders/versions_parser.py:11-15]()。 Git 源由 `GenericGitLoader._parse_module_source` 拆解 `protocol`、`root_module`、`inner_module` 与 `version`；`GithubLoader` 进一步把 `github.com/org/repo` 重写为 `git::https://` 形式，`GithubAccessTokenLoader` 则把凭据注入 URL 以支持私有仓库 资料来源：[checkov/terraform/module_loading/loaders/github_loader.py:13-33]()、[checkov/terraform/module_loading/loaders/github_access_token_loader.py]()。 ## 抑制规则与外部模块注意事项 Checkov 通过注释形式识别抑制注解（如 `checkov:skip=CKV_ID:reason`）。社区已报告的痛点是：当目标检查位于下载到 `.external_modules/` 的外部模块源码中时，suppression 不会生效，导致第三方模块的命中难以屏蔽 资料来源：[#4366]()。临时方案是结合 `--skip-check` 与 `--skip-framework`，或直接修改外部模块源后再发布。 使用未确定的占位符（如 `${K8S_APP_NAME}` 或 `random_id`）时，Checkov 会在 Kubernetes、Terraform plan 等场景中静默跳过某些检查（`CKV_GCP_62`、`CKV_GCP_63` 即典型）。建议在资源中提供可静态解析的值，或启用 `--evaluate-variables` 资料来源：[#7473]()、[#7210]()。 ## 常见故障排除 以下汇总社区中高频出现的问题与对应排查思路： - **CKV2 检查未运行（Homebrew 安装）**：Homebrew 发行版不包含 CKV2 策略包，应改用 `pip install checkov` 或官方 Docker 镜像以保持与 CI 一致 资料来源：[#6645]()。 - **依赖 CVE 告警**：3.2.517 等旧版本捆绑的 `urllib3`、`asteval`、`ply` 存在公开漏洞，需升级到包含修复版本的发行版 资料来源：[#7504]()。 - **Python 包打包版本限制**：通过 `pip` 集成时 `checkov` 仅以 23.x 形式发布，会与要求 `>=24` 的依赖冲突，需在打包脚本中放宽约束 资料来源：[#6950]()。 - **CloudFront v2 日志误报（CKV_AWS_86）**：检查未覆盖 `logging.v2` 字段，可临时通过 `--skip-check CKV_AWS_86` 屏蔽 资料来源：[#7385]()。 - **GKE `remove_default_node_pool` 误报（CKV_GCP_123）**：设置该字段后仍失败时，可加 `checkov:skip=CKV_GCP_123` 直至上游修复 资料来源：[#7406]()。 - **Spanner 多密钥误报（CKV_GCP_93）**：当前实现未识别多 KMS 密钥模式，建议同样使用注释抑制 资料来源：[#7402]()。 - **启动报错 `AttributeError: module 'pycares' has no attribute 'ares_query_a_result'`**：常见于 `uv` 等隔离环境，请固定 `pycares` 版本或改用 `pip` 资料来源：[#7398]()。 - **Bicep `extension` 关键字解析失败**：底层 `pycep` 解析器尚未支持，应升级依赖或在模板中暂时避免使用 资料来源：[#7364]()。 - **`.tfvars` 文件未被识别**：当前对纯 `.tfvars` 文件的支持有限，建议将变量内联到 `.tf` 中或通过 `--repo-root-plan-file` 关联 资料来源：[#386]()。 ## 参见 - [README.md](https://github.com/bridgecrewio/checkov/blob/main/README.md) - [Checkov 策略索引与编写指南](https://github.com/bridgecrewio/checkov/blob/main/docs/6.Contribution/Contribution%20Overview.md) - Issue [#4366](https://github.com/bridgecrewio/checkov/issues/4366) — 外部模块抑制支持 - Issue [#7379](https://github.com/bridgecrewio/checkov/issues/7379) — API 密钥缺失时的告警增强 - [v2 → v3 迁移指南](https://github.com/bridgecrewio/checkov/blob/main/docs/1.Welcome/Migration.md) --- --- ## Doramagic 踩坑日志 项目：bridgecrewio/checkov 摘要：发现 35 个潜在踩坑项，其中 9 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bicep / ARM support expectations are misleading for real-world Azure usage。 ## 1. 安装坑 · 来源证据：Bicep / ARM support expectations are misleading for real-world Azure usage - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bicep / ARM support expectations are misleading for real-world Azure usage - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7394 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安装坑 · 来源证据：Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/6645 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：update Python module packaging - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：update Python module packaging - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/6950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 来源证据：GCS Bucket Logging Checks with Undetermined Value - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：GCS Bucket Logging Checks with Undetermined Value - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7473 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 安全/权限坑 · 失败模式：security_permissions: Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517 - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517 - 对用户的影响：Developers may expose sensitive permissions or credentials: Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517 - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7504 | Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517 ## 6. 安全/权限坑 · 来源证据：CKV_GCP_93 false positive when using multi-key configuration - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CKV_GCP_93 false positive when using multi-key configuration - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7402 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 安全/权限坑 · 来源证据：Expose variables from terraform plan - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Expose variables from terraform plan - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7396 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 安全/权限坑 · 来源证据：Kubernetes manifests with ${VAR} placeholders are silently skipped - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Kubernetes manifests with ${VAR} placeholders are silently skipped - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7210 | 来源类型 github_issue 暴露的待验证使用条件。 ## 9. 安全/权限坑 · 来源证据：Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Multiple CVEs in Dependencies (urllib3, asteval, ply) - Checkov 3.2.517 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7504 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 10. 安装坑 · 失败模式：installation: Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew - 对用户的影响：Developers may fail before the first successful local run: Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/6645 | Discrepancy Between Homebrew vs pip Installations: CKV2 Checks Not Running with Homebrew ## 11. 安装坑 · 失败模式：installation: feat(general): Add warnings when API-dependent parameters are used without API key - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: feat(general): Add warnings when API-dependent parameters are used without API key - 对用户的影响：Developers may fail before the first successful local run: feat(general): Add warnings when API-dependent parameters are used without API key - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7379 | feat(general): Add warnings when API-dependent parameters are used without API key ## 12. 安装坑 · 失败模式：installation: update Python module packaging - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: update Python module packaging - 对用户的影响：Developers may fail before the first successful local run: update Python module packaging - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/6950 | update Python module packaging ## 13. 配置坑 · 失败模式：configuration: Bicep: Missing parser support for `extension` keyword - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Bicep: Missing parser support for `extension` keyword - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Bicep: Missing parser support for `extension` keyword - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7364 | Bicep: Missing parser support for `extension` keyword ## 14. 配置坑 · 失败模式：configuration: CKV_AWS_86 only validates v1 logging, not v2 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: CKV_AWS_86 only validates v1 logging, not v2 - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CKV_AWS_86 only validates v1 logging, not v2 - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7385 | CKV_AWS_86 only validates v1 logging, not v2 ## 15. 配置坑 · 失败模式：configuration: CKV_GCP_123 triggers even if remove_default_node_pool is set - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: CKV_GCP_123 triggers even if remove_default_node_pool is set - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CKV_GCP_123 triggers even if remove_default_node_pool is set - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7406 | CKV_GCP_123 triggers even if remove_default_node_pool is set ## 16. 配置坑 · 失败模式：configuration: CKV_GCP_93 false positive when using multi-key configuration - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: CKV_GCP_93 false positive when using multi-key configuration - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CKV_GCP_93 false positive when using multi-key configuration - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7402 | CKV_GCP_93 false positive when using multi-key configuration ## 17. 配置坑 · 失败模式：configuration: GCS Bucket Logging Checks with Undetermined Value - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: GCS Bucket Logging Checks with Undetermined Value - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: GCS Bucket Logging Checks with Undetermined Value - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7473 | GCS Bucket Logging Checks with Undetermined Value ## 18. 配置坑 · 来源证据：CKV_GCP_123 triggers even if remove_default_node_pool is set - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：CKV_GCP_123 triggers even if remove_default_node_pool is set - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7406 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 19. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/bridgecrewio/checkov | README/documentation is current enough for a first validation pass. ## 20. 运行坑 · 运行可能依赖外部服务 - 严重度：medium - 证据强度：source_linked - 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。 - 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 - 证据：packet_text.keyword_scan | https://github.com/bridgecrewio/checkov | matched external service / cloud / webhook / database keyword ## 21. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/bridgecrewio/checkov | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/bridgecrewio/checkov | no_demo; severity=medium ## 23. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/bridgecrewio/checkov | no_demo; severity=medium ## 24. 安全/权限坑 · 来源证据：Bicep: Missing parser support for `extension` keyword - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bicep: Missing parser support for `extension` keyword - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7364 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 25. 安全/权限坑 · 来源证据：CKV_AWS_86 only validates v1 logging, not v2 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CKV_AWS_86 only validates v1 logging, not v2 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7385 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 26. 安全/权限坑 · 来源证据：feat(general): Add warnings when API-dependent parameters are used without API key - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(general): Add warnings when API-dependent parameters are used without API key - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/bridgecrewio/checkov/issues/7379 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 27. 能力坑 · 失败模式：capability: Bicep / ARM support expectations are misleading for real-world Azure usage - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Bicep / ARM support expectations are misleading for real-world Azure usage - 对用户的影响：Developers may hit a documented source-backed failure mode: Bicep / ARM support expectations are misleading for real-world Azure usage - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7394 | Bicep / ARM support expectations are misleading for real-world Azure usage ## 28. 能力坑 · 失败模式：capability: Expose variables from terraform plan - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Expose variables from terraform plan - 对用户的影响：Developers may hit a documented source-backed failure mode: Expose variables from terraform plan - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7396 | Expose variables from terraform plan ## 29. 能力坑 · 失败模式：capability: Kubernetes manifests with ${VAR} placeholders are silently skipped - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: Kubernetes manifests with ${VAR} placeholders are silently skipped - 对用户的影响：Developers may hit a documented source-backed failure mode: Kubernetes manifests with ${VAR} placeholders are silently skipped - 证据：failure_mode_cluster:github_issue | https://github.com/bridgecrewio/checkov/issues/7210 | Kubernetes manifests with ${VAR} placeholders are silently skipped ## 30. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/bridgecrewio/checkov | issue_or_pr_quality=unknown ## 31. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/bridgecrewio/checkov | release_recency=unknown ## 32. 维护坑 · 失败模式：maintenance: 3.2.533 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: 3.2.533 - 对用户的影响：Upgrade or migration may change expected behavior: 3.2.533 - 证据：failure_mode_cluster:github_release | https://github.com/bridgecrewio/checkov/releases/tag/3.2.533 | 3.2.533 ## 33. 维护坑 · 失败模式：maintenance: 3.2.534 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: 3.2.534 - 对用户的影响：Upgrade or migration may change expected behavior: 3.2.534 - 证据：failure_mode_cluster:github_release | https://github.com/bridgecrewio/checkov/releases/tag/3.2.534 | 3.2.534 ## 34. 维护坑 · 失败模式：maintenance: 3.3.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: 3.3.0 - 对用户的影响：Upgrade or migration may change expected behavior: 3.3.0 - 证据：failure_mode_cluster:github_release | https://github.com/bridgecrewio/checkov/releases/tag/3.3.0 | 3.3.0 ## 35. 维护坑 · 失败模式：maintenance: 3.3.1 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: 3.3.1 - 对用户的影响：Upgrade or migration may change expected behavior: 3.3.1 - 证据：failure_mode_cluster:github_release | https://github.com/bridgecrewio/checkov/releases/tag/3.3.1 | 3.3.1