Malachi.AuditLog (malachi v0.8.13)

Structured audit system with ETS storage and secondary indexes.

Tracks security events including authentication, lockouts, sessions, and administrative activities. Maintains 30-day history with automatic cleanup.

Event Types

:auth_success - Successful authentication
:auth_failure - Failed authentication
:auth_lockout - Account locked due to excessive attempts
:session_created - New session created
:session_revoked - Session manually revoked
:session_expired - Session expired by timeout
:session_hijack_attempt - Hijacking attempt detected
:account_unlocked - Account unlocked by admin
:config_validation_failed - Configuration validation failed
:dashboard_access - Dashboard HTTP endpoint accessed
:dashboard_login_success - Successful dashboard login
:dashboard_auth_failure - Failed dashboard authentication

Event Structure

Each event is stored as:

{event_id, timestamp, event_type, username, ip, action, status, metadata}

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

flush()

Flush buffered events to disk immediately. Useful for testing or ensuring events are written before shutdown.

get_events(limit \\ 1000)

Returns all events (limited to most recent).

get_events_by_type(event_type, limit \\ 1000)

Returns events of a specific type.

get_events_by_user(username, limit \\ 1000)

Returns events for a specific user.

get_stats()

Returns event statistics.

log_event(event_type, context, action, status, metadata)

Records an audit event.

start_link(opts)

Starts the audit log, which buffers security events and periodically flushes them to ETS and, if configured, a file or stdout.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

flush()

Flush buffered events to disk immediately. Useful for testing or ensuring events are written before shutdown.

get_events(limit \\ 1000)

Returns all events (limited to most recent).

Parameters

limit - Maximum number of events to return (default: 1000)

get_events_by_type(event_type, limit \\ 1000)

Returns events of a specific type.

Parameters

event_type - Event type to filter
limit - Maximum number of events to return (default: 1000)

get_events_by_user(username, limit \\ 1000)

Returns events for a specific user.

Parameters

username - Username
limit - Maximum number of events to return (default: 1000)

get_stats()

Returns event statistics.

log_event(event_type, context, action, status, metadata)

Records an audit event.

Parameters

event_type - Atom representing the event type
context - Map with username and ip (optional)
action - String describing the action (e.g., "authenticate", "unlock_account")
status - :success or :failure
metadata - Map with event-specific additional data

Examples

iex> AuditLog.log_event(:auth_success, %{username: "admin", ip: {192, 168, 1, 1}}, 
...>   "authenticate", :success, %{})
:ok

iex> AuditLog.log_event(:auth_lockout, %{username: "user", ip: {10, 0, 0, 1}},
...>   "account_locked", :automatic, %{attempt_count: 5, lockout_duration_ms: 300_000})
:ok

start_link(opts)

Starts the audit log, which buffers security events and periodically flushes them to ETS and, if configured, a file or stdout.