Openclaw Ledger

Tamper-evident audit trail for agent sessions. Hash-chained logs of workspace changes with cryptographic verification. Know exactly what changed, when, and detect if anyone altered the record. Free alert layer — upgrade to openclaw-ledger-pro for freeze, forensics, and chain restoration.

Security Scan

The skill largely implements a local hash‑chained ledger as advertised, but there are small but important mismatches (undeclared environment variable use, marketing claims about 'pro' countermeasures, and broad filesystem access) that merit caution before installing into production workspaces.

Purpose & Capability

Name/description match the delivered capability: the included Python script implements init/record/verify/log/status for a hash-chained audit trail. However, the README and the script header advertise additional capabilities (freeze, quarantine, forensics, restoration) that are not exposed in the SKILL.md command list; source/homepage are unknown. Overall the core purpose is implemented, but marketing claims and provenance are inconsistent.

Instruction Scope

The runtime instructions call the included script (python3 {baseDir}/scripts/ledger.py) which walks the entire workspace and snapshots filenames, sizes, and SHA‑256 hashes. The code writes local artifacts (.ledger/chain.jsonl and .ledger/session.json) containing file paths and hashes. The script also reads an environment variable OPENCLAW_WORKSPACE to resolve the workspace if --workspace is not supplied, but this env var is not declared in requires.env or documented in SKILL.md — a mismatch. The behavior is local-only (no network libs observed) but the broad filesystem scanning and undisclosed env usage are scope concerns.

Install Mechanism

No install spec is provided (instruction-only), and the skill includes a Python script using only the standard library. README suggests manual git clone/copy. No remote downloads, package installs, or extract-from-URL operations were found in the provided files.

Credentials

The registry metadata declares no required env vars, yet the code consults OPENCLAW_WORKSPACE to discover the workspace path. The script requires only python3 (reasonable) but will read the entire workspace tree (file names and hashes), which can expose sensitive project structure. No network credentials are requested, which is appropriate for a local ledger, but the undeclared env var and wide read access are disproportionate to the absence of any documentation about privacy or retention.

Persistence & Privilege

The skill does not request always:true and uses only its own workspace-scoped .ledger directory to store chain/session artifacts. There is no evidence it modifies other skills' configuration or system-wide settings. It may create quarantine/frozen directories under the workspace (names appear in code), but actions are local and confined to the target workspace.

What to consider before installing

Before installing or running this skill: (1) Review the full script locally — especially the truncated tail — to confirm there are no file‑moving or deletion operations you don't expect (search for 'shutil.move', 'os.remove', '.quarantine', 'frozen', 'restore', etc.). (2) Note that the ledger records file paths and SHA‑256 hashes in .ledger/session.json and chain.jsonl — this can reveal directory structure and filenames even though it does not store file contents. Don't point it at sensitive or production workspaces until you are comfortable with that data being stored locally. (3) The code will honor OPENCLAW_WORKSPACE if set; this env var was not declared in the skill metadata — be aware of implicit workspace selection. (4) Because the source/homepage is unknown, run the script first in an isolated test workspace or container and verify there are no unexpected network calls or destructive actions. (5) If you plan to rely on the tool for security/auditing, confirm provenance (official repo or signed releases) and consider code review or vendor verification before trusting ledger contents for forensics.

Tamper-evident audit trail for agent workspaces. Every workspace change is recorded in a hash-chained log — if anyone alters an entry, the chain breaks and you know.

The Problem

Agents modify files, execute commands, install skills — and leave no verifiable record. If something goes wrong, you can't trace what happened. If logs exist, nothing proves they haven't been altered after the fact.

Commands

Initialize

Create the ledger and snapshot current workspace state.

python3 {baseDir}/scripts/ledger.py init --workspace /path/to/workspace

Record Changes

Snapshot current state and log all changes since last record.

python3 {baseDir}/scripts/ledger.py record --workspace /path/to/workspace
python3 {baseDir}/scripts/ledger.py record -m "Installed new skill" --workspace /path/to/workspace

Verify Chain

Verify the hash chain is intact — no entries tampered with.

python3 {baseDir}/scripts/ledger.py verify --workspace /path/to/workspace

View Log

Show recent ledger entries.

python3 {baseDir}/scripts/ledger.py log --workspace /path/to/workspace
python3 {baseDir}/scripts/ledger.py log -n 20 --workspace /path/to/workspace

Quick Status

python3 {baseDir}/scripts/ledger.py status --workspace /path/to/workspace

How It Works

Each entry contains:

• Timestamp
• SHA-256 hash of the previous entry
• Event type and data (file changes, snapshots)

If any entry is modified, inserted, or deleted, the hash chain breaks and verify detects it.

Exit Codes

• 0 — Clean / chain intact
• 1 — No ledger or minor issues
• 2 — Chain tampered / corrupt entries

No External Dependencies

Python standard library only. No pip install. No network calls. Everything runs locally.

Cross-Platform

Works with OpenClaw, Claude Code, Cursor, and any tool using the Agent Skills specification.