# Audit log and recordings

> What Nokku records, how to find it, and how to read it from your own tools.

Nokku keeps two kinds of evidence: an **audit log** of what people and machines did, and **session recordings** of what happened on the servers. Together they answer the auditor's favorite question: who had access to what, and what did they do with it?

Reading both needs the **viewer** role or higher.

## The audit log

Every change is logged with who did it, when, from where, and whether it was allowed. That includes:

- Changes in the workspace: servers, grants, teams, users, the CA, settings.
- Sign-ins and sign-in failures, new and revoked sessions, added or removed credentials.
- Every certificate issued, with its principals and expiry. A certificate you see in a server log can be traced back to the person who requested it.
- Calls that were denied, so a viewer trying an admin action leaves a trace.
- Relay connections, and every time someone watches a recording.

Plain reads aren't logged, so the log stays readable.

You can search and filter the log in the web app, and **export** it for an auditor as CSV or JSON.

Each server with `nokkud` also writes its own log of logins, commands and forwards, see [Where its files live](/docs/servers/add-server#where-its-files-live).

## Read it from your own tools

The audit log is part of the [API](/api), so a SIEM or a script can fetch it. Give a **service account** the `viewer` role and call `ListAuditLogs` with its key, see [Call the API](/docs/access/automation#call-the-api).

- Filter by time and ask only for the events since your last call.
- Every event has an ID that never changes, so reading one twice does no harm.

## Stream it to your SIEM

Instead of fetching, the core can push every event as it happens. The owner adds a stream on the **Audit log** page under **Streaming**. It may not be enabled on every instance.

| Destination | URL                                                                                    | Secret      |
| ----------- | -------------------------------------------------------------------------------------- | ----------- |
| Webhook     | Any `https://` endpoint, gets a JSON array of events                                   | Signing key |
| Splunk      | Your HTTP Event Collector, like `https://splunk:8088/services/collector/event`         | HEC token   |
| Datadog     | The logs intake of your site, like `https://http-intake.logs.datadoghq.eu/api/v2/logs` | API key     |

- Each stream remembers the last event it delivered. A destination that is down gets everything it missed once it is back, in order.
- Every event keeps its ID. A retry can send one again, so let the receiver drop what it has.
- A webhook request carries `X-Nokku-Timestamp` and `X-Nokku-Signature: sha256=<hex>`, an HMAC-SHA256 of the timestamp, a dot and the body. Check it, and refuse old timestamps.
- **Send a test event** shows at once whether the destination takes it. A failing stream shows its last error and keeps trying.

A self-hosted core connects to private addresses too, so a SIEM on your internal network works. The hosted service only reaches public ones.

## Session recordings

Servers with `nokkud` record sessions when recording is on for that daemon. It's on by default, see [Session rules](/docs/servers/session-rules).

- Shells are recorded, and so is the output of a single command like `ssh my-server "cat app.log"`. File transfers over SFTP and port forwards are not, but they are in the audit trail.
- What someone types is recorded only while the terminal shows it, so passwords typed at a prompt are left out.
- When recording is on, a session with a terminal starts with a line saying so, and the web terminal shows a badge.
- The daemon streams each recording to the core while the session runs. If the daemon or the server dies in the middle, the core keeps the part it already has.
- The core stores it **encrypted**, each recording with its own key, and decrypts it only while someone watches.
- If the core is unreachable, the daemon keeps recordings locally and uploads them once it's back. Once the core has a recording, the daemon deletes its local file.
- A recording has a size limit. A session with a terminal that reaches it is closed with a notice, so flooding the screen can't switch recording off. A session without one, like a single command, keeps running, and only the rest of its output goes unrecorded.
- When the server's disk is almost full, a session still runs without a recording. A full disk must not lock you out. The gap is written to the audit trail.
- Someone with the **editor** role can delete a recording. A deletion is written to the audit log.

Watch recordings in the web app, where each one is linked to the person and the server.

> **Warning: Recordings are sensitive**
>
> Nothing in a recording is redacted. A secret printed on the screen is in it.
> Treat recordings like the servers they come from. Who watched which recording
> is itself logged.

Servers set up with `nk sync` are not recorded. Recording needs the daemon.

## How long things are kept

Audit events and recordings are kept for the workspace's retention period, then deleted automatically. If you need them longer, export the log or stream it into your own tools.

A workspace can also have a storage limit for recordings. When a new recording would go over it, the oldest ones are deleted to make room, and every deletion is written to the audit log. The newest recordings are never pushed out this way. The servers keep no copy of an uploaded recording, so a deleted one is gone.

If the retention period gets shorter, for example after a license expires, nothing is deleted right away. See [License keys](/docs/self-hosting/license#when-a-key-expires).
