What it does
A log of administrative and governance events that is written by appending and never edited in place. Each entry is chained to the one before it with an HMAC under a server-held key, and the head of the chain is witnessed in two other places, so editing, reordering, deleting or truncating entries is detected by a verification pass. Entries can be browsed, filtered and verified over HTTP.
How it works
Events are appended as JSON lines to audit.log in the data directory. Each line holds a sequence number, a timestamp, an actor, an action, a target, a metadata object, the previous hash, the key epoch and its own hash, which is HMAC-SHA-256 over the previous hash and the canonical record. After every append the new head is saved in two further places: a checkpoint record in the engine and a small anchor file written by atomic rename. Verification recomputes the whole chain and compares the result with both, which is how it catches truncation that a walk of the file alone would miss.
The chain key comes from KYNETRA_AUDIT_HMAC_KEY (hex, at least 32 bytes) or, failing that, is generated once and stored in the engine. A server bound beyond loopback refuses to start for the first time without a supplied or stored key, so it does not mint a chain that nobody can recover. A replica keeps its own chain in its own log.
Events include token, role and binding changes, user and password changes, two-factor activation and resets, project export and purge, webhook, provider and residency-policy changes, organisation security updates, and purpose-denied writes. Ordinary reads and writes of application data are not logged one by one. A second trail of compliance events (two-factor activation, user administration, GDPR erasure and DPDP actions) is stored as ordinary records in the engine. It is not chained, and the generic write routes refuse to alter it.
GET /admin/v1/audit/logs (platform administrators) and GET /admin/audit (admin role) page through entries newest first, filter by actor and action, and take a limit of 1 to 200 with an opaque cursor. A request inspects at most 1,000 entries or one mebibyte rather than the whole file, and secret-shaped values in the response copy are redacted without touching the stored records. The response carries the cached verification status. GET /admin/audit/verify runs the full verification and returns the entry count or the failure.
Where you reach it
- HTTP
GET /admin/v1/audit/logs?actor=&action=&limit=&cursor= - HTTP
GET /admin/audit - HTTP
GET /admin/audit/verify - Config
KYNETRA_AUDIT_HMAC_KEY
Example
# Newest first, filtered to one action
curl -s "$KYNETRA_URL/admin/v1/audit/logs?action=token.create&limit=20" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# Recompute the whole chain and check both witnesses
curl -s "$KYNETRA_URL/admin/audit/verify" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# {"ok": true, "count": 1234} or {"ok": false, "error": "..."}Limits
- The log is tamper-evident, not tamper-proof. Verification needs the key, so the server or a holder of the key checks the chain. When the key is stored in the engine, whoever can rewrite the data directory can also read it. Supply KYNETRA_AUDIT_HMAC_KEY from a secret manager to keep the key apart from the log.
- Audit writes are not part of the action's own transaction. If an append fails, the failure is logged and the action itself proceeds.
- Not every control-plane change is in the chain. Project key rotation and organisation membership changes are not recorded in it, and a few events, such as organisation security and billing updates, are recorded under a generic actor name.
- Operators cannot rotate the chain key in this release; see the audit-log key rotation page.
- There is no automated truncation or archival. Entries are kept in full.
- Each node keeps its own chain, so there is no merged view across a primary and its replicas.
Evidence
- On this siteSecurity overview
- Tests64 audit-log tests (tampering, reordering, deletion, tail truncation, wrong key, torn tail, fail-closed key and checkpoint loading, bounded browsing, replica chains) and 18 mounted-route tests that keep the key and checkpoint records unreadable and unwritable through the generic routes
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.