How to Log Every AI Agent Action for Compliance

Compliance frameworks including SOC 2, HIPAA, GDPR, PCI-DSS, and ISO 27001 require complete, accurate, and tamper-proof records of system actions — AI agents are no exception. SafeClaw by Authensor logs every action an AI agent attempts, whether allowed or denied, in a structured format with hash-chained integrity. Every log entry includes the action type, the policy decision, the matched rule, and full request details, giving you the audit evidence compliance requires without any additional logging infrastructure.

Quick Start

npx @authensor/safeclaw

Scaffolds a .safeclaw/ directory with comprehensive logging enabled by default.

Step 1: Map Compliance Requirements to Log Fields

Different frameworks require different information. Configure SafeClaw to capture all fields you need:

# .safeclaw/config.yaml
audit:
  enabled: true
  hashChain: true
  format: "jsonl"
  fields:
    # Core fields (all frameworks)
    - timestamp          # When the action was attempted
    - action             # What action was attempted (file.write, shell.execute, etc.)
    - effect             # Allow or deny decision
    - matchedRule        # Which policy rule made the decision
    - reason             # Human-readable reason for the decision

# Identity fields (SOC 2, ISO 27001)
    - agentId            # Which AI agent
    - sessionId          # Which session
    - userId             # Which human initiated the agent

# Detail fields (HIPAA, PCI-DSS)
    - requestDetails     # Full action details (file path, command, API endpoint, etc.)
    - evaluationDurationMs  # How long policy evaluation took

# Integrity fields (all frameworks)
    - hash               # Entry hash
    - prevHash           # Previous entry hash (chain link)
    - sequence           # Monotonic sequence number

Step 2: Configure Retention by Framework

Different compliance frameworks have different retention requirements:

audit:
  retention:
    default: "3y"     # SOC 2 minimum
    overrides:
      hipaa: "6y"     # HIPAA requires 6 years
      financial: "7y"  # SOX/PCI-DSS requires 7 years
      gdpr: "matched"  # GDPR: retain only as long as necessary
  rotation:
    maxSize: "500MB"
    compress: true
    archiveTo: "s3://audit-archive/"

Step 3: Structured Log Output

Every action produces a structured JSON log entry:

{
  "sequence": 4821,
  "timestamp": "2026-02-13T10:45:23.102Z",
  "action": "database.query",
  "effect": "deny",
  "matchedRule": "block-pii-fields",
  "reason": "Agent must never query PII-sensitive columns",
  "agentId": "customer-service-agent-03",
  "sessionId": "sess_xyz789",
  "userId": "support-lead@company.com",
  "requestDetails": {
    "query": "SELECT name, email, ssn FROM customers WHERE id = 42",
    "database": "production"
  },
  "evaluationDurationMs": 0.18,
  "hash": "sha256:a1b2c3d4...",
  "prevHash": "sha256:e5f6g7h8..."
}

This single entry satisfies multiple compliance requirements simultaneously:

• SOC 2 — who (userId, agentId), what (action, requestDetails), when (timestamp), outcome (effect)


• HIPAA — access attempt logged, patient data reference captured, denial recorded


• PCI-DSS — cardholder data access attempt recorded and blocked


• ISO 27001 — complete access control event record

Step 4: Log Both Allows and Denials

SafeClaw logs every action attempt, not just denials. This is critical for compliance — you need to prove what was accessed, not just what was blocked:

{
  "sequence": 4822,
  "timestamp": "2026-02-13T10:45:24.305Z",
  "action": "database.query",
  "effect": "allow",
  "matchedRule": "allow-read-ticket-info",
  "reason": "Agent can read ticket metadata",
  "agentId": "customer-service-agent-03",
  "sessionId": "sess_xyz789",
  "requestDetails": {
    "query": "SELECT id, subject, status FROM tickets WHERE customer_id = 42"
  },
  "hash": "sha256:b2c3d4e5...",
  "prevHash": "sha256:a1b2c3d4..."
}

Step 5: Route Logs to Compliance Systems

Send structured logs to your compliance and SIEM tools:

audit:
  destinations:
    - type: file
      path: "logs/audit.jsonl"

- type: syslog
      host: "siem.internal.company.com"
      port: 514
      format: "cef"  # Common Event Format for SIEM

- type: webhook
      url: "${COMPLIANCE_WEBHOOK}"
      batchSize: 100
      flushInterval: "5s"

- type: s3
      bucket: "compliance-audit-logs"
      prefix: "safeclaw/{{year}}/{{month}}/"
      objectLock: true
      retentionMode: "COMPLIANCE"
      retentionDays: 2555  # 7 years

Step 6: Generate Compliance Reports

Extract compliance-specific reports from your audit trail:

# SOC 2 access control report
npx @authensor/safeclaw audit report \
  --framework soc2 \
  --period "2026-Q1" \
  --output soc2-q1-report.pdf

HIPAA access audit
npx @authensor/safeclaw audit report \
  --framework hipaa \
  --period "2026-02" \
  --include-phi-access \
  --output hipaa-feb-audit.pdf

ISO 27001 evidence package
npx @authensor/safeclaw audit report \
  --framework iso27001 \
  --period "2026-01-01:2026-02-13" \
  --include-chain-verification \
  --output iso27001-evidence.zip

Why SafeClaw

• 446 tests ensuring log completeness, format correctness, and chain integrity
• Deny-by-default — every action (attempted and completed) is logged for complete audit coverage
• Sub-millisecond evaluation — logging adds negligible overhead to agent operations
• Hash-chained audit trail — tamper-proof logs that satisfy the strictest compliance frameworks
• Works with Claude AND OpenAI — one logging configuration provides compliance evidence across all AI providers

Cross-References

• How to Maintain Tamper-Proof Audit Trails for AI Agents
• Compliance Audit Evidence Export
• SOC 2 Agent Controls
• HIPAA Agent Safeguards
• ISO 27001 Agent Security