Audit¶

The audit trail provides an immutable, queryable log of all significant actions in Verity. Audit records are stored in ClickHouse for high-performance time-range queries and long-term retention.

Audit Record Schema¶

Field	Type	Description
`event_id`	UUID	Unique event identifier.
`occurred_at`	datetime	When the action occurred.
`actor_id`	UUID	Verity ID of the actor who performed the action.
`actor_email`	string	Email of the actor (denormalized for query convenience).
`action`	string	Action performed (e.g. `review.decide`, `grant.revoke`, `report.generate`).
`entity_type`	string	Type of entity affected (e.g. `review_packet`, `grant`, `principal`).
`entity_id`	UUID	ID of the affected entity.
`entity_name`	string	Human-readable name of the affected entity.
`decision`	string	Decision made, if applicable (e.g. `REVOKE`, `CONFIRM`).
`justification`	string	Justification text provided by the actor (nullable).
`risk_level`	string	Risk level at the time of action (nullable).
`source_ip`	string	IP address of the request origin.
`metadata`	object	Additional context key-value data.
`regulation`	string	Applicable regulation (e.g. `SOX`, `GDPR`) (nullable).
`compliance_status`	string	Compliance status (e.g. `compliant`, `violation`) (nullable).
`data_classification`	string	Data classification level of the affected entity (nullable).
`retention_years`	integer	Retention period in years.

Query Audit Trail¶

GET /v1/audit

Query the audit trail with time-range and attribute filters. Results are ordered by occurred_at descending (most recent first).

Query Parameters¶

Parameter	Type	Default	Description
`start`	datetime	24 hours ago	Start of the time range (ISO 8601).
`end`	datetime	now	End of the time range (ISO 8601).
`actor_id`	UUID	—	Filter by the actor who performed the action.
`entity_type`	string	—	Filter by entity type (e.g. `review_packet`, `grant`).
`action`	string	—	Filter by action (e.g. `review.decide`, `grant.revoke`).
`limit`	integer	50	Items per page (max 100).

Example Request¶

curl -s "http://localhost:8000/v1/audit?start=2025-07-14T00:00:00Z&end=2025-07-15T00:00:00Z&action=review.decide&limit=3" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

{
  "items": [
    {
      "event_id": "019fa0b1-c2d3-7000-8000-00000000a001",
      "occurred_at": "2025-07-14T16:45:00Z",
      "actor_id": "019f1a2b-3c4d-7000-8000-000000000099",
      "actor_email": "manager@contoso.com",
      "action": "review.decide",
      "entity_type": "review_packet",
      "entity_id": "019f6b7c-8d9e-7000-8000-000000006001",
      "entity_name": "Bob Martinez → PROD.ANALYTICS.CUSTOMERS",
      "decision": "REVOKE",
      "justification": "User has not accessed this dataset in 87 days. Revoking per least-privilege policy.",
      "risk_level": "HIGH",
      "source_ip": "10.0.1.42",
      "metadata": {
        "decay_score_at_decision": 12.5,
        "grant_ids": ["019f2c3d-4e5f-7000-8000-000000000020"]
      },
      "regulation": "SOX",
      "compliance_status": "compliant",
      "data_classification": "CONFIDENTIAL",
      "retention_years": 7
    },
    {
      "event_id": "019fa0b1-c2d3-7000-8000-00000000a002",
      "occurred_at": "2025-07-14T15:30:00Z",
      "actor_id": "019f1a2b-3c4d-7000-8000-000000000099",
      "actor_email": "manager@contoso.com",
      "action": "review.decide",
      "entity_type": "review_packet",
      "entity_id": "019f6b7c-8d9e-7000-8000-000000006003",
      "entity_name": "Carol Zhang → PROD.FINANCE.GL_ENTRIES",
      "decision": "CONFIRM",
      "justification": "Confirmed with data owner — quarterly SOX audit requires continued access.",
      "risk_level": "MEDIUM",
      "source_ip": "10.0.1.42",
      "metadata": {
        "decay_score_at_decision": 28.7,
        "grant_ids": ["019f2c3d-4e5f-7000-8000-000000000060"],
        "next_review_at": "2025-10-15T00:00:00Z"
      },
      "regulation": "SOX",
      "compliance_status": "compliant",
      "data_classification": "CONFIDENTIAL",
      "retention_years": 7
    },
    {
      "event_id": "019fa0b1-c2d3-7000-8000-00000000a003",
      "occurred_at": "2025-07-14T14:15:00Z",
      "actor_id": "019f1a2b-3c4d-7000-8000-000000000080",
      "actor_email": "ciso@contoso.com",
      "action": "review.decide",
      "entity_type": "review_packet",
      "entity_id": "019f6b7c-8d9e-7000-8000-000000006005",
      "entity_name": "svc-etl-pipeline → PROD.RAW.PII_RECORDS",
      "decision": "REVOKE",
      "justification": "Service principal decommissioned. Pipeline migrated to new identity.",
      "risk_level": "CRITICAL",
      "source_ip": "10.0.2.10",
      "metadata": {
        "decay_score_at_decision": 3.1,
        "grant_ids": ["019f2c3d-4e5f-7000-8000-000000000080"]
      },
      "regulation": "GDPR",
      "compliance_status": "compliant",
      "data_classification": "RESTRICTED",
      "retention_years": 10
    }
  ],
  "next_cursor": "eyJldmVudF9pZCI6IjAxOWZhMGIxLWMyZDMtNzAwMC04MDAwLTAwMDAwMDAwYTAwNCJ9"
}

Common Audit Actions¶

Action	Description
`review.decide`	A reviewer submitted a decision.
`review.reassign`	A review packet was reassigned.
`review.escalate`	A review was escalated to another reviewer.
`review.expire`	A review packet expired without a decision.
`grant.revoke`	An access grant was revoked via remediation.
`grant.discover`	A new grant was discovered by a connector.
`report.generate`	A compliance report was generated.
`principal.sync`	Principal data was synced from a connector.
`asset.sync`	Asset data was synced from a connector.
`score.compute`	A decay score was recomputed.

Filtering by Entity Type¶

# All grant revocations in the last 7 days
curl -s "http://localhost:8000/v1/audit?start=2025-07-08T00:00:00Z&entity_type=grant&action=grant.revoke" \
  -H "Authorization: Bearer $TOKEN"

Filtering by Actor¶

# All actions by a specific user
curl -s "http://localhost:8000/v1/audit?actor_id=019f1a2b-3c4d-7000-8000-000000000099&limit=20" \
  -H "Authorization: Bearer $TOKEN"