Audit logs 101: a developer's guide to tamper-evident audit trails

An audit log records significant actions so a team can later establish who did what, when, and to which resource. Developers use audit trails to investigate incidents, review administrative changes, support compliance work, and give customers visibility into activity in a product.

But a log is only useful as evidence if people can rely on its history. A row in an application database can be changed by someone with sufficient access. That does not make ordinary logging pointless; it means the record's location and integrity controls matter when others need to verify it.

This guide covers what to record, how to structure events, and what tamper-evident logging can, and cannot, prove.

What belongs in an audit log?

Audit logs focus on actions that change state, affect access, or carry operational or compliance significance. They are different from diagnostic logs, which help engineers understand system behaviour and troubleshoot failures. The two can share infrastructure, but they often need different access rules, retention periods, and levels of detail.

Common audit events include:

• Authentication and access: sign-ins, failed attempts, permission changes, and denied access.
• Data changes: creation, updates, deletion, restoration, and sensitive exports.
• Administrative actions: account lifecycle changes, configuration updates, and changes to keys or integrations.
• High-impact decisions: approvals, payments, policy overrides, and automated actions that affect a customer or resource.
• Audit-system activity: log exports, access to records, collection failures, and retention changes.

The OWASP Logging Cheat Sheet offers practical guidance on choosing events and protecting logged information. Start with actions that matter to a security review or investigation, rather than trying to record every detail of every request. For what SOC 2, ISO 27001 and PCI DSS each ask of the result, see our guide to audit log requirements.

Make each event understandable

An event should make sense to someone who did not write the code that produced it. Use structured, versioned data rather than a free-text sentence whose meaning may change between services.

A useful event answers:

• Who performed the action? Identify a human, service, or automated agent.
• What happened? Use a stable action name, such as member.role_changed.
• When did it happen? Record a UTC timestamp, and distinguish the time the event occurred from when it was received if delays are possible.
• Which resource was affected? Use a stable resource identifier.
• What was the outcome? Record success or failure and, where appropriate, a reason.
• How can it be correlated? Include a request, workflow, or trace identifier when available.

For example:

{
  "schema_version": "1",
  "occurred_at": "2026-10-29T14:22:31Z",
  "actor": "user:jmorton",
  "action": "member.role_changed",
  "resource": "team:acme/settings",
  "outcome": "success",
  "request_id": "req-84f2",
  "payload": {
    "member": "user:kpatel",
    "from_role": "editor",
    "to_role": "admin"
  }
}

Keep event payloads proportionate. A concise description of a change is often more useful, and safer, than copying an entire request or record into the log. Never include passwords, access tokens, private keys, or secrets. Treat audit data as sensitive: restrict who can read it, and consider logging access to the logs themselves.

What makes a log tamper-evident?

Tamper-evident means a later change to a record can be detected. It does not mean that changes are impossible.

A common mechanism is a hash chain. A system hashes an event together with the hash of the previous event. Each record is therefore linked to its predecessor. If someone edits an event, removes one from the middle, or changes the order, the chain no longer verifies from that point onward.

A chain needs a trusted reference point. If an administrator can rewrite the events and replace the final hash, a locally stored chain alone may not reveal the rewrite. Systems can strengthen the design by periodically sealing checkpoints outside the writer's control and signing them with a protected key.

In Sigilbase, each event is hashed with SHA-256 and linked to the previous event. Events are periodically sealed into Merkle checkpoints signed with Ed25519 keys. An exported evidence bundle can then be checked offline with the open-source verifier, without contacting Sigilbase.

That separation matters. If the party being audited alone holds the log and the means to rewrite it, an auditor must rely on that party's account of the history. Independent custody and offline verification give the reviewer a way to check whether the exported records match the sealed history. The mechanism, and the claims it does and does not support, are covered in more depth in tamper-evident audit logs: what they are, why they matter.

Design the collection path, not just the schema

A well-designed event can still be lost if the application fails between making a change and writing its audit record. Decide what should happen when the logging service is unavailable, and test that behaviour.

For important state changes, developers often use a transactional outbox: the application writes the business change and an event to the same database transaction, then a worker delivers the event to the audit service. This reduces the risk of recording one without the other. It does not eliminate the need to monitor delivery, retries, and gaps. The producer side, from idempotency keys to backoff and reconciliation, has its own guide: audit event ingestion best practices.

Also consider:

1. Emit events at the right boundary. Record actions where the application confirms authorisation and determines the outcome, not only in a user interface.
2. Use stable identities. Do not accept an unverified actor identity from a client request as proof of who acted.
3. Define failure behaviour. Some actions may need to stop if required evidence cannot be recorded; others may be buffered and retried. Make the choice explicit.
4. Monitor for missing events. Alert on collector silence, queue overflow, or unexpected sequence gaps.
5. Protect access and retention settings. Limit who can read, export, or change the handling of audit data.

The NIST Guide to Computer Security Log Management is a useful reference for planning log generation, transmission, storage, and review as an operational programme.

Verification is not the same as truth

A successful cryptographic verification supports a specific conclusion: the evidence checked against the relevant checkpoints has not been altered in a way the verifier detects. It does not prove that an event was accurate when it was first recorded, that the application captured every event it should have, or that a person's account of an action is truthful.

A hash chain also does not, by itself, prevent someone from deleting a whole unanchored tail of events. Checkpoints, independent custody, source monitoring, and clear expectations about the covered time range help address that risk. Verification results should be interpreted in that context.

These boundaries are important in compliance work too. Tamper-evident records can strengthen evidence, but they do not establish that an organisation meets a framework or replace an auditor's judgement. See how audit evidence can support SOC 2 reviews and what to consider when building customer-facing enterprise audit logs.

A practical starting checklist

Before shipping an audit trail, confirm that your team can answer:

• Which events are essential to record, and who owns that decision?
• Does each event identify an actor, action, time, resource, and outcome?
• Can events be linked to the relevant request or workflow?
• Are sensitive values excluded or appropriately protected?
• What happens if event delivery fails?
• Who can read, export, or change retention settings?
• Can a reviewer detect changes to exported evidence independently?
• What does a successful verification establish, and what remains unproven?

A useful audit log is clear enough to interpret and disciplined enough to verify. Start with the events your team needs to explain, make their structure consistent, and decide who should be able to change or verify the resulting record. When evidence must stand beyond your own database, tamper-evident design gives reviewers a way to check the history rather than simply trust an export.