first commit

docs/incident-management.md

@@ -0,0 +1,18 @@
+# Incident management
+
+The central HTTPS admin console provides a case workflow alongside the immutable security event stream. Administrators and operators can create one case per existing event, assign a subject identifier, set severity, investigate, resolve, dismiss or reopen. Auditors can read cases and their history but cannot mutate them. Unknown methods, including deletion, are denied by the central permission middleware.
+
+Endpoints:
+- `GET /api/admin/incidents`: bounded descending pagination (`limit` 1–100, `before` numeric case cursor), optional status and severity filters.
+- `POST /api/admin/incidents`: `{eventId, severity?}`; returns a stable UUID and revision 1. Missing events return 404, duplicate event references return 409. Case audit events cannot recursively create cases.
+- `GET /api/admin/incidents/:id`: current metadata and bounded immutable history.
+- `PATCH /api/admin/incidents/:id`: `{expectedRevision, status?, severity?, assignee?, comment?}`. Stale revisions return 409; clients must refresh and deliberately reapply their changes.
+
+Allowed statuses are `open`, `investigating`, `resolved`, `dismissed`; severities `low`, `medium`, `high`, `critical`. Assignments are explicit SSO subject identifiers, not a verified directory picker; all control characters are forbidden. Empty assignments use null. Analyst notes are limited to 1,000 characters and reject control characters. A case is limited to 1,000 history entries; further edits fail closed rather than truncating evidence.
+
+Cases reference existing events without copying document or prompt contents. Their source event view allowlists decision, rule, policy version, destination host, severity, source reference, content type, classification and coverage metadata. Arbitrary event payload fields are excluded. Every successful mutation atomically updates the compare-and-swap revision, appends an immutable history entry and records an audit event. Analyst notes remain in the restricted case history; ordinary security events, ECS/CEF and telemetry receive only their character count. Hashes of notes are deliberately excluded because predictable text could be guessed. Notes must contain investigation summaries, not document excerpts, prompts, credentials or secrets; free text cannot automatically guarantee this constraint.
+
+Initial audit retention preserves every incident source event, including resolved cases. There is no case deletion, case expiry, automatic case generation, notifications, external ticket integration, evidence attachment storage or directory synchronization. These require separate deployment policy and implementation. The current SQLite administration database needs a protected service account, backups, explicit access permissions and deployment retention arrangements.
+
+Evidence: `node --test tests/incidents.test.mjs` exercises real HTTP routes, role separation, bounded metadata/notes, immutable source events, duplicate rejection, optimistic concurrency, reopening, filters and pagination.
+