Skip to content

audit.mdx

Latest commit

 

History

History
269 lines (198 loc) · 15.8 KB

audit.mdx

File metadata and controls

269 lines (198 loc) · 15.8 KB
Raw
title Audit
description Audit protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Audit Log Architecture

Comprehensive audit logging system for compliance and security.

Supports SOX, HIPAA, GDPR, and other regulatory requirements.

Features:

  • Records all CRUD operations on data

  • Tracks authentication events (login, logout, password reset)

  • Monitors authorization changes (permissions, roles)

  • Configurable retention policies (180-day GDPR requirement)

  • Suspicious activity detection and alerting

**Source:** `packages/spec/src/system/audit.zod.ts`

TypeScript Usage

import { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system';
import type { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system';

// Validate data
const result = AuditConfig.parse(data);

AuditConfig

Properties

Property Type Required Description
name string ✅ Configuration name (snake_case, max 64 chars)
label string ✅ Display label
enabled boolean optional Enable audit logging
eventTypes Enum<'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'data.export' | 'data.import' | 'data.bulk_update' | 'data.bulk_delete' | 'auth.login' | 'auth.login_failed' | 'auth.logout' | 'auth.session_created' | 'auth.session_expired' | 'auth.password_reset' | 'auth.password_changed' | 'auth.email_verified' | 'auth.mfa_enabled' | 'auth.mfa_disabled' | 'auth.account_locked' | 'auth.account_unlocked' | 'authz.permission_granted' | 'authz.permission_revoked' | 'authz.role_assigned' | 'authz.role_removed' | 'authz.role_created' | 'authz.role_updated' | 'authz.role_deleted' | 'authz.policy_created' | 'authz.policy_updated' | 'authz.policy_deleted' | 'system.config_changed' | 'system.plugin_installed' | 'system.plugin_uninstalled' | 'system.backup_created' | 'system.backup_restored' | 'system.integration_added' | 'system.integration_removed' | 'security.access_denied' | 'security.suspicious_activity' | 'security.data_breach' | 'security.api_key_created' | 'security.api_key_revoked'>[] optional Event types to audit
excludeEventTypes Enum<'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'data.export' | 'data.import' | 'data.bulk_update' | 'data.bulk_delete' | 'auth.login' | 'auth.login_failed' | 'auth.logout' | 'auth.session_created' | 'auth.session_expired' | 'auth.password_reset' | 'auth.password_changed' | 'auth.email_verified' | 'auth.mfa_enabled' | 'auth.mfa_disabled' | 'auth.account_locked' | 'auth.account_unlocked' | 'authz.permission_granted' | 'authz.permission_revoked' | 'authz.role_assigned' | 'authz.role_removed' | 'authz.role_created' | 'authz.role_updated' | 'authz.role_deleted' | 'authz.policy_created' | 'authz.policy_updated' | 'authz.policy_deleted' | 'system.config_changed' | 'system.plugin_installed' | 'system.plugin_uninstalled' | 'system.backup_created' | 'system.backup_restored' | 'system.integration_added' | 'system.integration_removed' | 'security.access_denied' | 'security.suspicious_activity' | 'security.data_breach' | 'security.api_key_created' | 'security.api_key_revoked'>[] optional Event types to exclude
minimumSeverity Enum<'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'> optional Minimum severity level
storage { type: Enum<'database' | 'elasticsearch' | 'mongodb' | 'clickhouse' | 's3' | 'gcs' | 'azure_blob' | 'custom'>; connectionString?: string; config?: Record<string, any>; bufferEnabled?: boolean; … } ✅ Storage configuration
retentionPolicy { retentionDays?: integer; archiveAfterRetention?: boolean; archiveStorage?: object; customRetention?: Record<string, integer>; … } optional Retention policy
suspiciousActivityRules { id: string; name: string; description?: string; enabled?: boolean; … }[] optional Suspicious activity rules
includeSensitiveData boolean optional Include sensitive data
redactFields string[] optional Fields to redact
logReads boolean optional Log read operations
readSamplingRate number optional Read sampling rate
logSystemEvents boolean optional Log system events
customHandlers { eventType: Enum<'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'data.export' | 'data.import' | 'data.bulk_update' | 'data.bulk_delete' | 'auth.login' | 'auth.login_failed' | 'auth.logout' | 'auth.session_created' | 'auth.session_expired' | 'auth.password_reset' | 'auth.password_changed' | 'auth.email_verified' | 'auth.mfa_enabled' | 'auth.mfa_disabled' | 'auth.account_locked' | 'auth.account_unlocked' | 'authz.permission_granted' | 'authz.permission_revoked' | 'authz.role_assigned' | 'authz.role_removed' | 'authz.role_created' | 'authz.role_updated' | 'authz.role_deleted' | 'authz.policy_created' | 'authz.policy_updated' | 'authz.policy_deleted' | 'system.config_changed' | 'system.plugin_installed' | 'system.plugin_uninstalled' | 'system.backup_created' | 'system.backup_restored' | 'system.integration_added' | 'system.integration_removed' | 'security.access_denied' | 'security.suspicious_activity' | 'security.data_breach' | 'security.api_key_created' | 'security.api_key_revoked'>; handlerId: string }[] optional Custom event handler references
compliance { standards?: Enum<'sox' | 'hipaa' | 'gdpr' | 'pci_dss' | 'iso_27001' | 'fedramp'>[]; immutableLogs?: boolean; requireSigning?: boolean; signingKey?: string } optional Compliance configuration

AuditEvent

Properties

Property Type Required Description
id string ✅ Audit event ID
eventType Enum<'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'data.export' | 'data.import' | 'data.bulk_update' | 'data.bulk_delete' | 'auth.login' | 'auth.login_failed' | 'auth.logout' | 'auth.session_created' | 'auth.session_expired' | 'auth.password_reset' | 'auth.password_changed' | 'auth.email_verified' | 'auth.mfa_enabled' | 'auth.mfa_disabled' | 'auth.account_locked' | 'auth.account_unlocked' | 'authz.permission_granted' | 'authz.permission_revoked' | 'authz.role_assigned' | 'authz.role_removed' | 'authz.role_created' | 'authz.role_updated' | 'authz.role_deleted' | 'authz.policy_created' | 'authz.policy_updated' | 'authz.policy_deleted' | 'system.config_changed' | 'system.plugin_installed' | 'system.plugin_uninstalled' | 'system.backup_created' | 'system.backup_restored' | 'system.integration_added' | 'system.integration_removed' | 'security.access_denied' | 'security.suspicious_activity' | 'security.data_breach' | 'security.api_key_created' | 'security.api_key_revoked'> ✅ Event type
severity Enum<'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'> ✅ Event severity
timestamp string ✅ Event timestamp
actor { type: Enum<'user' | 'system' | 'service' | 'api_client' | 'integration'>; id: string; name?: string; email?: string; … } ✅ Event actor
target { type: string; id: string; name?: string; metadata?: Record<string, any> } optional Event target
description string ✅ Event description
changes { field: string; oldValue?: any; newValue?: any }[] optional List of changes
result Enum<'success' | 'failure' | 'partial'> ✅ Action result
errorMessage string optional Error message
tenantId string optional Tenant identifier
requestId string optional Request ID for tracing
metadata Record<string, any> optional Additional metadata
location { country?: string; region?: string; city?: string } optional Geographic location

AuditEventActor

Properties

Property Type Required Description
type Enum<'user' | 'system' | 'service' | 'api_client' | 'integration'> ✅ Actor type
id string ✅ Actor identifier
name string optional Actor display name
email string optional Actor email address
ipAddress string optional Actor IP address
userAgent string optional User agent string

AuditEventChange

Properties

Property Type Required Description
field string ✅ Changed field name
oldValue any optional Previous value
newValue any optional New value

AuditEventFilter

Properties

Property Type Required Description
eventTypes Enum<'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'data.export' | 'data.import' | 'data.bulk_update' | 'data.bulk_delete' | 'auth.login' | 'auth.login_failed' | 'auth.logout' | 'auth.session_created' | 'auth.session_expired' | 'auth.password_reset' | 'auth.password_changed' | 'auth.email_verified' | 'auth.mfa_enabled' | 'auth.mfa_disabled' | 'auth.account_locked' | 'auth.account_unlocked' | 'authz.permission_granted' | 'authz.permission_revoked' | 'authz.role_assigned' | 'authz.role_removed' | 'authz.role_created' | 'authz.role_updated' | 'authz.role_deleted' | 'authz.policy_created' | 'authz.policy_updated' | 'authz.policy_deleted' | 'system.config_changed' | 'system.plugin_installed' | 'system.plugin_uninstalled' | 'system.backup_created' | 'system.backup_restored' | 'system.integration_added' | 'system.integration_removed' | 'security.access_denied' | 'security.suspicious_activity' | 'security.data_breach' | 'security.api_key_created' | 'security.api_key_revoked'>[] optional Event types to include
severities Enum<'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'>[] optional Severity levels to include
actorId string optional Actor identifier
tenantId string optional Tenant identifier
timeRange { from: string; to: string } optional Time range filter
result Enum<'success' | 'failure' | 'partial'> optional Result status
searchQuery string optional Search query
customFilters Record<string, any> optional Custom filters

AuditEventSeverity

Allowed Values

  • debug
  • info
  • notice
  • warning
  • error
  • critical
  • alert
  • emergency

AuditEventTarget

Properties

Property Type Required Description
type string ✅ Target type
id string ✅ Target identifier
name string optional Target display name
metadata Record<string, any> optional Target metadata

AuditEventType

Allowed Values

  • data.create
  • data.read
  • data.update
  • data.delete
  • data.export
  • data.import
  • data.bulk_update
  • data.bulk_delete
  • auth.login
  • auth.login_failed
  • auth.logout
  • auth.session_created
  • auth.session_expired
  • auth.password_reset
  • auth.password_changed
  • auth.email_verified
  • auth.mfa_enabled
  • auth.mfa_disabled
  • auth.account_locked
  • auth.account_unlocked
  • authz.permission_granted
  • authz.permission_revoked
  • authz.role_assigned
  • authz.role_removed
  • authz.role_created
  • authz.role_updated
  • authz.role_deleted
  • authz.policy_created
  • authz.policy_updated
  • authz.policy_deleted
  • system.config_changed
  • system.plugin_installed
  • system.plugin_uninstalled
  • system.backup_created
  • system.backup_restored
  • system.integration_added
  • system.integration_removed
  • security.access_denied
  • security.suspicious_activity
  • security.data_breach
  • security.api_key_created
  • security.api_key_revoked

AuditRetentionPolicy

Properties

Property Type Required Description
retentionDays integer ✅ Retention period in days
archiveAfterRetention boolean ✅ Archive logs after retention period
archiveStorage { type: Enum<'s3' | 'gcs' | 'azure_blob' | 'filesystem'>; endpoint?: string; bucket?: string; path?: string; … } optional Archive storage configuration
customRetention Record<string, integer> optional Custom retention by event type
minimumRetentionDays integer optional Minimum retention for compliance

AuditStorageConfig

Properties

Property Type Required Description
type Enum<'database' | 'elasticsearch' | 'mongodb' | 'clickhouse' | 's3' | 'gcs' | 'azure_blob' | 'custom'> ✅ Storage backend type
connectionString string optional Connection string
config Record<string, any> optional Storage-specific configuration
bufferEnabled boolean ✅ Enable buffering
bufferSize integer ✅ Buffer size
flushIntervalSeconds integer ✅ Flush interval in seconds
compression boolean ✅ Enable compression

SuspiciousActivityRule

Properties

Property Type Required Description
id string ✅ Rule identifier
name string ✅ Rule name
description string optional Rule description
enabled boolean optional Rule enabled status
eventTypes Enum<'data.create' | 'data.read' | 'data.update' | 'data.delete' | 'data.export' | 'data.import' | 'data.bulk_update' | 'data.bulk_delete' | 'auth.login' | 'auth.login_failed' | 'auth.logout' | 'auth.session_created' | 'auth.session_expired' | 'auth.password_reset' | 'auth.password_changed' | 'auth.email_verified' | 'auth.mfa_enabled' | 'auth.mfa_disabled' | 'auth.account_locked' | 'auth.account_unlocked' | 'authz.permission_granted' | 'authz.permission_revoked' | 'authz.role_assigned' | 'authz.role_removed' | 'authz.role_created' | 'authz.role_updated' | 'authz.role_deleted' | 'authz.policy_created' | 'authz.policy_updated' | 'authz.policy_deleted' | 'system.config_changed' | 'system.plugin_installed' | 'system.plugin_uninstalled' | 'system.backup_created' | 'system.backup_restored' | 'system.integration_added' | 'system.integration_removed' | 'security.access_denied' | 'security.suspicious_activity' | 'security.data_breach' | 'security.api_key_created' | 'security.api_key_revoked'>[] ✅ Event types to monitor
condition { threshold: integer; windowSeconds: integer; groupBy?: string[]; filters?: Record<string, any> } | string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } ✅ Detection condition — structured threshold or CEL predicate
actions Enum<'alert' | 'lock_account' | 'block_ip' | 'require_mfa' | 'log_critical' | 'webhook'>[] ✅ Actions to take
alertSeverity Enum<'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'> optional Alert severity
notifications { email?: string[]; slack?: string; webhook?: string } optional Notification configuration