2026-01-26 · Authensor

How to Audit Every Action Your AI Agent Takes

To audit every action your AI agent takes, install SafeClaw (npx @authensor/safeclaw) which automatically logs every action — file reads, file writes, shell commands, and network requests — to a tamper-proof audit trail using SHA-256 hash chains. Each log entry is cryptographically linked to the previous one, making it impossible to alter or delete records without detection. You get a complete, verifiable history of everything your agent did, when it did it, and what policy decision was made.

Why This Matters

When an AI agent causes an incident — deletes a file, leaks a credential, modifies production config — the first question is "what happened?" Without an audit trail, you're guessing. Standard application logs can be modified, truncated, or deleted by the same agent that caused the problem. A tamper-proof audit trail using SHA-256 hash chains ensures that no entry can be altered after it's written. This is also a requirement for compliance frameworks like SOC 2, HIPAA, and ISO 27001, which mandate immutable audit logs for automated systems with data access.

Step-by-Step Instructions

Step 1: Install SafeClaw

npx @authensor/safeclaw

Audit logging is enabled by default — every SafeClaw installation records all actions to the hash chain. SafeClaw has zero third-party dependencies and the client is 100% open source (MIT license).

Step 2: Get Your API Key

Visit safeclaw.onrender.com. Free tier with 7-day renewable key, no credit card required. The browser dashboard provides a visual audit trail viewer.

Step 3: Understand What Gets Logged

Every action your agent proposes is logged with:

The control plane sees only this metadata. It never sees your file contents, command outputs, or API keys.

Step 4: Define Your Policy (Audit Happens Regardless)

Even in simulation mode, every action is logged. But having a policy means each log entry includes the decision that was made, making the audit trail actionable.

# Simulation mode: logs everything, blocks nothing
SAFECLAW_MODE=simulation npx @authensor/safeclaw


Enforce mode: logs everything, blocks policy violations

SAFECLAW_MODE=enforce npx @authensor/safeclaw

Step 5: Verify Hash Chain Integrity

To verify that no audit records have been tampered with, validate the hash chain:

npx @authensor/safeclaw audit verify

This recomputes every SHA-256 hash from the first entry forward and confirms each entry links correctly to the next. If any entry was modified, inserted, or deleted, the verification fails.

Step 6: Export Audit Records for Compliance

# Export as JSON
npx @authensor/safeclaw audit export --format json --output audit-report.json


Export as CSV for spreadsheet analysis

npx @authensor/safeclaw audit export --format csv --output audit-report.csv


Export for a specific date range

npx @authensor/safeclaw audit export --from 2026-02-01 --to 2026-02-13

Example Policy

version: "1.0"
default: deny


rules:
  # Allow standard operations (all logged automatically)
  - action: file_read
    path: "./src/**"
    decision: allow
    reason: "Read source files"



- action: file_write
    path: "./output/**"
    decision: allow
    reason: "Write output files"



- action: shell_exec
    command: "npm test*"
    decision: allow
    reason: "Run tests"



- action: network
    domain: "api.anthropic.com"
    decision: allow
    reason: "LLM API calls"



# Sensitive actions: deny and log
  - action: file_read
    path: "*/.env"
    decision: deny
    reason: "Credential access attempt — logged for review"



- action: shell_exec
    command: "rm *"
    decision: deny
    reason: "Destructive command — logged for review"



- action: network
    domain: "*"
    decision: deny
    reason: "Unknown outbound — logged for review"

What Happens When It Works

ALLOW — Agent reads a source file (logged for audit):

{
  "action": "file_read",
  "path": "./src/models/user.ts",
  "decision": "ALLOW",
  "rule": "Read source files",
  "timestamp": "2026-02-13T08:30:01.042Z",
  "agentId": "agent-prod-001",
  "hash": "sha256:a1b2c3d4e5f6789...prev:0000000000",
  "chainIndex": 1
}

DENY — Agent tries to read credentials (logged for incident review):

{
  "action": "file_read",
  "path": "/home/deploy/.env.production",
  "decision": "DENY",
  "rule": "Credential access attempt — logged for review",
  "timestamp": "2026-02-13T08:30:02.108Z",
  "agentId": "agent-prod-001",
  "hash": "sha256:b2c3d4e5f6g7890...prev:a1b2c3d4e5f6789",
  "chainIndex": 2
}

REQUIRE_APPROVAL — Agent action escalated to human (logged with approval status):

{
  "action": "file_write",
  "path": "./src/config/database.ts",
  "decision": "REQUIRE_APPROVAL",
  "rule": "Config changes need human review",
  "timestamp": "2026-02-13T08:30:03.215Z",
  "agentId": "agent-prod-001",
  "approvedBy": "eng-lead@company.com",
  "hash": "sha256:c3d4e5f6g7h8901...prev:b2c3d4e5f6g7890",
  "chainIndex": 3
}

Common Mistakes

  1. Relying on standard application logs for agent auditing. Application logs can be modified or deleted — including by the agent itself. If your agent has shell_exec access, it can run truncate -s 0 /var/log/agent.log. A SHA-256 hash chain audit trail is cryptographically tamper-proof: altering any entry breaks the chain, and verification immediately detects the tampering.
  1. Logging only denied actions. Allowed actions matter too. During an incident investigation, you need to reconstruct the full sequence of actions — what the agent did, not just what it was prevented from doing. SafeClaw logs every action regardless of decision.
  1. Not exporting audit data for external retention. Audit trails are only useful if they're preserved. Export your audit data regularly to external storage (S3, a compliance archive, etc.) to ensure retention beyond your SafeClaw subscription period and to meet compliance requirements for multi-year audit retention.

Cross-References

Try SafeClaw

Action-level gating for AI agents. Set it up in your browser in 60 seconds.

$ npx @authensor/safeclaw