Summary

Document the security module at include/kcenon/logger/security/ which provides audit logging, log sanitization, secure key storage, path validation, and signal management.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

logger_system includes a complete security module with 6 headers providing critical security functionality. None of these are documented, which is especially concerning because security features must be properly understood and configured to be effective.

Source files:

• include/kcenon/logger/security/audit_logger.h — Tamper-evident audit logging
• include/kcenon/logger/security/log_sanitizer.h — PII/sensitive data scrubbing
• include/kcenon/logger/security/path_validator.h — Log file path validation (traversal prevention)
• include/kcenon/logger/security/secure_key_storage.h — Secure storage for encryption keys
• include/kcenon/logger/security/signal_manager.h — Signal handling for graceful shutdown
• include/kcenon/logger/security/signal_manager_interface.h — Signal manager abstraction

Scope (What)

Create docs/SECURITY_GUIDE.md covering:

1. Security Module Overview

• Purpose: Defense-in-depth for logging infrastructure
• Threat model: What attacks does this module defend against?
• Architecture: How security components integrate with core logging

2. Audit Logger (audit_logger.h)

• Tamper-evident log creation
• Chained hash verification (if implemented)
• Compliance requirements addressed (SOX, HIPAA, GDPR audit trails)
• API: create audit entry, verify chain, export audit log
• Configuration: retention, rotation, integrity verification interval

3. Log Sanitizer (log_sanitizer.h)

• PII detection and scrubbing patterns
• Sensitive data categories (emails, SSNs, credit cards, API keys, passwords)
• Custom sanitization rules
• API: sanitize(), add_pattern(), remove_pattern()
• Performance impact of sanitization

4. Path Validator (path_validator.h)

• Path traversal attack prevention (../../../etc/passwd)
• Symlink resolution and validation
• Allowed directory configuration
• API: validate_path(), is_safe(), normalize()

5. Secure Key Storage (secure_key_storage.h)

• How encryption keys are stored and retrieved
• Key rotation support
• Integration with encrypted_writer
• Platform-specific secure storage (keychain, DPAPI, etc.)

6. Signal Manager (signal_manager.h, signal_manager_interface.h)

• Graceful shutdown handling (SIGTERM, SIGINT, SIGHUP)
• Log flushing on signal receipt
• Custom signal handler registration
• Cross-platform signal support

7. Configuration Example

auto logger = logger_builder::create()
    .with_sanitizer(sanitizer_config{
        .scrub_emails = true,
        .scrub_credit_cards = true,
        .custom_patterns = {"API-KEY-[A-Z0-9]+"}
    })
    .with_audit(audit_config{
        .chain_verification = true,
        .retention_days = 90
    })
    .with_path_validation("/var/log/app/")
    .build();

Acceptance Criteria

• All 6 security headers documented
• Threat model and security architecture explained
• Each component's API fully documented
• Configuration examples for each component
• Integration with core logging explained
• Compliance considerations noted