Reliable multi-tenant auto setup audit capability
tegwick
b098fb12ca
The detection half audit-core argued up to a MUST and then could not support. Two registered sources were waiting on it. T04, heartbeats. A heartbeat is an ordinary event — same envelope, same append-only custody, same chain, no special table. Deliberate: a heartbeat stored outside the chain would be the one record here that could be back-dated. Declared per class rather than per source, because a per-source heartbeat from a mixed-volume emitter is satisfied by its chattiest class and says nothing about the quiet, security-relevant one, which is the only reason heartbeats exist. Not the §17 cadence schema T05 waits on: cadence describes expected rate, this says how often a source promises to say "nothing to report" for a class that may legitimately be silent. no_heartbeat_since_registration is its own finding kind rather than a skip — it is the case most likely to be a broken integration and the one a naive "compare against last seen" implementation silently drops. Grace widens the window so one late run does not flap; it never removes a finding. T06, reconciliation. Counts, never payloads. The awkward part is that every registered sender holds may_read: false, which taken literally makes the §9.6 reconciliation obligation undischargeable by every source actually registered. Resolved by observing that a source asking how many of its own events we hold is not reading the archive — it learns nothing it did not itself emit. So the surface is scoped to the caller's own sources and tenants and returns no payloads; anything wider stays behind may_read and full tenant scope. Another source's counts return 403 rather than an empty count, because a zero would read as "we hold none of yours" — a false answer to a question about completeness. No default window, since a count whose bounds the caller did not choose is not comparable to anything the caller computed. T07, the findings surface. /v1/stream-findings, following the dead-letter and secret-finding conventions: may_read plus full tenant scope, since findings span every sender and carry no tenant key to filter on. The bound is on every response rather than in a document nobody opens beside it. A missing heartbeat is not proof of suppression, and agreement on counts proves neither completeness nor that any event occurred. Both controls cover loss, outage, drain failure and accident; neither covers a source lying about itself, and where the emitter is compromised both agree with it. Closing that needs an observer independent of the emitter, which §16 put outside our scope. The scope overlay may shorten a heartbeat interval or add a class, never lengthen or remove one — same asymmetry as evidence_kind, and for the same reason: a ConfigMap refresh must not widen the window in which a suppressed class goes unnoticed without anyone deciding to. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Nb7Q6ZmXppNDkTWytfYqfv Assistant: claude-code Assistant-Model: opus Assistant-Process: 2069992@bnt-lap001 Assistant-Session: 167dd7f8-2a25-4be1-aa46-3b6f1a5f94c6 |
||
|---|---|---|
| .claude/rules | ||
| .forgejo/workflows | ||
| .repo-manager | ||
| audit_core | ||
| data/capability | ||
| deploy | ||
| docs | ||
| evidence | ||
| history | ||
| intakes | ||
| registry | ||
| scripts | ||
| spec | ||
| tests | ||
| workplans | ||
| .custodian-brief.md | ||
| .dockerignore | ||
| .gitignore | ||
| .repo-classification.yaml | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| Containerfile | ||
| INTENT.md | ||
| layer.yaml | ||
| LICENSE | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
| SCOPE.md | ||
| TamqMessagingIntroduction.md | ||
| tenancy.yaml | ||
| WORK-RECORDS.md | ||
Reliable multi-tenant auto setup audit capability
Production on railiance01 (AUDIT-WP-0005): PostgreSQL custody, digest-pinned
image, operator procedures in
docs/operator-runbook.md. Manifests live in
deploy/.
Backend contract
The pluggable backend interface, event schema (audit-core.event.v1alpha1),
retention policy, and migration path from the mock file backend are documented
in docs/audit-backend-contract.md.
Development Mock Backend
The first implementation is intentionally tiny: a replaceable audit interface with a mock file backend.
By default it writes JSONL audit events to:
/tmp/audit-core/audit-YYYYMMDDTHH.jsonl
Files older than 7 days are removed when the backend writes or when cleanup is run explicitly. This backend is for local integration and bootstrap wiring. It is not durable audit custody.
Example:
python3 -m audit_core emit \
--source openbao \
--action openbao.authenticated_readiness_proof \
--resource openbao/openbao-0 \
--outcome success \
--detail file_audit_visible=true \
--detail backend=mock-file
Cleanup:
python3 -m audit_core cleanup
Make targets:
make test
make mock-audit-smoke
make mock-audit-cleanup
Environment:
AUDIT_CORE_MOCK_DIR: override the output directory.AUDIT_CORE_MOCK_RETENTION_DAYS: override the default 7-day cleanup window.