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/checkovCheckov 在 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 并非单纯的增量升级以下是本文覆盖的四个破坏性/行为变更点变更项变更类型影响对象移除 level up 流程功能移除习惯裸跑checkov命令的用户Python 自定义检查语法简化接口调整使用 Python 编写自定义策略的用户--repo-id成为 API Key 场景必填项新校验使用 Bridgecrew/Prisma Cloud API Key 的用户移除--no-guide、--skip-suppressions、--skip-policy-downloadFlag 清理在命令行或配置文件中引用这三个 flag 的自动化脚本对于大多数本地扫描不带 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 新语法v3v3 起签名只保留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的签名已改为只接收confabstractmethod 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-idCheckov 会尝试从 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 迁移对照v2 用法v3 用法checkov -d . --no-guidecheckov -d . --skip-downloadcheckov -d . --skip-suppressionscheckov -d . --skip-downloadcheckov -d . --skip-policy-downloadcheckov -d . --skip-download迁移动作在命令行、.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 升级后建议按以下清单逐项核对裸跑检查checkov不再触发 level up 流程改为显式checkov -d pathPython 自定义检查删除scan_resource_conf中的entity_type形参改用self.entity_typeAPI Key 扫描命令中补齐--repo-id org/repo格式含/且两段非空旧 flag 清理移除--no-guide、--skip-suppressions、--skip-policy-download按需使用--skip-downloadCI 回归在本地与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Checkov v2 到 v3 迁移指南：破坏性变更、Python 自定义检查新语法与命令行 Flag 整理
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/checkovCheckov 在 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 并非单纯的增量升级以下是本文覆盖的四个破坏性/行为变更点变更项变更类型影响对象移除 level up 流程功能移除习惯裸跑checkov命令的用户Python 自定义检查语法简化接口调整使用 Python 编写自定义策略的用户--repo-id成为 API Key 场景必填项新校验使用 Bridgecrew/Prisma Cloud API Key 的用户移除--no-guide、--skip-suppressions、--skip-policy-downloadFlag 清理在命令行或配置文件中引用这三个 flag 的自动化脚本对于大多数本地扫描不带 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 新语法v3v3 起签名只保留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的签名已改为只接收confabstractmethod 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-idCheckov 会尝试从 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 迁移对照v2 用法v3 用法checkov -d . --no-guidecheckov -d . --skip-downloadcheckov -d . --skip-suppressionscheckov -d . --skip-downloadcheckov -d . --skip-policy-downloadcheckov -d . --skip-download迁移动作在命令行、.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 升级后建议按以下清单逐项核对裸跑检查checkov不再触发 level up 流程改为显式checkov -d pathPython 自定义检查删除scan_resource_conf中的entity_type形参改用self.entity_typeAPI Key 扫描命令中补齐--repo-id org/repo格式含/且两段非空旧 flag 清理移除--no-guide、--skip-suppressions、--skip-policy-download按需使用--skip-downloadCI 回归在本地与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考