stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
4831c7fcb0d8c8d9bdf01c106f8bcf27810f4fb0
git.stella-ops.org/docs/migration/exception-governance.md
StellaOps Bot 4831c7fcb0
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
up
2025-11-26 09:28:16 +02:00

3.1 KiB
Raw Blame History

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.