Comprehensive security event tracking — logins, 2FA changes, API key operations, admin actions, and suspicious activity.

Audit Logging

FastCMS includes a comprehensive audit logging system for tracking security-relevant events.

What Gets Logged

Authentication — login, logout, failed attempts, token refresh
2FA — setup, enable, disable, verification, backup code usage
API Keys — create, update, delete, revoke
Security — rate limiting, suspicious activity
Admin Actions — settings changes, backups

Event Types

Event Type	Description
`auth`	Authentication-related events
`user`	User management
`api_key`	API key operations
`two_factor`	2FA/TOTP events
`collection`	Collection operations
`record`	Record operations
`file`	File operations
`admin`	Administrative actions
`system`	System events
`security`	Security-related events

Severity Levels

Level	Use Case
`info`	Successful logins, standard actions
`warning`	Failed logins, configuration changes
`critical`	Suspicious activity, access denied

API Endpoints

All endpoints require admin authentication.

List Audit Logs

GET /api/v1/audit
Authorization: Bearer {admin_token}

Query Parameters:

Parameter	Description
`limit`	Max results (1-1000, default: 100)
`offset`	Skip results
`event_type`	Filter by event type
`severity`	Filter by severity
`user_id`	Filter by user ID
`ip_address`	Filter by IP
`from_date`	Filter from date
`to_date`	Filter to date

Response:

{
  "items": [
    {
      "id": "550e8400-...",
      "event_type": "auth",
      "event_action": "login",
      "severity": "info",
      "user_email": "user@example.com",
      "ip_address": "192.168.1.100",
      "description": "User logged in via password",
      "outcome": "success",
      "created": "2025-01-15T10:30:00"
    }
  ],
  "total": 1
}

Get Security Events

GET /api/v1/audit/security?severity=critical
Authorization: Bearer {admin_token}

Get Failed Logins

GET /api/v1/audit/failed-logins?ip_address=10.0.0.1
Authorization: Bearer {admin_token}

Get Statistics

GET /api/v1/audit/statistics
Authorization: Bearer {admin_token}

{
  "by_event_type": {"auth": 150, "api_key": 25},
  "by_severity": {"info": 160, "warning": 20, "critical": 5},
  "by_outcome": {"success": 175, "failure": 10},
  "total": 185
}

Cleanup Old Logs

DELETE /api/v1/audit/cleanup?retention_days=90
Authorization: Bearer {admin_token}

Programmatic Usage

from app.services.audit_service import (
    AuditService, EventType, EventAction, Severity
)

async def log_custom_event(db):
    service = AuditService(db)

    await service.log(
        event_type=EventType.ADMIN,
        event_action=EventAction.SETTINGS_CHANGE,
        description="System settings updated",
        user_id="admin-123",
        user_email="admin@example.com",
        ip_address="192.168.1.1",
        details={"setting": "rate_limit", "old": 100, "new": 200},
        severity=Severity.WARNING,
    )

Best Practices

What to Always Log

Login attempts (success and failure)
Password changes
2FA configuration changes
API key operations
Administrative actions
Access to sensitive data

What to Avoid Logging

Sensitive data content (passwords, tokens)
High-frequency read operations
Internal system calls

Retention

Default: 90 days
Minimum recommended: 30 days
Check compliance requirements (GDPR, SOC2)

Monitoring Alerts

Set up alerts for:

Multiple failed logins from same IP
2FA disabled on admin accounts
Critical severity events
API key revocations

Audit Logging

On this page