Audit log

Revka records every security-relevant action — command executions, file access, config changes, authentication outcomes, and policy violations — to a tamper-evident Merkle hash-chain audit log. Each entry is SHA-256 linked to the one before it, so altering, inserting, or deleting any record breaks the chain and is detectable. You can optionally sign every entry with HMAC-SHA256, query the trail over the REST API, and verify the chain’s integrity on demand.

Use this page to enable auditing, turn on signing, read the event format, and wire the log into a SIEM via the webhook audit hook.

Note

The audit log is a local, persistent file written by the daemon. For real-time, outbound delivery of tool-call events to an external endpoint, use the webhook audit hook instead — the two are complementary.

Enable the audit log

Auditing is configured under [security.audit] in ~/.revka/config.toml and is on by default.

[security.audit]
enabled = true              # default true
log_path = "audit.log"      # relative to the revka/workspace dir
max_size_mb = 100           # rotate when the file reaches this size
sign_events = false         # optional HMAC-SHA256 signing (see below)

Key	Type	Default	Meaning
enabled	bool	true	Master switch. When false, the logger leaves no file on disk and the API returns empty results.
log_path	string	"audit.log"	Log file path, resolved relative to the workspace directory.
max_size_mb	u32	100	Size threshold (MB) at which the active log rotates to a numbered archive.
sign_events	bool	false	When true, each entry is signed with HMAC-SHA256. Requires REVKA_AUDIT_SIGNING_KEY.

The logger touches the log file on a fresh install so readers never hit a “not found” error, and it recovers the chain state from the last entry on restart so new writes continue the existing chain.

How the Merkle chain works

Every entry carries three chaining fields in addition to its payload:

• sequence — a monotonically increasing counter, starting at 0.
• prev_hash — the entry_hash of the previous entry. The first (genesis) entry uses a well-known seed of 64 zeros.
• entry_hash — SHA-256(prev_hash || canonical_JSON_of_content), where content is the entry’s payload fields excluding prev_hash and entry_hash (but including sequence).

Because each hash folds in the previous one, modifying any entry changes its entry_hash, which no longer matches the prev_hash recorded in the next entry — invalidating every record downstream. Sequence numbers must also be contiguous, so deleting an entry is detectable as a gap.

Writes are serialized under a mutex and protected by an advisory exclusive file lock (so a brief two-daemon overlap can’t interleave bytes), and each append is flushed with fsync for durability. The sequence and prev_hash only advance after a successful write, so an I/O failure cannot leave a gap.

Event format

Entries are written one JSON object per line (JSONL). A signed command-execution entry looks like this:

{
  "timestamp": "2026-06-18T10:00:00Z",
  "event_id": "f1c2…-uuid",
  "event_type": "command_execution",
  "actor": { "channel": "telegram", "user_id": "123", "username": "@alice" },
  "action": { "command": "ls -la", "risk_level": "low", "approved": false, "allowed": true },
  "result": { "success": true, "exit_code": 0, "duration_ms": 15, "error": null },
  "security": { "policy_violation": false, "rate_limit_remaining": 19, "sandbox_backend": "firejail" },
  "sequence": 42,
  "prev_hash": "<64 hex chars>",
  "entry_hash": "<64 hex chars>",
  "signature": "<64 hex chars>"
}

The signature field is present only when sign_events = true. The actor, action, and result objects may be absent depending on the event type.

Event types

event_type is one of:

Value	Logged when
command_execution	A shell command runs (with risk level, approval, allowed/blocked, and timing).
file_access	A file operation is evaluated.
config_change	Configuration is modified.
auth_success	Authentication succeeds (e.g. a client pairs).
auth_failure	Authentication fails (e.g. an invalid pairing code).
policy_violation	A security policy blocks an action.
security_event	Other security-relevant events (WebSocket connection, pairing flow).

HMAC signing

Hash-chaining alone is tamper-evident: an attacker who can rewrite the whole file could recompute every hash. Enabling sign_events adds an HMAC-SHA256 signature over each entry_hash, keyed by a secret only you hold — so a forged chain can’t be re-signed without the key.

1. Generate a 32-byte key (64 hex characters) and export it as REVKA_AUDIT_SIGNING_KEY before the gateway starts — the key is loaded once when the logger is constructed.

   Linux / macOS

   export REVKA_AUDIT_SIGNING_KEY="$(openssl rand -hex 32)"

   Windows (PowerShell)

   $bytes = New-Object byte[] 32
   [System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
   $env:REVKA_AUDIT_SIGNING_KEY = ($bytes | ForEach-Object { $_.ToString('x2') }) -join ''

2. Turn on signing in config:

   [security.audit]
   enabled = true
   sign_events = true

3. Start the daemon. From now on, every new entry includes a signature.

Caution

When sign_events = true and REVKA_AUDIT_SIGNING_KEY is missing, not valid hex, or not exactly 32 bytes, audit-logger construction fails and the daemon logs a warning and runs with the audit log disabled (it does not abort startup). Store the key in a secret manager — losing it means new entries can no longer be signed, and existing signatures can no longer be verified.

Signed and unsigned records are forward-compatible: a chain that contains a mix of both (for example, entries written before you enabled signing) still verifies cleanly. Records that carry a signature are checked against the key when it is available; records without one are skipped.

Audit log API

Both endpoints are part of the Gateway API and require a bearer token from the pairing flow.

Query recent events

GET /api/audit?limit=50&event_type=command_execution&since=2026-01-01T00:00:00Z
Authorization: Bearer <token>

Parameter	Type	Default	Notes
limit	int	50	Maximum events to return. Capped at 500.
event_type	string	—	Filter to one event type (see table above).
since	string	—	RFC 3339 timestamp lower bound.

Events are returned newest-first:

{
  "events": [ /* AuditEvent objects, newest first */ ],
  "count": 50,
  "audit_enabled": true
}

If auditing is disabled, the endpoint returns {"events": [], "count": 0, "audit_enabled": false} rather than an error, so dashboards degrade gracefully.

curl -s "http://127.0.0.1:42617/api/audit?limit=20&event_type=policy_violation" \
  -H "Authorization: Bearer rk_<token>"

Verify chain integrity

GET /api/audit/verify
Authorization: Bearer <token>

This re-reads the active log and checks that every entry_hash recomputes correctly, every prev_hash links to its predecessor, sequence numbers are contiguous from 0, and (when the signing key is available) every signature matches.

{ "verified": true, "entry_count": 128 }

On the first violation it returns the reason:

{ "verified": false, "error": "entry_hash mismatch at line 43 (sequence 42): expected …, got …" }

curl -s http://127.0.0.1:42617/api/audit/verify \
  -H "Authorization: Bearer rk_<token>"

If auditing is disabled, the response is {"verified": false, "error": "Audit logging not enabled"}.

Tip

To verify signatures via /api/audit/verify, make sure REVKA_AUDIT_SIGNING_KEY is set in the daemon’s environment. Without it, the chain still verifies structurally but signature checks are skipped.

Log rotation

When the active log reaches max_size_mb, it rotates: audit.log becomes audit.log.1.log, older archives shift up (.1 → .2, … .9 → .10), and a fresh audit.log starts.

Rotation resets the chain to genesis for the new file, so /api/audit/verify succeeds immediately against the active log. Each rotated audit.log.N.log archive is its own self-contained chain and remains independently verifiable — keep the archives if you need a continuous historical record.

Webhook audit hook

For real-time, push-based audit delivery — feeding a SIEM, a compliance pipeline, or centralized log storage — use the built-in WebhookAuditHook. It POSTs a JSON payload to an external HTTPS endpoint for every tool call whose name matches a configured glob pattern, without anyone polling /api/audit.

Configure it under [hooks.builtin.webhook_audit]:

[hooks]
enabled = true

[hooks.builtin.webhook_audit]
enabled = true
url = "https://siem.example.com/revka/audit"
tool_patterns = ["Bash", "Write", "mcp__*"]
include_args = false
max_args_bytes = 4096

Key	Type	Default	Meaning
enabled	bool	false	Enable the hook.
url	string	""	Target endpoint. Must be https:// (see security note). Empty + enabled logs a warning and drops events.
tool_patterns	list	[]	Glob patterns for tool names to audit (* wildcard, e.g. mcp__*, *_write). An empty list audits nothing.
include_args	bool	false	Include tool arguments in the payload. May contain secrets or PII — leave off unless you need it.
max_args_bytes	u64	4096	Truncate serialized args to this many bytes (0 = unlimited).

The POST body looks like:

{
  "event": "tool_call",
  "timestamp": "2026-06-18T10:00:00Z",
  "tool": "Bash",
  "success": true,
  "duration_ms": 42,
  "error": null,
  "args": null
}

args is null when include_args = false (or when no captured arguments exist). Delivery is fire-and-forget: failures are logged but never block or crash the agent. The hook runs last in the lifecycle pipeline.

Caution

The url is validated at startup to block SSRF: loopback, RFC1918 private ranges, link-local addresses, and plain http:// URLs are rejected, and a misconfigured URL aborts startup (HTTP localhost is permitted only in debug builds). Point the hook at a public HTTPS collector.

Lightweight local logging

If you only want tool calls echoed to the daemon’s structured logs (no external endpoint), enable the companion CommandLoggerHook instead — it writes each completed tool call to tracing with tool name, duration, and success:

[hooks.builtin]
command_logger = true

Related pages

• Policy, commands & sandboxing — what generates command_execution and policy_violation events.
• Secrets, pairing & device auth — the bearer tokens behind auth_success / auth_failure.
• OTP gating & emergency stop — additional gates whose outcomes are audited.
• Cost, audit, ClawHub & credentials API — the audit endpoints in the full API reference.
• Observability & tracing — the hooks pipeline and runtime trace diagnostics.
• Logs, audit, doctor, pairing & skins pages — the dashboard audit viewer.