Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

Relationships

#2102 Serve Audit Log - Phase 6: Full documentation

Opened by stack72 · 9/10/2026

Summary

The serve audit log is feature-complete through Phase 4 (#2004, #2028, #2049, #2074) but the documentation has not kept pace. The in-repo design doc is a 205-line implementation summary, while the original design artifact is a 1694-line specification. The swamp skill has no audit routing, no audit guide, and no audit reference. CLI help text for the audit parent command still describes the old local audit timeline, not the serve audit subsystem.

This phase closes every documentation gap so users, operators, and agents can discover, configure, and troubleshoot the audit log without reading source code.

Documentation gaps found

Location Current state Gap
design/README.md index serve-audit NOT listed in enablers table Missing row
design/enablers/serve-audit.md 205 lines, implementation-focused Missing: event schema, categories table, sinks detail, HMAC, storage layout, failure modes, policy detail, prior art
design/primitives/serve.md 2-line mention at line 379 Audit is a major subsystem, not a bullet
.claude/skills/swamp/SKILL.md routing table No audit row No way for agents to route audit questions
.claude/skills/swamp/SKILL.md Common Commands No audit commands listed swamp audit log/verify/export missing
.claude/skills/swamp/references/serve/guide.md No audit mention Operators cannot find audit docs through the skill
.claude/skills/swamp/references/audit/ Does not exist No dedicated audit guide or reference for the skill
swamp audit CLI description Describes old local audit timeline Does not describe serve audit subcommands (log, verify, export)
Troubleshooting references Only reference local audit No serve audit troubleshooting (WAL, sink connectivity, chain breaks)

What Phase 6 adds

1. Expand design/enablers/serve-audit.md

The in-repo design doc should be the authoritative reference for how the audit system works. Expand from 205 lines to cover everything the original design artifact specified:

  • Event schema: full AuditEvent interface with field descriptions and types
  • AuditDecision: what it captures and why (grantId, effect, groups at decision time)
  • Categories table: all 7 categories (auth, access, execution, secrets, admin, data, system) with actions and security signal
  • Management vs data event tiers: which categories are which, default routing
  • Audit stages: request/response semantics, when each is emitted
  • Audit policy: four detail levels (none/metadata/request/requestResponse), rule evaluation (first-match), YAML examples
  • Storage architecture: ring buffer, WAL, store sink, batched JSONL, date-partitioned layout
  • Durable delivery: failure mode table (backend unreachable, node crash, disk loss) with mitigations
  • Multi-target fan-out: how multiple store targets work, primary vs replicas
  • Chain hashing: how sequence/digest work, seed, canonical JSON, verification
  • Sinks: webhook (JSON + CEF field mapping), syslog (RFC 5424 field mapping, facility/severity), WebSocket
  • HMAC: which fields are hashed, how verification works, opt-out per policy rule, key storage
  • Fail-secure mode: what it does, when to use it
  • Sink filtering: per-sink category/tier/outcome filtering
  • Retention: per-target, date-partition GC, interaction with write-once storage
  • Config reference: complete swamp-serve.yaml audit block with all options annotated
  • Prior art: what was borrowed from Kubernetes, HashiCorp Vault, AWS CloudTrail, Temporal

2. Update design/README.md

Add serve-audit to the enablers index table so it is discoverable from the design doc root.

3. Update design/primitives/serve.md

Expand the audit mention from a 2-line bullet to a proper subsection describing what the audit log is, what it captures, and linking to the enabler doc.

4. Create .claude/skills/swamp/references/audit/guide.md

New skill guide for the audit log. This is what agents load when a user asks about audit. Covers:

  • What the audit log is and when to use it
  • Enabling audit (config block)
  • Querying: swamp audit log with filters
  • Verifying integrity: swamp audit verify
  • Bulk export: swamp audit export
  • Live tailing: swamp audit log --follow
  • Configuring sinks (webhook, syslog)
  • Audit policy configuration
  • HMAC and sensitive fields
  • Troubleshooting (WAL issues, sink connectivity, chain breaks, fail-secure lockout)

5. Create .claude/skills/swamp/references/audit/reference.md

Detailed reference loaded by the guide when deeper context is needed:

  • Full event schema with every field
  • Complete config schema with defaults and validation rules
  • CEF field mapping table
  • Syslog facility/severity mapping table
  • Policy rule evaluation semantics
  • CLI command reference (all flags for log, verify, export)
  • Server request types (audit.query, audit.verify, audit.subscribe, audit.export)
  • Filter shape reference
  • Error codes and troubleshooting recipes

6. Update .claude/skills/swamp/SKILL.md

  • Add routing table row: Audit — serve audit log, query, verify, export, SIEM integration -> references/audit/guide.md
  • Add Common Commands section entries:
    • swamp audit log --since 24h --category secrets
    • swamp audit verify --since 7d
    • swamp audit export --from 2026-07-01 --to 2026-09-30 --format csv

7. Update .claude/skills/swamp/references/serve/guide.md

Add an audit subsection or link to the dedicated audit guide. Operators looking at serve docs should discover audit exists.

8. Fix swamp audit CLI description

The parent audit command description says it is about local CLI audit timelines. Update to describe it as the entry point for both local audit record and serve audit log subcommands. The subcommand descriptions (log, verify, export) should clearly state they query a remote serve instance.

File: src/cli/commands/audit.ts — update the command description string.

9. Troubleshooting content

Add serve audit troubleshooting to the troubleshooting guide or audit guide:

  • WAL directory filling up (remote store unreachable)
  • Webhook sink returning errors (auth, connectivity, format)
  • Syslog sink circuit breaker tripping
  • Chain verification reporting breaks (what causes gaps, how to interpret)
  • Fail-secure mode rejecting requests (all stores unreachable)
  • HMAC key not found (vault not configured)
  • audit.query returning empty results (time range, filter mismatch, retention expired)

Files to create

  • .claude/skills/swamp/references/audit/guide.md
  • .claude/skills/swamp/references/audit/reference.md

Files to modify

  • design/enablers/serve-audit.md — expand from 205 lines to full spec
  • design/README.md — add enablers index row
  • design/primitives/serve.md — expand audit mention
  • .claude/skills/swamp/SKILL.md — routing table + common commands
  • .claude/skills/swamp/references/serve/guide.md — add audit link/section
  • src/cli/commands/audit.ts — fix parent command description

What it delivers

  • Operators can configure and troubleshoot the audit log without reading source code
  • Agents can route audit questions to the right guide and give accurate answers
  • The design doc is the single source of truth for how the system works
  • CLI help text accurately describes all audit subcommands
  • Troubleshooting recipes for every common failure mode

Not in scope

Phase 5 (extension sink API, alert rules, compliance templates, HMAC key rotation) is still unfiled and separate from documentation.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

9/10/2026, 6:00:00 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.