up

docs/migration/exception-governance.md

@@ -0,0 +1,64 @@
+# Exception Governance Migration Guide
+
+Status: Draft (2025-11-26) — aligns with Excititor VEX/exception flows and Doc task DOCS-EXC-25-007.
+
+## Why this migration
+- Retire legacy suppressions/waivers and move to policy/VEX-first exceptions with provenance.
+- Provide auditable, reversible exceptions with rollout/rollback plans and notifications.
+
+## Target state
+- Exceptions are recorded as:
+  - VEX statements (OpenVEX) referencing findings and components.
+  - Policy overrides (simulator) with scope, expiry, and rationale.
+  - Optional authority approval attestation (DSSE) per exception bundle.
+- Persistence: Excititor stores exception records with tenant, source, scope, expiry, approver, evidence links.
+- Propagation:
+  - Graph overlays surface exception status on nodes/edges.
+  - Notify emits `exception.created/expired` events.
+  - CLI/Console consume exception status via `/exceptions` API.
+
+## Migration steps
+1) **Freeze legacy inputs**
+   - Disable new legacy suppressions in UI/CLI.
+   - Mark existing suppressions read-only; export CSV/NDJSON snapshot.
+2) **Export legacy suppressions**
+   - Run `exc suppressions export --format ndjson --with-rationale --with-expiry`.
+   - Store exports with SHA256 and DSSE envelope in `exceptions/export-YYYYMMDD/`.
+3) **Transform to VEX/policy overrides**
+   - Convert each suppression to OpenVEX statement:
+     - `status`: `not_affected` or `under_investigation`.
+     - `justification`: map legacy reason → VEX justification code.
+     - `impact`: optional; include nearest safe version if known.
+   - Generate policy override record with:
+     - `scope` (component, environment, service).
+     - `expiresAt` (carry forward or set 30/90d).
+     - `rationale` from legacy note.
+4) **Import**
+   - Use Excititor `/exceptions/import` (or CLI `exc exceptions import`) to load transformed NDJSON.
+   - Verify import report: counts by status, rejected items, conflicts.
+5) **Notify & rollout**
+   - Notify downstream systems: Graph overlays refresh, Scanner/Vuln Explorer respect VEX, Policy Engine caches reload.
+   - Announce change freeze window and rollback plan.
+
+## Rollback plan
+- Keep legacy suppressions export.
+- If import fails or downstream errors:
+  - Disable new exception endpoints feature flag.
+  - Re-enable legacy suppressions (read-only → writable) temporarily.
+  - Investigate rejected items; re-run transform/import after fix.
+
+## Notifications
+- When migrating: send summary to tenants with counts per status and upcoming expiries.
+- Ongoing: Notify events `exception.created`, `exception.expired`, `exception.rejected` with tenant + scope.
+
+## Validation checklist
+- [ ] Legacy suppressions export stored with SHA256 + DSSE.
+- [ ] Transform script maps all legacy reasons → VEX justification codes.
+- [ ] Import dry-run produces zero rejects or documented rejects with reasons.
+- [ ] Overlay/Console shows exceptions on affected components.
+- [ ] Rollback tested on staging.
+
+## References
+- Excititor module: `docs/modules/excititor/architecture.md`, `vex_observations.md`.
+- Policy simulator: `docs/modules/policy/architecture.md` (POLICY-ENGINE-30-001..003).
+- Graph overlays: `docs/modules/graph/architecture-index.md`.