up

docs/migration/exception-governance.md

@@ -1,64 +1,58 @@
 # Exception Governance Migration Guide
 
-Status: Draft (2025-11-26) — aligns with Excititor VEX/exception flows and Doc task DOCS-EXC-25-007.
+> **Imposed rule:** All exceptions must be time-bound, tenant-scoped, and auditable; legacy perpetual suppressions are prohibited after cutover.
 
-## 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.
+This guide explains how to migrate from legacy suppressions/notifications to the unified Exception Governance model in Excititor and Console.
 
-## 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.
+## 1. What changes
+- **Unified exception object:** replaces ad-hoc suppressions. Fields: `tenant`, `scope` (purl/image/component), `vuln` (CVE/alias), `justification`, `expiration`, `owner`, `evidence_refs`, `policy_binding`, `status` (draft/staged/active/expired).
+- **Two-phase activation:** `draft → staged → active` with policy simulator snapshot; rollbacks produce a compensating exception marked `supersedes`.
+- **Notifications:** move from broad email hooks to route-specific notifications (policy events, expiring exceptions) using Notify service templates.
+- **Auditability:** each lifecycle change emits Timeline + Evidence Locker entries; exports include DSSE attestation of the exception set.
 
-## 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.
+## 2. Migration phases
+1. **Inventory legacy suppressions**
+   - Export current suppressions and notification rules (per tenant) to NDJSON.
+   - Classify by scope: package, image, repo, tenant-wide.
+2. **Normalize and enrich**
+   - Map each suppression to the unified schema; add `expiration` (default 30/90 days), `owner`, `justification` (use VEX schema categories when available).
+   - Attach evidence references (ticket URL, VEX claim ID, scan report digest) where missing.
+3. **Create staged exceptions**
+   - Import NDJSON via Console or `stella exceptions import --stage` (CLI guide: `docs/modules/cli/guides/exceptions.md`).
+   - Run policy simulator; resolve conflicts flagged by Aggregation-Only Contract (AOC) enforcement.
+4. **Activate with guardrails**
+   - Promote staged → active in batches; each promotion emits Timeline events and optional Rekor-backed attestation bundle (if Attestor is enabled).
+   - Configure Notify templates for expiring exceptions (T‑14/T‑3 days) and denied promotions.
+5. **Decommission legacy paths**
+   - Disable legacy suppression writes; keep read-only for 30 days with banner noting deprecation.
+   - Remove legacy notification hooks after confirming staged/active parity.
 
-## 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.
+## 3. Data shapes
+- **Import NDJSON record (minimal):** `{ tenant, vuln, scope:{type:'purl'|'image'|'component', value}, justification, expiration, owner }
+- **Export manifest:** `{ generated_at, tenant, count, sha256, aoc_enforced, source:'migration-legacy-suppressions' }`
+- **Attestation (optional):** DSSE over exception set digest; stored alongside manifest in Evidence Locker.
 
-## 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.
+## 4. Rollback plan
+- Keep legacy suppressions read-only for 30 days.
+- If a promotion batch causes regressions, mark affected exceptions `expired` and re-enable corresponding legacy suppressions for that tenant only.
+- Emit `rollback_notice` Timeline events and Notify operators.
 
-## 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.
+## 5. Air-gap considerations
+- Imports/exports are file-based (NDJSON + manifest); no external calls required.
+- Verification uses bundled attestations; Rekor proofs are optional offline.
+- Console shows AOC badge when Aggregation-Only Contract limits apply; exports record `aoc=true`.
 
-## 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`.
+## 6. Checklists
+- [ ] All legacy suppressions exported to NDJSON per tenant.
+- [ ] Every exception has justification, owner, expiration.
+- [ ] Policy simulator run and results attached to exception batch.
+- [ ] Notify templates enabled for expiring/denied promotions.
+- [ ] Legacy write paths disabled; read-only banner present.
+- [ ] Attestation bundle stored (if Attestor available) and Evidence Locker entry created.
+
+## 7. References
+- `docs/modules/excititor/architecture.md`
+- `docs/modules/excititor/implementation_plan.md`
+- `docs/modules/cli/guides/exceptions.md`
+- `docs/security/export-hardening.md`
+- `docs/policy/ui-integration.md`