git.stella-ops.org/docs/policy/overview.md

Policy System Overview

Imposed rule: Policies that change reachability or trust weighting must enter shadow mode first and ship coverage fixtures; promotion is blocked until shadow + coverage gates pass (see docs/policy/lifecycle.md).

This overview orients authors, reviewers, and operators to the Stella Policy system: the SPL language, lifecycle, evidence inputs, and how policies are enforced online and in air-gapped sites.

1. What the Policy System Does

• Combines SBOM facts, advisories (Concelier), VEX claims (Excititor), reachability signals (Graphs + runtime), trust/entropy signals, and operator metadata to produce deterministic findings.
• Produces explainable outputs: every verdict carries rule, rationale (because), inputs, and evidence hashes.
• Works online or offline: policies, inputs, and outputs are content-addressed and can be replayed with no network.

2. Layers

• SPL (Stella Policy Language): declarative rules (stella-dsl@1) with profiles, maps, and rule blocks; no loops or network calls.
• Compiler: canonicalises SPL, emits IR + hash; used by CLI, Console, and CI. Canonical hashes feed attestation and replay.
• Engine: evaluates IR against SBOM/VEX/reachability signals; outputs effective findings and explains every rule fire.
• Attestation: optional DSSE over policy IR and approval metadata; Rekor mirror when online.
• Distribution: policy packs are versioned, tenant-scoped, and promoted via Authority scopes; Offline Kit includes packs + attestations.

3. Inputs & Signals

• SBOM inventory/usage (Scanner), advisories (Concelier), VEX (Excititor), reachability graphs/runtime (Signals), trust/entropy/uncertainty scores, secret-leak findings, environment metadata, and tenant policy defaults.
• Signals dictionary (normalised): trust_score, reachability.state/score, entropy_penalty, uncertainty.level, runtime_hits.
• All inputs must be content-addressed; missing fields evaluate to unknown/null and must be handled explicitly.

4. Lifecycle (summary)

1. Draft in SPL with shadow mode on and coverage fixtures (stella policy test).
2. Submit with lint/simulate + coverage artefacts attached.
3. Review/approve with Authority scopes; determinism and shadow gates enforced in CI.
4. Publish/attest (DSSE + optional Rekor); promote to environments; activate runs.
5. Archive or roll back with audit trail preserved.

5. Governance & Roles

• Scopes: policy:author, policy:review, policy:approve, policy:operate, policy:publish, policy:activate, policy:audit.
• Two-person rule recommended for publish/promote; enforced by Authority per tenant.
• AOC: Aggregation-Only Contract applies to regulated tenants—UI/CLI must respect AOC flags on policies and evidence.

6. Review Checklist (fast path)

• Lint + simulate outputs attached and fresh (<24h).
• Shadow mode enabled; coverage fixtures passing; twin-run determinism check green.
• because present on every status/severity change; suppressions scoped.
• Inputs handled explicitly when unknown (reachability/runtime missing).
• Attestation metadata ready (reason, ticket, IR hash) if publish is requested.
• AOC impact noted; air-gap replay steps documented if applicable.

7. Air-gap / Offline Notes

• Policy packs, attestations, and coverage fixtures ship in Offline Kits; no live feed calls allowed during evaluation.
• CLI stella policy simulate --sealed enforces no-network; policy runs must use frozen SBOM/advisory/VEX bundles and reachability graphs.
• Attestations and hashes recorded in Evidence Locker; Timeline events emitted on publish/activate.

8. Key References

• docs/policy/dsl.md (language)
• docs/policy/lifecycle.md (process, gates)
• docs/policy/architecture.md (engine internals)
• docs/modules/policy/implementation_plan.md
• docs/policy/governance.md (once published)