# Policy Import/Export Guide

This guide covers bidirectional policy exchange between Stella's native C# engine and OPA/Rego.

## Overview

Stella supports two policy formats:
- **PolicyPack v2 (JSON)**: Canonical format with typed gates, environment overrides, and remediation hints.
- **OPA/Rego**: Standard policy-as-code format for interoperability with OPA-based toolchains.

The C# gate engine remains primary. Rego is an export target for teams using OPA, and an import source for adopting external policies.

## Formats

### PolicyPack v2 (JSON)

Schema: `policy.stellaops.io/v2`

Structure:
```json
{
  "apiVersion": "policy.stellaops.io/v2",
  "kind": "PolicyPack",
  "metadata": { "name": "...", "version": "1.0.0" },
  "spec": {
    "settings": { "defaultAction": "block", "deterministicMode": true },
    "gates": [...],
    "rules": [...]
  }
}
```

Key features:
- Per-environment configuration overrides (production/staging/development thresholds)
- Structured remediation hints with CLI command templates
- Deterministic evaluation mode
- SHA-256 content digest for integrity

### OPA/Rego

Generated or imported Rego follows the deny-by-default pattern:

```rego
package stella.release

import rego.v1

default allow := false

deny contains msg if {
    not input.dsse.verified
    msg := "DSSE signature missing"
}

allow if { count(deny) == 0 }

remediation contains hint if {
    some msg in deny
    msg == "DSSE signature missing"
    hint := {"code": "DSSE_MISS", "fix": "...", "severity": "critical"}
}
```

## CLI Commands

### Export

Export a policy to JSON or Rego:

```bash
# Export to Rego
stella policy export --file policy.json --format rego --output-file release.rego

# Export with environment-specific thresholds
stella policy export --file policy.json --format rego --environment production

# Export without remediation hints
stella policy export --file policy.json --format json --include-remediation false

# Export to stdout (pipe-friendly)
stella policy export --file policy.json --format rego | opa check -
```

### Import

Import a policy from JSON or Rego:

```bash
# Import and validate a JSON policy
stella policy import --file production-baseline.json

# Import with validation only (no persist)
stella policy import --file external-policy.rego --validate-only

# Dry-run to preview changes
stella policy import --file new-rules.json --dry-run

# Force format detection
stella policy import --file rules.txt --format rego
```

### Validate

Validate a policy file:

```bash
# Basic validation
stella policy validate --file policy.json

# Strict mode (warnings become errors)
stella policy validate --file policy.json --strict

# JSON output for CI integration
stella policy validate --file policy.json --output json
```

Exit codes: `0` = valid, `1` = warnings, `2` = errors.

### Evaluate

Evaluate a policy against evidence:

```bash
# Evaluate with table output
stella policy evaluate --policy baseline.json --input evidence.json

# With environment override
stella policy evaluate --policy baseline.json --input evidence.json --environment staging

# JSON output for programmatic use
stella policy evaluate --policy baseline.json --input evidence.json --output json

# CI mode (GitHub Actions annotations)
stella policy evaluate --policy baseline.json --input evidence.json --output ci
```

Exit codes: `0` = allow, `1` = warn, `2` = block.

## Evidence Input Format

The evaluation input follows the canonical evidence JSON schema:

```json
{
  "environment": "production",
  "subject": {
    "imageDigest": "sha256:abc...",
    "purl": "pkg:docker/myapp@1.0.0",
    "tags": ["env:prod"]
  },
  "dsse": { "verified": true, "signers": ["ca://fulcio/..."] },
  "rekor": { "verified": true, "logID": "...", "integratedTime": 1737480000 },
  "sbom": { "format": "cyclonedx-1.6", "canonicalDigest": "sha256:..." },
  "freshness": { "tstVerified": true, "timestamp": "2026-01-22T10:00:00Z", "maxAgeHours": 24 },
  "cvss": { "score": 7.5, "version": "3.1" },
  "reachability": { "status": "confirmed", "confidence": 0.85 },
  "confidence": 0.82
}
```

## Remediation Hints

When a gate blocks, the CLI displays actionable fix suggestions:

```
Decision: BLOCK

Gate        Type                  Result  Reason
signature   SignatureRequiredGate  FAIL    Required signature missing
sbom        SbomPresenceGate      PASS    passed

Remediation:
  SIG_MISS: Required signature missing
    - Sign attestation with DSSE.
      $ stella attest attach --sign --image sha256:abc...
    - Anchor attestation in Rekor.
      $ stella attest attach --rekor --image sha256:abc...
```

## Rego Import Behavior

When importing Rego files, the system:
1. Parses `deny` rules and maps known patterns to native gates (CVSS comparisons, boolean checks).
2. Extracts `remediation` rules into structured hints.
3. Unknown patterns are preserved and evaluated via the embedded OPA evaluator.
4. Validation reports which rules mapped natively vs. remain OPA-evaluated.

## Determinism

All evaluations are deterministic:
- Same policy + same input = same output (hash-verifiable)
- No time-dependent logic in deterministic mode
- `outputDigest` in evaluation results enables replay verification

## API Endpoints

The Platform API exposes policy interop at `/api/v1/policy/interop`:

| Method | Path | Description |
|--------|------|-------------|
| POST | `/export` | Export policy to format |
| POST | `/import` | Import policy from format |
| POST | `/validate` | Validate policy document |
| POST | `/evaluate` | Evaluate policy against input |
| GET | `/formats` | List supported formats |

## Gate Types

Supported gate types with Rego translation:

| Gate Type | Rego Pattern | Remediation Code |
|-----------|-------------|-----------------|
| `CvssThresholdGate` | `input.cvss.score >= threshold` | `CVSS_EXCEED` |
| `SignatureRequiredGate` | `not input.dsse.verified` | `SIG_MISS` |
| `EvidenceFreshnessGate` | `not input.freshness.tstVerified` | `FRESH_EXPIRED` |
| `SbomPresenceGate` | `not input.sbom.canonicalDigest` | `SBOM_MISS` |
| `MinimumConfidenceGate` | `input.confidence < threshold` | `CONF_LOW` |
| `UnknownsBudgetGate` | `input.unknownsRatio > threshold` | `UNK_EXCEED` |
| `ReachabilityRequirementGate` | `not input.reachability.status` | `REACH_REQUIRED` |