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