Problem
NemoClaw provides container-level isolation but has no forensic audit capability. Container logs are not tamper-evident — if an attacker or misconfigured process modifies log entries, there is no way to detect the tampering. Compliance teams reviewing agent activity have no verifiable record of what happened inside the sandbox.
Proposal
Add a tamper-evident, hash-chained JSONL audit logger under nemoclaw/src/security/ that can be wired into sandbox events.
Design
Hash chain: Each audit entry includes a SHA-256 hash of the previous entry's payload. Modifying any entry breaks all downstream hashes, making tampering detectable.
Entry structure:
seq — monotonic sequence numberchain_id — random hex identifier unique per audit instanceprev_hash — hash of the previous entry (empty for the first entry)entry_hash — SHA-256 of the canonical JSON payload (excluding entry_hash itself)type — event type stringtime — ISO 8601 timestampdata — arbitrary JSON payload
Capabilities:
- Append-only JSONL persistence
verifyChain() — reads the file and validates every hash link, detecting any tampering or gapsexportEntries(since, limit) — export entries by sequence number rangetailEntries(n) — return the last N entries- Resume chain state from existing file on startup
Scope
- New file:
nemoclaw/src/security/audit-chain.ts
- New file:
nemoclaw/src/security/audit-chain.test.ts
- New file:
docs/reference/audit-chain.md
- No changes to existing NemoClaw code
- Full Vitest test coverage including tamper detection and error paths
Non-goals
- REST API endpoints for audit queries (future work)
- Integration with OpenShell's event system (consumer decides when to log)
- Log rotation or archival (out of scope for initial module)
Problem
NemoClaw provides container-level isolation but has no forensic audit capability. Container logs are not tamper-evident — if an attacker or misconfigured process modifies log entries, there is no way to detect the tampering. Compliance teams reviewing agent activity have no verifiable record of what happened inside the sandbox.
Proposal
Add a tamper-evident, hash-chained JSONL audit logger under
nemoclaw/src/security/that can be wired into sandbox events.Design
Hash chain: Each audit entry includes a SHA-256 hash of the previous entry's payload. Modifying any entry breaks all downstream hashes, making tampering detectable.
Entry structure:
seq— monotonic sequence numberchain_id— random hex identifier unique per audit instanceprev_hash— hash of the previous entry (empty for the first entry)entry_hash— SHA-256 of the canonical JSON payload (excluding entry_hash itself)type— event type stringtime— ISO 8601 timestampdata— arbitrary JSON payloadCapabilities:
verifyChain()— reads the file and validates every hash link, detecting any tampering or gapsexportEntries(since, limit)— export entries by sequence number rangetailEntries(n)— return the last N entriesScope
nemoclaw/src/security/audit-chain.tsnemoclaw/src/security/audit-chain.test.tsdocs/reference/audit-chain.mdNon-goals