Policy Import/Export Guide

Audience: Platform engineers and policy authors integrating Stella Ops with OPA-based toolchains, plus CI engineers wiring policy gates into pipelines. Scope: Bidirectional policy exchange between the Stella Ops native gate engine and OPA/Rego — formats, CLI commands, evidence input, remediation hints, and the interop API.

This guide covers bidirectional policy exchange between the Stella Ops native gate engine and OPA/Rego.

Overview

Stella Ops 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 native gate engine remains primary. Rego is an export target for teams that run OPA, and an import source for adopting external policies.

Formats

PolicyPack v2 (JSON)

Schema: policy.stellaops.io/v2

Structure:

{
  "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:

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:

# 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:

# 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:

# 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:

# 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:

{
  "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, Stella Ops:

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 Policy Engine exposes policy interop at /api/v1/policy/interop. All routes require a resolved tenant and policy:read; /import additionally requires policy:write:

Gate Types

Supported gate types with Rego translation:

Related Documentation

• Policy System Overview — where import/export fits in the Policy system.
• Stella Policy DSL (stella-dsl@1) — the native authoring language.
• Policy Lifecycle & Approvals — validating and promoting imported policies.
• Policy Engine Architecture — gate engine internals.