---
title: Audit Trail
description: Cryptographic audit logging for compliance and security
---

## What is the audit trail?

Pinchy includes a built-in audit trail that logs every significant action on the platform. Each entry is cryptographically signed with HMAC-SHA256 to detect tampering. The audit log is append-only — PostgreSQL triggers prevent any modification or deletion of existing entries.

The audit trail is designed for **compliance and security**. It answers the question: "Who did what, and when?"

![Audit trail showing diverse events from users and agents](/screenshots/audit-trail.png)

## What gets logged

Pinchy logs event types across seven categories:

### Tool execution

| Event Type        | Description                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `tool.<toolName>` | An agent executed a tool — event type is dynamic per tool (e.g. `tool.shell`, `tool.pinchy_read`, `tool.fs_read`) |
| `tool.denied`     | An agent attempted to use a tool that was not in its allow-list                                                   |

Each tool execution produces **one audit entry** — logged when the tool call completes (end phase only). The detail includes the tool name, parameters, and result. Start events are received but not persisted.

## Event Status

Every entry in the audit log — not just tool calls — carries a status that
shows whether the action succeeded or failed:

- A green check mark indicates a successful event (a login, an agent
  update, a tool call that returned cleanly, a config change, etc.).
- A red X indicates a failure (e.g., a failed login, a denied tool, a tool
  call that errored out, or any other event marked as a failure).
- Legacy entries from before this feature was added show a neutral "—"
  with a "Logged before status tracking" tooltip. The schema did not track
  success/failure at the time. This is normal and not an integrity issue.

You can filter the audit log by status using the **Status** dropdown above
the table. Filtering applies to every event type, not just tool calls:

- **All Statuses** — show every entry.
- **Success only** — only successful events. Legacy entries are excluded.
- **Failures only** — only failed events. This surfaces `auth.failed`
  attempts, denied or errored tool calls, and anything else marked as a
  failure — useful for spotting recurring problems quickly.

The **Event Type** filter and **Status** filter are complementary. Combine
them to answer questions like "all failed Auth events in the last 24
hours" or "all failed tool calls for this agent".

When viewing a failed event's detail, the error message is shown
prominently above the raw event JSON, so you don't have to dig through the
detail blob to find the cause.

The **Status** column is also included in CSV and PDF exports, alongside
an Error column with the failure message. Status filtering applies to
exports too.

### Authentication

| Event Type    | Description                                            |
| ------------- | ------------------------------------------------------ |
| `auth.login`  | A user successfully logged in                          |
| `auth.failed` | A login attempt failed (wrong password, unknown email) |
| `auth.logout` | A user logged out                                      |

### Agent management

| Event Type                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent.created`               | A new agent was created                                                                                                                                                                                                                                                                                                                                                                                                             |
| `agent.updated`               | An agent's settings or permissions were changed                                                                                                                                                                                                                                                                                                                                                                                     |
| `agent.deleted`               | An agent was deleted                                                                                                                                                                                                                                                                                                                                                                                                                |
| `agent.memory_changed`        | A file in the agent's durable long-term memory (`MEMORY.md` or `memory/*.md`) was created, modified, or deleted                                                                                                                                                                                                                                                                                                                     |
| `agent.model_unavailable`     | The agent's configured model returned an HTTP 5xx (server-side failure or discontinuation). One entry per `(agent, model)` per 5 minutes — repeated failures inside the window are aggregated to avoid log spam. Detail captures the upstream `ref` ID.                                                                                                                                                                             |
| `agent.upstream_format_error` | The upstream provider rejected the request with a known schema/format defect that retry usually clears (currently: Gemini 3 `thought_signature` dropped on tool-call replay). One entry per `(agent, model)` per 5 minutes. Detail captures the matched pattern and upstream `ref` ID so frequency tracking is automatic — see [Chat connection states › Upstream format errors](/explanation/chat-states/#upstream-format-errors). |

#### `agent.memory_changed`

OpenClaw maintains durable per-agent long-term memory in `~/.openclaw/agents/<agentId>/MEMORY.md` and `~/.openclaw/agents/<agentId>/memory/*.md`. Those files are reloaded into the agent's context at every session start, so they directly shape behavior in every future conversation. Memory is written in two ways:

- Explicitly, when the user or agent decides to remember something.
- Implicitly, via the pre-compaction memory flush — a silent turn that runs before OpenClaw summarizes a long conversation and asks the agent to save important context.

Pinchy watches these files and emits an audit entry on every change so an auditor can answer "the agent suddenly believes X — when and how did that get into its memory?"

- `actorType`: `"agent"` — the agent whose memory changed.
- `actorId`: the agent id.
- `resource`: `agent:<agentId>`.
- `detail`:
  - `agent`: `{ id, name }` — snapshot of the agent at the time of the change.
  - `file`: the relative path under the agent directory — either `"MEMORY.md"` or `"memory/<file>.md"`.
  - `addedLines`: number of lines added compared to the prior snapshot.
  - `removedLines`: number of lines removed compared to the prior snapshot.
  - `byteSize`: size of the file in bytes after the change (`0` for deletions).

The detail never contains file contents — only counts and the relative filename. Deletions surface as `byteSize: 0` and `removedLines` equal to the previous line count.

### Chat runtime

| Event Type                      | Description                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chat.background_run_completed` | A chat run finished after the user navigated away from the chat page (a "background run"). Detail records `agent.{id,name}` and the run's wall-clock `durationMs`. Used together with the sidebar pulse dot for the per-agent background-runtime feature.                                                                                                 |
| `chat.silent_stream`            | A streaming run ended without producing any assistant text — typically a cold-path tool call that timed out inside OpenClaw's embedded layer. Throttled per `(agent, model)` so a degraded provider can't flood the log via user retries. Detail captures `agent.{id,name}`, `model`, the originating `providerError`, and `reason: "silent_stream_end"`. |

### User management

| Event Type            | Description                                                                                                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user.invited`        | An admin invited a new user                                                                                                                                                                                                                        |
| `user.invite_blocked` | An admin attempted to invite a user but the action was refused by a licence/seat-cap guard. Detail records the (redacted) `email`, the chosen `role`, the `reason` (e.g. `seat_cap`), and the relevant licence counters (`seatsUsed`, `maxUsers`). |
| `user.updated`        | A user's profile was changed                                                                                                                                                                                                                       |
| `user.role_updated`   | A user's role was changed (e.g. member → admin)                                                                                                                                                                                                    |
| `user.groups_updated` | A user's group memberships were changed                                                                                                                                                                                                            |
| `user.deleted`        | A user account was deleted                                                                                                                                                                                                                         |

### Group management

| Event Type              | Description                                   |
| ----------------------- | --------------------------------------------- |
| `group.created`         | A new group was created                       |
| `group.updated`         | A group's settings were changed               |
| `group.deleted`         | A group was deleted                           |
| `group.members_updated` | Members were added to or removed from a group |

### Channel management

| Event Type        | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| `channel.created` | An agent was connected to an external channel (e.g. a Telegram bot token was added) |
| `channel.deleted` | An agent was disconnected from a channel (or all channels of one type were removed) |

### Configuration

| Event Type       | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| `config.changed` | A system configuration setting was changed (e.g., provider API key) |

### Audit trail access

| Event Type       | Description                                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `audit.exported` | An admin downloaded an audit-trail export (CSV or PDF). The detail records the chosen format, applied filters, and row count — but never the exported data itself. |

### What is NOT logged

**Chat messages are not logged in the audit trail.** The audit trail records actions and events, not conversation content. Chat messages are stored separately in the conversation history managed by OpenClaw.

## Sensitive data redaction

Tool parameters and results are automatically sanitized before being stored in the audit log. This prevents accidental exposure of secrets such as API keys, passwords, or tokens.

### What gets redacted

- **Sensitive field names** — Any JSON field whose name contains `password`, `secret`, `token`, `apiKey`, `credential`, or similar terms has its value replaced with `[REDACTED]`.
- **Known secret patterns** — String values matching known formats (OpenAI keys `sk-…`, GitHub tokens `ghp_…`, Slack tokens `xoxb-…`, Bearer tokens, Telegram bot tokens, Meta access tokens, and others) are replaced with `[REDACTED]`.
- **Environment file content** — When a tool reads a file containing lines like `SECRET_KEY=value`, the value portion is redacted while the key name is preserved.

### Defense in Depth

Sanitization runs at two layers:

1. **Plugin layer** — The `pinchy-audit` OpenClaw plugin redacts sensitive data before sending it to Pinchy over HTTP. Secrets never leave the agent runtime.
2. **API layer** — The tool-use endpoint redacts again before writing to the database. This catches anything the plugin layer might have missed.

The redaction rules are built-in and require no configuration.

### Email addresses (GDPR Art. 17)

Email addresses are personal data under GDPR. Because the audit log is HMAC-signed and append-only, a raw email address written into a row would survive every right-to-erasure request — the row cannot be edited, and editing would invalidate its signature.

Pinchy avoids this by **never recording plaintext email addresses in `detail`**. Instead, events that need to identify an inviter, login attempt, or invited recipient store two derived fields:

- **`emailHash`** — keyed HMAC-SHA256 of the lowercased+trimmed email, using the same `audit_hmac_secret` that signs each row. An admin holding a known address can recompute the hash and match against the log; a leaked log on its own does not yield the addresses back.
- **`emailPreview`** — short masked form, e.g. `cl…lm@devcraft.academy` (first 2 + last 2 characters of the local part, plus the full domain). Enough for a human auditor to recognise an address they already know, not enough for bulk re-identification. For very short local parts (≤4 characters), the preview equals the address — there is nothing useful to mask. The hash still provides one-way protection in that case.

`user.deleted` events go further: they record only the user's display name. The `userId` is already in the `resource` field, and the audit log is not the right place to keep a deactivated user's contact details.

#### Multi-instance deployments

Hash determinism depends on every Pinchy instance using the **same** `audit_hmac_secret`. The default behaviour — auto-generate a secret file under `/app/secrets/.audit_hmac_secret` on first start — produces a different secret per instance. If you run more than one Pinchy instance against a shared Postgres (HA, blue/green, multiple replicas), set `AUDIT_HMAC_SECRET` explicitly via env var or mount the same secret file on every instance. Without this, the same email address will hash to different values on different instances, and an admin will not be able to look up its history from one place. The same prerequisite applies to row HMAC verification.

## How HMAC signing works

Each audit log entry is signed with **HMAC-SHA256** to ensure integrity:

1. When an audit event occurs, Pinchy constructs a payload from the entry's fields (event type, actor, timestamp, metadata).
2. The payload is signed using a server-side HMAC secret.
3. The resulting signature is stored alongside the entry in the `hmac` column.
4. The HMAC secret is auto-generated at startup if the `AUDIT_HMAC_SECRET` environment variable is not set.

If anyone modifies a row directly in the database, the HMAC signature will no longer match — and integrity verification will flag the tampered entry.

## How to verify integrity

Admins can verify the integrity of the audit log in two ways:

### Via the admin UI

1. Navigate to the **Audit** page in the admin area.
2. Click the **Verify Integrity** button.
3. Pinchy recomputes HMAC signatures for all entries and reports any mismatches.

### Via the API

Send a `GET` request to `/api/audit/verify`. Optional `fromId` and `toId` parameters let you verify a specific range of entries.

```bash
curl -b session_cookie https://your-pinchy-instance/api/audit/verify
```

The response indicates whether all entries are intact:

```json
{
  "valid": true,
  "totalChecked": 142,
  "invalidIds": []
}
```

If tampered entries are found, `valid` is `false` and `invalidIds` contains the IDs of the affected rows.

## Export for compliance

The audit log can be exported in two formats — **CSV** for data analysis and downstream tooling, **PDF** for formal reports, archival, and regulatory submissions. Both formats apply the same filters and pass through the same sanitization rules, so secrets are never written to either output.

EU AI Act Article 12 (record-keeping for high-risk AI systems, applicable from 2 August 2026) and most enterprise compliance frameworks require that audit logs can be produced for external review on demand. Both exports include the per-row HMAC signature so an auditor can independently verify that the exported entries match the cryptographic evidence in the database.

### What's included in the export

Every export — regardless of format — contains:

- **Timestamp** (UTC, ISO 8601)
- **Actor** — name (snapshotted) and ID, plus type (user, agent, system)
- **Event type** — what happened (`auth.login`, `agent.updated`, `tool.shell`, …)
- **Resource** — name (snapshotted) and ID of the affected entity, where applicable
- **Status** — `success` or `failure` (legacy entries before status tracking show empty)
- **Error message** — for failed events
- **Detail** — the structured event payload, **after** sensitive-data redaction
- **Integrity hash** — the row's HMAC-SHA256 signature, so the export is independently verifiable
- **Schema version** — which HMAC version was used to sign the row

### Via the admin UI

1. Navigate to the **Audit** page.
2. Apply any desired filters (date range, event type, status).
3. Click **Export** and choose **Export as CSV** or **Export as PDF**.

### Via the API

Send a `GET` request to `/api/audit/export` with optional filter parameters (`eventType`, `actorId`, `resource`, `status`, `from`, `to`). Use the `format` parameter to pick the output: `csv` (default) or `pdf`.

```bash
# CSV export (default)
curl -b session_cookie "https://your-pinchy-instance/api/audit/export?from=2026-01-01&to=2026-02-01" -o audit-log.csv

# PDF export — formal report, suitable for printing and archival
curl -b session_cookie "https://your-pinchy-instance/api/audit/export?format=pdf&from=2026-01-01&to=2026-02-01" -o audit-log.pdf

# Filter to a specific agent's tool calls
curl -b session_cookie "https://your-pinchy-instance/api/audit/export?resource=agent:abc123&eventType=tool.shell" -o smithers-shell-audit.csv
```

The PDF report contains a header with generation timestamp, the active filters, and the total number of entries, followed by a paginated table of the entries themselves. Each page is footed with a page counter and a reminder that the underlying data is HMAC-SHA256 signed.

### CSV vs PDF — when to use which

The two formats target different audiences:

- **CSV** is the complete record. It includes every column, including the structured `detail` payload (sanitized) for each event. Use CSV for downstream tooling, SIEM ingestion, spreadsheets, scripted analysis, and any case where an auditor wants to recompute the row HMAC themselves.
- **PDF** is the printable summary. It shows timestamp, actor, event, resource, status, and the first 16 hex characters of the HMAC for each row — enough to identify and corroborate an entry against the database, but not the full payload. Use PDF for formal reports, signed archival, and submissions to regulators who expect a paginated document.

If a stakeholder needs the full event payload in a printable format, generate the CSV and let them produce a PDF from there with their preferred tooling — the PDF view in Pinchy is intentionally summary-only.

### Known limitation: non-Latin characters in PDF

The PDF renderer uses PDFKit's built-in Helvetica font, which covers Latin-1 only. Actor or agent names written in scripts outside Latin-1 (Cyrillic, CJK, Arabic, Devanagari, etc.) will render as boxes or empty space in the PDF output. The CSV export is unaffected — it is UTF-8 throughout. If you need a PDF with non-Latin names, export as CSV and convert on the client side, or [open an issue](https://github.com/heypinchy/pinchy/issues) so we can prioritize bundling a Unicode font.

## Immutability guarantees

The audit trail uses multiple layers to ensure entries cannot be modified:

1. **PostgreSQL triggers** — `BEFORE UPDATE` and `BEFORE DELETE` triggers on the `auditLog` table raise an exception, preventing any modification or deletion at the database level.
2. **HMAC signatures** — Even if triggers were somehow bypassed, any modification would invalidate the cryptographic signature.
3. **Append-only API** — The application code only inserts entries. There is no update or delete endpoint for audit entries.

## Fire-and-forget pattern

Audit logging uses a fire-and-forget pattern: if logging fails (e.g., database connection issue), the main operation still succeeds. This ensures that audit logging never degrades the user experience or blocks critical operations.

The trade-off is that in rare failure scenarios, an action might not be logged. For most enterprise deployments, this is preferable to having audit logging cause outages.

## Access control

Only **admins** can access the audit trail — both the UI page and the API endpoints. Regular users cannot view, verify, or export audit entries.
