Compliance Evidence

TapPass’s compliance story rests on mechanisms that exist in the server itself: a hash-chained, dual-signed audit trail, cryptographic erasure for GDPR, configurable retention, and policy what-if replay. This page documents what each mechanism does and which endpoint or CLI command produces the evidence.

Every governed event is appended to the audit trail with three integrity mechanisms:

The signing key lives at TAPPASS_AUDIT_SIGNING_KEY (or is auto-generated in TAPPASS_KEYS_DIR, default keys/); set TAPPASS_AUDIT_KEY_PASSWORD to keep the PEM encrypted at rest.

GET /api/audit/integrity recomputes each event’s hash, checks chain linkage end-to-end, and verifies event signatures. It is org-scoped, requires a developer role, and results are cached for 5 minutes to prevent DoS via repeated full-chain scans.

curl -s -H "Authorization: Bearer $TOKEN" \
  https://tappass.example.com/api/audit/integrity | python -m json.tool

Response shape:

{
  "status": "intact",            // or "compromised" (or "empty" before any events)
  "events": 15432,
  "valid": 15432,
  "broken": 0,
  "broken_events": [],           // [{line, event_id, reason: chain_broken|content_modified|...}]
  "chain_length": 15432,
  "current_head": "a1b2c3..."
}

broken_events distinguishes chain_broken (a _prev_hash no longer matches its predecessor, insertion, deletion, or reordering) from content_modified (recomputed hash differs, fields were edited).

External auditors can verify signatures without trusting the server:

curl -s https://tappass.example.com/api/audit/signing-key | python -m json.tool

Returns the audit public keys with usage instructions.

Evidence extraction is a query, not a separate instrumentation effort:

The CLI equivalent is tappass audit list --event-type pii_detected --since 30d.

Erasure is a two-step, receipt-backed process under /api/compliance/gdpr:

Execution replaces PII fields with [ERASED:GDPR-Art17] tombstones (cryptographic erasure) across the audit store, the JSONL log, and vault credentials. It then produces a receipt, data subject, executor, counts of erased events/records/credentials, and a hash of the receipt, which is itself recorded in the (signed) audit trail as an erasure-executed event. The tombstone preserves the chain: the event still hashes and verifies, only the personal data is gone.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  https://tappass.example.com/api/compliance/gdpr/dsar \
  -d '{"subject": "user@example.com"}'

Exports everything the trail holds about a data subject.

Query the trail for processing evidence: pii_detected events carry agent ID, entity types, and the action taken (redacted / blocked / allowed); LLM-call events show which provider received data. See the audit query endpoints above.

TAPPASS_AUDIT_RETENTION_DAYS (default 365, 0 = forever) sets how long audit records are kept. Retention is operator-triggered, there is no background scheduler, via the settings API:

Rotation (TAPPASS_AUDIT_ROTATION_MAX_MB, default 100) and optional archiving (local/S3/Azure Blob, with gzip) are configured in the same retention config.

• Approval workflows (/api/approvals, CLI tappass approvals) give humans an approve/deny gate on governed actions, with every decision written to the audit trail.
• Trust scoring (GET /api/trust/scores, GET /api/trust/scores/{agent_uuid}, GET /api/trust/alerts) provides continuous per-agent oversight signals derived from audit events.
• Policy replay (POST /api/audit/replay, plus /api/audit/replay/batch for impact analysis and /api/audit/playground/test for sandbox testing) re-runs past events against proposed policy, what-if analysis before a policy change ships, with no audit writes and no side effects. CLI: tappass audit replay <event_id> --policy-overrides @overrides.json.

The integrity endpoint above is the core evidence: a point-in-time, cryptographically verified statement that the audit trail is intact, repeatable on demand, with the signing keys published for independent verification. Audit event samples (GET /api/audit?limit=1000) plus the dual-signature scheme demonstrate that logging controls operated over the period.

Self-hosted deployments ship a helper at deploy/on-prem/scripts/generate-compliance-evidence.sh. It runs the unit and security test suites, the eval corpus, Bandit SAST, and pip-audit SCA, then writes the raw results plus a SUMMARY.md into a compliance-evidence/ directory, a dated artifact bundle you can hand to auditors alongside /api/audit/integrity output:

./deploy/on-prem/scripts/generate-compliance-evidence.sh
# → compliance-evidence/{unit-tests.xml, security-tests.xml, eval-corpus.json,
#                      bandit-sast.json, pip-audit-sca.json, SUMMARY.md}