Review the audit log

The audit log records every change made in the panel, by the scheduler or on a node: sign-ins, user and role changes, site changes, certificates and node actions. Each node chains its own entries by hash, so an edited or removed entry shows up when you verify.

Before you start

• Sign in as an Owner or Administrator. The Audit log entry under Logs in the sidebar needs the View audit log capability. Custom roles can hold it too.
• To change how long entries are kept you must be an Owner, because the setting lives on Settings.

Steps

Find an entry

1. Open Audit log in the sidebar. Entries are grouped by day, newest first, 100 per page.
2. Use the filters above the list.
   • The search box takes a domain, user name, action or anything recorded with an entry.
   • All actions narrows to one action. Each option shows how many entries it has.
   • The time list offers Any time, Last hour, Last 24 hours, Last 7 days and Last 30 days.
   • The row of segments filters by kind: All, Sites, Sign-ins & users, Certificates, System and Failed. Failed is the place to look for refused or errored actions.
3. Click an entry to open it. It shows when, who, the node (on a cluster), the action id, the result when it failed, and the entry number with a short hash. The recorded details follow.
4. Click Everything about <target> → or Everything by <user> → to see all entries for that site or person.
5. Click Older entries → at the bottom for the next page, and ← Newest to return.

Verify the chain

1. Click Verify chain at the top of the page.
2. Wait while the panel checks every entry on every node. On a large log it can take a moment.

A good result reads “Every chain checks out — no entry has been edited or removed.” with one line per node, such as intact · 1204 entries. A bad result reads “A chain did not verify — an entry was changed or removed outside a retention purge, or the check could not run.” and the failing node’s line starts with BROKEN.

From a shell on a node the same check is sudo hctl audit verify. Search is sudo hctl audit search -q <text>, with --action and --failed available, and sudo hctl audit --limit 20 prints the latest entries.

Export the log

1. Set the filters you want. The export follows them.
2. Click Export CSV. The browser downloads the file.

An export stops at 50,000 rows. Narrow the filter, for example to one time window, and export again for more.

Set how long entries are kept

1. Open Settings in the sidebar, then Access under Security.
2. In the Audit log group, find Audit log retention. The badge shows the current setting in days, or kept forever.
3. Enter Keep entries for in days. 0 keeps entries forever, which is the default. The form accepts 0 to 3650.
4. Click Save. The page shows “Audit log retention saved — the agent restarts in about 5 s.”

Before you shorten retention

Entries older than the number of days are deleted automatically by a purge that runs about once a minute, and deleted entries cannot be recovered. Click Export CSV first from Audit log with no filter and keep the file.

The purge re-anchors the hash chain at the oldest entry kept, so Verify chain still passes. This cannot be undone.

On a cluster, the setting you save is the master’s. Each worker keeps its own entries and purges them by the audit_retention_days key in its own /etc/hyperion/agent.toml, which keeps them forever unless it is set there.

Check that it worked

• A new action you take, such as saving a role, appears at the top of Audit log within moments.
• Verify chain reports intact for the master and every worker.
• After you change retention, the badge on Audit log retention shows <n> days or kept forever.

If it fails

• “No audit entries yet”: the log is empty, or retention removed everything.
• A banner names a node and says it “didn’t answer”: its entries are missing from the page. Check the node on Nodes. See Check the health of your nodes.
• A banner says a node “runs an older agent”: only that node’s newest 1000 entries are searched. Update the node to search all of its log.
• Verify chain shows “no answer: …” or “check failed: …” for a node: the panel could not ask that node. Test the connection first.
• Verify chain shows BROKEN: treat it as an incident. Export the log, then check who has shell or database access to that node.
• Export CSV stops short: you reached 50,000 rows. Narrow the filter.

Related

• Read your notifications