rego-skill

May 31, 2026 · View on GitHub

A Claude Code skill for generating, reviewing, and testing OPA Rego policies following security best practices.

Features

Policy Generation - Create secure policies with default deny
Security Review - Comprehensive checklist for vulnerability detection
Test Generation - Automatic test creation with allow/deny/edge cases
OPA 1.0+ Syntax - if / in / contains / every are built-in keywords (no import needed); import rego.v1 is supported for 0.x compatibility
Structured Decisions - Rich output for debugging and auditing
Suite-wide Security Audit (Workflow) - A multi-agent fan-out that audits an entire policy corpus against the security rubric, adversarially verifies each finding, and surfaces cross-policy conflicts. See WORKFLOW.md.

Installation

Personal Installation

# Clone to your Claude skills directory
git clone https://github.com/Void3110/rego-skill.git ~/.claude/skills/rego-skill

Project Installation

# Clone to your project
git clone https://github.com/Void3110/rego-skill.git .claude/skills/rego-skill

# Commit to share with team
git add .claude/skills/rego-skill
git commit -m "Add rego-skill for OPA policy development"

Prerequisites

OPA CLI installed
Claude Code CLI

Usage

The skill auto-activates when you mention OPA, Rego, authorization policies, or access control.

Generate a Policy

User: Create a policy where admins can read, write, and delete. Editors can read and write. Viewers can only read.

Claude will:

Clarify requirements
Generate policy with default allow := false
Create comprehensive *_test.rego
Validate with opa check and opa test . -v
Review against security checklist

Review Existing Policy

User: Review @policies/auth.rego for security issues

Write Tests

User: Write tests for @policies/gateway.rego

Mandatory Workflow

Every policy task follows this sequence:

Understand - Clarify requirements before writing code
Generate - Write policy with explicit default deny
Test - Create comprehensive tests with allow AND deny cases
Validate - Run opa check and opa test . -v
Review - Check against security checklist
Iterate - Fix any failures before declaring complete

Documentation

Document	Purpose
SKILL.md	Core instructions and patterns
GENERATE.md	Step-by-step policy generation
SECURITY.md	Security review checklist
TESTING.md	Test patterns and coverage
BEST-PRACTICES.md	Performance, style, and OPA 1.0 migration notes
WORKFLOW.md	The suite-wide security-audit Workflow — in depth (architecture, token cost, design)

Examples

See examples/ for complete working policies:

rbac.rego + rbac_test.rego - Role-Based Access Control
gateway.rego + gateway_test.rego - API Gateway Authorization

Run example tests:

cd examples
opa test . -v
# PASS: 47/47

Suite-wide Security Audit (Workflow)

Beyond authoring one policy at a time, the skill ships a multi-agent audit Workflow (rego-security-audit-workflow.js) that audits an entire policy corpus at once:

fans out one auditor per .rego policy, scoring each against the 10-check security rubric;
adversarially verifies every Critical/Medium finding (a skeptic tries to refute it from the code) so false alarms are dropped before they reach the report;
runs a cross-policy pass to catch shadowed/overlapping rules and helper drift that a single-file review can't see;
writes a dated audit-reports/REGO-SECURITY-AUDIT-<date>.md. Report-only — it never edits a policy.

Two caveats:

This uses the Claude Code Workflow feature (multi-agent orchestration), a relatively new capability — your Claude Code version must expose it. The rest of the skill works without it.

It can be token-hungry. A run spawns many agents (one per policy, plus verifiers, plus cross-policy agents), so cost scales with corpus size and findings density. The workflow has built-in caps (maxPolicies, per-policy verify limits, incremental mode). Budget accordingly.

See WORKFLOW.md for the full architecture, measured token costs, and design rationale, and the "Suite-wide security audit" section of SKILL.md for how to run it.

A sample report generated by running this workflow on this repo's own policies lives in audit-reports/ — it caught a real glob.match auth bypass in examples/gateway.rego (since fixed).

Quick Reference

Default Deny Pattern

package mypackage
# OPA 1.0+: no import needed. (Add `import rego.v1` only to also run on OPA 0.x.)

default allow := false

allow if {
    # explicit conditions only
}

Modern Rego Syntax (OPA 1.0+)

On OPA 1.0+ the if / in / contains / every keywords are built in — no import required. See BEST-PRACTICES.md for the full 1.0 migration notes.

package mypackage

# Use 'if' keyword
allow if {
    some role in input.user.roles
    role == "admin"
}

# Use 'contains' for sets
violations contains msg if {
    # condition
    msg := "violation message"
}

# Use 'every' for universal checks
all_valid if {
    every item in input.items {
        item.status == "approved"
    }
}

Structured Decisions

decision := {
    "allowed": allowed,
    "reason": reason,
    "context": {
        "user": input.user.id,
        "action": input.action
    }
}

Security Checklist

Before completing any policy:

Default deny is explicit (default allow := false)
No unconditional allow := true
Input validation for required fields
Type checking where needed (is_string, is_array)
No path traversal vulnerabilities
Tests cover allow AND deny cases
Tests cover edge cases (null, empty, missing)

License

MIT

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request