企业官网建设流程全解析

使用 GitHub Actions 集成 Checkov：在 CI 中自动扫描 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

Checkov 是 Bridgecrew 推出的基础设施即代码（IaC）静态扫描工具，能够在构建阶段发现云资源配置错误与安全漏洞。本指南以仓库文档 docs/4.Integrations/GitHub Actions.md 为核心，完整讲解如何将 Checkov 接入 GitHub Actions：既可直接使用 Marketplace 上的官方 Action，也可基于 Action 输入参数自行编写 workflow。读完本文，你将掌握在 Pull Request 评审和构建流程中自动执行 Terraform 等 IaC 策略扫描、阅读失败报告并修复问题、以及利用软失败（soft-fail）与问题匹配器（problem matcher）等高级能力落地安全门禁的完整方案。

集成思路：为什么把 Checkov 放进 GitHub Actions

将 Checkov 集成到 GitHub Actions 的价值在于“自动化且零人工干预”：每次 push 或 PR 触发时，工作流自动对仓库中的 IaC 代码执行策略扫描，发现任何不合规配置即让构建失败，把安全评审前置到代码合入之前。这种模式既覆盖 PR 评审阶段，也能作为任何构建流程的一部分运行，是 CI/CD 安全左移的典型实践。

集成有两条路线，本文会分别展开：

1. 直接使用 Marketplace 上的预置 Action（bridgecrewio/checkov-action），开箱即用；
2. 自行编写 workflow 调用 Checkov，通过对 Action 输入参数（INPUT_*）的精细控制实现定制化扫描策略。

准备工作：workflow 文件放在哪里

GitHub Actions 的 workflow 文件统一放在仓库的.github/workflows目录下，Checkov 官方示例使用如下目录结构：

├───.github │ └───workflows

在该目录中新建workflow.yml并提交后，GitHub 会自动识别并在对应事件触发时执行。同时需要确认仓库 Actions 权限允许工作流访问，若需扫描私有 Terraform 模块，还需配置相应的 token 权限。

基础配置：自建 Checkov Action 的最小 workflow

在workflow.yml中添加一个使用bridgecrewio/checkov-action的 step，即可完成最小可用的集成：

--- name: Checkov on: push: branches: - master jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Test with Checkov id: checkov uses: bridgecrewio/checkov-action@master with: directory: example/examplea framework: terraform

对该示例的关键点逐一说明：

• on.push.branches: [master]：仅当代码 push 到 master 分支时触发扫描，也可按需改用pull_request事件，在 PR 评审阶段执行策略检查；
• actions/checkout：检出仓库代码，是后续扫描的前提；
• actions/setup-python+python-version: 3.9：为 Action 提供 Python 运行环境（Checkov 基于 Python 实现，其 CLI 入口为 checkov/main.py）；
• directory: example/examplea：指定被扫描的目录；
• framework: terraform：指定只对 Terraform 框架执行扫描。

值得注意的是framework参数在底层会被转换为--frameworkCLI 参数（nargs='+'类型），因此支持空格或逗号分隔的多框架写法，例如terraform,cloudformation或terraform arm，详见 checkov/common/util/ext_argument_parser.py 中--framework的定义。

运行结果：失败与成功两种典型场景

每次 push 后 GitHub 都会自动运行该 job。如果 Checkov 发现任何错误，构建将失败；反之则通过。下面是官方文档中的完整实测案例。

Action 失败：EFS 未加密

示例代码中的文件aws_efs_file_system.sharedstore.tf将encrypted显式设为false，不符合“EFS 必须加密”的安全策略：

resource "aws_efs_file_system" "sharedstore" { creation_token = var.efs["creation_token"] lifecycle_policy { transition_to_ia = var.efs["transition_to_ia"] } kms_key_id = var.efs["kms_key_id"] encrypted = false performance_mode = var.efs["performance_mode"] provisioned_throughput_in_mibps = var.efs["provisioned_throughput_in_mibps"] throughput_mode = var.efs["throughput_mode"] }

该资源会命中 Checkov 内置策略CKV_AWS_42（Ensure EFS is securely encrypted）。从仓库源码 checkov/terraform/checks/resource/aws/EFSEncryptionEnabled.py 可以看到，这条检查通过get_inspected_key()返回"encrypted"键，对aws_efs_file_system资源进行取值校验，任何非 true 的取值都会判定为 FAILED，进而使 Action 以非零退出码结束、构建失败：

Pipeline 成功：将 encrypted 置为 true

修复方式非常简单：将encrypted的值改为true，使资源满足加密要求。重新 push 后，Checkov 扫描通过，job 显示为绿色成功状态：

深入底层：Action 的输入参数如何映射到 Checkov CLI

官方 Action 的核心逻辑位于 github_action_resources/entrypoint.sh。该脚本把 GitHub Actions 的with:输入（环境变量INPUT_*）逐一转换为checkov命令的 CLI 参数，最终执行checkov "${CKV_ARGS[@]}"并把退出码透传给 Actions（第 172-191 行）。理解这张映射表，是定制扫描行为的关键。

扫描目标：docker-image / file / directory 三选一

entrypoint 按优先级决定扫描对象（第 70-79 行）：

例如未指定任何目标时，脚本会执行-d .，即扫描整个仓库；指定directory: example/examplea则等价于-d example/examplea。

单值与布尔参数

entrypoint 通过add_flag与add_bool两个辅助函数处理单值参数和布尔开关（第 26-36 行、第 82-99 行）：

• 单值参数（有值才追加）：output_file_path→--output-file-path、baseline→--baseline、config_file→--config-file、repo_root_for_plan_enrichment→--repo-root-for-plan-enrichment、policy_metadata_filter→--policy-metadata-filter等；
• 布尔参数（值等于true才追加）：output_bc_ids→--output-bc-ids、compact→--compact、quiet→--quiet、soft_fail→--soft-fail、deep_analysis→--deep-analysis、skip_results_upload→--skip-results-upload、download_external_modules→--download-external-modules true等。

其中--baseline用于基于.checkov.baseline基线文件忽略历史遗留问题；--config-file可指定 YAML 配置文件批量管理扫描参数；--deep-analysis用于对 Terraform 做深层依赖分析（对应仓库中的 checkov/terraform/deep_analysis_plan_graph_manager.py）。

多值参数：空格列表与 CSV 的差异

entrypoint 区分两类多值参数（第 38-67 行）：

• 空格列表（add_space_list）：适用于nargs='+'类型参数，一个 flag 后跟多个值，包括framework、skip_framework，以及多文件file；
• CSV 列表（add_csv）：适用于action='append'类型参数，逗号分隔的每个 token 各自生成一个 flag，包括check、skip_check、soft_fail_on、hard_fail_on、external_checks_dirs、external_checks_repos、output_format、var_file、skip_path、skip_cve_package。

以framework: terraform,sca_package为例，最终生成--framework terraform sca_package（单个 flag、两个位置参数）。此外 CSV 解析会自动去除 token 首尾空格，且由于按 flag 边界拆分，能有效防止通过输入注入额外命令行参数（tests/github_action_resources/test_entrypoint.py中第 200-224 行的测试专门验证了这一防护行为）。

平台集成与上下文上报

当配置了API_KEY_VARIABLE时，脚本会自动附加--bc-api-key、--branch、--repo-id（第 161-165 行），把扫描结果上报到 Bridgecrew/Prisma Cloud 平台统一看板。同时脚本利用 GitHub 自带的环境变量导出丰富的 CI 上下文（第 129-153 行）：分支（GITHUB_HEAD_REF/GITHUB_REF_NAME）、PR 编号与 URL、提交哈希、作者、运行编号与仓库 URL 等，供平台侧关联分析。脚本开头还通过export BC_SOURCE=githubActions标记扫描来源（第 16 行）。

高级能力：问题匹配器与软失败门禁

Action 会在运行前通过::add-matcher::注册问题匹配器（entrypoint 第 121-125 行），把 Checkov 的 CLI 输出转换为 GitHub 的代码注解。仓库提供了两份匹配器定义：

• github_action_resources/checkov-problem-matcher.json：默认模式，解析Check: <id>: <描述>、FAILED状态行以及File: /path:行号-行号，在 PR 中定位到具体文件和行；
• github_action_resources/checkov-problem-matcher-softfail.json：在默认模式基础上增加"severity": "error"标注，用于软失败场景。

当未开启软失败时使用前者（失败即红色错误注解），开启后使用后者。两者的差异与 entrypoint 的--soft-fail布尔开关联动：软失败模式下 Checkov 始终返回 0 退出码（--soft-fail在 checkov/common/util/ext_argument_parser.py 中的定义为“运行检查但总是返回 0”），避免因中低危问题阻塞合入。

如果想实现更精细的失败策略，可使用soft_fail_on与hard_fail_on输入：

• --soft-fail-on CKV_AWS_1,LOW：仅当指定检查或指定严重级别及以下的检查失败时返回 0；
• --hard-fail-on HIGH,CRITICAL：仅当指定严重级别及以上的检查失败时返回非零；
• 两者可同时使用，--hard-fail-on在平局时优先，未命中任何条件的结果默认按硬失败处理（见 checkov/common/util/ext_argument_parser.py 的完整语义说明）。

实战建议与验证

• 从最小配置起步：先复制官方示例，用directory指向单个目录、framework: terraform跑通闭环，再逐步增加check/skip_check、soft_fail_on/hard_fail_on、baseline、external_checks_dirs等参数；
• 用测试驱动理解参数行为：仓库中的 tests/github_action_resources/test_entrypoint.py 通过伪造checkov可执行文件断言最终 argv，覆盖了默认目录、文件/镜像目标优先级、布尔开关、CSV 与空格列表解析、空输入忽略、参数注入防护等 23 个场景。阅读这些用例可以精确掌握每个INPUT_*变量的底层行为；
• 处理历史存量问题：引入 Checkov 的初期，可用baseline生成基线豁免存量不合规项，再通过后续 PR 逐步清零；
• 私有模块下载：若扫描依赖私有 Terraform 模块，可配合download_external_modules与GITHUB_OVERRIDE_URL/GITHUB_PAT（entrypoint 第 155-159 行）配置访问令牌；
• 多框架扫描：仓库内置的 runner 覆盖 Terraform、CloudFormation、Kubernetes、Dockerfile、Secrets、Bicep、ARM、Helm 等数十种框架（见 checkov/main.py 的DEFAULT_RUNNERS），framework参数可自由组合或省略（默认全部扫描）。

至此，你已具备在 GitHub Actions 中完整落地 Checkov 扫描的能力：从最小 workflow 起步，到按需定制扫描目标与失败门禁，再到借助问题匹配器让结果直接呈现在 PR 上，形成可持续演进的基础设施安全防线。更多集成场景可参考仓库 docs/4.Integrations 目录下的 GitLab CI、Jenkins、Bitbucket Cloud Pipelines 等文档。

【免费下载链接】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