# OPA/Rego Policy Examples for CVE Gating

This directory contains Open Policy Agent (OPA) Rego policies for CVE-aware release gating. These policies can be used alongside or instead of the Stella DSL for advanced policy scenarios.

## Quick Start

```bash
# Install OPA
brew install opa  # macOS
# or download from https://www.openpolicyagent.org/docs/latest/#running-opa

# Run all tests
opa test . -v

# Evaluate a policy
opa eval -d epss-threshold.rego -i sample-input.json "data.stellaops.gates.epss.allow"
```

## Available Policies

| Policy | Description |
|--------|-------------|
| [cve-gate-base.rego](cve-gate-base.rego) | Base policy with DSSE signature and Rekor anchor verification |
| [epss-threshold.rego](epss-threshold.rego) | EPSS exploitation probability threshold enforcement |
| [kev-blocker.rego](kev-blocker.rego) | CISA KEV catalog blocking |
| [reachable-cve.rego](reachable-cve.rego) | Reachability-aware CVE blocking |
| [release-aggregate.rego](release-aggregate.rego) | Aggregate CVE count limits per release |

## Input Schema

All policies expect input conforming to `input-schema.json`. Key fields:

```json
{
  "attestation": {
    "dsse_envelope": { ... },
    "rekor_entry": { ... }
  },
  "cve_findings": [
    {
      "cve_id": "CVE-2024-1234",
      "cvss_score": 7.5,
      "epss_score": 0.42,
      "is_kev": false,
      "is_reachable": true
    }
  ],
  "environment": "production",
  "config": {
    "epss_threshold": 0.6,
    "max_critical": 0,
    "max_high": 3
  }
}
```

See [input-schema.json](input-schema.json) for full schema documentation.

## Policy Composition

Policies can be combined using OPA's standard composition:

```rego
package stellaops.gates.combined

import data.stellaops.gates.base
import data.stellaops.gates.epss
import data.stellaops.gates.kev
import data.stellaops.gates.reachable

# All gates must pass
default allow = false

allow {
    base.valid_attestation
    epss.allow
    kev.allow
    reachable.allow
}

# Collect all denial reasons
deny[msg] {
    not base.valid_attestation
    msg := base.deny[_]
}

deny[msg] {
    not epss.allow
    msg := epss.deny[_]
}

deny[msg] {
    not kev.allow
    msg := kev.deny[_]
}

deny[msg] {
    not reachable.allow
    msg := reachable.deny[_]
}
```

## Integration with Stella

These policies can be executed via the Stella CLI:

```bash
# Evaluate OPA policy against release candidate
stella policy evaluate --engine opa --policy examples/policies/opa/epss-threshold.rego --image myapp:v1.2.3

# Evaluate multiple policies
stella policy evaluate --engine opa --bundle examples/policies/opa/ --image myapp:v1.2.3
```

## Testing

Each policy has corresponding test files (`*_test.rego`). Run tests with:

```bash
# All tests
opa test . -v

# Specific policy tests
opa test epss-threshold.rego epss-threshold_test.rego -v
```

## Configuration

Policy configuration is passed via `input.config`. Environment-specific overrides are supported:

```json
{
  "config": {
    "epss_threshold": 0.6,
    "environments": {
      "production": {
        "epss_threshold": 0.3
      },
      "staging": {
        "epss_threshold": 0.7
      }
    }
  }
}
```

---

*Last updated: 2026-01-19.*