Ledger

Ledger keeps a record of a run that can’t be changed without it showing. It’s a built-in plugin in VPN Works since 0.5.0: an Observer that seals every event as it happens, and an Advisor that checks the record and names the line anyone changed.

After an incident or in an audit, “where did this program send data?” needs an answer people believe. An ordinary log can be edited by anyone who can reach it, and a careful edit leaves no mark. Ledger makes every edit leave one.

vpnw guard --plugin ledger --policy agent.toml -- ./my-agent
vpnw verify ~/.local/state/vpnw/ledger/r-3f9a1c.ledger

How It Seals a Run

Ledger writes each event to its own file the moment it arrives, exactly as vpnw recorded it, with a SHA-256 hash that covers the line before it. Every 100 events, and at the end, it writes a checkpoint, and when the run finishes it writes an end line. Each of those is a link in the same chain, so nothing in the file can be changed, removed, added or moved without the chain breaking right there.

Two copies go somewhere else. Each checkpoint is also written into the run’s trace, and at the end Ledger prints the ledger’s path and its last hash. Kept out of reach, either one catches the one thing a chain can’t: a whole ledger written again from scratch.

Writes go straight to the file. A run that’s killed halfway leaves a ledger that ends where the run did, and everything in it still checks out.

Signed by the Kernel

Since 0.10.0 every checkpoint and the end line are signed. The kernel holds the key, one per machine, and Ledger never sees it: it asks the kernel for a signature, and the kernel signs only in Ledger’s name and for the run it is part of. So anyone with the public key can check a ledger, and a ledger written again after a checkpoint, hashes and all, fails at that checkpoint.

vpnw key                                                  # this machine's public key
vpnw verify r-3f9a1c.ledger --key vpnw-ed25519:J+BD…      # on any machine

On the machine that ran it, verify checks against that machine’s key without being asked.

How It Checks

vpnw verify reads the ledger line by line, as it is on disk. Its answer is one of three:

• intact: every line matches its hash, the run ended normally, and the checkpoint copies and the kept hash, when given, match too.
• CHANGED: with the file and the line. An edited event, a line removed, copied or added, two lines swapped, a checkpoint removed or added, the header or the end line edited, bytes added after the end. When the chain was written again from some line on, the copies in the trace catch it, and the trace’s own events name the line.
• cut short: the ledger stops without an end line, or halfway through a line. The run was killed there, or someone removed the end; what is there checks out.

With a key to check against, a signature that’s missing, moved or doesn’t match is CHANGED too, and so is a ledger written again unsigned or with another key.

Built as Plugins

Ledger is two plugins, and neither has any way in that other plugins don’t. The Observer writes its file through the file.write permission, new in 0.5.0 and open to every plugin: vpnw creates one new file for the plugin, and the plugin can only add to it. It can’t read it, move around in it, or reach any other file. The checker reads the ledger through another addition every Advisor can use: it’s handed the lines of its files exactly as they are, since a checker that sees a tidied-up copy can’t tell what changed.

What It Can’t Show

Signatures hold against everyone who can’t read the key: whoever holds the ledger later, a reviewer, another user of the machine. The program being watched is another matter. vpnw runs it as your user and limits the network, not files, so while it runs it could read the key too. Against the program itself, the copies are the answer: keep the last hash, or the trace, somewhere it can’t change.

Earlier

In VPN Works 0.2.0, Ledger caught 12 of 12 edits to an AI agent’s sealed record at the exact line. The case study