StellaOps Policy Engine

Audience: policy authors writing Stella DSL packs, release engineers wiring promotion gates, and integrators consuming policy verdicts.

Policy Engine compiles and evaluates stella-dsl@1 policies deterministically, joining advisories, VEX evidence, and SBOM inventories into explainable findings with full provenance. It owns the PASS/FAIL promotion-gate decisions that the Release Orchestrator enforces, and exposes simulation and diff APIs so authors can preview the impact of a change before it ships.

This is the canonical Policy module dossier. The ../policy-engine/directory is a pointer stub plus the auto-generated API reference.

Responsibilities

• Compile stella-dsl@1 packs into executable graphs.
• Join advisories, VEX evidence, and SBOM inventories to derive effective findings.
• Expose simulation and diff APIs for UI/CLI workflows.
• Emit change-stream driven events for Notify/Scheduler integrations.
• Own promotion gate PASS/FAIL decision outputs consumed by Release Orchestrator.

Registry and Plugin Boundary

Policy is pack-first, not evaluator-plugin-first. Release safety semantics remain host-owned: severity fusion, KEV/EPSS handling, reachability weighting, signature verification, release gates, exceptions, trust weighting, and deterministic verdict hashing are implemented by Policy Engine and its shared libraries.

The following are declarative data/policy packs by default and must not execute code when imported or activated:

• stella-dsl@1 policy packs and SPL documents.
• Rego interoperability documents, YAML/JSON policy packs, scoring profiles, gates, exception effects, routing templates, trust weights, and coverage fixtures.
• Air-gap policy bundles, signed exports, policy mirror bundles, and environment overlays.

Third-party executable evaluators are future/rare extension points. They require a dedicated Policy sprint, a signed plugin contract, admission policy, trust-root configuration, deterministic IO limits, and explicit test coverage before any runtime code can be loaded. Kubernetes admission webhooks are not part of the base Policy default; they would be a separate integration surface, not a reason to turn policy packs into executable plugins.

Key components

• StellaOps.Policy.Engine — Minimal-API service host plus background workers (policy-engine, host slot 14). Hosts compilation, evaluation, simulation, Policy Studio pack lifecycle, gate decisions, exception management, risk-profile, and air-gap surfaces. The former StellaOps.Policy.Gateway project has been merged into the Engine; its gateway endpoints are now served by the Engine and StellaOps.Policy.Gateway is retained for reference only.
• StellaOps.PolicyDsl — stella-dsl@1 parser/compiler (PolicyParser, PolicyCompiler) with completion provider tooling.
• Shared libraries under StellaOps.Policy.*: StellaOps.Policy.Persistence (PostgreSQL storage + startup migrations), StellaOps.Policy.RiskProfile, StellaOps.Policy.Scoring (CVSS v4 receipts), StellaOps.Policy.Determinization, StellaOps.Policy.Exceptions, StellaOps.Policy.Explainability, StellaOps.Policy.Unknowns, StellaOps.Policy.AuthSignals, StellaOps.Policy.Predicates, and StellaOps.Policy.Interop.

Integrations & dependencies

• PostgreSQL (schemas policy and policy_app) is the system of record for packs/revisions, evaluation runs, risk profiles, CVSS/EPSS receipts, snapshots, violation events, conflicts, ledger exports, exceptions, budgets, and explain traces (policy.explanations). Schema is created and migrated on startup via AddStartupMigrations (see StellaOps.Infrastructure.Postgres.Migrations) using the embedded SQL under StellaOps.Policy.Persistence/Migrations/. There is no external init-script dependency.
• Postgres-backed messaging transport (StellaOps.Messaging.Transport.Postgres) and distributed cache for change-stream inputs and incremental re-evaluation signals.
• Scheduler / Orchestrator integration for incremental re-evaluation triggers and job orchestration (/policy/orchestrator/jobs, /policy/worker/run).
• Reachability/Signals integration (AddReachabilityFactsSignalsIntegration) and VEX decision emission for evidence joins.
• Attestor/Signer integration for verdict attestations and signed verdict bundles (VerdictAttestation; Rekor transparency is offline by default).
• Authority resource-server integration enforcing policy:*, effective:write, findings:read, exceptions:*, and airgap:* scopes. Tenant context is enforced by middleware and resolved via PolicyStellaOpsTenantResolver.
• CLI/UI (Console) for policy authoring, simulation, approvals, and explain viewing.

API surface (selected route prefixes)

Routes are served under the policy-engine service (lowercased URLs). Highlights grounded in StellaOps.Policy.Engine/Endpoints:

• POST /api/policy/policies/{policyId}/versions/{version}:compile — compile and lint a stella-dsl@1 document (policy:edit).
• /api/policy/packs — pack lifecycle: create pack/revision (policy:edit), compile+sign bundle, evaluate revision (policy:read), :activate with two-person approval (policy:activate).
• /api/policy/decisions, /api/policy/snapshots, /api/policy/violations, /api/policy/conflicts — decisions, snapshots, violation events, and conflict resolution.
• /policy/eval/batch, /policy/worker/run, /policy/orchestrator/jobs — batch evaluation and worker/orchestrator jobs.
• /api/risk/profiles, /api/risk/simulation, /api/risk/overrides, /api/risk/scopes, /api/risk/events — risk-profile authoring, simulation, overrides, scope attachments, and events.
• /api/v1/authority/effective-policies, /api/v1/authority/scope-attachments — effective-policy materialization (effective:write).
• /api/cvss/receipts — CVSS v4 receipt CRUD and amendment history.
• /api/v1/policy/gate, /api/v1/gate, /api/v1/gates, /policy/... — promotion gate evaluation, score-based gates, and unknowns gates (consumed by Release Orchestrator).
• /api/policy/exceptions, /api/v1/policy/exception — exception lifecycle and approvals (exceptions:read|request|approve).
• /api/v1/airgap/bundles, /api/v1/airgap/risk-profiles, /system/airgap — air-gap bundle import, risk-profile export/import, and sealed-mode controls (airgap:seal, airgap:status:read).
• GET /openapi/v1.json (anonymous), GET /healthz, GET /readyz — OpenAPI discovery and health/readiness.

Authorization scopes (enforced by endpoints)

• Read: policy:read, findings:read, exceptions:read, airgap:status:read.
• Authoring / mutation: policy:edit, policy:write, policy:author.
• Lifecycle / run: policy:activate, policy:run, policy:operate, policy:approve, policy:simulate.
• Audit: policy:audit.
• Exceptions: exceptions:request, exceptions:approve.
• Effective findings (Policy Engine identity only): effective:write.
• Air-gap: airgap:seal.

Additional policy:* scopes exist in the canonical catalog (StellaOpsScopes.cs: policy:submit, policy:review, policy:publish, policy:promote) but are not currently enforced by Policy Engine endpoints — they belong to the broader Policy Studio governance surface.

Observability

• Meter / ActivitySource name: StellaOps.Policy.Engine.
• Spans: policy.select, policy.evaluate, policy.materialize, policy.simulate, policy.compile.
• Representative metrics: policy_run_seconds, policy_run_queue_depth, policy_rules_fired_total, policy_compilation_total, policy_compilation_seconds, policy_simulation_total, policy_findings_materialized_total, policy_evaluations_total, policy_errors_total, policy_slo_burn_rate, policy_error_budget_remaining, policy_vex_decisions_total, policy_reachability_applied_total, policy_airgap_sealed (full list in Telemetry/PolicyEngineTelemetry.cs).

Operational notes

• DSL grammar and lifecycle: dsl-grammar-specification.md, POLICY_TEMPLATES.md, recheck-policy.md.
• Determinization API and architecture: determinization-api.md, determinization-architecture.md.
• Governance and scope mapping: ../../security/policy-governance.md.
• Promotion gate ownership contract: promotion-gate-ownership-contract.md.
• Readiness briefs: secret-leak-detection-readiness.md, windows-package-readiness.md, ../scanner/design/macos-analyzer.md, ../scanner/design/windows-analyzer.md.
• Ruby capability predicates design: design/ruby-capability-predicates.md.

Backlog references

• DOCS-POLICY-20-001 … DOCS-POLICY-20-012 (completed baseline).
• DOCS-POLICY-23-007 (upcoming command updates).

Implementation Status

Note: The phase labels below originated as a forward roadmap; several phases marked “In Progress”/“Planned” already have shipped runtime surfaces in StellaOps.Policy.Engine. The status annotations have been reconciled against the code; remaining gaps are noted per phase.

Phase 1 – Deterministic evaluation core (Implemented)

• DSL compiler (StellaOps.PolicyDsl) with caching, static analysis, runtime guardrails
• Batch evaluator (/policy/eval/batch) with deterministic ordering, change-stream inputs
• Effective findings materialization (Policy Engine identity, effective:write)
• Explain trace generation with evidence linking, persisted in policy.explanations

Phase 2 – Orchestration & incremental runs (Implemented)

• Orchestrator/worker jobs (/policy/orchestrator/jobs, /policy/worker/run) with persisted job stores
• Determinism verification endpoints (/api/v1/verify) and replay audit tables
• Incremental processing via Postgres-backed messaging/change streams
• Snapshots and resume state (/api/policy/snapshots, policy.snapshots)

Phase 3 – Policy Studio workflows (Largely implemented)

• Pack registry with draft/approved revision lifecycle and two-person activation (/api/policy/packs)
• Signed bundle compilation (/{packId}/revisions/{version}/bundle)
• Console integration surfaces: simulation diff, attestation reports, exports
• CLI parity tracked separately (see backlog DOCS-POLICY-23-007)

Phase 4 – Simulation & approvals (Largely implemented)

• Diff/simulation APIs: /policy/console/simulations/diff, /simulation/overlay, /simulation/path-scope, /api/risk/simulation
• Exception approval queues and workflows (/api/policy/exceptions, /api/v1/policy/exception)
• Console/CLI policy preview integration

Phase 5 – Exports & offline parity (Largely implemented)

• Console export jobs/bundles (/api/v1/export) and policy/risk-profile air-gap bundles (/api/v1/airgap/bundles, /api/v1/airgap/risk-profiles) with signed manifests and verification
• Sealed-mode controls and staleness signaling (/system/airgap)
• Ledger export (/policy/ledger/export)

Phase 6 – Observability & hardening (Implemented)

• Metrics and tracing under meter/source StellaOps.Policy.Engine (see Observability section)
• Rate limiting for simulation endpoints; guard-violation detection in the determinism layer
• Incident-mode controls (IncidentModeService); runbooks/compliance attestations tracked in docs

Key Acceptance Criteria

• Evaluation deterministic across runs; effective findings materialised only by Policy Engine
• Incremental runs handle deltas within ≤5 min SLA; replay verification succeeds
• Policy Studio supports full lifecycle with signed promotions and explain traces
• Exports reproducible with signed manifests; Offline Kit delivers same tooling
• Guardrails prevent forbidden IO; static analysis integrated into CI

Technical Decisions & Risks

• Non-determinism prevented via strict static analysis, runtime guards, replay tests
• Policy drift managed through simulation previews, approval workflow, audit trail
• Scaling handled via sharded workers, incremental deltas, caching, queue fairness
• Guard bypass prevented by analyzers in CI and runtime rejection of forbidden operations

Epic alignment

• Epic 2 – Policy Engine & Editor: deliver deterministic evaluation, DSL infrastructure, explain traces, and incremental runs.
• Epic 4 – Policy Studio: integrate registry workflows, simulation at scale, approvals, and promotion semantics.