企业官网建设流程全解析

Checkov v2 到 v3 迁移指南：破坏性变更、Python 自定义检查新语法与命令行 Flag 整理

【免费下载链接】checkovPrevent cloud misconfigurations and find vulnerabilities during build-time in infrastructure as code, container images and open source packages with Checkov by Bridgecrew.项目地址: https://gitcode.com/GitHub_Trending/ch/checkov

Checkov 在 v3 版本中除了引入新功能外，还对原有行为做了一系列调整甚至完全移除。本篇迁移指南基于 docs/1.Welcome/Migration.md 展开，并结合当前仓库的源码实现（checkov/main.py、checkov/common/util/ext_argument_parser.py、checkov/common/bridgecrew/platform_integration.py、checkov/terraform/checks/resource/base_resource_check.py）逐项讲解：无参数运行时的 "level up" 流程为何消失、Python 自定义检查如何改用简化语法、使用平台 API Key 时为何必须指定--repo-id，以及三个废弃 flag 如何统一收编为--skip-download。读完本文，你可以对照自己的扫描脚本、CI 流水线与自定义检查代码，完成从 v2 到 v3 的无痛迁移。

一、v3 变更总览

v3 并非单纯的增量升级，以下是本文覆盖的四个破坏性/行为变更点：

对于大多数本地扫描（不带 API Key）的用法，除自定义检查语法外，其余变更基本无感；但凡是接入平台的 CI 流程，建议逐条核对。

二、"level up" 流程被移除

v3 之前，直接运行不带任何参数的checkov会触发 "level up" 流程——这是面向 Bridgecrew 独立版（standalone edition）的引导式体验。由于 Bridgecrew 独立版已于 2023 年底停止服务（见官方 End-of-Life 公告），v3 将该流程彻底移除。

从当前仓库源码看，checkov/main.py中已不存在任何 level up 相关分支逻辑，印证了这一功能在 v3 中的完全移除。迁移动作很简单：

• 不要再依赖"裸跑checkov会引导你注册/升级平台账号"这一交互；
• 所有扫描都应显式携带参数，例如至少指定扫描目录：checkov -d .；
• 如果脚本里依赖 level up 的交互式输出做后续判断，需要改为解析常规扫描报告。

三、Python 自定义检查：签名简化，entity_type 改为实例属性

v3 对 Python 自定义检查的核心改动是scan_resource_conf的方法签名。

3.1 旧语法（v2）

在 v2 中，自定义检查必须显式接收entity_type参数：

from __future__ import annotations from typing import Any from checkov.common.models.enums import CheckResult from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck class Example(BaseResourceCheck): ... def scan_resource_conf(self, conf: dict[str, list[Any]], entity_type: str) -> CheckResult: ...

3.2 新语法（v3）

v3 起签名只保留conf，若仍需知道当前资源类型，改为通过实例属性self.entity_type访问：

from __future__ import annotations from typing import Any from checkov.common.models.enums import CheckResult from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck class Example(BaseResourceCheck): ... def scan_resource_conf(self, conf: dict[str, list[Any]]) -> CheckResult: if self.entity_type == 'aws_instance': ... ...

3.3 源码层面发生了什么

这一变更对应 checkov/terraform/checks/resource/base_resource_check.py 中的基类实现：v3 中scan_entity_conf会在调用scan_resource_conf之前先把entity_type存入实例：

def scan_entity_conf(self, conf: Dict[str, List[Any]], entity_type: str) -> CheckResult: self.entity_type = entity_type ... return self.scan_resource_conf(conf)

而抽象方法scan_resource_conf的签名已改为只接收conf：

@abstractmethod def scan_resource_conf(self, conf: Dict[str, List[Any]]) -> CheckResult: ...

也就是说，框架在调度检查时负责注入entity_type，子类通过self.entity_type读取。迁移要点：

• 删除方法签名中多余的entity_type参数；
• 需要区分资源类型时改用self.entity_type；
• 注意self.entity_type是运行时由框架设置的实例属性，不要在类的__init__或类体顶层依赖其初值。

该模式同样适用于其他基于BaseResourceCheck派生的资源类检查（如 serverless、cloudformation 等目录下各自的base_resource_check），自定义检查按各自框架的基类同步调整即可。

四、API Key 场景：--repo-id成为必填项

v3 起，任何使用平台 API Key 运行 Checkov 的扫描都必须显式提供--repo-id，否则会直接报错退出。

4.1 正确用法

checkov -d . --bc-api-key xyz --repo-id example/example

--repo-id的格式要求为<repo_owner>/<repo_name>，例如bridgecrewio/checkov。

4.2 源码中的强制校验

校验逻辑位于 checkov/main.py 与 checkov/main.py：

• 一旦检测到--bc-api-key而--repo-id缺失（且非--list场景），解析器立即报错：--repo-id is required when using a platform API key；
• 即使提供了--repo-id，还会进一步校验其格式：必须包含/且两段都不能为空，否则提示--repo-id argument format should be 'organization/repository_name'。

该参数在 checkov/common/util/ext_argument_parser.py 中的定义也明确指出：Required when using the platform integration (API key)。

4.3 从源码看有哪些豁免与默认行为

值得注意的细节（来自 checkov/common/bridgecrew/platform_integration.py 的persist_repo_id实现）：

• 仅当使用--list（只列出策略不执行扫描）时，repo id 才被忽略；
• 若未显式传--repo-id，Checkov 会尝试从 CI 元数据提取器（CI_METADATA_EXTRACTOR.from_branch）推导，否则基于扫描目录/文件名生成形如cli_repo/<basename>的默认值；但带 API Key 的扫描不会走到这一兜底逻辑，因为上面第 4.2 节的硬校验会先拦截；
• 因此迁移时，务必在 CI 与本地带 Key 的扫描命令中统一补齐--repo-id <org>/<repo>，避免因校验失败导致流水线中断。

五、三个废弃 Flag 移除，统一收编为--skip-download

以下 flag 在 v2 中已废弃一段时间，v3 中被彻底移除：

• --no-guide
• --skip-suppressions
• --skip-policy-download

它们原本的职责被合并进单一的--skip-downloadflag。

5.1 新 flag 的语义

在 checkov/common/util/ext_argument_parser.py 中，--skip-download的帮助文本完整说明了其影响范围：

Do not download any data from Prisma Cloud. This will omit doc links, severities, etc., as well as custom policies and suppressions if using an API token. Note: it will prevent BC platform IDs from being available in Checkov.

翻译成行为清单即：使用--skip-download后，将不再从平台下载任何数据——包括文档链接（guide）、严重级别（severities）、自定义策略与抑制规则（suppressions），同时平台策略 ID 也将不可用。

5.2 源码中的落地

在 checkov/common/bridgecrew/platform_integration.py 中，skip_download标志被分布在多个下载入口（如第 994、1011、1065、1108、1153、1265 行附近的if self.skip_download is True:分支），统一控制各类平台数据的获取；而 checkov/main.py 中还会读取环境变量BC_SKIP_MAPPING，当其值为TRUE时同样会强制开启skip_download。

5.3 迁移对照

迁移动作：

• 在命令行、.checkov.yml配置文件及 CI 脚本中全局搜索并替换上述三个旧 flag；
• 确认--skip-download的副作用符合预期——尤其在使用 API Key 且希望保留平台策略、抑制规则与 doc 链接时，不要贸然添加该 flag；
• 若同时使用 API Key 与--skip-download，请注意 checkov/main.py 中的提示逻辑：Checkov 会建议配合--include-all-checkov-policies或--external-checks-dir，以保证跳过平台下载后仍能获得完整的策略集。

六、迁移清单速查

完成 v2 → v3 升级后，建议按以下清单逐项核对：

1. 裸跑检查：checkov不再触发 "level up" 流程，改为显式checkov -d <path>；
2. Python 自定义检查：删除scan_resource_conf中的entity_type形参，改用self.entity_type；
3. API Key 扫描：命令中补齐--repo-id <org>/<repo>，格式含/且两段非空；
4. 旧 flag 清理：移除--no-guide、--skip-suppressions、--skip-policy-download，按需使用--skip-download；
5. CI 回归：在本地与 CI 中各跑一次带 API Key 的扫描，确认报告、抑制规则与严重级别输出符合 v2 时期的预期。

迁移过程中如遇报错，可先通过checkov --help查看 checkov/common/util/ext_argument_parser.py 中注册的全部当前参数，再对照本文逐项排查。

【免费下载链接】checkovPrevent cloud misconfigurations and find vulnerabilities during build-time in infrastructure as code, container images and open source packages with Checkov by Bridgecrew.项目地址: https://gitcode.com/GitHub_Trending/ch/checkov