Skip to content

AUDIT.md

Latest commit

 

History

History
155 lines (113 loc) · 4.51 KB

AUDIT.md

File metadata and controls

155 lines (113 loc) · 4.51 KB

Audit Logging

SimpleTuner's audit logging system provides a tamper-evident record of security-relevant events. All administrative actions, authentication events, and job operations are logged with cryptographic chain verification.

Overview

The audit log captures:

  • Authentication events: Login attempts (success/failure), logouts, session expirations
  • User management: User creation, updates, deletions, permission changes
  • API key operations: Key creation, revocation, usage
  • Credential management: Provider credential changes
  • Job operations: Submissions, cancellations, approvals

Accessing Audit Logs

Web UI

Navigate to the Audit tab in the admin panel to browse audit entries with filtering options.

CLI

# List recent audit entries
simpletuner auth audit list

# Filter by event type
simpletuner auth audit list --event-type auth.login.failed

# Filter by user
simpletuner auth audit user 123

# View security events only
simpletuner auth audit security

# Get statistics
simpletuner auth audit stats

# Verify chain integrity
simpletuner auth audit verify

API Endpoints

All endpoints require the admin.audit permission.

Method Endpoint Description
GET /api/audit List audit entries with filters
GET /api/audit/stats Get audit statistics
GET /api/audit/types List available event types
GET /api/audit/verify Verify chain integrity
GET /api/audit/user/{user_id} Get entries for a user
GET /api/audit/security Get security-related events

Event Types

Authentication Events

Event Description
auth.login.success Successful login
auth.login.failed Failed login attempt
auth.logout User logged out
auth.session.expired Session expired
auth.api_key.used API key was used

User Management Events

Event Description
user.created New user created
user.updated User details updated
user.deleted User deleted
user.password.changed User changed their password
user.level.changed User level/role changed
user.permission.changed User permission changed

API Key Events

Event Description
api_key.created New API key created
api_key.revoked API key revoked

Credential Events

Event Description
credential.created Provider credential added
credential.deleted Provider credential removed
credential.used Credential was used

Job Events

Event Description
job.submitted Job submitted to queue
job.cancelled Job was cancelled
job.approved Job approval granted
job.rejected Job approval denied

Query Parameters

When listing audit entries, you can filter by:

Parameter Type Description
event_type string Filter by event type
actor_id int Filter by user who performed action
target_type string Filter by target resource type
target_id string Filter by target resource ID
since ISO date Start timestamp
until ISO date End timestamp
limit int Max entries (1-500, default 50)
offset int Pagination offset

Chain Integrity

Each audit entry includes:

  • A cryptographic hash of its content
  • A reference to the previous entry's hash
  • Timestamp from a monotonic clock

This creates a hash chain that makes tampering detectable. Use the verify endpoint or CLI command to check integrity:

# Verify entire chain
simpletuner auth audit verify

# Verify specific range
simpletuner auth audit verify --start-id 100 --end-id 200

The verification checks:

  1. Each entry's hash matches its content
  2. Each entry correctly references the previous entry's hash
  3. No gaps in the sequence

Retention

Audit logs are stored in the SimpleTuner database. Configure retention in your deployment:

# Environment variable for retention period (days)
SIMPLETUNER_AUDIT_RETENTION_DAYS=365

Older entries can be archived or purged according to your compliance requirements.

Security Considerations

  • Audit logs are append-only; entries cannot be modified or deleted through the API
  • The admin.audit permission is required to view logs
  • Failed login attempts are logged with IP addresses for security monitoring
  • Consider forwarding audit logs to a SIEM for production deployments