sica-fondt/knowledge/cyber-skills/skills/implementing-policy-as-code-with-open-policy-agent/references/api-reference.md

API Reference: Open Policy Agent (OPA) Policy-as-Code

Libraries Used

Library	Purpose
requests	HTTP client for OPA REST API
json	Parse OPA decision responses
subprocess	Run opa eval and opa test CLI commands
yaml	Parse Kubernetes admission review objects

Installation

# OPA binary
curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64_static
chmod 755 opa && sudo mv opa /usr/local/bin/

# Python dependencies
pip install requests pyyaml

OPA REST API Endpoints

Method	Endpoint	Description
PUT	/v1/policies/{id}	Create or update a policy module
GET	/v1/policies/{id}	Retrieve a policy module
DELETE	/v1/policies/{id}	Delete a policy module
GET	/v1/policies	List all policy modules
PUT	/v1/data/{path}	Create or overwrite a document
GET	/v1/data/{path}	Evaluate a rule or retrieve data
POST	/v1/data/{path}	Evaluate a rule with input
PATCH	/v1/data/{path}	Patch a data document
POST	/v1/query	Execute ad-hoc Rego query
POST	/v1/compile	Partially evaluate a query
GET	/health	Health check (liveness)
GET	/health?bundles	Health check including bundle status

Core Operations

Upload a Rego Policy

import requests
import os

OPA_URL = os.environ.get("OPA_URL", "http://localhost:8181")

policy_rego = """
package authz

default allow := false

allow if {
    input.user.role == "admin"
}

allow if {
    input.user.role == "editor"
    input.action == "read"
}
"""

resp = requests.put(
    f"{OPA_URL}/v1/policies/authz",
    data=policy_rego,
    headers={"Content-Type": "text/plain"},
    timeout=10,
)
resp.raise_for_status()

Evaluate a Policy Decision

decision_input = {
    "input": {
        "user": {"role": "editor", "name": "alice"},
        "action": "read",
        "resource": "/api/reports",
    }
}

resp = requests.post(
    f"{OPA_URL}/v1/data/authz/allow",
    json=decision_input,
    timeout=10,
)
result = resp.json()
allowed = result.get("result", False)  # True

Upload Data Documents

role_permissions = {
    "admin": ["read", "write", "delete", "admin"],
    "editor": ["read", "write"],
    "viewer": ["read"],
}

resp = requests.put(
    f"{OPA_URL}/v1/data/roles",
    json=role_permissions,
    timeout=10,
)

List All Policies

resp = requests.get(f"{OPA_URL}/v1/policies", timeout=10)
policies = resp.json().get("result", [])
for p in policies:
    print(f"  {p['id']} — {len(p.get('raw', ''))} bytes")

OPA CLI Reference

# Evaluate a policy locally
opa eval -i input.json -d policy.rego "data.authz.allow"

# Run Rego unit tests
opa test ./policies/ -v

# Check policy syntax
opa check policy.rego

# Format Rego files
opa fmt -w policy.rego

# Start OPA as a server
opa run --server --addr :8181 ./policies/ ./data/

# Build an OPA bundle
opa build -b ./policies/ -o bundle.tar.gz

Kubernetes Gatekeeper Integration

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              type: array
              items:
                type: string
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8srequiredlabels
        violation[{"msg": msg}] {
          provided := {l | input.review.object.metadata.labels[l]}
          required := {l | l := input.parameters.labels[_]}
          missing := required - provided
          count(missing) > 0
          msg := sprintf("Missing required labels: %v", [missing])
        }

Output Format

{
  "decision_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": true,
  "policy": "data.authz.allow",
  "input": {
    "user": {"role": "admin"},
    "action": "delete",
    "resource": "/api/users/42"
  }
}