Anthropic-Cybersecurity-Skills 实战：使用 Checkov、tfsec、Terrascan 与 OPA/Rego 审计 Terraform 基础设施安全

导读

本文基于 auditing-terraform-infrastructure-for-security 技能文档，系统讲解如何在云资源部署之前，对 Terraform 基础设施即代码（IaC）进行安全审计。你将掌握一套完整的实战方案：用 Checkov 做全面 IaC 静态扫描、用 tfsec 做 Terraform 原生问题检测、用 Terrascan 做 CIS/NIST 等多框架合规校验、用 OPA/Rego 编写组织级自定义策略，并把以上扫描以安全门禁的形式集成进 GitHub Actions CI/CD 流水线，最后还能直接审计已部署的 Terraform 状态文件，输出可汇报的安全审计报告。

适用场景与边界

何时使用

• 将安全扫描集成到 Terraform 部署的 CI/CD 流水线中；
• 在 apply 之前审查 Terraform 计划（plan）与模块的安全最佳实践；
• 为云基础设施的供给流程构建 policy-as-code（策略即代码）护栏；
• 审计现有 Terraform 状态文件，识别已经部署的配置错误；
• 在多个 Terraform 项目间强制统一组织的安全标准。

不要用它做什么

本技能不适用于运行时安全监控（应使用 CSPM 工具）、应用安全测试（应使用 SAST/DAST 工具），也不适用于云配置漂移检测（部署后应使用 AWS Config 或 Azure Policy）。

前置条件

• 安装 Checkov：pip install checkov
• 安装 tfsec：brew install tfsec（或从 GitHub 下载二进制）
• 安装 Terrascan：brew install terrascan
• Terraform v1.0+（用于生成 plan）
• OPA（Open Policy Agent），用于自定义策略执行
• 一个包含待审计 Terraform 代码的 Git 仓库

六步安全审计工作流

步骤 1：使用 Checkov 扫描 Terraform 代码

Checkov 是开源的 IaC 静态分析工具，内置 1000+ 条策略，覆盖 Terraform、CloudFormation、Kubernetes、ARM 与 Dockerfile。核心用法如下：

# 扫描一个 Terraform 目录
checkov -d ./terraform/ --framework terraform

# 指定检查类别（按 Check ID 过滤）
checkov -d ./terraform/ --check CKV_AWS_18,CKV_AWS_19,CKV_AWS_20,CKV_AWS_21

# 以 JSON 输出结果
checkov -d ./terraform/ --output json > checkov-results.json

# 扫描 Terraform plan 文件（更精准的分析）
terraform init && terraform plan -out=tfplan
terraform show -json tfplan > tfplan.json
checkov -f tfplan.json --framework terraform_plan

# 跳过特定检查并给出理由
checkov -d ./terraform/ --skip-check CKV_AWS_145 \
  --bc-api-key $BRIDGECREW_API_KEY

# 扫描 Terraform modules
checkov -d ./modules/ --framework terraform --compact

# 列出所有可用检查
checkov --list --framework terraform | grep CKV_AWS

为什么要扫 plan 而不是只扫目录？ 目录扫描针对的是源码文本，而 terraform_plan 框架直接解析 terraform show -json tfplan 导出的计划 JSON，能够结合变量解析后的实际值进行分析，从而显著减少误报。这个"先 plan 再扫 plan"的流程是后续所有扫描器（tfsec、Terrascan、OPA）的通用前置步骤。

常用 CKV Check ID 速查表（完整清单可运行 checkov --list 查看）：

Check ID	检查内容
CKV_AWS_18	S3 访问日志记录
CKV_AWS_19	S3 服务端加密
CKV_AWS_20	S3 Block Public Access
CKV_AWS_24	安全组允许来自 0.0.0.0/0 的 SSH
CKV_AWS_1	IAM 策略包含通配符动作
CKV_AWS_145	RDS 加密
CKV_AWS_41	Lambda 环境变量中的机密

步骤 2：使用 tfsec 扫描 Terraform 专属问题

tfsec 提供 Terraform 原生的静态分析，附带详细修复建议，并支持 SARIF 输出（可对接 GitHub Security tab）：

# 扫描一个 Terraform 目录
tfsec ./terraform/

# 设置最低严重级别阈值
tfsec ./terraform/ --minimum-severity HIGH

# 以 JSON 输出，便于 CI/CD 处理
tfsec ./terraform/ --format json > tfsec-results.json

# 使用自定义检查
tfsec ./terraform/ --custom-check-dir ./custom-checks/

# 排除特定规则（并排除下载的模块）
tfsec ./terraform/ --exclude-downloaded-modules \
  --exclude aws-s3-enable-bucket-logging

# 扫描并仅对特定严重级别失败
tfsec ./terraform/ --minimum-severity CRITICAL --soft-fail

# 生成 SARIF 输出，用于 GitHub Security tab
tfsec ./terraform/ --format sarif > tfsec.sarif

步骤 3：使用 Terrascan 进行多框架合规校验

Terrascan 支持针对 CIS、NIST、SOC 2 等合规框架的策略检查：

# 按 CIS AWS benchmark 扫描 Terraform
terrascan scan -t aws -i terraform -d ./terraform/ \
  --policy-type aws --verbose

# 按特定合规类别扫描
terrascan scan -t aws -i terraform -d ./terraform/ \
  --policy-type aws \
  --categories "Compliance Validation"

# 以 JSON 输出
terrascan scan -t aws -i terraform -d ./terraform/ \
  --output json > terrascan-results.json

# 扫描 Terraform plan
terrascan scan -t aws -i terraform \
  --iac-file tfplan.json \
  --iac-type tfplan

# 列出可用策略
terrascan scan --list-policies -t aws

步骤 4：为组织标准编写自定义 OPA 策略

Checkov、tfsec 覆盖的是通用最佳实践，而组织的专属要求（必填标签、命名规范、特定的加密要求）需要用 OPA/Rego 来表达。以下三个 Rego 策略覆盖了最典型的云安全风险：

# policy/aws_s3_encryption.rego
package terraform.aws.s3

deny[msg] {
    resource := input.resource.aws_s3_bucket[name]
    not resource.server_side_encryption_configuration
    msg := sprintf("S3 bucket '%s' must have server-side encryption enabled", [name])
}

# policy/aws_iam_no_wildcards.rego
package terraform.aws.iam

deny[msg] {
    resource := input.resource.aws_iam_policy[name]
    statement := resource.policy.Statement[_]
    statement.Action == "*"
    statement.Effect == "Allow"
    msg := sprintf("IAM policy '%s' must not use wildcard (*) actions", [name])
}

deny[msg] {
    resource := input.resource.aws_iam_policy[name]
    statement := resource.policy.Statement[_]
    statement.Resource == "*"
    statement.Effect == "Allow"
    contains(statement.Action[_], "*")
    msg := sprintf("IAM policy '%s' has overly permissive actions on wildcard resources", [name])
}

# policy/aws_no_public_ingress.rego
package terraform.aws.security_group

deny[msg] {
    resource := input.resource.aws_security_group_rule[name]
    resource.type == "ingress"
    resource.cidr_blocks[_] == "0.0.0.0/0"
    resource.from_port <= 22
    resource.to_port >= 22
    msg := sprintf("Security group rule '%s' allows SSH from 0.0.0.0/0", [name])
}

评估方式有两种：直接对 plan JSON 跑 OPA，或用 Conftest 做更易用的封装：

# 使用 OPA 直接评估 Terraform plan
terraform show -json tfplan | opa eval \
  --data ./policy/ \
  --input /dev/stdin \
  "data.terraform.aws" \
  --format pretty

# 使用 Conftest 更便捷地测试 OPA 策略
conftest test tfplan.json --policy ./policy/ --output json

步骤 5：将安全扫描集成进 CI/CD 流水线

把 IaC 安全扫描设为强制门禁。下面的 GitHub Actions 工作流展示了从 plan 生成、Checkov 扫描、tfsec 扫描、SARIF 上传到 OPA 策略检查的完整链路：

# GitHub Actions: Terraform security pipeline
name: Terraform Security Scan
on:
  pull_request:
    paths: ['terraform/**']

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3

      - name: Terraform Init & Plan
        run: |
          cd terraform/
          terraform init
          terraform plan -out=tfplan
          terraform show -json tfplan > tfplan.json

      - name: Checkov Scan
        uses: bridgecrewio/checkov-action@master
        with:
          directory: terraform/
          framework: terraform
          output_format: sarif
          output_file_path: checkov.sarif
          soft_fail: false

      - name: tfsec Scan
        uses: aquasecurity/tfsec-action@v1.0.0
        with:
          working_directory: terraform/
          soft_fail: false

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: checkov.sarif

      - name: OPA Policy Check
        run: |
          conftest test terraform/tfplan.json \
            --policy ./policy/ \
            --output json

关键设计点：soft_fail: false 意味着任何失败项都会阻断合并，形成真正的门禁；paths: ['terraform/**'] 让工作流仅在 Terraform 文件变更时触发，节省流水线资源。

步骤 6：扫描 Terraform 状态以发现已部署的配置错误

审计当前状态文件，识别已经上线但存在安全问题的资源：

# 将当前状态导出为 JSON
terraform show -json > terraform-state.json

# 使用 Checkov 扫描状态文件
checkov -f terraform-state.json --framework terraform_plan

# 查询状态中特定的安全问题
terraform state list | while read resource; do
  terraform state show "$resource" 2>/dev/null | grep -i "public\|0.0.0.0\|encrypt.*false\|password"
done

# 查找缺少必需标签的资源
terraform state list | grep aws_instance | while read resource; do
  tags=$(terraform state show "$resource" | grep -A20 "tags")
  if ! echo "$tags" | grep -q "Environment"; then
    echo "MISSING TAG: $resource lacks 'Environment' tag"
  fi
done

仓库配套的自动化审计 Agent

本技能目录下提供了可直接运行的审计脚本 scripts/agent.py，它把上面的 CLI 流程封装成一条命令，适合 Agent 或脚本化调用。从源码结构看，其工作流分为四层：

1. 调用层：run_checkov()、run_checkov_on_plan()、run_tfsec() 分别以子进程方式调用对应扫描器，统一设置 120 秒超时并捕获输出；
2. 解析层：parse_checkov_results() 从 JSON 中提取 check_id、resource、file_path、file_line_range、severity、guideline；parse_tfsec_results() 则提取 rule_id、description、severity、location（文件名:起始行）与 resolution 修复建议；
3. plan 直扫层：scan_tf_plan_for_issues() 不依赖外部扫描器，直接解析 plan JSON 的 resource_changes，对 aws_s3_bucket（缺加密）、aws_security_group_rule（SSH 对 0.0.0.0/0 开放）、aws_iam_policy（通配符 Action）三类高风险资源做快速判定；
4. 汇总层：generate_report() 合并三类来源的发现，按 CRITICAL → HIGH → MEDIUM → LOW 排序，输出带时间戳、总数与分级计数的审计报告。

典型用法：

python scripts/agent.py --terraform-dir ./terraform/ --tool both
python scripts/agent.py --plan-json tfplan.json --tool plan_only --output audit.json

此外，references/api-reference.md 还提供了 Checkov 的 Python API 示例，适合把扫描嵌入更复杂的自动化逻辑：

from checkov.runner_registry import RunnerRegistry
from checkov.terraform.runner import Runner

runner = Runner()
report = runner.run(root_folder="./terraform/")
for check in report.failed_checks:
    print(check.check_id, check.resource, check.file_path)

关键概念

术语	定义
Infrastructure as Code	通过声明式配置文件（Terraform、CloudFormation）而非手动控制台操作来管理云基础设施的实践
Policy as Code	将安全与合规策略表达为可执行代码（Rego、Python），可自动对基础设施定义进行评估
Shift Left Security	将安全检查前移到开发生命周期早期，在部署前扫描 IaC 而非供给后再审计
Terraform Plan	Terraform 将要执行的变更预览，可导出为 JSON 以便在 apply 之前进行安全扫描
Checkov	开源 IaC 静态分析工具，支持 Terraform、CloudFormation、Kubernetes 与 Docker，内置 1000+ 策略
OPA/Rego	Open Policy Agent 及其策略语言 Rego，用于定义针对结构化数据输入进行评估的自定义安全规则

工具与系统速览

• Checkov：全面的 IaC 扫描器，内置 1000+ 策略，覆盖 Terraform、CloudFormation、Kubernetes、ARM 与 Dockerfile；
• tfsec：Terraform 专属静态分析工具，提供详细修复建议与 SARIF 输出；
• Terrascan：多 IaC 扫描器，支持 CIS、NIST、SOC 2 等合规框架的策略即代码；
• OPA/Conftest：自定义策略引擎，用 Rego 语言定义组织专属安全规则；
• Bridgecrew：基于 Checkov 的商业平台，提供漂移检测与供应链安全能力。

实战场景：为现有 Terraform CI/CD 流水线添加安全门禁

背景：某 DevOps 团队通过 GitHub Actions 中的 Terraform 部署基础设施，但没有任何安全扫描。近期审计发现多个 S3 存储桶未加密，且安全组允许来自互联网的 SSH 访问。

实施步骤：

1. 在 GitHub Actions 工作流中加入 Checkov 作为第一道安全门禁；
2. 运行 checkov -d ./terraform/ 建立现有问题基线；
3. 对已有发现进行分级处置：修复 CRITICAL 项、为 HIGH 项创建工单、对已接受风险做抑制；
4. 加入 tfsec 作为第二扫描器，覆盖 Terraform 专属检查；
5. 为组织标准编写自定义 OPA 策略（必填标签、命名规范等）；
6. 配置流水线，阻断带 CRITICAL 或 HIGH 发现的 PR；
7. 生成 SARIF 报告集成到 GitHub Security tab。

常见陷阱：给现有项目添加安全扫描，初期必然会产生数百条发现。应渐进式落地——先只阻断 CRITICAL，再逐步扩展到 HIGH。对有意为之的例外情况，使用内联抑制注释并附带文档化理由：

#checkov:skip=CKV_AWS_18:Public bucket for static website

输出格式：标准安全审计报告

审计完成后可输出如下标准化报告，便于跨团队汇报与问题跟踪：

Terraform Security Audit Report
==================================
Repository: acme-corp/infrastructure
Branch: main
Scan Date: 2026-02-23
Tools: Checkov 3.x, tfsec 1.x, OPA custom policies

SCAN RESULTS:
  Checkov checks passed:    187
  Checkov checks failed:     34
  tfsec checks passed:      156
  tfsec checks failed:       28
  OPA custom policies:       12 passed, 3 failed

CRITICAL FINDINGS:
[TF-001] S3 Bucket Without Encryption
  File: modules/storage/main.tf:24
  Resource: aws_s3_bucket.data_lake
  Check: CKV_AWS_19
  Fix: Add server_side_encryption_configuration block

[TF-002] Security Group Allows SSH from 0.0.0.0/0
  File: modules/network/security.tf:45
  Resource: aws_security_group_rule.ssh_access
  Check: CKV_AWS_24
  Fix: Restrict cidr_blocks to bastion subnet

[TF-003] IAM Policy with Wildcard Actions
  File: modules/iam/policies.tf:12
  Resource: aws_iam_policy.developer_policy
  Check: CKV_AWS_1
  Fix: Scope actions to specific services required

SUMMARY BY SEVERITY:
  Critical:  6 findings
  High:     14 findings
  Medium:   28 findings
  Low:      18 findings
  Info:     12 findings

框架映射与本技能在库中的定位

本技能在 Anthropic-Cybersecurity-Skills 库中隶属于 cloud-security 领域，frontmatter 中映射了 NIST CSF 2.0 的 PR.IR-01（威胁与漏洞管理响应）、ID.AM-08（资产管理）、GV.SC-06（供应链风险管理）、DE.CM-01（监控）等子类别，以及 MITRE ATT&CK 的 T1078.004（云账户滥用）、T1530（云存储数据收集）、T1190（面向公网的漏洞利用）、T1552.001（凭据存储于文件中）、T1580（云基础设施发现）等技术，可在 mappings 目录中查看库级框架覆盖全貌。这组映射说明：IaC 安全审计不仅是"写代码前检查一下"，而是覆盖资产识别、供应链风险、持续监控与威胁响应的纵深防御环节。