agent-audit-log 🛡️

Tamper-Evident Audit Logging for AI Agent Sessions

A Project by SILICON VALLEY GLOBAL PH INC

agent-audit-log captures a structured, chronological, SHA-256 hash-chained record of everything an AI agent read, wrote, or executed during a session, exportable as a PR review artifact.

⚠️ The Problem

When an AI agent works autonomously across a session, there is usually no reliable record of what it actually touched. If something breaks, or a reviewer wants to sanity-check what happened before merging, they are left reconstructing intent from a diff and a chat transcript. agent-audit-log captures a structured, chronological, chain-hashed record of the agent's actions as they happen, so a session can be replayed or audited after the fact — acting as a black box recorder for agent work.

🧩 Key Architecture Pillars

File Access Capture (src/capture/fileWatcher.ts)

Hooks into file read, write, and delete operations during an agent session, recording relative path, operation type, timestamp, file size, and SHA-256 content hashes.

Command Capture (src/capture/commandLog.ts)

Records every shell and CLI command executed by the agent, including command arguments, exit codes, execution duration, and standard output/error snippets.

Tamper-Evident Chain (src/log/tamperEvidence.ts)

Hashes each log entry together with the previous entry's hash in a cryptographic SHA-256 hash chain, so any after-the-fact edit, insertion, or deletion breaks the chain and is detected via verification.

Redaction & Fail-Safe (src/redact/sanitizer.ts)

Scans captured commands and file payloads for likely API keys, JWT tokens, AWS credentials, and PII before writing to the log, redacting sensitive data and logging warnings if capture attachment drops.

Export & Reporting (src/export/reportGenerator.ts)

Exports sealed audit logs as structured raw JSON (audit-log.json), human-readable Markdown (audit-log.md), and formatted HTML (audit-log.html) reports suitable for PR review artifacts.

Session Wrapper (src/cli/index.ts)

CLI entry point that wraps an agent session command (agent-audit-log run -- <agent command>), manages real-time event capture, finalizes and seals the hash chain on exit, and provides log verification tools.

📊 Output Formats

• audit-log.json: Structured, raw SHA-256 hash-chained log data format for programmatic ingestion and automated compliance verification.
• audit-log.md: Human-readable Markdown summary with PR-ready tables, file access lists, command timelines, and tamper-verification badges.
• audit-log.html: Formatted web artifact for browser viewing and security compliance archives.

📦 Installation

npm install @siliconvalleyglobal/agent-audit-log

💻 Usage Example

1. Wrap an AI Agent Session

Wrap any AI agent command (or script) with agent-audit-log:

npx agent-audit-log run -- npx claude-code "Refactor authentication flow"

2. Verify Log Chain Integrity

Verify that an audit log has not been edited or tampered with:

npx agent-audit-log verify .agent-audit-log/audit-log.json

3. Review Artifact Output

Sealed audit logs are exported to .agent-audit-log/:

• .agent-audit-log/audit-log.json
• .agent-audit-log/audit-log.md
• .agent-audit-log/audit-log.html

📄 License

Distributed under the MIT License. See LICENSE for more information.

Copyright (c) 2026 SILICON VALLEY GLOBAL PH INC.