Audit Log & Log Forwarding

Every significant action in your instance is written to one audit log: sign-ins, permission changes, approvals, exports, scans and support sessions. Entries can only be added, never edited or deleted by a person, and each one is chained to the one before it so tampering can be detected.

What It Does

You read the log in System → System Logs. There you can filter it, ask for entries in plain English, export what you see for an auditor, and run a check that the log has not been altered. The list re-reads itself every 30 seconds and has a refresh button (the circular-arrow icon; hovering over it shows Refresh Logs) for a fresh reading straight away; it is not a live stream. You decide how long entries are kept under Security Settings → Audit Log Retention, and you can send every entry to your own monitoring system (a SIEM) under Security Settings → Log forwarding (SIEM).

If something here is not working as you expect, start with When something goes wrong.

Reading The Log

The log is served by the logging service through the gateway. Reading, exporting and verifying need view_logs. Request and response shapes for these routes are in the API Reference; the limits below are what that table does not state.

• Filters. The list and the export take the same filters: level, userEmail, includeActions, excludeActions, daysAgo, q (text in the details) and correlationId. On screen these are Severity, User, Actions, Exclude, Time Range and Search.
• Page size. A list request returns at most 500 entries however large limit is. The response echoes the limit and page it used, with total, counts and retentionDays.
• Export cap. An export holds the newest 50,000 matching entries at most. Two response headers say what you got: X-Export-Row-Count and X-Export-Truncated (1 when entries were left out). Narrow the time range and export again to get the rest. Every export is itself logged as AUDIT_LOG_EXPORTED, at warning level, with the filters used, the row count and whether it was cut off.
• Plain-English search. The Ask in plain English box sends the question to the local AI model (POST /api/v1/ai/parse-log-query, view_logs), which returns filters. The filters are then applied by the normal list request, so the model never reads the log.

Retention

The retention period is a setting, Security Settings → Audit Log Retention, between 90 and 3,650 days (ten years); it is 90 days until someone chooses. A value outside that range is refused, so retention can never be set below 90 days. The scheduled retention job is the only thing that removes entries; the DELETE route above exists only to refuse and record the attempt.

The Tamper-Evident Hash Chain

Every entry stores three chain values: chainSeq (its position), prevHash (the hash of the entry before it; empty only for the very first) and chainHash (its own hash). They are set by a database trigger when the row is inserted, not by application code. The trigger takes a lock first, so entries written at the same moment by different services are still linked one after another.

How One Hash Is Built

chainHash is the SHA-256, written as 64 lower-case hex characters, of eight values joined with the character |, in this order. A value that is missing counts as an empty string.

1. prevHash
2. id, as a decimal number
3. createdAt in UTC, written YYYY-MM-DDTHH:MM:SS.ffffff: six digits of fraction, no zone letter
4. level
5. action
6. details
7. userEmail
8. payload, as PostgreSQL prints a jsonb value as text

What The Verify Route Checks

• Content. Each entry’s stored chainHash must equal the hash recomputed from its own eight values. A failure is reported as brokenType: "content".
• Linkage. In chainSeq order, each entry’s prevHash must equal the chainHash of the entry before it. A failure is brokenType: "linkage"; it is what a removed or reordered entry causes.
• Anchor. The entry named by the latest anchor must still exist with the same hash. A failure is brokenType: "anchor".
• The answer also carries ok, chained, unchained (entries written before chaining existed, which are counted and not treated as a break), firstBrokenId and the anchor with a note saying whether an anchor file is confirmed to have left the server.

The Anchor

Once a day, at 02:30 by the logging service’s clock, the id and chainHash of the newest entry and the number of chained entries are recorded as an anchor. The same values are written to a small JSON file (anchorId, headId, headHash, rowCount, at) which is uploaded to your backup bucket under audit-anchors/, inside the prefix you set, when a backup destination is configured. It is encrypted like other backup objects when the backup key is set; open it with the decryptor under Recovery Tools. Each run writes AUDIT_CHAIN_ANCHORED to the log, as a warning while no anchor file has left the server. An anchor that exists only in the database protects against less: someone able to rewrite the whole chain in the database could rewrite the anchor row too. The copy in your bucket is the one they cannot reach.

Checking It Yourself

The JSON export (GET /api/v1/user-management/logs/export?format=json) returns every column of each entry, including chainSeq, prevHash and chainHash. The CSV export does not carry the chain columns. With a JSON export you can check the linkage, and compare an anchor file from your bucket against it, without trusting the instance. The export covers the last 30 days unless you pass daysAgo, and at most the newest 50,000 entries; the body’s truncated flag says when it was cut. To compare an older anchor, pass a daysAgo that reaches back to the anchor’s date, otherwise the entry it names is simply not in the export.

• What this proves. No entry between two neighbours in the export was removed or reordered, and, with an anchor file, that the chain still passes through the entry your bucket recorded on that day.
• Recomputing a hash outside the database needs two things an export does not give exactly. The export prints createdAt to the millisecond, while the hash uses six digits; entries written by the application have three trailing zeros, entries written by host maintenance scripts may not. And payload must be in PostgreSQL’s own jsonb text form: keys ordered by length and then by byte value, "key": value with one space after each colon and comma, numbers as the database stored them. The verify route recomputes every hash inside the database with the stored values, so use it for the content check.
• What a forwarded event carries. id, seq and chainHash, but not prevHash, and its details and payload are scrubbed copies. A SIEM can therefore spot a missing seq and can later compare a chainHash it holds with the one in an export, but it cannot recompute a hash.
• Retention. When old entries are removed by the retention job, the oldest entry left keeps a prevHash that points at an entry no longer present. The linkage check starts from the oldest entry present, so this is not reported as a break.

Audit Action Catalogue

The action field of an entry is a fixed name such as LOGIN_FAILURE. This is the list to write SIEM rules from: 888 action names in 14 groups, one group per part of the product that writes them, each with the level or levels it is written at (897 rows in all, as a few names are written by two parts and appear in both groups). It is generated from app commit 99e5035a2 by reading the 1,058 places the code writes an entry, and is not edited by hand.

• Level received. The level shown is the one that is stored, and so the one forwarded. Code that writes warn is stored as warning, and code that writes critical is stored as error; the list marks the second kind as “written as critical”, because those are the events the code itself ranks highest. More than one level on a row means the action is written at each of them, depending on the outcome, and “chosen at run time” means the code does not fix it.
• Logs filter family. The family the entry falls under in the Actions and Exclude filters on System Logs (Sign-ins (all), Failed sign-ins, MFA, Users, Permissions & roles, Denied / blocked, Elevation (sudo), Workflows, Automations, Sync, Finance, Signatures, Compliance, Audit, Licensing). A family is a set of name fragments, so one action can be in several, and many are in none.
• Names built at run time. 14 names contain a part that is filled in when the entry is written, such as the provider type in SYNC_<type>_FAILED. They are listed under their group with the variable part in angle brackets; match them by prefix. A further 2 places write a name they are handed at run time, so a name that only they write is not in this list.
• Unknown names. The list is what this release writes from fixed names. Write rules that let an unlisted action through to review, not ones that drop it.

Log Forwarding

Forwarding streams each audit entry to up to 10 destinations. Managing destinations needs the administrator role, and the routes are listed under Log forwarding in the API Reference. Every destination receives the same event; only the envelope differs. The action names an event can carry are listed in the Audit Action Catalogue above.

The Event

One event is at most 64 KB. A larger one is not cut in the middle: its payload is replaced by { omitted: true, reason }, and the full row stays in System Logs and the export. The test event has id: 0, the action LOG_FORWARD_TEST and payload: { test: true }.

The Log Line, Per Destination Type

In the examples below, <event> stands for one event exactly as in the table above, with its keys in that order. The values are examples.

The collector’s certificate is always verified for syslog, against the public roots or the CA certificate you pasted. Syslog has no application-level acknowledgement, so “delivered” means written to a verified TLS session.

The Webhook Signature

A complete receiver in Node.js and in Python is on Webhooks: Verifying A Signed Delivery From Your Instance. Answer a bad signature with 401, not 400: a 401 is retried, while a 400 is read as the events being refused.

Batching, Retries And Skips

• Batches. Up to 200 events or 1 MB per request, whichever comes first, and up to 25 requests or 20 seconds of work per destination on each pass. Each request times out after 15 seconds.
• Retried without limit. A network or TLS failure, 401, 403, 404, 408, 429, any 5xx and any redirect (redirects are not followed). The destination keeps its place and waits 5 seconds, then 10, then 20, doubling up to 5 minutes, each wait varied by up to 20 percent. Nothing is dropped while it waits.
• Rejected. Any other 4xx (for example 400, 413 or 422) means the receiver refused the content. A batch of several events is halved and retried at once to find the event at fault. A single event rejected 3 times in a row is skipped so the rest can flow: it stays in the audit log, and the skip is recorded as LOG_FORWARD_EVENT_SKIPPED.
• At least once. A batch that was received but not acknowledged is sent again, so a receiver can see the same event twice. De-duplicate on id.