Waterwall Reversible-tokenization egress proxy for AI coding agents file an issue repo v2
📄 View as Markdown (for AI)

CLI Reference

The waterwall command is the venv console script (/opt/waterwall/.venv/bin/waterwall, shim at /opt/waterwall/bin/waterwall). Symlink it onto PATH for convenience — see the Runbook. Commands that read protected paths (signing.key, /var/log/waterwall) need root.

Commands

waterwall verify-install [--runtime]
waterwall verify-chain   <log>  --pubkey <pub>
waterwall verify-receipt <file> --pubkey <pub>
waterwall export-evidence --chain <log> --policy <patterns.py> \
    --pubkey <pub> --signing-key <key> -o <out.tar.gz> \
    [--receipts-dir D] [--manifests-dir D] [--since YYYY-MM-DD] [--until YYYY-MM-DD]
waterwall verify-evidence <bundle.tar.gz> --pubkey <pub>
waterwall regen-ca [--hosts-file permitted_hosts.yaml] [--out-dir /etc/waterwall]
waterwall rotate-chain [--chain-path <log>]
waterwall pre-launch-hook
waterwall dashboard
Command What it does
verify-install [--runtime] 10 health checks. Startup mode binds the ports; --runtime reads the live admin state and re-validates the on-disk CA + listener.
verify-chain Walks the chain log: prev_hash continuity plus, for each checkpoint, recomputes the root from the line's own content before verifying its Ed25519 signature. An empty log fails (not a vacuous OK).
verify-receipt Verifies a single Ed25519 action receipt against the public key.
export-evidence Produces a tarball of chain + receipts + manifests + policy + pubkey with an Ed25519-signed MANIFEST. --signing-key is required. --since/--until filter receipts/manifests by date; the chain is always included in full.
verify-evidence Full bundle audit: per-file SHA-256 → MANIFEST signature → chain crypto → MANIFEST chain-stats cross-check → per-receipt signatures → receipt-to-chain cross-reference → bundled-pubkey identity. Any failure short-circuits with a reason.
regen-ca Regenerates the Name-Constrained RSA-4096 CA so its permittedSubtrees match the current host list. Generates into a temp dir and swaps only on success.
rotate-chain Archives the current chain with a properly-chained terminal entry and starts fresh. Proxy must be stopped.
pre-launch-hook Reads /healthz; emits a SessionStart warning and exits non-zero when the proxy is down or kill-switched. Used by the launch wrapper.
dashboard Launches the TUI.

Verifying a running deployment

sudo waterwall verify-install --runtime
sudo waterwall verify-chain    /var/log/waterwall/proxy.jsonl --pubkey /etc/waterwall/signing.pub
sudo waterwall export-evidence --chain /var/log/waterwall/proxy.jsonl --policy /etc/waterwall/patterns.py \
    --pubkey /etc/waterwall/signing.pub --signing-key /etc/waterwall/signing.key -o /tmp/evidence.tar.gz
sudo waterwall verify-evidence /tmp/evidence.tar.gz --pubkey /etc/waterwall/signing.pub

Anyone holding only the public key can run verify-chain, verify-receipt, and verify-evidence to independently audit the evidence — that is the point of the signed, hash-chained design.