first commit

docs/audit-retention.md

@@ -0,0 +1,28 @@
+# Security event retention
+
+`AUDIT_RETENTION_DAYS=0` disables deletion by default. A deployment administrator
+may opt in with 1..3650 days. The server checks hourly and removes at most 500
+eligible database events per pass. It uses the current SIEM exporter's durable
+cursor, never a historical destination's cursor. A successful HTTP response means
+the receiving SIEM accepted a batch; it is not a guarantee of its archival policy.
+
+Only expired events already delivered through that cursor are eligible. All
+incident source events remain protected, including resolved cases. Sigma
+correlations cannot be left pointing at removed source events across a batch
+boundary. Related alert rows are removed in the same transaction. The device-event
+UUID ledger remains intact, so retransmission cannot recreate expired events.
+Policy history, signatures, users and device credentials are outside this job.
+
+Deletion and its metadata-only audit event commit atomically. A failure rolls
+everything back and appears in the administration status. The service account
+must protect the SQLite database and backups. Logical deletion does not promise
+secure erasure from SQLite pages, WAL files, disks or backups.
+
+The module exports `pruneAuditEvents(..., {dryRun:true})` for deployment validation.
+There is no browser-policy switch or unauthenticated cleanup endpoint. Status in
+the admin console is read-only. Retention of incident notes/history, the durable
+dedup ledger, local `security.ndjson`/CEF files, external SIEM records and backups
+requires a separate lifecycle; this database job does not govern those stores.
+
+`tests/audit-retention.test.mjs` verifies export and batch boundaries, incident
+preservation, replay-ledger preservation, explicit opt-in and transactional failure.