atelier/domains/compliance/audit-logs.md

Audit Logs — Derived Rules

Derives from domains/compliance/first-principles.md. Covers P1 (Audit Logs are Append-Only), P2 (Every Significant Action is Logged), P7 (Identity is Attributable), P9 (Secrets Redacted in Audit), and P10 (Compliance Posture Observable). Referenced by data-retention.md (retention applies to audit logs themselves) and evidence.md (audit logs are evidence).

Audit Logs are Append-Only (P1 Audit Logs are Append-Only)

• An audit record is immutable once written. The storage substrate enforces this; policy alone does not. Write-once, append-only sinks (WORM buckets, immutable log streams, hash-chained ledgers) are the mechanism.
• Deletion or mutation of an audit record is itself an auditable incident. The tampering is the signal, not just the underlying event. A system that allows DELETE FROM audit_log is a system whose audit log is a draft.
• The append-only guarantee is testable: attempt to write, then attempt to overwrite, then attempt to delete. If the overwrite or delete succeeds, the guarantee is absent and the design is a violation.

Structured Audit Events (P2 Every Significant Action is Logged)

• The set of auditable actions is defined a priori, in code, before the action ships. The catalog is versioned and reviewed. An auditable action with no log line is a violation, not a gap to backfill later.

• Audit events are structured (JSON / protobuf / a typed schema), not prose. A prose log line ("user logged in") is unqueryable and unaggregatable; a structured event is both. The event schema is the contract between the producer and the audit pipeline.

  {
    "timestamp": "2024-11-07T15:03:22Z",
    "event": "auth.login",
    "actor": { "kind": "user", "id": "u_8f3a", "session": "s_12b9" },
    "action": "succeeded",
    "target": { "kind": "service", "id": "billing-api" },
    "source": { "ip": "203.0.113.42", "region": "us-east-1" },
    "request_id": "req_91c2",
    "version": "audit-schema/v2"
  }
  

• The catalog of significant actions typically includes: authentication (success and failure), authorization decisions (allow and deny), data access (read, write, delete), configuration changes, policy changes, retention executions, and admin operations. The exact set is declared per system; the discipline is that it is declared.

Cloud Audit Log Conventions (Prior Art, Abstracted)

• AWS CloudTrail, Google Cloud Audit Logs, and Azure Activity Log share a common shape: immutable, time-ordered, queryable, with actor / action / target / source / result fields. Atelier's audit-logs doc adopts the shape, not the vendor.
• The shape is the contract; the sink is the implementation. A self-hosted audit log that follows the same shape composes with the same tooling (SIEM, query engines, evidence exporters) as the cloud vendors'.

Queryability (P10 Compliance Posture Observable)

• An audit log that cannot be queried is an audit log that cannot be used. Queryability is a first-class design goal: the event schema is typed, fields are indexed, and the common queries (who acted on what when, what failed, what was denied) are cheap.
• "Who did X between T1 and T2" must be a single query, not a forensics project. If the query requires a custom script per investigation, the audit log is structured for storage, not for use — a C7 (Observability) violation.

Identity is Attributable (P7 Identity is Attributable)

• Every audit event records the authenticated principal that acted — not a shared account, not a generic service, not "admin." The actor field is populated at the time of the action from the authenticated session, not resolved after the fact.
• A shared account in the actor field breaks accountability: an event attributed to svc-deploy could be any of ten engineers. This is the compliance angle on domains/security/authorization.md and domains/kubernetes/rbac.md: bind actions to unique principals, not to roles many can assume.
• Machine-to-machine actions record the workload identity (a service account, a signed instance identity), not a human — but the identity is still unique and attributable to a deployable unit.

Redaction at the Boundary (P9 Secrets Redacted in Audit)

• Audit logs must not leak secrets, credentials, tokens, or PII. Redaction is structural: applied at the logging boundary, before the record is written to the append-only sink — not opportunistic scrubbing after the fact. Once a secret is in an append-only log, the remediation is expensive (rotate, rewrite access scope), so redaction-at-source is the only sound position.

• The redaction policy is itself auditable: which fields are redacted, by what rule, in which event type. A redaction rule that lives in someone's head is a P9 violation waiting to happen.

  // before redaction (DO NOT LOG)
  {
    "event": "config.read",
    "target": { "kind": "secret", "id": "db-password" },
    "value": "p@ssw0rd-plaintext-leaked"   // VIOLATION
  }
  // after structural redaction
  {
    "event": "config.read",
    "target": { "kind": "secret", "id": "db-password" },
    "value": "[REDACTED:secret]",
    "redaction": "secret-value-policy/v1"
  }
  

• Never log request bodies, response bodies, headers like Authorization, or environment variables that may carry secrets. Log the fact of the action, not the content of the secret.

Retention of Audit Logs Themselves

• Audit logs are subject to retention policy (cross data- retention.md), but the floor is set by the accountability need, not by storage economy. An audit log deleted before its retention period is a P1 violation dressed as a P3 action.
• The retention rule for audit logs is itself logged (meta-audit): when an audit log segment ages out and is deleted, the deletion is recorded in a higher-tier audit log with the rule that authorized it. The chain is observable end to end.

What Violates Audit-Log Discipline

Violation	Principle
Audit log on a mutable filesystem with no write-once protection	P1 Audit Logs are Append-Only
DELETE FROM audit_log WHERE timestamp < ... as routine cleanup	P1 Audit Logs are Append-Only
An auth-success event with no audit record	P2 Every Significant Action is Logged
A prose log line ("user did a thing") instead of a structured event	P2 Every Significant Action is Logged
A shared admin account as the actor in audit events	P7 Identity is Attributable
An Authorization: Bearer <token> header logged in plaintext	P9 Secrets and Sensitive Data are Redacted in Audit
A redaction rule applied inconsistently across event types	P9 Secrets and Sensitive Data are Redacted in Audit
"Who did X?" requires a custom forensics script per investigation	P10 Compliance Posture is Observable
An audit log segment deleted with no meta-audit record	P1 Audit Logs are Append-Only

Relationship to Other Domains

• domains/observability/logging.md — audit logs are structured logging with an append-only guarantee; the logging primitives (levels, structured fields, correlation IDs) compose here.
• domains/security/authorization.md — the actor in an audit event is the principal the authorization layer authenticated.
• domains/security/secrets.md — redaction at the logging boundary is the audit-side complement of secret management.
• domains/compliance/data-retention.md — retention policy applies to audit logs; the audit log's own deletion is meta-audited.
• domains/compliance/evidence.md — audit logs are a primary evidence artifact; the append-only guarantee is what makes them admissible.
• domains/kubernetes/rbac.md — workload identity in audit events derives from the RBAC principal that acted.