An auditor asked a simple question after a refunds agent mishandled a disputed claim: show that the validators configured for that agent actually ran on the requests in the incident window. The team had dashboards, Slack alerts, and a policy document. What they did not have was a signed record that tied a specific policy snapshot and an ordered list of verdicts to those request IDs. Reconstructing the story from editable logs took days and still left room for doubt about whether a rule had been disabled for part of the window.
That is the gap proof of guardrail execution closes. ValGuard can attach an HMAC-signed evidence envelope to each request: policy snapshot hash, engine version, ordered validator verdicts, and SHA-256 digests of request and response. Digests only. No raw prompts. No PII payload retention in the envelope. This pillar explains what the envelope contains, how to verify it in the dashboard and offline, how to export a window for auditors, and what the product deliberately does not claim.
For the product story of why relative agent ranking matters alongside audit trails, see agent health score. For metadata-only compliance posture, see metadata-only evidence vs payload retention.
Why “we have validators” is not evidence
Most AI stacks can show that a rule catalog exists. Fewer can show that a named rule produced a pass, warn, or block on a named request at a named time, under a named configuration version. Gateway access logs prove a request hit a proxy. They do not prove which validators ran or what they decided.
When something goes wrong, stakeholders ask three questions:
- Which rules were active?
- Did those rules evaluate this payload?
- Can an independent party re-check the signature without trusting a screenshot?
Evidence envelopes answer those questions with a stable JSON shape (typ: valguard-evidence/1) and an HMAC over the exact payload bytes. The dashboard Proof panel verifies the signature. Offline, valguard-cli verify-proof --file envelope.json does the same with the deployment secret.
What the envelope contains
| Field | Role |
|---|---|
request_id / org_id | Tenant and request binding |
checked_at | When evidence was sealed |
engine_version | Validation engine build identity |
policy_snapshot_hash | Hash of the validator config snapshot for that request |
request_digest / response_digest | SHA-256 digests (sha256:…) of the sealed payloads |
verdicts[] | Ordered rule outcomes (rule id, disposition, reason metadata without raw PII) |
key_id + signature | Org-scoped HMAC key generation and signature over the payload |
Growth+ plans that include analytics can open Request detail → Proof, verify the signature in-browser, and download the JSON. Workspace Settings → Guardrail evidence shows the current key_id, rotation notice, and a date-range export for auditor windows.
How verification works
Verification is intentionally boring:
- Recompute HMAC-SHA256 with the org key derived from
EVIDENCE_HMAC_SECRET(or the outbound webhook secret fallback) and the envelopekey_id. - Compare to the stored signature without re-marshaling the JSON in a different key order.
- Treat a mismatch as tamper or wrong secret, not as a soft warning.
That is execution evidence for this deployment. It is not absolute non-repudiation, not a court certification, and not a substitute for organizational compliance programs. Say what the envelope proves: configured validators ran and produced these verdicts under this policy snapshot. Do not say the product certifies SOC2, HIPAA, or GDPR for the customer.
Exporting a window without storing prompts
Settings export returns signed envelopes for a from/to window with admin role and analytics entitlement. Use it for monthly auditor packs and incident holds. Pair it with playbooks that keep humans in the loop when coverage is incomplete:
- Monthly auditor evidence export
- Regulator question response
- Incident proof retention
- Validator change with proof
- Third-party verifier handoff
The third-party handoff playbook documents HMAC export plus verify-proof CLI steps. It does not invent Merkle trees or ZK proofs. Those remain out of scope for this release.
Offline verify in practice
After you download an envelope from the Proof panel:
valguard-cli verify-proof --file envelope.json
The CLI uses the same secret resolution as the proxy and web app. Rotate platform secrets only with an operator process; existing envelopes stay verifiable under the key_id they were signed with. The tutorial verify guardrail proof walks UI verify, download, export, and CLI together.
Do not pretty-print or re-key the JSON before verify. HMAC is over the sealed payload bytes. If a reviewer reformats the file in an editor that reorders keys, verification fails even though the semantic content looks identical. Keep the downloaded file intact, or re-export from the API.
Policy snapshots and change management
Every envelope carries a policy_snapshot_hash. When you tighten a schema or flip a rule from shadow to enforce, new requests should show a new hash. That is how you answer “were yesterday’s rules the same as today’s?” without reconstructing dashboard clicks from memory.
Use the validator change with proof playbook to capture before/after hashes on sample requests and attach them to a change ticket. Approvers see a short note with two hashes instead of a vague “we updated validators.” If the hash does not move after a claimed change, escalate — the publish path may not have reached the proxy cache yet.
Incident holds without prompt dumps
Security and legal sometimes issue a hold on a time window. The instinct is to snapshot every prompt. Prefer confirming that request_evidence rows exist for the request IDs in that window, export the envelopes, and record the key_id generations present. Payloads, if required, come from your application retention under a separate policy. The incident proof retention playbook turns that into a checklist with a human handoff when coverage is incomplete.
This split keeps the guardrail layer aligned with zero-retention defaults while still producing artifacts an incident commander can attach to a ticket in hours, not weeks.
How this differs from gateway logs
API gateway logs answer: who called which route, with which status code, at which time. They are necessary and insufficient. They rarely record validator rule IDs, dispositions, or the configuration hash that was active. Generic audit tables that store “validation failed” as a boolean are also insufficient — they collapse rule identity and make it impossible to prove a specific PII or schema rule ran.
Evidence envelopes sit next to validation logs. Logs help engineers debug. Envelopes help auditors and external reviewers confirm integrity of a sealed decision record. Keep both. Do not treat one as a substitute for the other.
What this is not
- Not ZK proofs or a public Merkle log in v1.
- Not a claim of absolute non-repudiation.
- Not storage of customer prompts inside the evidence table.
- Not available as a Free-tier analytics surface; Proof and export follow Growth+ analytics gating.
- Not a replacement for organizational SOC2, HIPAA, or GDPR certification work.
Closing the auditor gap
The refunds incident above needed three artifacts: request IDs in the window, signed envelopes for those IDs, and a precise sentence about what HMAC evidence means. With proof of execution, that package is a Settings export plus offline verify, not a week of log archaeology. Combine it with compliance-oriented validation for the broader control narrative, and keep claim language honest so legal and security teams will actually use the feature.
Start with one Growth+ agent, send a few validated requests, open Proof, verify, download, and run verify-proof once. Then schedule a monthly export ritual with monthly auditor evidence export so the first real auditor question is not the first time anyone tries the path.
Ops detail: observability docs and ops evidence section.
Book a technical walkthrough with our team → Start free in shadow mode — no credit card →