Audit log

Audit log

The Audit log is the compliance evidence trail.

Every governed event — every LLM call, every tool call, every Pipeline step decision — produces a hash-chained, signed audit row. Tamper-detectable. Verifiable offline. The single source of truth for "what did this Agent actually do?"

At a glance

Records	every Pipeline step decision (allow / deny / redact) on every call across every Session
Carries	trace_id, session_id, agent_id, project_id, policy_version, signed mandate (Ed25519)
Format	hash-chained: each row includes SHA-256 of the previous row's hash
Verifiable	offline via JWKS — auditors don't need TapPass infrastructure to verify a row
Used for	compliance reports, drift baselines, incident response, cross-customer Intelligence (2027)

What gets recorded

Every governed call produces one or more audit rows. Per call you see:

{
  "audit_id":         "audit-9f1c…",
  "trace_id":         "trace-abc…",      // one call (LLM or tool)
  "session_id":       "sess-xyz…",       // which Session this call was part of
  "agent_id":         "support-bot-v2",
  "project_id":       "eu-customer-support",
  "policy_version":   1042,

  "phase":            "before",          // before / during / after
  "step_id":          "detect_pii",
  "decision":         "allow",
  "reason":           null,              // populated on deny / redact

  "input_summary":    {...},             // PII-redacted preview
  "output_summary":   {...},             // PII-redacted preview

  "mandate": {
    "issued_at":      "...",
    "expires_at":     "...",
    "signature":      "ed25519:..."
  },

  "prev_hash":        "sha256:abc123…",  // chain link
  "this_hash":        "sha256:def456…"
}

Every row links to the previous via prev_hash. Forge or delete a row → chain breaks → tamper detected.

How verification works

The audit log is offline-verifiable:

1. TapPass publishes its public keys at a JWKS endpoint (.well-known/jwks.json).
2. An auditor downloads the audit log + the JWKS.
3. For each row, they verify: (a) the Ed25519 mandate signature against the published key, (b) the prev_hash matches the previous row's this_hash.
4. If any row fails, the chain is broken → forensic alarm.

This means even if TapPass's servers were compromised, an auditor with a snapshot of the log + the JWKS can independently prove which actions were authorized.

Three layers of integrity

The audit log defends against three different threat models:

Layer	Mechanism	Protects against
Hash chain	Each row includes SHA-256 of previous row	Insertion / deletion / reordering
Mandate signatures	Ed25519 on each event's canonical hash	Forged events (without signing key)
Checkpoint anchoring	Signed checkpoints written every N events	Full chain replacement

Same machinery that backs the live engineering audit — see Audit trail internals for the implementation deep-dive.

What it's used for

                AUDIT LOG
                    │
        ┌───────────┼───────────┬────────────┬─────────────┐
        ▼           ▼           ▼            ▼             ▼
   Compliance   Drift       Incident      Operator     Cross-customer
   reports      baselines   response      dashboards   intelligence
                                                       (2027)

Use case	What the audit log provides
SOC 2 / ISO 42001 / EU AI Act reports	One-click export filtered by control + time range. Auditors verify offline via JWKS.
Drift baselines	Pre-deployment evaluation establishes typical tool-call distribution per Session. Production audit feeds drift comparison.
Incident response	Filter by session_id or trace_id → reconstruct exactly what an Agent did, in order, with every decision's reason.
Operator dashboards	Live trace viewer; per-Sandbox / per-Agent / per-Project / per-Session filtering.
Cross-customer Intelligence (2027)	Anonymized cross-tenant pattern detection (opt-in).

Where it lives

• Per-org append-only store (Postgres + offline cold storage for retention).
• Per-event canonical JSON (deterministic serialization for signature verification).
• Retention: configurable per Project policy; minimum 7 years for SOC 2.

Surfaces

Persona	Surface	What you do
Auditor	Dashboard audit views	Browse, filter, export. Filtered by team membership + scope.
Operator	tappass audit tail	Live tail; --filter session_id=…
Operator	tappass audit export --pack soc2-cc6.1 --range 30d	One-click compliance report
Auditor (offline)	JWKS endpoint + downloaded log	Independently verify integrity

Related concepts

• Records every event from → Sessions inside Sandboxes running Agents in Projects
• Decisions tagged with → which Policy version + which Pipeline step
• Signed by → the Policy engine at the moment of decision
• Read by → Auditors (filtered by team role + scope)