Audit Logging

Gnok records a comprehensive audit trail of all data access and administrative operations for compliance and forensics. Audit logs are immutable and append-only.

Event Categories

Audit events are organized into six categories. Each category covers a distinct area of system activity.

Category	Events	Example
Authentication	LoginSuccess, LoginFailure, TokenRefresh, SessionExpired	User alice logged in via JWT
Authorization	AccessDenied, PrivilegeCheck, RLSApplied, MaskingApplied	User bob denied SELECT on orders
DataAccess	Query, Export, DataPreview, TimeTravel	Query Q-123 scanned 1.2M rows from orders
Administrative	RoleChange, PolicyUpdate, ConfigChange, WarehouseResize	Role analyst granted to alice
Schema	CreateObject, AlterObject, DropObject	Table orders created by alice
Security	Grant, Revoke, PolicyCreate, PolicyDrop	GRANT SELECT ON orders TO analyst

Authentication Events

Authentication events capture every interaction with the identity layer:

• LoginSuccess -- Recorded when a user authenticates successfully. Captures the authentication method (JWT, password, SSO) and the identity provider.
• LoginFailure -- Recorded on failed authentication attempts. Captures the failure reason (invalid token, expired credentials, unknown user).
• TokenRefresh -- Recorded when a session token is refreshed.
• SessionExpired -- Recorded when a session times out or is explicitly terminated.

Authorization Events

Authorization events track privilege checks at every level of the object hierarchy:

• PrivilegeCheck -- Recorded for every privilege evaluation during query planning. Includes the object, requested privilege, and result.
• AccessDenied -- Recorded when a query is rejected due to insufficient privileges.
• RLSApplied -- Recorded when a row-level security policy filters rows from query results.
• MaskingApplied -- Recorded when a column masking policy transforms column values.

Data Access Events

Data access events provide a record of all queries and data movement:

• Query -- Recorded for every SQL statement executed. Includes the SQL text (optionally truncated), tables accessed, rows scanned, rows returned, and execution duration.
• Export -- Recorded when query results are exported or downloaded.

Audit Record Schema

Every audit event conforms to a structured schema. The following fields are present on all records:

Field	Type	Description
event_id	UUID	Unique event identifier
timestamp	TIMESTAMP	Event time in UTC
category	VARCHAR	Event category (Authentication, Authorization, DataAccess, Administrative, Schema, Security)
event_type	VARCHAR	Specific event type within the category
outcome	VARCHAR	SUCCESS, FAILURE, or DENIED
actor_id	VARCHAR	User ID from the identity provider
actor_name	VARCHAR	Human-readable username
tenant_id	VARCHAR	Your organization's identifier
session_id	VARCHAR	Session identifier
client_ip	VARCHAR	Client IP address
target_type	VARCHAR	Object type: TABLE, SCHEMA, CATALOG, ROLE, POLICY, WAREHOUSE
target_name	VARCHAR	Fully qualified object name
statement	VARCHAR	SQL statement text (truncated to 4096 characters by default)
details	JSON	Additional event-specific details

Example Record

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-06-15T10:30:00Z",
  "category": "DataAccess",
  "event_type": "Query",
  "outcome": "SUCCESS",
  "actor_id": "user-abc123",
  "actor_name": "alice@example.com",
  "tenant_id": "acme-corp",
  "session_id": "sess-abc123",
  "client_ip": "10.0.1.42",
  "target_type": "TABLE",
  "target_name": "catalog.schema.orders",
  "statement": "SELECT * FROM orders WHERE region = 'US'",
  "details": {
    "tables_accessed": ["catalog.schema.orders"],
    "columns_accessed": ["order_id", "amount", "region"],
    "rows_scanned": 5200000,
    "rows_returned": 1042,
    "duration_ms": 156,
    "rls_policies_applied": ["region_filter"],
    "masking_applied": ["email:mask_email"]
  }
}

Configuration

Audit storage and capture settings are managed by Gnok. Authorized administrators can inspect the audit information exposed to their account. Confirm the scope and retention required by your organization through your account arrangements.

Querying Audit Logs

Via SQL

Audit logs can be queried directly using the SHOW AUDIT EVENTS command:

-- Recent activity by a specific user
SHOW AUDIT EVENTS
WHERE actor_name = 'alice@example.com'
  AND timestamp > '2025-06-01'
ORDER BY timestamp DESC
LIMIT 100;

-- Failed authentication attempts in the last 7 days
SHOW AUDIT EVENTS
WHERE category = 'Authentication'
  AND outcome = 'FAILURE'
  AND timestamp >= CURRENT_TIMESTAMP - INTERVAL '7 days'
ORDER BY timestamp DESC;

-- All privilege changes
SHOW AUDIT EVENTS
WHERE category = 'Security'
ORDER BY timestamp DESC;

-- Queries that accessed sensitive columns
SHOW AUDIT EVENTS
WHERE category = 'DataAccess'
  AND details:columns_accessed::VARCHAR LIKE '%ssn%'
ORDER BY timestamp DESC;

Via Catalog Service REST API

The Gnok Catalog exposes a REST endpoint for querying audit events programmatically:

curl -X GET 'https://catalog.example.com/v1/audit/events' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "category": "DataAccess",
      "actor_name": "alice@example.com",
      "start_time": "2025-06-01T00:00:00Z",
      "end_time": "2025-06-15T00:00:00Z"
    },
    "limit": 100
  }'

Retention

Confirm audit retention and export requirements for your account with Gnok. Engine defaults and examples are not a contractual retention guarantee.

Performance

Audit capture and persistence are managed by the service. If records appear missing, provide the event time and query or account reference to support.

Compliance Templates

Audit logs can support your organization's evidence and investigation processes. A logging feature alone does not establish SOC 2, HIPAA, PCI-DSS, or other compliance. Confirm the required access, retention, and controls with your compliance team and Gnok.