audit-log-architect

name

audit-log-architect

description

Design a durable, tenant-scoped audit log system — an audit event taxonomy (authentication events, access-control changes, data access and exports, admin/support actions, security events, billing changes), a record schema (actor, tenant, action, target, outcome, correlation id, timestamp), integrity guarantees (append-only, tamper-evidence, an explicit audit-write-failure policy), retention and redaction rules, tenant-scoped access to audit data, and negative tests proving audit writes cannot be silently skipped and audit reads cannot cross tenants. Includes a migration path for introducing auditing to a live system with rollback. Use when building or overhauling audit logging, when compliance (SOC 2, ISO 27001, customer contracts) requires an audit trail, or when audit events are currently ad-hoc console logs. Do NOT use for API/webhook event contracts consumed by integrations (api-event-architect), for observability/tracing design, or for deciding who may do what (authorization-matrix-designer).

Audit Log Architect

Purpose

Produce an audit system that can answer "who did what, to what, in which tenant, when, and what happened" — durably, provably, and without leaking one tenant's activity to another. Deliverables: an event taxonomy, a record schema, integrity and failure-policy rules, retention/redaction policy, a tenant-scoped access model, negative tests, and a plan for introducing it to a live system. An audit log differs from application logging in exactly the properties people skip: completeness by taxonomy, immutability, and scoped access — a grep-able stdout stream is not an audit trail.

Use When

• Use when: compliance (SOC 2, ISO 27001, HIPAA-adjacent, enterprise contracts) requires demonstrable audit trails.
• Use when: audit-worthy actions are currently ad-hoc logger.info calls with no schema, durability, or access story.
• Use when: designing tenant-facing audit views ("show my workspace's activity") or staff-action accountability (support access must be auditable).
• Use when: an incident post-mortem revealed you cannot reconstruct who did what.
• Do NOT use when: designing events that INTEGRATIONS consume (webhooks, event feeds) — that is api-event-architect; audit events are a record, not an integration contract, even when one action produces both.
• Do NOT use when: the need is debugging/observability (traces, metrics, app logs) — different retention, different audience, different guarantees.
• Do NOT use when: deciding who is ALLOWED to act — that is authorization-matrix-designer; this skill records what they did.

Inputs to Inspect

1. The authorization design (authorization-matrix-designer output): sensitive permissions, cross-tenant platform roles, and brokered-access rules — each implies required audit events.
2. The tenant model: tenant boundary, lifecycle states (audit retention must survive offboarding questions), membership semantics for actor identity.
3. Current logging: what is emitted today, from where, with what fields — the gap between it and the taxonomy is the work.
4. Compliance requirements naming specific events, retention periods, or access rules (SOC 2 criteria, contractual audit clauses).
5. Data-sensitivity constraints: what may never appear in an audit payload (secrets, credentials, full PII records).
6. Volume expectations: events/day at the taxonomy's scope — drives storage and the high-volume design decisions.

Workflow

1. Build the event taxonomy from the starter set in references/audit-event-taxonomy.md: authentication, access-control changes, data access/export, admin and support actions, security events, billing/plan changes, lifecycle transitions. For each category: which concrete actions MUST be recorded. The taxonomy is the completeness contract — an unlisted action is a decision, not an oversight.
2. Define the record schema: actor (user/service/support-grant id, never just "admin"), on-behalf-of for impersonation, tenant id, action (from the taxonomy), target (type + id), outcome (success/denied/failed), timestamp, correlation/request id, origin (IP/user-agent where policy allows), and a redacted details payload. Schema versioned from day one.
3. Set integrity rules: append-only store — no update or delete API exists; tamper-evidence proportional to requirements (restricted DB permissions at minimum, hash-chaining/WORM storage where contracts demand it); clock source stated.
4. Decide the write-failure policy per category — the question that distinguishes audit from logging: if the audit write fails, does the action proceed? Security-critical categories (access-control changes, impersonation, exports) fail closed or queue-with-guarantee; lower categories may fail open with an alert. Write the policy down per category.
5. Define retention and redaction: retention per category (compliance floor, cost ceiling), what redaction removes from payloads before write (secrets always; PII per policy), and whether audit records survive tenant purge (usually yes, in de-identified or platform-scoped form — state it, it is a legal decision → flag to the human).
6. Design the access model: tenant admins read their own tenant's events only (scoped views); platform/staff audit access is itself an audited action; no general-purpose query access to the raw store. Support-facing and tenant-facing views may differ in fields — say how.
7. Write the negative-test plan: cross-tenant audit read denied; update/delete attempts on audit records fail at the store level; an audited action performed without a resulting event = test failure (completeness probe on the top sensitive actions); impersonation without an audit event fails.
8. Plan the rollout to a live system: emit-only first (no consumer), verify volume and schema against real traffic, then attach views and alerts; backfill is usually impossible — state the audit-coverage start date honestly rather than fabricating history. Rollback: emission can be disabled per category without touching business logic; already-written records are never deleted by a rollback.

Output Format

AUDIT LOG DESIGN — <product/scope>
Event taxonomy: <category → concrete actions recorded; explicit exclusions
  with rationale>
Record schema: <fields, versioned; impersonation via on-behalf-of>
Integrity: <append-only mechanism; tamper-evidence level; clock source>
Write-failure policy: <category → fail-closed / queued-guaranteed /
  fail-open+alert>
Retention & redaction: <category → retention; payload redaction rules;
  post-purge policy (flagged as legal decision)>
Access model: <tenant-scoped views; staff access audited; raw-store access:
  none>
Negative-test plan: <test — attempted violation — expected result>
Rollout & rollback: <emit-only → verify → attach consumers; coverage start
  date; per-category disable; records never deleted>
Assumptions & open questions: <each with risk-if-wrong / who answers>

Validation Checklist

• Every sensitive permission and brokered-access rule from the authorization design has a corresponding audit event.
• Actor is always a resolvable identity; impersonation carries both identities via on-behalf-of.
• No update/delete path exists to audit records; the mechanism is named.
• Write-failure policy is explicit per category — the fail-open/closed question is answered, not dodged.
• Payload redaction rules exist; secrets can never be written.
• Tenant admins can read only their tenant; staff audit reads are themselves audited.
• Negative tests cover cross-tenant reads, tampering, and completeness (action-without-event).
• Rollout starts emit-only and rollback never deletes written records.
• Audit events are not conflated with integration webhooks or app logs.

Tenant Isolation Rules

• Every audit event carries the tenant id (or an explicit platform scope for tenant-less staff actions); there is no ambiguous scope.
• Tenant-facing audit queries are scoped at the store/view layer, not by application-side filtering of a global table.
• Cross-tenant audit access (staff, regulators) is enumerated, brokered, and produces its own audit events.

Security Rules

• Append-only is a property of the store's permissions, not a code convention — the application role used for writes has no UPDATE/DELETE.
• Secrets, tokens, and credentials never enter payloads; redaction runs before write, not at read time.
• Security-critical actions (access-control changes, impersonation, exports) must not silently proceed when auditing is unavailable — per the stated fail-closed/queued policy.
• Negative tests are part of the deliverable; an audit system without a tamper test and a completeness probe is a logging system.

Gotchas

• High-volume read events (every record view) can swamp the store; the taxonomy may record reads at coarser grain (search performed, export taken) — but that is a stated decision with compliance sign-off, not sampling by accident.
• Audit through the ORM inherits soft-delete and update paths you thought you removed; write via a dedicated append-only writer.
• "We'll backfill audit history later" is fiction; the coverage start date is what it is — document it.
• Correlation ids that never propagate to background jobs make job actions unattributable; the job context must carry actor + correlation from the triggering request.
• Tenant purge vs audit retention is a genuine legal tension — surface it; do not resolve it silently in either direction.

Stop Conditions

• Compliance regime or contractual audit clauses unknown AND they would change taxonomy/retention → ask before designing to guesses.
• Post-purge audit retention (keep vs destroy) is a legal decision → human-approval-boundary; present both options with consequences.
• The system has no authorization design to hang events off → run authorization-matrix-designer first or in tandem; auditing undefined permissions records noise.
• Asked to implement the pipeline in the same pass → separate, scoped task; this skill delivers the design and test plan.

Supporting Files

• references/audit-event-taxonomy.md — starter taxonomy by category with must-record actions and grain guidance.
• evals/evals.json — trigger + behavior cases.
• evals/trigger-evals.json — discrimination against authorization-matrix-designer and api-event-architect (access & events cluster).