Infrastructure as Code Validation with c7n-left
Relevant source files
The following files were used as context for generating this wiki page:
c7n-left evaluates Cloud Custodian policies directly against Infrastructure as Code (IaC) source assets. It enables "shift-left" security by integrating policy enforcement into developer workstations and CI/CD pipelines.
The tool focuses on preventative enforcement earlier in the deployment lifecycle. It complements the standard Custodian cloud providers, which typically act as detective controls on already deployed infrastructure. By catching compliance and governance issues before deployment, it reduces remediation costs and improves security posture.
Sources: tools/c7n_left/README.md:1-10, tools/c7n_terraform/readme.md:7-16, README.md:32-33
Architecture and Core Workflow
c7n-left utilizes a dedicated CLI to process IaC directories and apply standard Custodian policy logic. The system parses IaC definitions, such as Terraform files, and maps them to resource types that the policy engine understands.
Evaluation Flow
The process begins when a user runs the c7n-left command. The tool loads policies from a specified directory and parses the target IaC files. It then executes filters against the parsed resource data.
The diagram shows the sequence of operations from CLI invocation to the generation of compliance results.
Sources: tools/c7n_left/README.md:38-50, tools/c7n_left/c7n_left/cli.py
Component Stack
The tool depends on several key libraries to handle specific IaC formats and CLI features.
| Dependency | Purpose |
|---|---|
tfparse | High-performance parsing of Terraform HCL assets. |
python-hcl2 | Secondary HCL parsing support. |
c7n | Core Cloud Custodian library for policy evaluation and filtering. |
click | CLI framework for command-line interactions. |
rich | Enhanced terminal output and formatting. |
Sources: tools/c7n_left/pyproject.toml:9-14
CLI Usage and Configuration
The c7n-left run command evaluates policies against a specified directory of IaC code. It supports various output formats, including CLI, JSON, and GitHub-specific annotations for Pull Request integration.
Execution Options
Users control the evaluation process through various flags defined in the CLI.
| Flag | Description | Default |
|---|---|---|
-p, --policy-dir | Path to the directory containing YAML policy files. | Required |
-d, --directory | The IaC root directory to evaluate (e.g., Terraform module). | Required |
-o, --output | Output format: cli, github, or json. | cli |
--filters | Select specific policies or resources using k=v pairs. | None |
--warn-on | Policies that log warnings instead of triggering failure exit codes. | None |
Sources: tools/c7n_left/README.md:38-60, tools/c7n_left/c7n_left/cli.py
Filtering Logic
The --filters option allows for fine-grained control over which policies and resources undergo evaluation. Supported filter keys include name, category, severity, type, and id. Most filters support globbing for pattern matching.
Sources: tools/c7n_left/README.md:104-125
Policy Language and Advanced Filters
c7n-left supports standard Custodian filters like value, and, or, and not. It also introduces specialized filters for complex IaC relationships and cloud-native attributes.
Specialized Filters
- taggable: Filters resources to those that support cloud provider tagging. It works across multiple providers including AWS, Azure, and GCP.
- traverse: Performs multi-hop graph traversal. It allows a policy to check related resources, such as verifying if an EC2 instance is associated with a specific security group rule.
- from_json: A JMESPath function that converts JSON-encoded strings (common in Terraform
container_definitions) into objects for evaluation.
Sources: tools/c7n_left/README.md:144-220
Environment Integration
Policies can interpolate environment variables using Python's format syntax. This allows policies to dynamically include metadata like repository names or PR numbers from CI systems.
policies:
- name: "check-{env[REPO]}-{env[PR_NUMBER]}"
resource: terraform.aws*
Sources: tools/c7n_left/README.md:237-250
Testing Infrastructure
c7n-left includes a native testing framework to validate policy logic against positive and negative IaC examples.
Test Structure
Tests reside in a tests directory adjacent to policy files. Each test case requires:
- A sub-directory named after the policy.
- Terraform files (
.tf) representing compliant and non-compliant states. - A
left.plan.yamlfile containing assertions.
The diagram illustrates the automated policy testing workflow.
Sources: tools/c7n_left/README.md:280-310, tools/c7n_left/c7n_left/cli.py
Conclusion
c7n-left extends the Cloud Custodian ecosystem by providing immediate feedback on infrastructure definitions. By using a common policy language for both development and runtime, organizations maintain consistent governance standards across the entire software development lifecycle. Its integration with CI tools and support for complex resource relationships makes it a critical tool for modern cloud engineering.