# How to Read the Gatekeeper Evidence Packet

**One-page reviewer guide — CISO Review Bundle.** Every record in this packet is a real
audit row persisted by the deployed Gatekeeper pipeline from **synthetic inputs**
(no real PHI). Nothing is mocked or hand-authored.

## Audit flow (how a record is produced)

1. An application sends a request to Gatekeeper (either the **Scan endpoint** `/scan`
   for redaction, or the **governed LLM proxy** `/proxy/openai` for model egress).
2. Governance headers (`X-Workflow-Tag`, `X-Actor-ID`) attribute the call to a
   workflow and an actor. Calls **without** these headers are still processed and
   logged, but flagged with an `UNGOVERNED_CALL` exception.
3. Gatekeeper evaluates the active policy (e.g. `hipaa_v1.0.0`): detects PHI/PII,
   detects prompt-injection/jailbreak patterns, then **redacts**, **blocks**, or
   **allows** before any upstream model is called.
4. The decision — with redaction counts, block reason, policy version + git SHA, and
   compliance control mappings — is written to the audit log. That persisted row is
   what this packet displays; the packet renderer adds no data of its own.

## Field meanings

| Field | Meaning |
|---|---|
| `workflow_tag` | The business workflow the call belongs to (from `X-Workflow-Tag`). |
| `actor_identity` | Who made the call (from `X-Actor-ID`). |
| Provider / Model | Which pipeline stage handled the call. `gatekeeper / scan` = the redaction (Scan) endpoint; `openai / gpt-4o-mini` = the governed OpenAI proxy route. |
| Policy / Policy Version (Git SHA lineage) | The policy pack evaluated, with full version + policy git SHA (e.g. `hipaa_v1.0.0+201683f`) for lineage. |
| Decision | The enforcement outcome — see below. |
| Redaction | Per-entity-type redaction counts from the record (e.g. `PERSON ×2, DATE_TIME ×1`), or `none`. |
| Timestamp | When the gateway persisted the row (UTC). |
| Workflow Tag / Governance Status | Governed (tag + actor present) or Ungoverned. |
| Policy Violations / Exceptions | Governance exceptions (e.g. `UNGOVERNED_CALL`), the block reason for blocked calls, or `none`. |
| Reason (blocked records only) | The real `block_reason` from the persisted audit row, e.g. "Obvious jailbreak detected by pattern matching". Never omitted for a BLOCKED record. |

## Decision values

- **ALLOWED** — the request passed policy evaluation unchanged and was forwarded.
- **REDACTED** — sensitive entities were detected and replaced before anything left
  the boundary; the counts appear in the Redaction field.
- **BLOCKED** — the request violated policy (e.g. a jailbreak/prompt-injection) and
  was stopped **before** the upstream model was called. Blocked records always
  display their `block_reason`.

## Compliance control statuses

Each record maps to controls (SOC 2 `CC6.1`, `CC6.3`, `CC6.8`; HIPAA `164.312(b)`):

- **satisfied** — this record provides evidence for the control (e.g. redaction proof
  for CC6.1, jailbreak block for CC6.8, audit trail for 164.312(b)).
- **not_applicable** — the control does not apply to this record's decision (e.g.
  CC6.8 "Jailbreak block" on a record where no jailbreak was attempted).
- **unavailable** — the pipeline could not produce evidence for the control at
  generation time; it is reported rather than fabricated.

Mapping is **evidence, not proof of formal compliance status**.

## Why UNGOVERNED_CALL exists

Calls that reach the gateway **without** governance headers cannot be attributed to a
workflow or actor. Gatekeeper still processes and logs them, but stamps an
`UNGOVERNED_CALL` exception so untagged PHI usage is **loudly flagged, never silently
passed**. Record 3 of the packet demonstrates this deliberately.

## Why the Provider differs between records

Records 1 and 3 were generated through the **Gatekeeper Scan endpoint** (the redaction
pipeline — provider `gatekeeper` / model `scan`). Record 2 was generated through the
**governed OpenAI proxy route** (`/proxy/openai` — provider `openai` / model
`gpt-4o-mini`), which enforces the block decision before the upstream model is called.
All three are real persisted audit rows from the same deployed pipeline.

## Demo Access

**Frontend Demo**
https://gatekeeper-shaachi.vercel.app/

**Evidence Packet**
https://gatekeeper-shaachi.vercel.app/sample-packet

**Evidence Packet PDF**
https://gatekeeper-shaachi.vercel.app/sample-packet.pdf

**Backend API**
https://gatekeeper-production-7dd1.up.railway.app

Both `/sample-packet` and `/sample-packet.pdf` are public, unauthenticated routes —
no credentials are required for a CISO or reviewer to open them. Each load runs three
live requests against the backend API above and renders the real, freshly persisted
audit rows; nothing is cached or mocked.

## Regeneration

- Evidence export API: `POST {base}/api/v1/evidence/export` (JSON, filterable by
  `workflow_tag`), where `{base}` is the Backend API URL above.
- The committed file artifacts (`governed_packet.*`, `ungoverned_packet.*`) are
  regenerated locally via `GET /api/evidence/artifacts` (see
  `docs/SAMPLE_EVIDENCE_PACKET.md`).