Audit & SIEM
HMAC-chained audit log, RFC 5424 syslog forwarding, 30-day retention with SIEM export, and an owner-only chain-verification API.
What gets audited
Every state-changing API call, every job phase transition, every login, every approval decision. KEK lifecycle operations are the exception — they run from the CLI, never touch the audit log, and so are never forwarded to syslog; the operator who started a rotation is recorded on the rotation record itself and shown in the By column of Settings → KEK Versions. Reads are not audited as a rule, and there is no setting to enable it — a GET is recorded only when the handler itself names an audit action, and only the reads listed here do. So state-changing requests are recorded — plus the few read-only calls that decrypt a credential and dial one of your systems (target / module health checks, credential tests, and the live pickers' MODULE_BROWSE listings, recorded with the target, credential and listing kind — and, for a listing from an unsaved connection, the address it was sent to (spec_address)), because who dialed what with which credential is an audit question even when nothing changed — and the three reads that hand data out of the system: the certificate export (CERTIFICATES_EXPORTED), the audit export (AUDIT_LOG_EXPORTED) and a certificate download (CERTIFICATE_DOWNLOADED, with the format and whether the private key was included; an approved download redeemed by one-time token is recorded the same way, attributed to the project and carrying the approval request id) — and an owner's runtime profile read (DEBUG_PROFILE_READ, with the profile name).
A state-changing request from a signed-in user that is refused before its handler runs — the role or CSRF check (HTTP 403) or a rate limit (429) — is audited too, under the route's own action name, with metadata.outcome = "failed", metadata.rejection = forbidden / rate_limited, the HTTP status, and the targeted resource id taken from the path. Requests with no valid login (HTTP 401, or a rate limit hit before sign-in) are deliberately not audited, so an anonymous client cannot flood the log; failed sign-ins are recorded by the login itself as AUTH_LOGIN_FAILED. A request whose handler crashed is still recorded, always with outcome: failed and metadata.panic = true; its status is 500, unless the handler had already sent a response — then it is the status the client actually received, and a request whose client disconnected after the change was made is recorded all the same. Any request that ends with HTTP 400 or higher carries outcome: failed, and syslog (RFC 5424 / CEF / LEEF) and the CSV export report such an entry as a failure whatever its action name — a rate-limited DISTRIBUTION_EXECUTED executed nothing. The JSON export adds action_name to entries older releases stored under a raw METHOD /api/v1/… route; the stored action itself is never rewritten (the HMAC chain covers it).
Pre-authentication events — a failed login, a login awaiting its second factor, a refused token refresh, a refresh-token reuse detection — carry no authenticated organization in the request. They are attributed to the default organization, so they appear in the organization's audit list and export like every other entry.
CA-connector connections are audited like AD CS connections: CA_CONNECTION_CREATED, CA_CONNECTION_UPDATED, CA_CONNECTION_DELETED, CA_CONNECTION_TESTED and CA_CONNECTION_CSR_GENERATED (a new mTLS client key and CSR were made), with the vendor credential and client key never written to the trail (only a masked hint).
HMAC chain
Each audit entry, as the API returns it, includes:
{
"id": "65f1a...",
"timestamp": "2026-04-28T10:42:11.443Z",
"actor_name": "alex@example.com",
"action": "CERT_ISSUED", // a manual-DNS certificate: written by the validation job when the certificate is stored (CERT_ISSUED_FAILED when the CA refuses the records)
"resource_type": "certificate",
"resource_id": "65f0...",
"old_value": { ... },
"new_value": { ... },
"seq": 4182,
"checksum": "ce42..."
}
The entry also stores prev_checksum (the previous entry's checksum), prev_timestamp (when the
entry numbered seq − 1 was written) and the formula version. These are kept in the database for
verification only; the API and the exports never return them.
checksum = HMAC-SHA-256(audit_secret, prev_checksum || id || timestamp || action || resource_type || seq || content_digest).
content_digest is the SHA-256 of every other stored fact of the entry in a fixed, length-prefixed
order: organization, project, actor id, actor name, actor IP, resource id, old_value, new_value,
changes, metadata and prev_timestamp — when the entry numbered seq − 1 was written. So the signature covers who did what to which resource, where,
when, with which values — plus the entry's position seq and the previous entry's checksum.
Reordering, deleting, renumbering or altering any of it (rewriting the actor of a record, changing a
stored value) breaks the chain at that entry and every entry afterwards. The only unsigned fields are
the syslog forwarding state, which the forwarder itself rewrites.
Entries written by releases before 1.7.0 were signed over the identity fields only (id, timestamp, action, resource type and the anchor); they keep verifying under that formula until they age out of retention, but a change to their actor or values is not detectable.
seq is the entry's position in the organization's chain: 1, 2, 3 … with no gaps, unique per
organization (a database index enforces it). Two requests audited at the same moment cannot both take
the same position — the one that loses re-reads the chain head and signs again — so the chain is one
sequence, never a fork, and verification is exact: a missing number inside the retention window means
an entry was deleted. Entries written by releases before 1.7.0 carry no seq; they are numbered once,
in timestamp order, when the upgraded instance starts (or on the first new entry or verification), and
keep verifying under the older formula. The numbering runs when each instance starts and once an hour
afterwards, and before an organization's first new entry on that instance; verification numbers them too.
Retention and the chain. Entries are deleted after 30 days by their timestamp, while the chain is
ordered by seq. The two usually agree, but an entry written by an older node during a rolling upgrade is
numbered after the chain head with an older timestamp — so retention can remove it from inside the
sequence. That is why every numbered entry stores and signs prev_timestamp: when the entry before it is
missing but its prev_timestamp says that predecessor was already past retention, the hole is retention,
not a deletion, and it is not reported. A missing entry whose predecessor was recent is reported
(missing_predecessor).
What the chain does not detect. Removing the newest entries (cutting the tail) or deleting the whole log leaves a chain that still verifies: there is no external commitment of the chain head, so nothing inside the database can say that more entries existed. If that matters to you, forward every entry to a SIEM as it is written (syslog) or export the log regularly (export) and compare.
The audit_secret is audit.signing_key when set, otherwise the JWT secret. Using a dedicated
audit.signing_key separates the two trust domains so a JWT-forger cannot also forge the chain.
Setting or changing audit.signing_key invalidates verification of entries written under the
previous key (they will report as breaks until they age out of retention). To decouple the audit
chain from the JWT secret without breaking verification, first set audit.signing_key to your
current jwt.secret, then rotate the JWT secret.
Verifying the chain
POST /api/v1/audit-logs/verify (Owner role, rate-limited to one request per minute; optional
?since=<RFC3339>, ?from_seq=<n> and ?limit= query parameters — from_seq and limit must be positive
integers, 400 otherwise; limit is capped at 1000) walks the chain in seq order and
returns { "verified": N, "intact": true|false, "breaks": [...], "next_seq": n, "next_since": "..." } —
call it again with from_seq=<next_seq> to continue through a long history (next_since is kept for
older clients). Each break names its seq and a reason: checksum_mismatch (the entry was altered,
or signed with another key), anchor_mismatch (it does not chain on its predecessor) or
missing_predecessor (the entry before it was deleted inside the retention window; the oldest entries
ageing out under the 30-day retention are not a break, and neither is an older-timestamped entry that
retention removed from inside the sequence — its successor's signed prev_timestamp tells the two apart).
since means "start at the first entry written at or after that time"; from there the walk continues
by position (seq), not by timestamp, so entries numbered out of timestamp order (written by an older
node during a rolling upgrade) are checked, not skipped. A break = either a bug or a tamper attempt —
investigate either way. Remember what verification cannot see: a truncated tail or a deleted log (see
HMAC chain).
An instance still on a release before 1.7.0 writes entries without seq. They are numbered after the
chain head when a 1.7.0 instance next appends or verifies, and only their own signature is checked —
no false break — so finish the upgrade before relying on the exact deletion check.
Entries written by releases before 1.5.45 were signed with a higher timestamp precision than the database stores, so they always report as breaks; they age out with the audit retention window (30 days). Entries written from 1.5.45 onward verify correctly, including the oldest surviving entry after retention has deleted its predecessor.
Syslog forwarding
Forward to a SIEM in real-time over syslog, encoded as RFC 5424, CEF (ArcSight/Splunk), or LEEF (IBM QRadar). Transports: UDP, TCP, TCP-with-TLS (TLS ≥ 1.2, custom CA and optional mTLS supported). See Syslog forwarding for the format details.
Settings → Syslog
Destination: siem.example.com:6514
Transport: TCP+TLS
TLS trust: <paste root>
One forwarder per organisation. Delivery is durable: events are queued in MongoDB before send, so a SIEM outage doesn't lose events — the queue drains with backoff once the SIEM is reachable again.
Full field mapping, settings reference, and troubleshooting: Syslog forwarding.
Who can read it
- The organization-wide log (list, entry and export) needs the organization admin or owner role; chain verification needs owner.
- A project's log can be read by any member of the project (viewer and up), and by organization-wide roles.
- A user limited to granted resources sees, in the project log, its own entries and entries about resources it can see; entries about users, groups, grant changes, the project and its policies made by others are hidden — in the list, an opened entry and the export. See what a restricted user sees.
Retention
Audit entries are kept for 30 days — a MongoDB TTL index on the audit collection deletes older entries automatically. For longer regulatory windows, forward to a SIEM (syslog) and/or run periodic exports; the SIEM becomes the long-term store.
Storage
Audit entries live in their own MongoDB collection with a 30-day TTL index. Sized for ~1 KB per entry.
Export
Bulk export for legal-hold or DR goes through the API — there is no certautopilot audit CLI command:
# org-wide (admin)
GET /api/v1/audit-logs/export?since=2026-01-01T00:00:00Z&until=2026-12-31T23:59:59Z
# one project
GET /api/v1/projects/{projectId}/audit-logs/export?since=...&until=...
since and until are RFC3339; a malformed value returns 400. The export also takes the list filters: action_prefix (repeatable, at most 20; upper-case letters, digits and _), actor (part of the actor name, any case, at most 64 characters), resource_type and resource_id (exact). The export holds at most 10,000 entries, newest first — narrow the range or the filters for more. The JSON form carries each entry's seq and checksum, the CSV form only id, time, actor, IP, action, resource and outcome; neither carries prev_checksum or the audit secret, so the chain cannot be re-verified offline — use the verification API (or forward to a SIEM).
Every export is itself an audit event (AUDIT_LOG_EXPORTED, with the format), as is a certificate inventory export (CERTIFICATES_EXPORTED). In the CSV form, any cell that starts with =, +, -, @, a tab or a carriage return is prefixed with an apostrophe so a spreadsheet reads it as text rather than a formula — the actor_name of a failed login is whatever the caller typed, and a certificate name or owner is free text.
Downloads. A certificate download records its format, whether the payload includes_private_key (PEM bundle, key, all, PFX, JKS, DER) and, for a PFX with a caller-supplied password, has_custom_password (never the password). A download by approved one-time token is recorded as CERTIFICATE_DOWNLOADED with via: approval_download_token, the approval request id, the format the request asked for and whether it includes_private_key — it is a GET, and GETs are otherwise not audited.
See also
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →