cloudcustodian/c7n-left

基础设施即代码的Custodian策略

镜像概述和主要用途

该工具允许Cloud Custodian直接针对基础设施即代码(IaC)源代码资产评估策略，同时提供独立的命令行界面(CLI)以增强源代码资产评估的命令行用户体验。适用于在开发和部署流程中对IaC资产进行策略合规性检查，确保基础设施配置符合安全、成本等最佳实践。

核心功能和特性

• IaC策略评估：直接针对Terraform等IaC源代码资产评估策略
• 独立CLI工具：提供c7n-left命令行工具，优化命令行用户体验
• 多资源类型支持：策略可指定多种资源类型（数组或通配符形式）
• 灵活过滤：支持通过CLI过滤器控制评估的策略和资源
• 多样化输出：提供CLI、GitHub、JSON等多种输出格式，适配不同使用场景（如GitHub Actions注释）
• 策略测试框架：支持编写和运行策略测试，验证策略有效性
• 安全镜像：提供签名Docker镜像，可通过cosign验证完整性

安装说明

Python安装

当前仅支持macOS和Linux系统上的Python > 3.10，Windows系统建议使用Docker镜像。

shell
pip install c7n-left

Docker镜像

提供签名Docker镜像：

shell
docker pull cloudcustodian/c7n-left:dev

镜像签名验证

可使用https://github.com/sigstore/cosign%E9%AA%8C%E8%AF%81%E9%95%9C%E5%83%8F%E7%AD%BE%E5%90%8D%EF%BC%9A

shell
export IMAGE=$(docker image inspect cloudcustodian/c7n-left:dev -f '{{index .RepoDigests 0}}')
cosign verify $IMAGE \
   --certificate-identity 'https://github.com/cloud-custodian/cloud-custodian/.github/workflows/docker.yml@refs/heads/main' \
   --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

使用方法和配置说明

基本使用

CLI命令选项

shell
❯ c7n-left run --help
Usage: c7n-left run [OPTIONS]

  针对IaC源评估策略。

  示例: c7n-left -p policy_dir -d terraform_root --filters "severity=HIGH"

  警告 - CLI界面可能会更改。

Options:
  --format TEXT
  --filters TEXT                  以k=v键值对形式过滤策略或资源，支持通配符
  -p, --policy-dir PATH           策略所在目录
  -d, --directory PATH            要评估的IaC目录
  -o, --output [cli|github|json]  输出格式（默认cli）
  --output-file FILENAME          输出文件（默认stdout）
  --var-file FILE                 从指定文件加载变量，可多次使用
  --output-query TEXT             使用jmespath表达式过滤json输出
  --summary [policy|resource]     摘要显示方式（默认policy）
  --help                          显示帮助信息并退出

示例策略和执行

创建包含策略的目录：

yaml
# policies/test.yaml
policies:
  - name: test
    resource: terraform.aws_s3_bucket
    metadata:
      severity: medium
    filters:
      - server_side_encryption_configuration: absent

评估Terraform根模块：

shell
❯ c7n-left run -p policies -d module
Running 1 policies on 1 resources
test - terraform.aws_s3_bucket
  Failed
  File: s3.tf:1-8
  1 resource "aws_s3_bucket" "example" {                                                                                
  2   bucket = "my-custodian-test-bucket"                                                                               
  3   acl    = "private"                                                                                                
  4                                                                                                                     
  5   tags = {                                                                                                          
  6     original-tag = "original-value"                                                                                 
  7   }                                                                                                                 
  8 }                                                                                                                   

Evaluation complete 0.00 seconds -> 1 Failures
           策略摘要           
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ 严重级别 ┃ 策略名称 ┃ 结果            ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ medium   │ test   │ 1失败 0通过      │
└──────────┴────────┴───────────────────┘
1个资源中0个合规，1个资源存在1个策略违规

Docker运行方式

需要使用卷挂载提供策略目录和Terraform根模块访问权限：

shell
docker run -ti --rm -v $(pwd)/policies:/policies -v $(pwd)/root-module:/module \
       cloudcustodian/c7n-left:dev run -p /policies -d /module

Terraform依赖处理

如果Terraform根模块有其他远程模块依赖，需先使用Terraform获取依赖：

shell
terraform get -update

CLI过滤器

通过--filters选项可控制评估的策略和资源，格式为k=v键值对，支持通配符。

可用过滤器

• name: 策略名称
• category: 策略类别
• severity: 最低策略严重级别（unknown、low、medium、high、critical）
• type: 资源类型，如aws_security_group
• id: 资源ID，如aws_vpc.example

使用示例

shell
# 对ebs卷和sqs队列运行所有加密策略
c7n-left run -p policy_dir -d terraform --filters="category=encryption type=aws_ebs_volume,aws_sqs_queue"

# 运行所有中等及以上级别成本策略
c7n-left run -p policy_dir -d terraform --filters="severity=medium category=cost"

策略的严重级别和类别在metadata部分指定：

yaml
policies:
  - name: check-encryption
    resource: [aws_ebs_volume, aws_sqs_queue]
    metadata:
      category: [encryption, security]
      severity: high
    filters:
       - kms_master_key_id: absent

输出格式

输出类型

• cli: 默认格式，显示详细结果和摘要表格
• github: 适合GitHub Actions，直接在PR中添加注释
• json: JSON格式输出，可通过--output-query使用jmespath表达式过滤

摘要显示

支持两种摘要显示方式，通过--summary指定：

• policy（默认）: 按策略显示摘要
• resource: 按资源显示摘要

策略语言

c7n-left策略支持超出标准Custodian策略的额外功能：

多资源类型

策略可针对多种资源类型，以数组或通配符形式指定：

yaml
policies:
  - name: check-encryption
    resource: [aws_ebs_volume, aws_sqs_queue]

遍历过滤器（traverse）

traverse过滤器允许从资源到任何相关资源的多跳图遍历：

示例：检查EC2实例关联的安全组是否有允许0.0.0.0/0访问的权限

yaml
policies:
 - name: check-security-group-open-cidr
   resource: terraform.aws_instance
   description: "EC2实例不应在ssh端口开放给所有IP"
   filters:
     - type: traverse
       resources:
         - aws_security_group
         - aws_security_ingress_permission
       attrs:
         - Ipv4: 0.0.0.0/0

策略测试

c7n-left支持编写和运行策略测试，验证策略是否按预期工作。

测试目录结构

在策略文件旁创建tests目录，测试结构如下：

policy-dir-a/
├── alb.yaml                  # 策略文件
└── tests
    └── alb-deletion-protection-disabled  # 测试目录（与策略名称对应）
        ├── left.plan.yaml    # 断言文件
        ├── negative1.tf      # 不应匹配策略的Terraform文件
        └── positive1.tf      # 应匹配策略的Terraform文件

断言文件格式

left.plan.yaml是断言数组，每个断言是匹配策略发现结果的字典，匹配数据来自c7n-left run --output json的输出。

示例断言文件：

yaml
# left.plan.yaml
- "resource.__tfmeta.filename": "positive1.tf"

运行测试

使用c7n-left test命令运行测试：

shell
❯ c7n-left test -p policy-dir-a/
Discovered 1 Tests
Failure alb-deletion-protection-disabled [{'resource.__tfmeta.filename': 'positive1.tf'}] checks not used

1 Test Complete (0.05s) 1 Failure

测试失败条件

测试失败的情况：

• 计划文件中的断言未匹配任何策略发现结果
• 策略发现结果未被计划文件中的断言匹配