Skip to content

Audit Logging

Comprehensive guide to audit logging and security event tracking in Champa Intelligence.

Overview

The audit logging system provides a complete, tamper-evident trail of all significant user actions and security events. This is essential for compliance, security investigations, and operational troubleshooting.

Required Permission: manage_users

Navigation: Admin → Audit Log

What Gets Logged

Security Events

Event Type Description Severity
login_success Successful user login INFO
login_failed Failed login attempt WARNING
login_blocked Account locked due to failed attempts CRITICAL
logout User logout INFO
session_expired Session expired INFO
session_revoked Admin revoked session WARNING
password_changed User changed password INFO
password_reset Admin reset user password WARNING
api_token_expired API token expired WARNING

User Management Events

Event Type Description Severity
user_created New user account created INFO
user_updated User account modified INFO
user_deleted User account deleted WARNING
user_status_changed User activated/deactivated WARNING
profile_updated User updated own profile INFO

Role & Permission Events

Event Type Description Severity
role_created New role created INFO
role_updated Role permissions modified WARNING
role_deleted Role deleted WARNING
permission_denied Access denied due to permissions WARNING
permission_check Permission verification DEBUG

Administrative Events

Event Type Description Severity
admin_action Generic admin action INFO
api_token_regenerated API token regenerated WARNING
cache_cleared Cache manually cleared INFO
sessions_cleanup Expired sessions cleaned up INFO

Viewing Audit Logs

Audit Log Interface

Columns:

Column Description
Timestamp When event occurred
User Username (or "system" for automated events)
Action Event type
Resource Type What was affected (user, role, session, etc.)
Resource ID Identifier of affected resource
Status Success or Failed
IP Address Origin IP address
User Agent Browser/client information
Details Additional context (JSON)

Example Entry:

Timestamp: 2025-01-15 10:30:45
User: admin
Action: user_created
Resource Type: user
Resource ID: 15
Status: success
IP Address: 192.168.1.100
User Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Details: {
  "created_user_id": 15,
  "created_username": "john.doe",
  "role": "process_analyst",
  "is_active": true
}

Retention & Archival

Retention Policy

Default Retention: - Audit logs retained indefinitely in PostgreSQL - No automatic deletion

Recommended Policy:

Event Type Retention Period
Security Events 7 years (compliance)
User Management 3 years
Admin Actions 3 years
Permission Checks 90 days
General Events 1 year

Best Practices

1. Regular Audit Reviews

Weekly: - Review failed login attempts - Check for permission denials - Monitor admin actions

Monthly: - Analyze access patterns - Review user activity - Check for anomalies

Quarterly: - Comprehensive security audit - Compliance reporting - Archive old logs

2. Automated Monitoring

Set up alerts for: - Multiple failed logins (>5 in 15 min) - Account lockouts - Admin user deletions - Permission changes - API token regeneration

3. Log Protection

Prevent tampering: - Audit table has no DELETE permission for app user - Only INSERT and SELECT allowed - Backup database regularly - Consider write-once storage for archives

Configuration:

-- Restrict audit log access
REVOKE DELETE ON auth.auth_audit_log FROM champa_app_user;
REVOKE UPDATE ON auth.auth_audit_log FROM champa_app_user;
GRANT INSERT, SELECT ON auth.auth_audit_log TO champa_app_user;

Troubleshooting

Audit Logs Not Appearing

Check database connection:

from db.auth import execute_query

try:
    result = execute_query(
        "SELECT COUNT(*) FROM auth.auth_audit_log",
        use_system_db=True
    )
    print(f"Total audit log entries: {result[0]['count']}")
except Exception as e:
    print(f"Error: {e}")

Verify audit function calls:

# Check application logs for audit errors
docker logs champa-intelligence | grep "audit"

Performance Issues

Slow queries due to large audit table:

-- Add indexes
CREATE INDEX idx_audit_user_id ON auth.auth_audit_log(user_id);
CREATE INDEX idx_audit_created_at ON auth.auth_audit_log(created_at DESC);
CREATE INDEX idx_audit_action_type ON auth.auth_audit_log(action_type);

-- Partition table by date (PostgreSQL 10+)
CREATE TABLE auth.auth_audit_log_2025_01 PARTITION OF auth.auth_audit_log
FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');

Next Steps

Support

For audit logging questions: