Conftest

How it works

Conftest is a Go CLI around the Open Policy Agent Rego engine, maintained under the open-policy-agent GitHub org. It picks a parser by file extension (YAML, JSON, HCL2, Dockerfile, TOML, INI, XML, CUE, Jsonnet, .env, HOCON, CycloneDX, SPDX, CODEOWNERS and others) or by --parser, and turns each file into the Rego input document. HCL is converted as written, so variables and modules are not evaluated.

Policies load from policy/ (or --policy). In the main namespace by default, rules named deny, violation (which can return structured data) and warn, optionally with a suffix such as deny_unpinned, produce failures or warnings. An exception rule can exempt matching inputs from named rules. --data adds JSON or YAML data files, and --combine passes all files as one array so a rule can compare files.

Output is stdout, json, tap, table, junit, github (workflow annotations), azuredevops or sarif. Failures give a non-zero exit code, and --fail-on-warn makes warnings fail too. conftest verify runs Rego unit tests for your policies, and conftest push and conftest pull share policy bundles through OCI registries, git or HTTPS.

For GitHub this means you write the rules: deny pull_request_target triggers, require uses: to end in a 40-character SHA, require a permissions: block, or check CODEOWNERS (parser added in v0.71.0) and github provider Terraform.

What it catches

• Any rule you can write in Rego over YAML, JSON, HCL2, TOML, INI, XML or Dockerfiles
• Workflow policies such as no pull_request_target and SHA-pinned uses:
• Kubernetes manifests and rendered Helm output (runAsNonRoot, required labels)
• Terraform plan JSON checks with resolved values
• Cross-file checks with --combine
• CODEOWNERS coverage rules

Run it

brew install conftest
conftest test --policy policy .github/workflows/
conftest verify --policy policy

In GitHub Actions

- uses: actions/checkout@<sha> # v7.0.1
  with:
    persist-credentials: false
- name: Test workflows against policy/
  run: >
    docker run --rm -v "$PWD:/project"
    openpolicyagent/conftest:v0.71.1
    test --policy policy --output github .github/workflows

What leaves your machine

Nothing during conftest test. conftest pull, test --update and plugin installs download from the OCI registry, git or HTTPS location you give.

Limits

• No built-in policies. Rego has a learning curve, and untested policies quietly pass everything, so write conftest verify tests.
• It checks files as parsed. Terraform variables, modules and expressions are not resolved unless you test terraform show -json plan output.
• Policies fetched with --update or conftest pull change whenever the source changes. Pin an OCI digest or git ref.
• There is no official GitHub Action; run the binary or the Docker image yourself.

Links

• Repository: open-policy-agent/conftest ↗
• Documentation ↗
• Options and output formats ↗
• Sharing policies ↗

Related tools