The audit trail as evidence

The audit log says who did what, to which workspace, and when. This page is about what makes that answer something an auditor can rely on: it is never silently incomplete, an edit made outside Madebook is detectable, and an organization can hold its own copy.

Organization → Audit has four tabs: the log, Integrity, Streaming and Exports.

Writes that cannot be lost quietly

Recording an audit event never fails the action it records — but a failed write used to be a silent gap. Now, when the database refuses an event, the event is appended to a durable spool file on the server's disk and fsynced before the call returns. A background job replays the spool every minute. The replayed entry keeps the time the thing happened and records when it was recovered.

Only if the spool cannot be written either — a full or read-only disk — is an event lost, and that count is shown on Integrity and in readiness. Operators: the spool must live on a persistent volume (MADEBOOK_AUDIT_SPOOL).

Seals: tamper evidence

Every minute, settled events (at least five minutes old) are sealed per organization into a SHA-256 hash chain: each seal covers its range of events, their count, and the previous seal's hash. Changing, removing or inserting an event, or rewriting a seal to match, breaks verification from that point on.

Integrity re-verifies on demand and names the first problem: an edited, removed or inserted event, or a rewritten seal. Seals travel in every stream and every export — which is what puts a copy of the chain outside this database.

The log is not claimed to be immutable. It is claimed to be tamper-evident, and that claim can be checked.

Streaming

Streaming delivers events and seals, in order and at least once, to:

Destination	Format
An HTTPS endpoint	JSON batches signed with X-Madebook-Signature: sha256=HMAC-SHA256(secret, raw body), plus X-Madebook-Delivery per batch. De-duplicate on the event id.
Splunk HTTP Event Collector	One event per line, sourcetype=madebook:audit (seals madebook:audit:seal), Authorization: Splunk <token>.

A destination that fails is retried with backoff — one minute, doubling, at most an hour — and receives what it missed when it returns. Redact personal data sends account ids but not IP addresses, user agents or email addresses.

Destinations must be HTTPS. Private addresses are refused unless the operator listed them in MADEBOOK_PRIVATE_HOSTS, and redirects are never followed.

Signed exports

Exports builds, in the background:

• the whole record of an organization;
• an evidence package for one pull request (from its page) or one mission (from its Evidence tab).

A package holds what changed and the requirement behind it; the rules in force (the approval policy version, the policies that fired, the enforcement reading); every CI result and approval with its standing; the exceptions and every compliance verdict; the audit entries about all of it and the seal chain; and a summary part answering the six questions in plain words.

Every part is hashed and the manifest is signed with Ed25519. The file is kept in the organization's own storage at Bookbag for seven days, then deleted. Downloads go through Madebook, which checks the file against its recorded hash before serving it.

To verify a file with nothing but the file:

node scripts/verify-export.mjs export.json --keys https://<madebook>/api/governance/api/exports/keys

The public keys are served without a session. Save a copy and you do not need Madebook to verify again. Keys are never deleted, so old exports still verify after a rotation.

This replaces the synchronous one-file export that used to sit on the Governance settings tab.

Who can do what

	Owner / admin	Member / viewer
Read the log, Integrity, Streaming, Exports	yes	no
Add, change or remove a stream	yes	no
Request or download an export	yes	no

Related

• The audit log
• The compliance check
• Operational readiness
• The governance journey