d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
55 lines
3.8 KiB
Markdown
55 lines
3.8 KiB
Markdown
# 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)
|