implementing-infrastructure-as-code-security-scanning

实施基础设施即代码安全扫描

适用场景

• 使用 Terraform、CloudFormation 或 Pulumi 配置云基础设施，并需要自动化安全验证
• 合规框架要求在部署前提供基础设施配置审查证据
• 防止常见的云配置错误，例如公开的 S3 存储桶、开放的安全组或未加密的存储
• 建立防护措施，在拉取请求中阻止不安全的基础设施变更
• 管理多云环境，需要在 AWS、Azure 和 GCP 之间采用一致的安全策略

请勿用于扫描应用程序源代码（请使用 SAST）、监控已部署基础设施的配置漂移（请使用云安全态势管理工具），或扫描容器镜像漏洞（请使用 Trivy）。

前提条件

• 已安装 Checkov v3.x（pip install checkov）或 tfsec
• 仓库中包含 Terraform、CloudFormation 或 Kubernetes IaC 文件
• CI/CD 流水线可访问 IaC 目录
• Bridgecrew API key（可选，用于 Checkov 平台集成）

工作流

步骤 1：针对 Terraform 文件运行 Checkov

# Scan all Terraform files in a directory
checkov -d ./terraform/ --framework terraform --output cli --output json --output-file-path ./results

# Scan specific file
checkov -f main.tf --output json

# Scan Terraform plan (more accurate for dynamic values)
terraform init && terraform plan -out=tfplan
terraform show -json tfplan > tfplan.json
checkov -f tfplan.json --framework terraform_plan

# Scan with specific checks only
checkov -d ./terraform/ --check CKV_AWS_18,CKV_AWS_19,CKV_AWS_20

# Skip specific checks
checkov -d ./terraform/ --skip-check CKV_AWS_145,CKV2_AWS_6

步骤 2：将 IaC 扫描集成到 GitHub Actions

# .github/workflows/iac-security.yml
name: IaC Security Scan

on:
  pull_request:
    paths:
      - 'terraform/**'
      - 'cloudformation/**'
      - 'k8s/**'

jobs:
  checkov:
    name: Checkov IaC Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Checkov
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: terraform/
          framework: terraform
          output_format: cli,sarif
          output_file_path: console,checkov.sarif
          soft_fail: false
          skip_check: CKV_AWS_145

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: checkov.sarif
          category: checkov-iac

  tfsec:
    name: tfsec Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tfsec
        uses: aquasecurity/[email protected]
        with:
          working_directory: terraform/
          sarif_file: tfsec.sarif
          soft_fail: false

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: tfsec.sarif
          category: tfsec

步骤 3：创建自定义 Checkov 策略

# custom_checks/s3_versioning.py
from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
from checkov.common.models.enums import CheckResult, CheckCategories


class S3BucketVersioning(BaseResourceCheck):
    def __init__(self):
        name = "Ensure S3 bucket has versioning enabled"
        id = "CKV_CUSTOM_1"
        supported_resources = ["aws_s3_bucket"]
        categories = [CheckCategories.GENERAL_SECURITY]
        super().__init__(name=name, id=id, categories=categories,
                         supported_resources=supported_resources)

    def scan_resource_conf(self, conf):
        versioning = conf.get("versioning", [{}])
        if isinstance(versioning, list) and len(versioning) > 0:
            if versioning[0].get("enabled", [False])[0]:
                return CheckResult.PASSED
        return CheckResult.FAILED


check = S3BucketVersioning()

步骤 4：配置基线和抑制项

# .checkov.yaml
branch: main
compact: true
directory:
  - terraform/
  - cloudformation/
framework:
  - terraform
  - cloudformation
  - kubernetes
output:
  - cli
  - sarif
skip-check:
  - CKV_AWS_145    # S3 default encryption with CMK (using SSE-S3 is acceptable)
  - CKV2_AWS_6     # S3 bucket request logging (handled at CloudTrail level)
soft-fail: false

步骤 5：扫描 Kubernetes 清单和 Helm Charts

# Scan Kubernetes manifests
checkov -d ./k8s/ --framework kubernetes

# Scan Helm charts (renders templates first)
checkov -d ./charts/myapp/ --framework helm

# Scan with KICS (Keeping Infrastructure as Code Secure)
docker run -v $(pwd)/k8s:/path checkmarx/kics:latest scan \
  --path /path \
  --output-path /path/results \
  --type Kubernetes \
  --report-formats json,sarif

核心概念

术语	定义
IaC 扫描	自动分析基础设施代码模板，在部署前检测安全配置错误
策略即代码	将安全策略定义为可执行代码，以便进行版本控制、测试和自动强制执行
CKV 检查 ID	Checkov 为每项安全检查分配的唯一标识符（例如，针对 S3 公开访问的 CKV_AWS_18）
Terraform Plan 扫描	扫描已解析的 Terraform plan JSON，其中包含计算后的值和模块展开结果
基于图的扫描	Checkov 分析资源之间关系的能力，而不仅仅是单个资源配置
漂移检测	识别 IaC 定义与实际部署的基础设施状态之间的差异
自定义策略	使用 Python 或 YAML 编写的组织专属安全检查，用于强制执行内部标准

工具与系统

• Checkov：Bridgecrew 推出的开源 IaC 扫描器，内置 2500 多项策略，覆盖主要云服务提供商
• tfsec：Aqua Security 推出的 Terraform 专用静态分析工具，深度理解 HCL
• KICS：Checkmarx 推出的开源 IaC 扫描器，支持 15 多种 IaC 框架
• Terrascan：支持 OPA Rego 策略的 IaC 扫描器，可用于编写自定义策略
• Snyk IaC：与 Snyk 平台集成的商业 IaC 扫描器

常见场景

场景：在 Terraform 中防止 S3 存储桶公开访问

背景：开发团队反复创建缺少适当访问控制的 S3 存储桶。最近的一次事件中，客户数据因存储桶公开而泄露。

处理方法：

1. 在 CI/CD 流水线中为所有 Terraform 变更启用 Checkov
2. 强制执行 CKV_AWS_18（禁止公开读取 ACL）、CKV_AWS_19（加密）和 CKV_AWS_20（禁止停用公开访问阻止）
3. 创建自定义策略，要求每个 S3 存储桶都配置 aws_s3_bucket_public_access_block 资源
4. 设置 soft_fail: false，在 S3 安全检查失败时阻止合并 PR
5. 提供带有安全默认值、可供团队复用的 Terraform 模块

注意事项：只扫描 .tf 文件会遗漏动态计算的值。使用 Terraform plan 扫描可提高准确性。Checkov 的资源关系检查（CKV2 前缀）需要图分析模式。

输出格式

IaC Security Scan Report
==========================
Framework: Terraform
Directory: terraform/
Scan Date: 2026-02-23

Checkov Results:
  Passed: 187
  Failed: 12
  Skipped: 3
  Unknown: 0

FAILED CHECKS:
  CKV_AWS_18  [HIGH]   S3 Bucket has public read ACL
              Resource: aws_s3_bucket.data_lake
              File:     terraform/storage.tf:15-28

  CKV_AWS_24  [HIGH]   CloudWatch log group not encrypted
              Resource: aws_cloudwatch_log_group.app
              File:     terraform/monitoring.tf:3-8

  CKV_AWS_79  [MEDIUM] Instance metadata service v1 enabled
              Resource: aws_instance.web
              File:     terraform/compute.tf:12-30

QUALITY GATE: FAILED (2 HIGH severity findings)