Audit Trail

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?”

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
auth.csrf_blocked	A state-changing request was rejected because its Origin / Referer headers didn’t match the locked domain. Detail captures method, pathname, origin, referer, and remoteAddress — see Hardening › CSRF gate.
auth.password_reset_completed	A user finished a password-reset invite. On success, detail snapshots the target {id, name} and the invite id; all of that user’s existing sessions are revoked in the same transaction. On failure (rare — e.g. DB error mid-flow), outcome: failure is written with the error message and the entire reset rolls back so the old password and the reset token both remain usable.

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.

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".
chat.agent_error	Umbrella event for every chat error chunk plus the silent-stream timeout. Fires alongside the specialised events (agent.model_unavailable, agent.upstream_format_error, chat.silent_stream), not instead of — so a single SQL query grouped by detail->>'errorClass' aggregates every failure shape including the long tail. Not throttled. Detail captures agent.{id,name}, model, errorClass (one of failover_incomplete_stream / schema_rejection / model_unavailable / transient / provider_config / silent_stream_timeout / unknown), and email-scrubbed providerError truncated to 1024 bytes.
chat.retry_triggered	The user clicked Retry on a chat message after a delivery or run failure. Detail records agent.{id,name}, the sessionKey, and a validated reason (orphan / partial_stream_failure / send_failure). The reason string is validated at the trust boundary so a malicious or buggy client cannot write arbitrary strings into HMAC-signed audit rows.
attachment.uploaded	A user attached a file to a chat message (via the composer paperclip or by drag-and-drop). Detail records agent.{id,name}, uploader.{id,name}, the sessionKey, and the file metadata: filename, detectedMimeType, sizeBytes, contentHash, and reused (true when the upload deduplicated against an existing content-addressed blob). The file contents themselves are never written to the audit row.

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.

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

The response indicates whether all entries are intact:

{
  "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.

# 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 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.