git.stella-ops.org/docs/migration/exception-governance.md

Exception Governance Migration Guide

Imposed rule: All exceptions must be time-bound, tenant-scoped, and auditable; legacy perpetual suppressions are prohibited after cutover.

This guide explains how to migrate from legacy suppressions/notifications to the unified Exception Governance model in Excititor and Console.

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.

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.

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.

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.

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.

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