43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# Exceptions API
|
|
|
|
Exceptions are time-bound, tenant-scoped, auditable objects that change policy outcomes without mutating upstream evidence. They are used for waivers, compensating controls, and scoped suppressions in a way that is replayable offline.
|
|
|
|
This document is the entry point for exception contracts. Concrete shapes live in the gateway and Console schemas listed below.
|
|
|
|
## Core Concepts
|
|
|
|
- **Exception object:** `{ exceptionId, tenantId, scope, vuln, effect, justification, owner, expiration, evidenceRefs, policyBinding, status }`
|
|
- **Append-only history:** changes are recorded as transitions; revoke/expire supersedes instead of delete.
|
|
- **Two-phase activation (recommended):** `draft → staged → active` to support simulation and controlled rollout.
|
|
- **Effects:** examples include `suppress`, `defer`, `downgrade`, `requireControl` (exact effect catalog is policy-driven).
|
|
|
|
## API Surfaces
|
|
|
|
- **Console CRUD/workflow (gateway-proxied):** see `docs/api/console/exception-schema.md`
|
|
- **Policy + Exceptions gateway contract:** `docs/api/gateway/policy-exceptions.md`
|
|
- **Exception workflow events (SSE stream):** `docs/api/gateway/exception-events.md`
|
|
|
|
## Security & Headers
|
|
|
|
Common requirements across endpoints:
|
|
|
|
- `Authorization: Bearer <token>` (or DPoP where configured)
|
|
- Tenant header (required): prefer `X-Stella-Tenant` (legacy alias: `X-StellaOps-Tenant`); see `docs/api/gateway/tenant-auth.md`.
|
|
|
|
Scopes vary by deployment, but typically follow:
|
|
|
|
- Read: `exception:read`
|
|
- Create/edit: `exception:write`
|
|
- Approve/reject/revoke: `exception:approve`
|
|
- Simulation endpoints: `policy:simulate` (plus `exception:read` when simulating with overrides)
|
|
|
|
## Offline / Air-Gap
|
|
|
|
- Imports/exports are file-based (NDJSON or JSON) with deterministic ordering and UTC timestamps.
|
|
- Signed exports (DSSE) are supported when Attestor is enabled; when disabled, exports remain hash-addressed and reproducible.
|
|
|
|
## Related Docs
|
|
|
|
- Exception Governance migration guide: `docs/migration/exception-governance.md`
|
|
- CLI usage guide: `docs/modules/cli/guides/exceptions.md`
|