Audit Logging

Overview

SyndrDB includes a comprehensive security audit logging system that tracks authentication events, session lifecycle, rate limiting actions, access control decisions, and system security events. Audit logs are stored as JSON-lines files with automatic rotation and retention management.

Audit logging is automatically enabled when authentication is active. No additional commands are needed.

Table of Contents

Security Event Types

Authentication Events

Event Type Severity Description
AUTH_SUCCESS INFO User authenticated successfully
AUTH_FAILURE WARNING Authentication attempt failed
AUTH_LOCKOUT WARNING Account locked after excessive failures
AUTH_UNLOCK INFO Account unlocked

Session Events

Event Type Severity Description
SESSION_CREATED INFO New session established
SESSION_EXPIRED INFO Session timeout/expiration
SESSION_DESTROYED INFO Session manually closed
SESSION_HIJACK CRITICAL Potential session hijack detected

Rate Limiting Events

Event Type Severity Description
RATE_LIMIT_HIT WARNING Rate limit exceeded
IP_BLOCKED WARNING IP address blocked (excessive failures)
IP_UNBLOCKED INFO IP address unblocked
PROGRESSIVE_DELAY INFO Progressive delay applied

Access Control Events

Event Type Severity Description
ACCESS_DENIED WARNING Permission check failed
PRIVILEGE_ESCALATION CRITICAL Unauthorized privilege escalation attempt
UNAUTHORIZED_ACCESS WARNING Attempt to access unauthorized resource

System Events

Event Type Severity Description
SECURITY_CONFIG_CHANGE WARNING Security configuration modified
AUDIT_LOG_TAMPER CRITICAL Audit log tampering detected
SYSTEM_COMPROMISE CRITICAL Critical system compromise detected

Log Entry Format

Each audit event is recorded as a JSON object. One JSON object is written per line in the log file (JSON-lines format):

{
  "id": "evt_1705627667000000000_1705627667",
  "timestamp": "2026-01-19T02:54:27Z",
  "event_type": "AUTH_SUCCESS",
  "severity": "INFO",
  "username": "alice",
  "session_id": "sess_abc123",
  "ip_address": "192.168.1.100",
  "port": 5432,
  "user_agent": "syndrdb-cli/1.0",
  "description": "User 'alice' authenticated successfully",
  "details": {
    "auth_method": "password"
  },
  "success": true,
  "error_code": ""
}

Field Reference

Field Description
id Unique event identifier (evt_<timestamp>_<unix>)
timestamp UTC timestamp
event_type One of the security event types above
severity INFO, WARNING, or CRITICAL
username Username involved (if applicable)
session_id Session identifier (if applicable)
ip_address Client IP address
port Client port
user_agent Client user-agent string
description Human-readable event description
details Additional contextual data (map)
success Whether the operation succeeded
error_code Error code if failed

Configuration

Audit logging is configured via the AuditConfig:

Setting Default Description
LogDirectory log_files/security Directory for audit log files
MaxFileSize 50 MB Maximum size per log file before rotation
MaxFiles 100 Maximum number of log files to retain
FlushInterval 5 seconds How often to flush buffer to disk
BufferSize 100 events Buffer size before forced flush
EnableEncryption false Whether to encrypt audit logs
EncryptionKey "" Key for log encryption

The log directory is created with secure permissions (0700 — owner read/write/execute only).

Log File Management

File Location

Audit log files are written to:

{LogDir}/security/security_audit_YYYY-MM-DD_HH-MM-SS.log

Rotation

When a log file exceeds MaxFileSize (50MB default), a new file is created with a fresh timestamp.

Retention

After rotation, files exceeding the MaxFiles count are deleted (oldest first). Default retention: 100 files × 50MB = ~5GB maximum.

Flushing

Events are flushed to disk when:

  • Buffer reaches BufferSize (100 events)
  • Flush timer fires (every 5 seconds)
  • Server graceful shutdown

Each flush includes an fsync call for durability.

Accessing Audit Logs

Audit logs are stored as JSON-lines files (one JSON object per line). They can be accessed by:

Direct File Access

# View recent events
tail -f log_files/security/security_audit_*.log

# Search for failed authentications
grep "AUTH_FAILURE" log_files/security/security_audit_*.log

# Count events by type
grep -c "AUTH_LOCKOUT" log_files/security/security_audit_*.log

Programmatic Access

The SecurityAuditor provides a GetStats() method returning buffer state, channel capacity, and configuration.

Enterprise Audit Extension

SyndrDB supports an AuditEventExtension interface for enterprise integrations:

  • Receives notifications for every command executed (SELECT, INSERT, UPDATE, DELETE, DDL)
  • Includes command text, database name, success status, client IP, username, session ID
  • Enables integration with SIEM tools, compliance platforms, and external monitoring

Best Practices

Do

  • Enable authentication to activate audit logging
  • Monitor CRITICAL severity events in real-time
  • Rotate and archive audit logs to external storage
  • Set appropriate MaxFiles and MaxFileSize for your compliance needs
  • Review AUTH_FAILURE patterns for potential brute-force attacks

Don't

  • Don't disable audit logging in production
  • Don't store audit logs on the same disk as database files
  • Don't ignore SESSION_HIJACK or SYSTEM_COMPROMISE events
  • Don't delete audit logs before your compliance retention period

Last updated: March 2026