Audit & syslog

Taranac keeps an immutable audit trail of every administrative change — who did what, to which object, from which IP, and when — and can forward both that trail and the live AAA logs (TACACS+, RADIUS, NAC) to an external syslog server or SIEM. Together these cover the two questions every audit asks: what happened inside the admin console and can we prove it to an external, tamper-resistant system.

The audit log answers the first question on its own and is always on — there is nothing to enable. Syslog forwarding answers the second: you point Taranac at a collector (Splunk, Elastic, Graylog, rsyslog, QRadar, etc.) and choose which event streams it should ship.

Every state change in Taranac calls into a single audit service, which writes one immutable row and then (fire-and-forget) hands the event to syslog forwarding. Each entry records:

• Event type — one of 312 codes as of 1.2.8, and the catalogue grows with almost every release. They are grouped by domain: user lifecycle, groups, RBAC, authentication, MFA, crypto/settings, licensing, LDAP config and sync, the Active Directory domain join, network objects, devices, TACACS+/RADIUS templates / profiles / command sets / config, AAA policy, log exclusions and syslog, NAC (endpoints, classification, policy, PKI and EST enrolment, captive portal), Reports and datasets, Configuration Tracker inventory / credentials / collection runs, cluster and HA operations, backups, workers, log rotation, and secret reveals. The full list is deliberately not reproduced here — it is long, it changes every release, and the log’s own filter and search are the authoritative index.
• Actor — username snapshot plus user ID; empty for automatic/system events.
• Target — type and ID of the affected object, plus a target username snapshot where the target is a user. The viewer shows it under the target type, and the search box matches it.
• IP address and user agent of the request.
• Details — an event-specific JSON payload. For updates this typically records what changed as old → new field diffs, so a row is self-explanatory without cross-referencing. It also carries the discriminator that makes an ambiguous event readable: a USER_LOGIN_FAILED row, for instance, carries a reason, and web_login_denied there means the credentials were right but the account’s group is barred from the web console — not a bad password.
• Node — on an HA cluster, the node that wrote the entry, stamped best-effort. It is left blank on a standalone install (and for events written before the cluster resolver is available at early boot). Surfaced as a Node column in the audit viewer, with a matching node filter that appears only once a cluster has more than one node. Since 1.2.8 the LDAP directory sync runs on the leader only, so a scheduled sync writes one set of LDAP_SYNC_* rows per cluster instead of one per node — an N-node cluster no longer multiplies that traffic by N.
• Timestamp — server time, timezone-aware.

The actor and target are stored as snapshots: even if you later rename or delete the user or object, the audit row still shows who and what it was at the time.

The Activity Log view offers filters on event type, target type, a date range (from / to), and — on a multi-node cluster only — node, plus a free-text search across actor, target username, event type, target type and IP. The API accepts two more that the filter bar does not set: actor ID and target ID. Default sort is newest first (created_at descending); you can also sort by event type, actor, target type or target username.

The Event Type dropdown is a curated list of the ~90 most common codes, not all 312. An event that is not on it is still recorded and still shown in the table — rendered as its raw code, e.g. GROUP_WEB_LOGIN_MODE_CHANGED (new in 1.2.8) or MFA_PUSH_EXPIRED (new in 1.2.0) — but you reach it through the search box or the API rather than the menu. The search matches event-type substrings, which is what you want for a class of events: SECRET_REVEALED finds every reveal, _DELETED every deletion. The dropdown filter, by contrast, is an exact match on one code.

You can export to XLSX or CSV, and the two scopes in the drawer are not two sizes of the same thing:

• Current view exports exactly what is on screen — the current page (at most 100 rows), with the active filters, search and sort applied. The drawer lists them as badges so there is no doubt what is being exported.
• All entries sends no filters at all — not the date range, not the event type, not even the sort. You get the newest 10,000 rows of the whole log.

The export columns are: ID, Time, Event Type, Actor, Target Type, Target ID, IP Address, User Agent, Details. The Node attribution and the target-username snapshot are in the viewer and the API, but not in the export file.

Audit rows are not partitioned like the AAA logs; they are deleted row by row, by date. A job runs daily at 03:00 and removes everything older than audit_log.retention_days — default 365. A value of 0 or less disables deletion entirely.

Optionally the rows about to go are archived first: turn on audit_log.archive_enabled and set audit_log.archive_path (default /data/audit-archive), and each run writes an audit_archive_<timestamp>.jsonl file carrying every field — details included — before the delete runs.

Both live under Settings → System → Log Rotation, where the audit log appears in the Security group with a row delete mechanism rather than a partition count, and the archive toggle and path have their own Audit log archive card. Editing either needs settings.edit.

The purge audits itself. Every run writes an AUDIT_RETENTION_PURGE row — a system event, so no actor — recording how many rows were deleted, the cutoff timestamp, and the archive path if one was written. A run that deleted nothing still writes it. A gap at the old end of the trail therefore has a row in the trail explaining it.

Forwarding is built around three objects — destination (where), binding (what), exclusion (what to suppress) — feeding two independent delivery paths.

Both paths use the same formatter and sender, so everything looks identical on the wire. Path B exists because the AAA daemons write their logs straight into the database; the backend owns those tables and is the natural place to forward from. (Notably, the bundled FreeRADIUS cannot send to a remote syslog itself, so doing it in the backend gives one consistent mechanism across all three protocols.)

Path B’s window has an upper bound that moves with the wall clock and a cursor that does not, so after any downtime the untouched range is exactly as wide as the outage. Until 1.2.2 that whole range was loaded in one query and fanned out in one burst — one message per record per destination. On a large estate that is not a slow catch-up but a second outage, arriving at the moment the system comes back.

Since 1.2.2 a pass reads at most syslog.forward_max_rows_per_run rows per source log table, default 5,000. It is an ordinary system setting, and it is clamped when read to the band 100–100,000 — so a mistyped value can neither stall the forwarder (0 or negative) nor restore the unbounded behaviour. Raise it to catch up faster after downtime; lower it if the receivers are slow.

When a pass stops at the ceiling:

• the cursor is advanced to the last row actually read, never to the window’s far edge, so the tail of a truncated window is not silently discarded;
• the position is a keyset over (timestamp, id), so a batch of rows sharing one timestamp resumes inside the group instead of skipping its remainder forever;
• the job starts the next pass immediately rather than waiting out its interval, up to 4 passes per 20-second tick. Whatever is still queued waits for the next tick, and the service log says so.

A backlog is therefore drained steadily over several passes instead of all at once, and nothing in it is skipped.

Delivery, though, is deliberately decoupled from the cursor — and this is the part to plan for. The cursor is one per source table and shared by every destination, so blocking it on delivery would let a single dead SIEM stall the stream for all the others and then flood the healthy ones on recovery. Instead the cursor always advances: nothing is queued and nothing is retried. What a destination did not take is gone. A destination that fails 5 sends in a row has the remainder of that batch abandoned rather than costing a 10-second TCP timeout per remaining message — those records are still counted as lost.

The loss is made visible rather than hidden. Each destination row carries its own delivery state, updated once per pass:

Any shortfall is also written to the service log as a WARNING naming the destination and the count. Destinations are tallied independently, so an unreachable receiver cannot make a healthy one’s numbers look worse.

Under Settings → Integrations → Syslog, add a destination and set:

Use Test on the destination to send a probe message and confirm the collector receives it before relying on it.

A destination is silent until you bind streams to it. Each binding picks a module and a log type; valid combinations:

Each binding can optionally override the destination’s facility or severity, which is handy for routing one stream to a different SIEM index. A binding is unique per (destination, module, log type).

Log exclusions suppress chatty AAA events (a polling monitor hitting a switch every minute, a service account, an entire subnet). An exclusion matches on who (exact username, username regex, or user group), where (any NAS, a specific network object, or a device group), scope (all / tacacs / radius) and which event types (authentication / authorization / accounting). It then has three independent output toggles:

These toggles are independent — you can keep events in the database for forensics yet stop them flooding the SIEM. The on-disk file backup of AAA logs is always written regardless of exclusions, so suppressing syslog never means losing the forensic copy.

The PRI value is computed the usual way: facility * 8 + severity. Severity is chosen automatically per event:

• Audit events map by type, from three fixed lists. Six failure events (USER_LOGIN_FAILED, PASSWORD_RESET_FAILED, EMAIL_FAILED, the TACACS+ and RADIUS reload failures, LDAP_SYNC_FAILED) → err. Fifteen security-significant events (USER_DELETED, GROUP_DELETED, RBAC_MODEL_DELETED, LDAP_CONFIG_DELETED, USER_LOCKED, MFA_DISABLED, MFA_RESET, KEY_ROTATED, USER_PASSWORD_RESET_BY_ADMIN, LDAP_USER_DEACTIVATED, LDAP_GROUP_REMOVED, and the device, device-group, TACACS+-settings and RADIUS-settings secret reveals) → warning. Thirteen operational events (logins, logout, new-IP login, the three config reloads, LDAP sync start/finish, data import/export, worker pause/resume/interval change) → notice. Everything else → info.
• AAA events — authentication failures/rejects and authorization denies → warning; accounting is always info.

A destination’s or binding’s facility/severity override takes precedence over these defaults.

A single line, control characters stripped:

<PRI>Mmm dd HH:MM:SS hostname taranac: event=USER_DELETED actor=admin target_type=user src=10.0.0.5

Includes a structured-data block your SIEM can parse without regex:

<PRI>1 2026-06-24T12:34:56.000000Z hostname taranac - USER_DELETED [taranac eventType="USER_DELETED" actor="admin" targetType="user" targetId="…" src="10.0.0.5" details="{…}"] event=USER_DELETED actor=admin target_type=user src=10.0.0.5

For AAA records the structured data carries protocol, log type, and the relevant fields (username, NAS IP/port, status/action, service, command, rule, profile, session ID). Audit details are serialized as compact JSON and truncated to ~1 KB to keep messages within syslog limits.

Choose CEF to emit events in Common Event Format, wrapped in a syslog envelope — the dialect ArcSight, Microsoft Sentinel and many other SIEMs parse out of the box:

<PRI>Mmm dd HH:MM:SS hostname CEF:0|Taranac|Taranac|<version>|USER_DELETED|USER_DELETED|6|rt=1750766096000 cat=audit act=USER_DELETED suser=admin src=10.0.0.5 cs1Label=targetType cs1=user …

The CEF header carries a fixed vendor and product of Taranac, the running app version, a signature ID and a name (both the event_type for an audit event; for an AAA log the signature ID is PROTOCOL_LOGTYPE, e.g. TACACS_AUTHENTICATION, and the name is the readable pair, tacacs authentication), and a severity mapped to CEF’s 0–10 scale. The extension carries typed fields — real IPs go into src / dvc, and free-form values into labelled custom strings (cs1…cs6 with csNLabel), so a SIEM never has to guess a field’s type.

The detail that matters for correlation: every CEF event leads with the canonical rt (event-time) field — epoch milliseconds of when the event happened, derived from the same UTC instant as the header timestamp. Your SIEM never has to reconstruct the time from the year-less, timezone-less BSD header, so a slow collector or a timezone gap can’t smear your timeline.

Path B forwards the same authentication, authorization and accounting records you see in the AAA log views. Those records carry snapshot fields (device name and groups, network object, user display name and groups) captured at log time, so they survive renames and deletions.

The authentication log: per-event who / where / outcome, with the same fields the forwarder ships to syslog.

Active sessions are derived from accounting records — the radius/nac accounting streams you bind for syslog.

• Tamper-evidence — no operator action edits or deletes an audit row, and the one process that removes them (retention) leaves a record of what it removed. Forward system:audit to an external, append-only SIEM as well, so the trail also lives somewhere the Taranac admins cannot reach at all.
• Privileged-action visibility — every secret reveal (*_SECRET_REVEALED), key rotation, MFA change and deletion is its own event type. Reach a whole class of them with the search box (which matches substrings) rather than the event-type dropdown (which matches one exact code, and lists only the commonest ~90).
• Retention — the SIEM owns long-term retention. In-product, the audit log is kept for audit_log.retention_days (default 365) and purged row-by-row nightly at 03:00, optionally written to a JSONL archive first; each purge leaves its own AUDIT_RETENTION_PURGE row. The AAA database logs have their own per-protocol retention.
• Completeness — keep the on-disk AAA file backup enabled (it ignores exclusions) so forensic data exists even for events you deliberately drop from the DB or SIEM.

• Logging & accounting — the AAA log tables and views that Path B forwards
• AAA policy — the rules whose changes appear as config_change events
• Alerts — in-product alerting, and the third exclusion output
• Roles & permissions — the audit_logs and syslog permissions that gate this section
• Taranac on GitHub