ValGuard.ai logoValGuard.ai
Operations~8 min read

How to verify guardrail proof

Signed evidence envelopes prove that configured validators ran for a request without storing the raw prompt in the proof. This tutorial walks the Growth+ path from a live request through the Proof panel, Settings export, and offline valguard-cli verify-proof.

By the end, you will know:

  • Where proof appears on request detail and what fields mean
  • How to verify a signature in the UI and download JSON
  • How to export a date window for auditors
  • How to verify offline with the CLI using the same HMAC secret model
  • What language to use (and avoid) when describing evidence to stakeholders
UI note: In current UI you may see both labels: Playbooks and Orchestration (same section, depending on plan/version). Agent creation is in Dashboard -> Agents -> Create agent. If a guide mentions Validation logs, open Dashboard -> Logs and apply filters.

  1. 1Prerequisites

    • Growth+ (or higher) with analytics enabled — Proof panel and export are gated on analytics
    • At least one agent with validators that has recent traffic
    • Optional: valguard-cli built from apps/proxy for offline verify
    • Platform secret available to operators: EVIDENCE_HMAC_SECRET or fallback OUTBOUND_WEBHOOK_HMAC_SECRET

  2. 2Steps

    Step 1: Open a request that ran validators

    Go to Dashboard → Requests and open a completed request for an agent with output or input validation. Prefer a request that blocked or warned so verdicts are non-empty.

    Step 2: Open the Proof panel

    On request detail, find Proof. You should see policy snapshot hash, engine version, digests, ordered verdicts, and verify / download actions.

    Request detail Proof panel with verify and download controls

    If the panel shows proof unavailable, the request may predate migration 000121, lack analytics entitlement, or failed to persist evidence. Send a new request after migrate and retry.

    Step 3: Verify the signature in the UI

    Click Verify signature. A successful check confirms the HMAC matches the sealed payload for this org key_id. A failure means wrong secret, tampered payload, or org mismatch — treat it as an incident, not a soft warning.

    Step 4: Download the envelope JSON

    Click Download JSON and save the file. Do not reformat the JSON before offline verify; canonical bytes matter for HMAC.

    Step 5: Confirm workspace evidence settings

    Go to Dashboard → Settings → Guardrail evidence. Note the current key_id and rotation notice. Key rotation is an operator action; envelopes remain verifiable under the key_id they were signed with.

    Step 6: Export an auditor window

    Pick a from / to range and export. Only admins can export. Use this for monthly packs or incident holds. Pair with the monthly auditor evidence export playbook when you need a narrative package.

    Step 7: Verify offline with the CLI

    On a machine with the same evidence secret as the deployment:

    cd apps/proxy
go run ./cmd/valguard-cli verify-proof --file /path/to/envelope.json

    Success means the signature matches. It does not mean absolute non-repudiation or a compliance certification. Read how to prove AI guardrails actually executed for claim language.

    Step 8: Hand off to a third party (optional)

    If an external reviewer will verify, use third-party verifier handoff. Share the export and CLI steps. Do not claim Merkle or ZK verification unless that product exists.

  3. 3Diagram / Flow

  4. 4Configuration Examples

    Ensure evidence secret is set on web and proxy (same value):

    # Preferred dedicated secret
EVIDENCE_HMAC_SECRET=...
# Fallback if unset: OUTBOUND_WEBHOOK_HMAC_SECRET

  5. 5Common Pitfalls

    • Calling evidence “absolute non-repudiation” in customer or regulator copy
    • Expecting Proof on Free plan without analytics
    • Re-marshaling downloaded JSON before CLI verify
    • Assuming missing envelopes mean validators did not run historically before migration 000121

  6. 6Next Steps

What's next?