Audit event schema
ThreatLens records two complementary things for every governed interaction:
- The decision record — one immutable row per request capturing what was decided and why.
- Governance events — an append-only stream of typed events (classification, policy, routing, identity, admin changes) that can be streamed to a SIEM.
Together they form the evidence trail behind every decision. For the admin view, see the audit log.
The decision record
One record is written per governed request. It is designed to answer "what did the model see, where did it go, and why" — without ever storing the raw sensitive content.
| Field | Meaning |
|---|---|
request_id | Unique ID for the request |
ts | Timestamp |
user_email, user_group | Who made the request |
client, client_type | Where it came from (workspace, gateway, files…) |
classification | The resolved data class |
risk_level, risk_score | Inherent risk of that class + computed score |
decision | The action actually applied (policy actions) |
intended_decision | What enforce mode would have done (used in monitor mode) |
shadow_action | The would-be action recorded while monitoring |
enforcement_mode | monitor or enforce at the time |
policy_code, policy_version | The rule that fired + matrix version |
decision_reason | Human-readable explanation |
provider, model, model_role | The destination resolved |
requested_destination, approved_destination, actual_destination | Where it was asked to go, what was approved, where it actually went |
redaction_details, output_dlp | What was masked inbound and outbound |
prompt_tokens, completion_tokens, tokens, cost | Usage and cost |
prompt_hash | Hash of the prompt (not the content itself) |
prev_hash, record_hash | Tamper-evident hash chain |
retention_expiry | When the record is eligible for deletion |
fp_reported_at, fp_reporter_email, fp_reason | False-positive feedback, if reported |
Records are append-only and chained (prev_hash → record_hash) so tampering is detectable. ThreatLens stores hashes and redacted excerpts, not raw sensitive payloads.
Governance event taxonomy
Events carry a type, a severity (info · low · medium · high · critical), a source, and a structured payload. The catalog:
Request lifecycle
| Event | When |
|---|---|
prompt.submitted | A request enters the gateway |
sensitive_data.detected | A detector matched sensitive content |
prompt_injection.detected | A prompt-injection pattern matched |
policy.evaluated | The matrix was evaluated for the request |
policy.violation | The request breached policy |
Routing & model
| Event | When |
|---|---|
model.route.selected | A destination/model was chosen |
model.request.allowed | Sent as-is |
model.request.redacted | Sent after redaction |
model.request.blocked | Stopped before the model |
Grounding (retrieval)
| Event | When |
|---|---|
grounding.document.retrieved | A source document was retrieved |
grounding.chunk.allowed | A chunk passed access-trim + DLP |
grounding.chunk.blocked | A chunk was withheld (ACL or DLP) |
grounding.answer.low_confidence | The grounded answer was low-confidence |
Identity & access
| Event | When |
|---|---|
user.login, user.login_failed, user.logout | Local/admin sign-in lifecycle |
user.sso_login | SSO sign-in |
user.invited, user.enabled, user.disabled, user.deleted | User lifecycle |
user.role_changed | A role/group assignment changed |
Administration
| Event | When |
|---|---|
admin.setting_changed | Any control-plane change — policy matrix, providers, custom rules, SSO, vault, password/lockout admin actions, and more |
Control-plane changes are also recorded with old_value / new_value, source IP, and actor for the RBAC audit log — every administrative mutation is captured.
Event types under agent.* (plan created, tool-call requested/allowed/blocked, approval required, action executed) are reserved for governed agentic workflows.
Export
Events can be streamed to your SIEM via a governed destination. Export requires the export_audit_logs permission.