在 Jenkins 流水线中集成 Checkov构建时阻断云配置错误Pipeline Script 完整实战【免费下载链接】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 接入 Jenkins 流水线可以在开发者创建或修改基础设施即代码IaC时立即执行安全扫描一旦检测到云配置错误misconfiguration就使构建失败从而把安全左移到 CI/CD 的源头。本指南基于当前仓库的 Jenkins 集成文档给出完整的pipeline script示例、每个命令行参数的源码级解读、无 Docker 环境的备选安装方式以及 Enforcement Rules 硬/软失败机制的底层原理帮助你在不牺牲开发者体验的前提下落地“配置即失败”的门禁策略。集成思路为什么用容器镜像跑 CheckovCheckov 官方发布的 Docker 镜像bridgecrew/checkov:latest内置了完整的运行时与全部策略集Jenkins Agent 无需预装 Python 与依赖即可直接调用。核心流程是Jenkins 流水线检出目标仓库示例中使用 terragoat一个故意包含大量云配置漏洞的 Terraform 示例仓库在inside容器中运行checkov -d .扫描全部 IaC 文件同时输出cli与junitxml两种格式CLI 结果直接打印到控制台JUnit XML 写入results.xml调用 Jenkins 原生junit步骤解析 XML把每一次违规作为一个测试用例呈现在构建报告里任一检查失败时 Checkov 以非零退出码结束sh步骤抛错流水线标记为失败。这里的关键是 Checkov 的退出码语义默认情况下存在 FAILED 结果即返回非零退出码Jenkins 的sh步骤会据此判定构建失败从而天然形成门禁。相关设计可对照 Hard and soft fail 文档中的详细说明。前置准备一个可用的 Jenkins 实例且 Agent 节点上安装并配置了 Docker流水线通过docker.image(...).inside(...)在容器内执行命令待扫描的 IaC 仓库Terraform、CloudFormation、Kubernetes、Ansible 等均可Checkov 内置多框架 Runner可选Bridgecrew / Prisma Cloud 平台 API Key——仅在需要使用--use-enforcement-rules与--repo-id平台集成能力时才需要。分步教程步骤 1创建或打开 Jenkins Pipeline 任务在 Jenkins 中新建一个 Pipeline 类型的 Job或复用已有 Job如图中所示步骤 2在 Pipeline 定义中新增 Checkov Stage将 Job 的 Pipeline 定义方式选为Pipeline script然后粘贴以下完整脚本pipeline { agent any stages { stage(Checkout) { steps { git branch: master, url: https://github.com/bridgecrewio/terragoat stash includes: **/*, name: terragoat } } stage(Checkov) { steps { script { docker.image(bridgecrew/checkov:latest).inside(--entrypoint) { unstash terragoat try { sh checkov -d . --use-enforcement-rules -o cli -o junitxml --output-file-path console,results.xml --repo-id example/terragoat --branch master junit skipPublishingChecks: true, testResults: results.xml } catch (err) { junit skipPublishingChecks: true, testResults: results.xml throw err } } } } } } options { preserveStashes() timestamps() } }脚本要点拆解代码段作用git branch: master, url: ...terragoat检出待扫描仓库实际项目中应替换为自己的代码仓库地址与分支stash includes: **/*, name: terragoat将工作区内容暂存供后续 Stage 在容器内unstash恢复避免容器内外文件系统隔离导致内容丢失docker.image(bridgecrew/checkov:latest).inside(--entrypoint)以 Jenkins 官方 Docker Pipeline 插件方式在容器内执行清空entrypoint是为了能直接调用checkov二进制checkov -d . ...以当前目录为扫描根目录执行 Checkov-d/--directory指定扫描目录junit skipPublishingChecks: true, testResults: results.xml将 Checkov 产出的 JUnit XML 发布为构建测试结果skipPublishingChecks表示不再额外创建 GitHub/GitLab checkstry ... catch (err) ... throw err无论扫描成功还是失败都先发布 JUnit 结果再决定是否抛出异常使构建失败保证失败时测试报告依然可见preserveStashes()保留 stash供重试等场景复用timestamps()在控制台日志中为每行输出附加时间戳便于审计Jenkins 中的 Pipeline 定义页面如下步骤 3运行构建并查看结果点击Build Now触发一次构建。构建结束后可以依次查看构建看板在 Jenkins 首页能看到所有 Job 的状态与最近构建结果失败的构建会以红色圆点标识Job 状态页进入具体 Job 后可见本次构建的失败状态、持续时长与变更信息测试结果由于流水线调用了junit步骤Checkov 的每一条失败检查都会被解析为一条失败的测试用例在 “Test Result” 页面按文件、检查 ID 与严重级别逐条展示便于开发者精准定位需要修复的资源配置备选方案不使用容器镜像的安装方式如果 Agent 环境不方便使用 Docker可以直接在流水线中通过pipenv安装并运行 Checkovsh pipenv run pip install checkov sh pipenv run checkov -d . --use-enforcement-rules -o cli -o junitxml --output-file-path console,results.xml --repo-id example/terragoat --branch master该方式需要 Agent 预先具备 Python 与 Pipenv 环境其余参数含义与容器方式完全一致。更详细的镜像使用说明可参考 Docker 集成文档。命令行参数源码级解读教程中的checkov命令集中了几个关键参数其解析逻辑定义在 参数解析器 中-o / --output多格式输出参数定义见 ext_argument_parser.py#L197-L204支持actionappend因此可以多次指定以同时输出多种格式。可取值在 runner_registry.py#L65-L76 的OUTPUT_CHOICES中定义包括cli、json、junitxml、sarif、cyclonedx、csv、gitlab_sast、spdx等。本示例同时选择了cli与junitxml。--output-file-path控制台与文件分流参数定义见 ext_argument_parser.py#L206-L212其 help 文本明确给出了本教程所用的高级用法通过逗号分隔把不同输出格式路由到不同目的地——console表示打印到标准输出results.xml表示将 JUnit XML 写入该文件。从 runner_registry.py#L620-L648 可以看出若不显式指定文件名映射Checkov 会按默认命名保存结果如results_junitxml.xml而在本示例的显式路由下results.xml正是随后junit testResults: results.xml步骤要解析的文件。--use-enforcement-rules启用平台策略门禁参数定义见 ext_argument_parser.py#L379-L392。它从 Bridgecrew / Prisma Cloud 平台拉取仓库匹配的 Enforcement Rule用平台统一配置的硬失败/软失败阈值替代命令行手动指定。其强制前置条件在 main.py#L195-L205 的normalize_config()中有明确校验使用--use-enforcement-rules时必须提供平台 API Key--bc-api-key否则解析器直接报错退出使用 API Key 时必须同时提供--repo-id格式为repo_owner/repo_name如example/terragoat。--repo-id与--branch平台集成标识--repo-id的定义见 ext_argument_parser.py#L362-L365用于标识被扫描的仓库--branch短参数-b见 ext_argument_parser.py#L366-L371指定仓库分支默认值为master。二者仅在配合平台 API Key 时生效用于将扫描结果与平台中的仓库/分支关联。深入Enforcement Rules 与硬/软失败机制--use-enforcement-rules的底层行为可以在源码中完整追溯平台返回的 Enforcement Rules 由 repo_config_integration.py 解析并缓存代码注释明确说明仅当显式传入--use-enforcement-rules时规则才会被应用见 repo_config_integration.py#L114。runner_filter.py#L175-L192 的apply_enforcement_rules()把每个报告类型映射到对应代码类别含 SCA 的漏洞与许可证双阈值的软失败阈值extract_enforcement_rule_threshold()再按检查 ID 提取具体阈值。runner_registry.py#L341-L369 计算最终退出码阈值若命令行未显式给出--soft-fail/--soft-fail-on/--hard-fail-on则以平台规则中的hard_fail_threshold与全局软失败开关为准。简言之Enforcement Rule 的效果等价于--skip-check soft阈值以下 --hard-fail-on hard阈值。例如平台规则配置 hard-fail 为 HIGH、soft-fail 为 MEDIUM 时等价于--skip-check LOW --hard-fail-on HIGHLOW 级检查被跳过MEDIUM 级仅软失败HIGH 及以上直接导致构建失败。对于 Jenkins 门禁场景这比在流水线脚本里硬编码阈值更易维护——团队只需在平台侧调整规则所有接入的流水线同步生效。最佳实践用 Inline Suppression 降低开发者挫败感接入门禁后任何未通过的检查都会阻塞合并容易引发开发者的抵触情绪。官方文档给出的核心建议是鼓励使用 Checkov 的行内抑制inline suppression机制当某个检查项被确认属于例外如临时环境、已知风险已接受时在 IaC 代码中通过注释声明#checkov:skipCKV_AWS_123:reason即可跳过该检查同时保留跳过理由供审计。这样做既能维持流水线整体门禁的严肃性又给团队留出了可控的例外通道。详细语法与场景见 Suppressing and Skipping Policies 文档。常见问题与排查建议构建在 Checkout 阶段失败确认git url可访问且分支存在stash/unstash需要工作区处于同一节点若使用多节点流水线请确认 stash 配置。容器内找不到checkov确认镜像标签为bridgecrew/checkov:latest或固定版本标签且--entrypoint写法正确。JUnit 报告缺失检查--output-file-path console,results.xml中results.xml的写入路径与junit testResults: results.xml的读取路径一致try/catch结构可确保失败时报告仍被发布。--use-enforcement-rules报错如 main.py#L201-L205 所述该参数强制要求 API Key若不使用平台规则可直接删去该参数与--repo-id、--branch改用--soft-fail-on/--hard-fail-on控制门禁详见 Hard and soft fail。想进一步理解 JUnit 输出结构junitxml报告由Report.get_junit_xml_string()生成见 report.py#L357每条失败检查对应一个testcase失败条目也可参考 JUnit XML 输出文档。通过以上配置Checkov 便以“构建内测试用例”的形式融入了 Jenkins每次提交都会触发 IaC 扫描违规即失败、失败即可见、理由可追溯最终形成一个既严格又顺畅的云安全左移流水线。【免费下载链接】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），仅供参考 在 Jenkins 流水线中集成 Checkov：构建时阻断云配置错误（Pipeline Script 完整实战）
在 Jenkins 流水线中集成 Checkov构建时阻断云配置错误Pipeline Script 完整实战【免费下载链接】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 接入 Jenkins 流水线可以在开发者创建或修改基础设施即代码IaC时立即执行安全扫描一旦检测到云配置错误misconfiguration就使构建失败从而把安全左移到 CI/CD 的源头。本指南基于当前仓库的 Jenkins 集成文档给出完整的pipeline script示例、每个命令行参数的源码级解读、无 Docker 环境的备选安装方式以及 Enforcement Rules 硬/软失败机制的底层原理帮助你在不牺牲开发者体验的前提下落地“配置即失败”的门禁策略。集成思路为什么用容器镜像跑 CheckovCheckov 官方发布的 Docker 镜像bridgecrew/checkov:latest内置了完整的运行时与全部策略集Jenkins Agent 无需预装 Python 与依赖即可直接调用。核心流程是Jenkins 流水线检出目标仓库示例中使用 terragoat一个故意包含大量云配置漏洞的 Terraform 示例仓库在inside容器中运行checkov -d .扫描全部 IaC 文件同时输出cli与junitxml两种格式CLI 结果直接打印到控制台JUnit XML 写入results.xml调用 Jenkins 原生junit步骤解析 XML把每一次违规作为一个测试用例呈现在构建报告里任一检查失败时 Checkov 以非零退出码结束sh步骤抛错流水线标记为失败。这里的关键是 Checkov 的退出码语义默认情况下存在 FAILED 结果即返回非零退出码Jenkins 的sh步骤会据此判定构建失败从而天然形成门禁。相关设计可对照 Hard and soft fail 文档中的详细说明。前置准备一个可用的 Jenkins 实例且 Agent 节点上安装并配置了 Docker流水线通过docker.image(...).inside(...)在容器内执行命令待扫描的 IaC 仓库Terraform、CloudFormation、Kubernetes、Ansible 等均可Checkov 内置多框架 Runner可选Bridgecrew / Prisma Cloud 平台 API Key——仅在需要使用--use-enforcement-rules与--repo-id平台集成能力时才需要。分步教程步骤 1创建或打开 Jenkins Pipeline 任务在 Jenkins 中新建一个 Pipeline 类型的 Job或复用已有 Job如图中所示步骤 2在 Pipeline 定义中新增 Checkov Stage将 Job 的 Pipeline 定义方式选为Pipeline script然后粘贴以下完整脚本pipeline { agent any stages { stage(Checkout) { steps { git branch: master, url: https://github.com/bridgecrewio/terragoat stash includes: **/*, name: terragoat } } stage(Checkov) { steps { script { docker.image(bridgecrew/checkov:latest).inside(--entrypoint) { unstash terragoat try { sh checkov -d . --use-enforcement-rules -o cli -o junitxml --output-file-path console,results.xml --repo-id example/terragoat --branch master junit skipPublishingChecks: true, testResults: results.xml } catch (err) { junit skipPublishingChecks: true, testResults: results.xml throw err } } } } } } options { preserveStashes() timestamps() } }脚本要点拆解代码段作用git branch: master, url: ...terragoat检出待扫描仓库实际项目中应替换为自己的代码仓库地址与分支stash includes: **/*, name: terragoat将工作区内容暂存供后续 Stage 在容器内unstash恢复避免容器内外文件系统隔离导致内容丢失docker.image(bridgecrew/checkov:latest).inside(--entrypoint)以 Jenkins 官方 Docker Pipeline 插件方式在容器内执行清空entrypoint是为了能直接调用checkov二进制checkov -d . ...以当前目录为扫描根目录执行 Checkov-d/--directory指定扫描目录junit skipPublishingChecks: true, testResults: results.xml将 Checkov 产出的 JUnit XML 发布为构建测试结果skipPublishingChecks表示不再额外创建 GitHub/GitLab checkstry ... catch (err) ... throw err无论扫描成功还是失败都先发布 JUnit 结果再决定是否抛出异常使构建失败保证失败时测试报告依然可见preserveStashes()保留 stash供重试等场景复用timestamps()在控制台日志中为每行输出附加时间戳便于审计Jenkins 中的 Pipeline 定义页面如下步骤 3运行构建并查看结果点击Build Now触发一次构建。构建结束后可以依次查看构建看板在 Jenkins 首页能看到所有 Job 的状态与最近构建结果失败的构建会以红色圆点标识Job 状态页进入具体 Job 后可见本次构建的失败状态、持续时长与变更信息测试结果由于流水线调用了junit步骤Checkov 的每一条失败检查都会被解析为一条失败的测试用例在 “Test Result” 页面按文件、检查 ID 与严重级别逐条展示便于开发者精准定位需要修复的资源配置备选方案不使用容器镜像的安装方式如果 Agent 环境不方便使用 Docker可以直接在流水线中通过pipenv安装并运行 Checkovsh pipenv run pip install checkov sh pipenv run checkov -d . --use-enforcement-rules -o cli -o junitxml --output-file-path console,results.xml --repo-id example/terragoat --branch master该方式需要 Agent 预先具备 Python 与 Pipenv 环境其余参数含义与容器方式完全一致。更详细的镜像使用说明可参考 Docker 集成文档。命令行参数源码级解读教程中的checkov命令集中了几个关键参数其解析逻辑定义在 参数解析器 中-o / --output多格式输出参数定义见 ext_argument_parser.py#L197-L204支持actionappend因此可以多次指定以同时输出多种格式。可取值在 runner_registry.py#L65-L76 的OUTPUT_CHOICES中定义包括cli、json、junitxml、sarif、cyclonedx、csv、gitlab_sast、spdx等。本示例同时选择了cli与junitxml。--output-file-path控制台与文件分流参数定义见 ext_argument_parser.py#L206-L212其 help 文本明确给出了本教程所用的高级用法通过逗号分隔把不同输出格式路由到不同目的地——console表示打印到标准输出results.xml表示将 JUnit XML 写入该文件。从 runner_registry.py#L620-L648 可以看出若不显式指定文件名映射Checkov 会按默认命名保存结果如results_junitxml.xml而在本示例的显式路由下results.xml正是随后junit testResults: results.xml步骤要解析的文件。--use-enforcement-rules启用平台策略门禁参数定义见 ext_argument_parser.py#L379-L392。它从 Bridgecrew / Prisma Cloud 平台拉取仓库匹配的 Enforcement Rule用平台统一配置的硬失败/软失败阈值替代命令行手动指定。其强制前置条件在 main.py#L195-L205 的normalize_config()中有明确校验使用--use-enforcement-rules时必须提供平台 API Key--bc-api-key否则解析器直接报错退出使用 API Key 时必须同时提供--repo-id格式为repo_owner/repo_name如example/terragoat。--repo-id与--branch平台集成标识--repo-id的定义见 ext_argument_parser.py#L362-L365用于标识被扫描的仓库--branch短参数-b见 ext_argument_parser.py#L366-L371指定仓库分支默认值为master。二者仅在配合平台 API Key 时生效用于将扫描结果与平台中的仓库/分支关联。深入Enforcement Rules 与硬/软失败机制--use-enforcement-rules的底层行为可以在源码中完整追溯平台返回的 Enforcement Rules 由 repo_config_integration.py 解析并缓存代码注释明确说明仅当显式传入--use-enforcement-rules时规则才会被应用见 repo_config_integration.py#L114。runner_filter.py#L175-L192 的apply_enforcement_rules()把每个报告类型映射到对应代码类别含 SCA 的漏洞与许可证双阈值的软失败阈值extract_enforcement_rule_threshold()再按检查 ID 提取具体阈值。runner_registry.py#L341-L369 计算最终退出码阈值若命令行未显式给出--soft-fail/--soft-fail-on/--hard-fail-on则以平台规则中的hard_fail_threshold与全局软失败开关为准。简言之Enforcement Rule 的效果等价于--skip-check soft阈值以下 --hard-fail-on hard阈值。例如平台规则配置 hard-fail 为 HIGH、soft-fail 为 MEDIUM 时等价于--skip-check LOW --hard-fail-on HIGHLOW 级检查被跳过MEDIUM 级仅软失败HIGH 及以上直接导致构建失败。对于 Jenkins 门禁场景这比在流水线脚本里硬编码阈值更易维护——团队只需在平台侧调整规则所有接入的流水线同步生效。最佳实践用 Inline Suppression 降低开发者挫败感接入门禁后任何未通过的检查都会阻塞合并容易引发开发者的抵触情绪。官方文档给出的核心建议是鼓励使用 Checkov 的行内抑制inline suppression机制当某个检查项被确认属于例外如临时环境、已知风险已接受时在 IaC 代码中通过注释声明#checkov:skipCKV_AWS_123:reason即可跳过该检查同时保留跳过理由供审计。这样做既能维持流水线整体门禁的严肃性又给团队留出了可控的例外通道。详细语法与场景见 Suppressing and Skipping Policies 文档。常见问题与排查建议构建在 Checkout 阶段失败确认git url可访问且分支存在stash/unstash需要工作区处于同一节点若使用多节点流水线请确认 stash 配置。容器内找不到checkov确认镜像标签为bridgecrew/checkov:latest或固定版本标签且--entrypoint写法正确。JUnit 报告缺失检查--output-file-path console,results.xml中results.xml的写入路径与junit testResults: results.xml的读取路径一致try/catch结构可确保失败时报告仍被发布。--use-enforcement-rules报错如 main.py#L201-L205 所述该参数强制要求 API Key若不使用平台规则可直接删去该参数与--repo-id、--branch改用--soft-fail-on/--hard-fail-on控制门禁详见 Hard and soft fail。想进一步理解 JUnit 输出结构junitxml报告由Report.get_junit_xml_string()生成见 report.py#L357每条失败检查对应一个testcase失败条目也可参考 JUnit XML 输出文档。通过以上配置Checkov 便以“构建内测试用例”的形式融入了 Jenkins每次提交都会触发 IaC 扫描违规即失败、失败即可见、理由可追溯最终形成一个既严格又顺畅的云安全左移流水线。【免费下载链接】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），仅供参考