terraform-compliance for policy checks against Terraform plans

Why terraform-compliance focuses on failed policy paths

terraform-compliance addresses a specific gap in infrastructure-as-code testing: checking whether a Terraform plan contains structures that violate an internal or security policy. Its intended users are Terraform developers, platform teams, security teams, and organizations that want to separate policy authorship from infrastructure implementation. A separate team can maintain test scenarios in another repository, which makes review and ownership more explicit than placing every rule directly in application code.

The project is deliberately centered on negative testing. Instead of proving that every normal operation succeeds, its scenarios describe conditions that must not exist in a plan. For example, an AWS S3 bucket policy can state that a newly created or updated bucket must include server-side encryption. Terraform already handles creation, update, and destruction through its resource model and plan comparison. The missing layer is policy evaluation against the proposed infrastructure before deployment.

That scope makes the project more targeted than a general Terraform test suite. It can answer whether a plan contains a prohibited setting or lacks a required block, but the README does not establish that it validates provider credentials, live cloud resources, deployment behavior, or every possible security control. Those jobs would need separate tooling or evidence.

How Radish scenarios receive and evaluate a Terraform plan

The visible architecture has two distinct inputs. The first is a `.feature` file containing policy scenarios. The second is a Terraform plan, supplied to the test framework according to the installation and usage documentation. Radish parses the feature files, while the project applies the scenarios to the plan representation.

The policy language is Gherkin-style BDD rather than Python assertions in the example documentation. A requirement such as preventing an unencrypted S3 bucket can be represented as a Scenario with a resource precondition and a required attribute. The documentation gives this short form:

Given I have AWS S3 Bucket defined
Then it must contain server_side_encryption_configuration

The named field comes from Terraform configuration. In the accompanying example, `server_side_encryption_configuration` appears inside the `aws_s3_bucket` resource:

resource "aws_s3_bucket" "b" {
  bucket = "my-bucket"
  acl    = "private"

  server_side_encryption_configuration {
    rule {
      apply_server_side_encryption_by_default {
        kms_master_key_id = "${aws_kms_key.mykey.arn}"
        sse_algorithm     = "aws:kms"
      }
    }
  }
}

Based on the repository layout, scenario parsing, Terraform resource matching, step implementation, and CLI integration live under `terraform_compliance/`. The CLI entry point is registered as `terraform-compliance=terraform_compliance.main:cli`. The README does not document the complete data flow for plan import or each supported step, so evaluators should confirm the documented scenarios against their Terraform resource types before relying on a policy library.

Installing terraform-compliance through pip or Docker

The README directs users to the Installation Guide and says that the package can be installed from `pip` or run through Docker. The README does not include the exact pip command, Docker build arguments, image name, or runtime command, so those details cannot be reproduced safely here. The repository confirms that PyPI hosts `terraform-compliance` and that the project has a Docker distribution.

The packaging metadata defines the Python distribution name as `terraform-compliance` and registers the `terraform-compliance` console command. Its dependencies include `radish-bdd`, `gitpython`, `netaddr`, `colorful`, `filetype`, `junit-xml`, `lxml`, `emoji`, `semver`, `IPython`, `diskcache`, and `orjson`. This is a meaningful dependency surface for a CLI installed into a developer image or CI runner.

The package metadata lists Python 3.7 through 3.12 as supported classifiers. The Docker definition uses `python:3.11-slim` and also builds for a Terraform executable, using `TERRAFORM_VERSION`, `TARGET_ARCH`, and `HASHICORP_PGP_KEY` build variables. That container path can reduce host setup work, but it also couples image rebuilds to Terraform version and architecture decisions. Use the installation guide to confirm the supported release, required Terraform artifact, and invocation syntax before creating a production pipeline.

A first policy check for encrypted S3 buckets

The clearest first use is the policy shown in the project documentation. Start with a Terraform configuration that declares one or more AWS S3 buckets, produce the plan artifact required by the project, and add a `.feature` file containing the S3 encryption scenario. The exact command for producing and passing the plan is not included in the README, so the workflow stops short of inventing a CLI flag or file format.

The expected policy is simple to read: first establish that an AWS S3 bucket is defined, then require `server_side_encryption_configuration`. If a bucket lacks that block, the scenario fails and the pipeline can stop the deployment according to the surrounding CI policy. If the plan contains the required configuration, the scenario passes for that particular condition.

This approach is useful because the policy remains close to the acceptance condition. Developers can see which resource and field are being constrained without first reading Python step definitions. Security teams can review scenarios independently from Terraform implementation details. The limitation is equally direct. A scenario only proves what its step checks. The README does not establish that passing encryption scenarios cover every encryption mode, every AWS provider schema change, or cloud-side defaults.

Policy ownership in CI pipelines and git hooks

The README identifies pipeline execution and git hooks as integration points. In a CI/CD pipeline, a failed scenario can become a pre-deployment gate, so a Terraform change does not proceed merely because its configuration is syntactically valid. This places policy evaluation near the point where infrastructure changes are reviewed and approved.

The segregation-of-duty model is the more distinctive deployment option. Terraform configuration can remain in the infrastructure repository while `.feature` files live in a policy repository maintained by another team. That separation does not automatically create organizational independence. The teams still need agreed ownership, review rules, and a controlled mechanism for updating scenarios. It does, however, give the project a natural home for controls that are not part of the resource implementation.

The repository includes `CHANGELOG.md`, `CONTRIBUTING.md`, `tox.ini`, `requirements.txt`, `requirements_dev.txt`, and pre-commit configuration. These files indicate support for development and release hygiene, but the README does not document a migration command, version compatibility matrix, or rollback procedure for policy changes. Operators should treat scenario updates like code changes and inspect the project documentation and changelog before changing a blocking rule.

Performance and dependency considerations for CI runners

The README has a dedicated performance note. If parsing is too slow, it points to an optional `faster_parsing` pip installation flag in the Installation Guide. The README does not explain the implementation, supported platforms, or behavior changes associated with that option, so the flag should be treated as a documented installation choice rather than an assumed performance guarantee.

The dependency set includes native or platform-sensitive components such as `lxml`, `orjson`, and `IPython`, although `requirements.txt` alone does not prove which ones require compilation on every platform. The Docker definition supplies a controlled Python 3.11 environment, which may make CI setup more consistent than constructing a local environment manually. It also adds Terraform installation logic to the image build.

For a first deployment, the main cost is likely policy engineering rather than runtime monitoring. Teams must decide which controls matter, express them as supported scenarios, and review false positives as Terraform schemas change. The README does not provide throughput numbers, worker behavior, or a documented way to parallelize policies, so capacity planning should not rely on an invented performance model.

What terraform-compliance does not replace

The closest functional alternative described by the README is HashiCorp Sentinel. The project presents terraform-compliance as a free, open-source, Terraform-focused equivalent for policy checks, with BDD scenarios and negative-testing emphasis. Sentinel is tied to HashiCorp Enterprise products, while terraform-compliance is presented as an independent package for Terraform plans.

A second practical alternative is to keep policy checks in a CI script that invokes a general-purpose infrastructure scanner. That approach can cover a broader set of security and policy checks, but it usually requires teams to interpret scanner output outside the feature-file format. The exact scanner, rule language, and supported resource scope cannot be named from the README, so the meaningful comparison is architectural: terraform-compliance makes the policy itself a readable BDD scenario, while a general scanner separates policy rules from scenario documentation.

terraform-compliance is the wrong tool when the requirement is full functional testing of Terraform operations, live cloud validation, or a complete security posture product. The project is also not a substitute for Terraform plan generation itself. It consumes a plan-oriented policy testing workflow, so teams without a usable Terraform plan or without scenarios matching their resource types will get limited value from installing it.

Maintenance, releases, upgrades, and MIT licensing

The repository is not archived. Its last push was on 2026-09-07, which is within the six-month window used to assess recent repository activity. Recent releases listed include `1.15.1` on 2026-05-08, `1.15.0` on 2026-05-05, and `1.14.1` on 2025-11-27. These dates show recent release activity, but the repository does not provide a support policy for older Terraform versions or Python versions.

Upgrades can affect both the framework and its scenario behavior. The package pins several dependencies in `requirements.txt`, including `radish-bdd==0.18.2`, while `setup.py` uses some minimum-version constraints. A clean upgrade path should therefore include reviewing `CHANGELOG.md`, checking dependency changes, and running the policy suite against representative plans. The README does not document an automated migration or rollback command for framework or scenario upgrades.

The project is licensed under MIT. The repository includes a `LICENSE` file and identifies the same license in package metadata. That designation generally means the code is offered under the MIT license's permissions and conditions, but this article does not provide legal advice. Organizations should still review the actual license text and their internal compliance requirements.

Editorial conclusion

Adopt terraform-compliance when engineers or security teams need readable, pre-deployment checks against Terraform plans, especially when policy ownership should be separated from infrastructure code. Do not treat it as a replacement for Terraform functional testing, cloud security scanners, or proof that deployed resources match policy. Verify first that your required checks can be expressed as Radish Gherkin scenarios, that Terraform can produce an acceptable plan artifact, and that the Python or container deployment route fits your supported environment. The strongest project-specific reason to proceed is its support for policy scenarios in a separately owned repository and in CI pipelines.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. terraform-compliance/cli on GitHub