Skip to main content

​
Overview

The audit log records every security-relevant event in profClaw: tool calls, approval decisions, security guard blocks, authentication events, and configuration changes. Logs are append-only and cannot be modified after writing.

​
What Gets Logged

Event TypeLogged Fields
Tool callTool name, params (sanitized), user, channel, result, duration
Tool blockedTool name, reason, security mode, risk level
Approval requestTool name, approver, decision (allow-once/allow-always/deny)
Prompt guard hitRisk level, score, pattern matched, input length
SSRF guard blockURL (host only), reason, resolved IP
FsGuard blockPath (normalized), operation, reason
Auth eventLogin, logout, token refresh, failed auth
Config changeField changed, old/new value (sensitive values masked)
Plugin loadPlugin name, version, permissions requested
Skill scanSkill name, findings, risk level

​
Log Format

Each audit entry is a structured JSON line: 
{
  "timestamp": "2026-03-12T09:15:32.445Z",
  "eventType": "tool_call",
  "level": "INFO",
  "risk": "LOW",
  "conversationId": "conv_abc123",
  "userId": "user_xyz",
  "channelProvider": "slack",
  "channelId": "C01234567",
  "tool": {
    "name": "read_file",
    "params": { "path": "src/index.ts" },
    "result": "success",
    "durationMs": 12
  }
}
Sensitive values in params (tokens, passwords, keys) are automatically masked: "apiKey": "***".

​
Viewing Audit Logs

​
CLI

# View recent events
profclaw audit log --last 100

# Filter by event type
profclaw audit log --type tool_call --last 50

# Filter by risk level
profclaw audit log --risk HIGH,CRITICAL

# Filter by user
profclaw audit log --user user_xyz

# Search for specific tool
profclaw audit log --tool exec

​
Via API

GET /api/audit/events?limit=50&type=tool_call&risk=HIGH
Authorization: Bearer <token>

​
Log Files

Audit logs are written to:
  • SQLite (default): stored in profClaw’s database
  • File: ~/.profclaw/audit.jsonl (enable with auditLog.file: true)
  • Syslog: Forward to external syslog server (enterprise)

​
Configuration

security:
  auditLog:
    enabled: true
    retention: 90           # Days to retain events
    file: false             # Also write to JSONL file
    filePath: "~/.profclaw/audit.jsonl"
    maskFields:
      - "apiKey"
      - "token"
      - "password"
      - "secret"
    syslog:
      enabled: false
      host: "logs.company.com"
      port: 514
      protocol: "udp"

​
Compliance Reports

Generate compliance reports from the audit log: 
# Summary report (last 30 days)
profclaw audit report --days 30

# Tool usage breakdown
profclaw audit report --type tool-usage

# Security events only
profclaw audit report --type security

# Export as CSV
profclaw audit report --format csv --output audit-report.csv
Sample report output: 
Audit Report: 2026-02-10 to 2026-03-12
Period: 30 days

Tool Calls: 2,847 total
  - read_file:     1,203 (42%)
  - web_fetch:       412 (14%)
  - exec:            298 (10%)
  - edit_file:       201  (7%)

Security Events: 23 total
  - Prompt guard warnings:  8
  - FsGuard blocks:         6
  - Approval denials:       5
  - SSRF blocks:            4

Risk Distribution:
  LOW:      2,831 (99.4%)
  MEDIUM:       9  (0.3%)
  HIGH:         4  (0.1%)
  CRITICAL:     0  (0.0%)

​
Alerting

Configure alerts for high-risk events: 
security:
  auditLog:
    alerts:
      - event: tool_blocked
        risk: HIGH
        notify: slack          # Send to Slack channel
        channel: "#security"

      - event: prompt_guard
        risk: CRITICAL
        notify: email
        to: "admin@example.com"

​
Log Retention

Audit logs are retained for 90 days by default. After retention expires, entries are permanently deleted. Adjust retention for compliance requirements: 
security:
  auditLog:
    retention: 365    # 1 year for compliance

Guards

Guard decisions that generate audit events.

Security Modes

Mode decisions are audit-logged.