Verifiable Pipeline Audit Trail#

This template is the cleanest public proof path in the current toolchain. It generates audit exports, verifies a good file, and demonstrates that tampering is detected both when event data changes and when the Merkle root changes.

What Problem It Solves#

Use this template when you need to answer:

• What does a VEX audit export look like at a high level?
• How do I verify an exported audit file with the public CLI?
• What failure mode do I get if an event changes?
• What failure mode do I get if only the Merkle root changes?

Uses#

• CLI

Prerequisites#

• Rust toolchain
• A clone of the vex workspace
• The vex CLI available on your PATH, or the workspace built locally

Step 1: Generate Evaluation Files#

The workspace includes a purpose-built example generator for CLI verification evaluation:

cargo run --example gen_audit_cli

Expected files:

• audit_valid.json
• audit_tampered.json
• audit_tampered_root.json

Expected console hints from the generator:

vex verify -a audit_valid.json          # Should pass
vex verify -a audit_tampered.json       # Should fail (hash mismatch)
vex verify -a audit_tampered_root.json  # Should fail (root mismatch)

Artifact produced:

• Three audit exports that exercise the current verification path

Step 2: Verify the Known-Good Audit#

vex verify --audit audit_valid.json

Expected output includes:

File: audit_valid.json
Events: 3
Merkle Root (File): <root>
✓ Merkle tree & Audit chain verified successfully.

What this proves:

• Each event hash is internally consistent
• Each chained previous_hash link is consistent
• The stored Merkle root matches the recomputed root

Step 3: Verify the Tampered Event File#

vex verify --audit audit_tampered.json

Expected failure:

Event hash mismatch at event <event-id>: expected <hash>, got <hash>

What changed:

• The event payload was modified
• The recorded hash was not recomputed

Step 4: Verify the Tampered Root File#

vex verify --audit audit_tampered_root.json

Expected failure:

Merkle root mismatch! File: fake_root_abc123, Calculated: <real-root>

What changed:

• The events still hash correctly
• The top-level Merkle root was replaced

Optional: Print Event Details#

Use --detailed if you want the first ten events listed after a successful verification:

vex verify --audit audit_valid.json --detailed

Expected detail format:

1. AgentCreated [abcd1234] @ 2026-04-04T10:30:00Z
2. AgentExecuted [ef567890] @ 2026-04-04T10:30:01Z

What Artifact Is Produced#

The verification artifact is the CLI result itself:

• success for an intact chain
• deterministic failure for tampered data
• deterministic failure for a tampered Merkle root

Current Limitations#

• This template proves verification and tamper detection. It does not, by itself, stand up a long-running API service.
• The exact JSON export is easiest to obtain through AuditStore::export() or the gen_audit_cli example rather than manual authoring.
• The CLI verifies integrity of the exported audit chain; it is not a live stream verifier.