Audit Module

Audit Module

Comprehensive audit logging system for HeliosDB Nano.

Features

• Tamper-proof logging: Append-only with SHA-256 checksums
• Async operation: Non-blocking buffered logging
• Configurable: Fine-grained control over what gets logged
• SQL queryable: Query audit logs with standard SQL
• Compliance-ready: Supports SOC2, HIPAA, GDPR requirements

Module Structure

audit/
├── mod.rs          - Module exports and initialization
├── events.rs       - Event types and operation classification
├── config.rs       - Configuration structures
├── logger.rs       - Main audit logger implementation
├── query.rs        - Query builder and filtering
└── README.md       - This file

Quick Start

use heliosdb_nano::audit::{AuditLogger, AuditConfig};
use std::sync::Arc;

// Create storage and logger
let storage = Arc::new(storage_engine);
let config = AuditConfig::default();
let logger = AuditLogger::new(storage, config)?;

// Log operations
logger.log_ddl("CREATE TABLE", "users", "CREATE TABLE users (...)", true, None)?;
logger.log_dml("INSERT", "users", "INSERT INTO users ...", 1, true, None)?;

Configuration Presets

• AuditConfig::default() - Standard configuration (DDL, DML, no SELECT)
• AuditConfig::minimal() - DDL only (lowest overhead)
• AuditConfig::verbose() - Everything including SELECT queries
• AuditConfig::compliance() - SOC2/HIPAA/GDPR ready (7-year retention)

Architecture

Event Flow

1. Operation occurs → Logger method called
2. Event created → AuditEvent struct with metadata
3. Checksum calculated → SHA-256 hash for tamper detection
4. Buffered → Sent to async channel
5. Flushed → Background task writes to storage

Storage

Audit events are stored in the __audit_log system table:

• Column family: Same as regular tables
• Key format: data:__audit_log:{event_id}
• Value format: Serialized Tuple (bincode)

Performance

• Async logging: Operations never block
• Buffering: Configurable buffer size (default: 100 events)
• Selective logging: Disable verbose operations (SELECT, transactions)
• Query truncation: Limit query text length to save space

Integration Points

With StorageEngine

// Initialize audit tables
audit::initialize_audit_tables(&storage)?;

// Logger has storage reference
let logger = AuditLogger::new(Arc::clone(&storage), config)?;

With SQL Executor

// Before execution
audit_logger.log_operation(...)?;

// After execution
audit_logger.log_operation(/* with results */)?;

With EmbeddedDatabase

// Optional: Wrap database with audit logging
let db_with_audit = AuditedDatabase::new(db, audit_logger);

Security Considerations

1. Protect audit table: Restrict access to __audit_log
2. Verify checksums: Periodically check event integrity
3. Secure storage: Encrypt at rest if required
4. Access control: Audit access to audit logs themselves
5. Retention policy: Archive old logs, don’t just delete

Testing

Run audit tests:

cargo test --test audit_tests

Run example:

cargo run --example audit_demo

Documentation

See /home/claude/HeliosDB/heliosdb-nano/docs/AUDIT_LOGGING.md for complete documentation.

Future Enhancements

• Digital signatures (asymmetric crypto)
• Separate column family for audit logs
• Automatic retention/archival
• Real-time audit event streaming
• Distributed audit log (multi-node)
• Audit log compression
• Custom audit event types
• Webhook notifications for critical events