Conftest — Test Structured Config with Open Policy Agent

Introduction

Conftest brings policy-as-code testing to configuration files. Using the Rego language from Open Policy Agent, teams write assertions that run against Kubernetes YAML, Terraform HCL, Dockerfiles, JSON, and dozens of other formats — catching misconfigurations in CI before they reach production.

What Conftest Does

• Tests configuration files against Rego policies with pass/fail/warn results
• Parses 20+ file formats including YAML, JSON, HCL, Dockerfile, INI, and XML
• Integrates into CI/CD pipelines as a gate for configuration changes
• Shares policies across teams via OCI registries (push/pull like container images)
• Supports unit testing of policies themselves with conftest verify

Architecture Overview

Conftest embeds the OPA engine as a library. When invoked, it detects the input file format, parses it into a JSON representation, and evaluates it against Rego policies in the policy directory. Policies define deny, warn, or violation rules that return messages for failed checks. The tool exits with a non-zero code if any deny rules match, making it CI-friendly.

Self-Hosting & Configuration

• Install via Homebrew, Scoop, Docker, or download binaries from GitHub releases
• Place Rego policies in a policy/ directory by convention or specify a custom path with -p
• Configure default namespaces, output formats, and policy paths in conftest.toml
• Push policies to OCI registries with conftest push and pull them in CI with conftest pull
• Run conftest verify to unit-test your Rego policies with test_ prefixed rules

Key Features

• Multi-format parsing supports Kubernetes, Terraform, Docker, CloudFormation, and more natively
• OCI registry distribution lets teams version and share policy bundles like container images
• Output formats include JSON, TAP, JUnit, and GitHub for integration with any CI system
• Combine rules allow merging multiple policy sources with different namespaces
• Pre-commit hook integration catches violations before code reaches the repository

Comparison with Similar Tools

• OPA/Gatekeeper — runtime admission control in Kubernetes; Conftest is shift-left testing in CI
• Checkov — Python-based scanner with built-in rules; Conftest uses Rego for custom policies
• Datree — Kubernetes-specific with SaaS dashboard; Conftest is local-first and format-agnostic
• Kyverno — Kubernetes admission controller with YAML policies; Conftest tests any config format
• tflint — Terraform-specific linter; Conftest handles Terraform plus any other structured config

FAQ

Q: Do I need to know Rego to use Conftest? A: Yes. Rego is the policy language. The basics are straightforward — most deny rules are 3-5 lines.

Q: Can I test Terraform plans? A: Yes. Run terraform plan -out=plan.tfplan then terraform show -json plan.tfplan | conftest test -.

Q: How do I share policies across teams? A: Push policy bundles to an OCI registry with conftest push and pull them in CI with conftest pull.

Q: Does Conftest replace OPA Gatekeeper? A: They complement each other. Conftest tests in CI (shift-left), Gatekeeper enforces at admission time (runtime).

Sources

• https://github.com/open-policy-agent/conftest
• https://conftest.dev