/opa

name: opa
description: Generate, test, validate, explain, and debug OPA (Open Policy Agent) Rego policies and Conftest configurations. Covers deny/warn/violation rules, unit tests, regal linting, conftest fmt, namespace design, input shape analysis, and GitHub Actions integration. Use when asked to "write a policy", "test a rego file", "validate policies", "explain this rego", or "why is my policy not firing".
argument-hint: "[generate|test|validate|explain|debug] [policy description or file path]"
title: "OPA Command"
sidebar_label: "opa"
custom_edit_url: null

Write, test, validate, explain, and debug OPA Rego policies with Conftest.

> **AI-agent behavior, not infra policy:** to gate what an AI coding agent (Copilot, Claude Code) can edit or run in a repo, use `/platform-skills:ai-governance` — a different policy engine for a different input shape (tool calls and diffs, not Terraform/Kubernetes manifests).

---

Interactive Wizard (fires when no arguments are provided)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

What do you need?
  1. generate — write a new production-ready Rego policy
  2. test     — write _test.rego unit tests for an existing policy
  3. validate — run the full pipeline (fmt, lint, tests) against a directory
  4. explain  — translate an existing Rego policy into plain English
  5. debug    — diagnose why a policy is not firing as expected

Enter 1–5 or mode name:

**Q2 — Context** (after mode selected, one at a time):

• **generate**: `Describe the policy — target resource type (Terraform/Kubernetes/GHA/Dockerfile) and what to deny or warn on:`
• **test**: `Paste the Rego policy to write tests for:`
• **validate**: `Provide the directory path containing your .rego files:`
• **explain**: `Paste the Rego policy to explain:`
• **debug**: `Describe the symptom — is the policy not firing, producing no output, or throwing an error? Paste the conftest output:`

Then proceed into the relevant mode below.

---

Mode: generate

Write a production-ready Rego policy from a description.

Steps: 1. Ask for: target resource type (Terraform HCL, Kubernetes manifest, GitHub Actions workflow, Dockerfile, JSON/YAML), the rule logic (what to deny or warn on), and whether a named namespace is needed 2. Parse what Conftest sees — use `conftest parse <file>` to show the input shape if the user has a file, then write rules that match that shape exactly 3. Generate the policy file:

• Start with a `# METADATA` block: `title`, `description`, `authors`, `entrypoint: true`
• Declare `package <namespace>` — use `main` only when a single policy set applies; use a named package (`package terraform.iam`, `package k8s.pods`) for multi-domain repos
• Add `import rego.v1` — required for modern Rego syntax
• Use `deny` for hard failures, `warn` for advisory violations, `violation` for OPA framework integrations (Gatekeeper, Conftest policy sets)
• Generate a descriptive `msg` that includes the offending resource name/value and a remediation hint
• Use `some` for iteration, `in` for membership, `startswith`/`contains` for string matching

4. Show the Conftest command to test the policy against sample input 5. State CI placement: conftest runs **after `terraform validate`** and **before `terraform plan`** as a blocking gate — failing conftest must prevent plan from running

**Validation:** Test the policy against both a passing and a failing resource before deploying to CI:

# Should produce no output (policy passes)
conftest test --policy <dir> <passing-resource.yaml>

# Should produce a deny/warn message (policy fires)
conftest test --policy <dir> <failing-resource.yaml>

Both must behave as expected. A policy that never fires on a failing resource is not enforcing anything.

Mode: test

Write `_test.rego` unit tests for a given policy.

Steps: 1. Read the policy to understand: package name, rule names, input shape 2. Generate a test file named `<policy>_test.rego` in the same directory:

• Package: `package <namespace>_test` (e.g. `package terraform.iam_test`)
• Add `import rego.v1`
• Import the policy under test: `import data.<namespace>`

3. For each `deny`/`warn`/`violation` rule, write:

• A **positive test** (rule fires): name prefixed `test_deny_` / `test_warn_`; assert `count(<rule>) == 1` or `count(<rule>) > 0`
• A **negative test** (rule does not fire): name prefixed `test_allow_`; assert `count(<rule>) == 0`

4. Write a helper function that builds the input fixture for each case — keep fixtures minimal and focused on the attributes the rule actually checks 5. Run tests: `conftest verify --policy <dir>`

**Validation:** All tests must pass with zero skipped:

conftest verify --policy <dir>
# Expected: PASS - X tests, 0 failures, 0 skipped
# Skipped tests mean test fixtures are incomplete — fix before merging

Mode: validate

Run the full policy validation pipeline against a directory.

Steps: 1. **Format check**: `conftest fmt <dir>/*.rego --check` — fails if any file is not canonically formatted 2. **Auto-format** (if check fails): `conftest fmt <dir>/*.rego` — rewrites in place 3. **Lint**: `regal lint <dir>` — reports style and correctness violations; fix each finding before continuing 4. **Unit tests**: `conftest verify --policy <dir>` — all `*_test.rego` files must pass 5. **Integration test** (if test data is available): `conftest test --policy <dir> <input-files>` 6. Report: PASS or list each failing step with the exact error and the fix

Mode: explain

Translate an existing Rego policy into plain English.

Steps: 1. Read the policy file — identify: package, rule names, types (deny/warn/violation), and the conditions 2. For each rule, explain in plain language:

• **What it checks**: the resource type and attribute being evaluated
• **What triggers it**: the condition that causes a deny/warn
• **What the message says**: what a developer will see when this fires
• **What