ea970ead2a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
api-governance / spectral-lint (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
# Policy Parity Migration Guide
|
|
|
|
> **Imposed rule:** Parity runs must use frozen inputs (SBOM, advisories, VEX, reachability, signals) and record hashes; activation is blocked until parity success is attested.
|
|
|
|
This guide describes how to dual-run old vs new policies and activate only after parity is proven.
|
|
|
|
## 1. Scope
|
|
- Applies to migration from legacy policy engine to SPL/DSL v1.
|
|
- Covers dual-run, comparison, rollback, and air-gap parity.
|
|
|
|
## 2. Dual-run process
|
|
1. **Freeze inputs**: snapshot SBOM/advisory/VEX/reachability feeds; record hashes.
|
|
2. **Shadow new policy**: run in shadow with same inputs; record findings and explain traces.
|
|
3. **Compare**: use `stella policy compare --base <legacy> --candidate <new>` to diff findings (status/severity) and rule hits.
|
|
4. **Thresholds**: parity passes when diff counts are zero or within approved budget (`--max-diff`); any status downgrade to `affected` must be reviewed.
|
|
5. **Attest**: generate parity report (hashes, diffs, runs) and DSSE-sign it; store in Evidence Locker.
|
|
6. **Promote**: activate new policy only after parity attestation verified and approvals captured.
|
|
|
|
## 3. CLI commands
|
|
- `stella policy compare --base policy-legacy@42 --candidate policy-new@3 --inputs frozen.inputs.json --max-diff 0`
|
|
- `stella policy parity report --base ... --candidate ... --output parity-report.json --sign`
|
|
|
|
## 4. Air-gap workflow
|
|
- Run compare offline using bundled inputs; export parity report + DSSE; import into Console/Authority when back online.
|
|
|
|
## 5. Rollback
|
|
- Keep legacy policy approved/archivable; rollback with `stella policy activate <legacy>` if parity regression discovered.
|
|
|
|
## 6. Checklist
|
|
- [ ] Inputs frozen and hashed.
|
|
- [ ] Shadow runs executed and stored.
|
|
- [ ] Diff computed and within budget.
|
|
- [ ] Parity report DSSE-signed and stored.
|
|
- [ ] Approvals recorded; two-person rule satisfied.
|
|
- [ ] Rollback path documented.
|
|
|
|
## References
|
|
- `docs/policy/runtime.md`
|
|
- `docs/policy/editor.md`
|
|
- `docs/policy/governance.md`
|
|
- `docs/policy/overview.md`
|