Audit Logs

Track and review all system changes with tamper-evident audit logging.

What Are Audit Logs?

Audit logs provide a complete, immutable record of all system events:

Audit Log Structure

Event Properties

Property	Description	Example
Event ID	Unique identifier	`550e8400-e29b-41d4-a716-446655440000`
Event Type	Specific event name	`deployment.created`
Category	Event category	`deployment`
Severity	Importance level	`info`, `security`
Actor	Who performed the action	User, System, API Key, Service
Resource	What was affected	Target, Deployment
Outcome	Result of action	`success`, `denied`
Timestamp	When it occurred	`2024-12-20 14:30:00`
Metadata	What the action carried	`{"changed_fields": ["status"]}`

Event Categories

Category	Description	Example Events
Authentication	Login, logout, tokens	`auth.login_success`, `auth.token_revoked`
Authorization	Permissions, roles	`authz.permission_denied`, `authz.role_updated`
Deployment	Deployment lifecycle	`deployment.created`, `deployment.completed`
Configuration	System configuration	`config.solution_created`, `config.imported`
User Management	User administration	`user.created`, `user.roles_assigned`
Tenant Management	Tenant operations	`tenant.created`, `tenant.deleted`
Target Management	Target operations	`target.created`, `auth.registration_approved`
Certificate	Certificate operations	`certificate.rotated`, `tenant.certificate_authority_created`
Storage	Storage backends	`storage.created`, `storage.accessed`
System	System operations	`system.startup`, `thorax_instance.deregistered`

Viewing Audit Logs

Audit Log List

┌─────────────────────────────────────────────────────────────┐
│  Audit Logs                                                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Filters:                                                   │
│  Category: [All             ▼]  Severity: [All         ▼]  │
│  Actor:    [All             ▼]  Outcome:  [All         ▼]  │
│  Date Range: [Last 7 days   ▼]                             │
│  Search: [_______________________________] [Search]         │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Timestamp         │ Event                │ Actor     │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ Dec 20, 14:32:15  │ deployment.created   │ alice     │  │
│  │ Dec 20, 14:30:00  │ auth.login_success   │ bob       │  │
│  │ Dec 20, 14:28:45  │ target.updated       │ admin     │  │
│  │ Dec 20, 14:25:10  │ config.solution_updated │ alice  │  │
│  │ Dec 20, 14:20:00  │ auth.login_failure   │ unknown   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  Showing 1-50 of 1,247 entries        [< Prev] [Next >]    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Audit Log Detail

┌─────────────────────────────────────────────────────────────┐
│  Audit Log Entry                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Event ID: 550e8400-e29b-41d4-a716-446655440000             │
│  Event Type: deployment.created                             │
│  Category: Deployment                                       │
│  Severity: ● Info                                           │
│  Outcome: ✓ Success                                         │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Actor:                                                     │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Type: User                                            │ │
│  │ ID: 42                                                │ │
│  │ Name: alice                                           │ │
│  │ Email: alice@example.com                              │ │
│  │ IP Address: 192.168.1.100                             │ │
│  │ User Agent: Mozilla/5.0...                            │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Resource:                                                  │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Type: Deployment                                      │ │
│  │ ID: 123                                               │ │
│  │ Name: customer-portal v1.2.0 to Production            │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Context:                                                   │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Tenant: Acme Corp                                     │ │
│  │ Environment: Production                               │ │
│  │ Request ID: abc123...                                 │ │
│  │ Correlation ID: def456...                             │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Timestamp: December 20, 2024 14:32:15 UTC                  │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Chain Integrity:                                           │
│  Entry Hash: a1b2c3d4e5f6...                               │
│  Previous Hash: 9z8y7x6w5v4...                             │
│  Chain Sequence: 1247                                       │
│  ✓ Hash verified                                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

State Change View

For configuration changes, view before/after state:

┌─────────────────────────────────────────────────────────────┐
│  State Change: config.solution_updated                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────┬─────────────────────────────┐ │
│  │ Previous State          │ New State                   │ │
│  ├─────────────────────────┼─────────────────────────────┤ │
│  │ {                       │ {                           │ │
│  │   "name": "portal",     │   "name": "portal",         │ │
│  │   "version": "1.1.0",   │   "version": "1.2.0",  ←    │ │
│  │   "enabled": true       │   "enabled": true           │ │
│  │ }                       │ }                           │ │
│  └─────────────────────────┴─────────────────────────────┘ │
│                                                             │
│  Changes detected: version (1.1.0 → 1.2.0)                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Filtering and Search

By Category

Filter logs by event category:

┌─────────────────────────────────────────────────────────────┐
│  Category Filter                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ☑ Authentication                                          │
│  ☑ Authorization                                           │
│  ☑ Deployment                                              │
│  ☐ Configuration                                           │
│  ☐ User Management                                         │
│  ☐ Tenant Management                                       │
│  ☐ Target Management                                       │
│  ☐ Certificate                                             │
│  ☐ Storage                                                 │
│  ☐ System                                                  │
│                                                             │
│                                          [Apply]           │
└─────────────────────────────────────────────────────────────┘

By Severity

Severity	Icon	Description
Info	●	Normal operations
Warning	⚠	Potential issues
Error	✗	Operation failed
Critical	⚡	System-level failures
Security	🔒	Security-related events

By Actor Type

Actor Type	Description	Examples
User	Human user	Login, create deployment
System	Automated system	Scheduled tasks, maintenance
API Key	API key access	External integrations
Service	Internal service or agent	Thorax orchestration, target heartbeat, registration

By Outcome

Outcome	Description
Success	Action completed successfully
Failure	Action failed
Partial	Partially completed
Denied	Permission denied
Error	System error occurred

Via CLI

List Audit Logs

# List recent audit logs
mantisctl audit list

# Filter by category
mantisctl audit list --category deployment

# Filter by actor (user UUID)
mantisctl audit list --actor-id 550e8400-e29b-41d4-a716-446655440000

# Filter by date range (ISO 8601)
mantisctl audit list --from "2024-12-01T00:00:00Z" --to "2024-12-20T23:59:59Z"

# Filter by severity (one of: info, warning, error, critical, security)
mantisctl audit list --severity critical

# Filter by outcome
mantisctl audit list --outcome failure

# Combine filters
mantisctl audit list \
  --category authentication \
  --severity critical \
  --outcome failure \
  --from "2024-12-20T00:00:00Z"

View Entry Details

# Get specific audit entry (by entry ID or event UUID)
mantisctl audit get 550e8400-e29b-41d4-a716-446655440000

# Output:
# Audit Log Entry
# ════════════════════════════════════════
# ID:           1247
# Event ID:     550e8400-e29b-41d4-a716-446655440000
# Event Type:   deployment.created
# Category:     deployment
# Severity:     info
#
# Actor Type:   user
# Actor ID:     9f8e7d6c-5b4a-3210-fedc-ba9876543210
# Actor Name:   alice
#
# Resource Type: deployment
# Resource ID:   123
# Resource Name: customer-portal v1.2.0 to Production
#
# Action:       create
# Outcome:      success
#
# Occurred at:  2024-12-20T14:32:15.123456
# Entry Hash:   a1b2c3d4e5f6...

Export Audit Logs

# Export to JSON
mantisctl audit export --format json --output audit-logs.json

# Export to CSV
mantisctl audit export --format csv --output audit-logs.csv

# Export with filters
mantisctl audit export \
  --category deployment \
  --from "2024-12-01T00:00:00Z" \
  --to "2024-12-31T23:59:59Z" \
  --format json \
  --output december-deployments.json

Hash Chain Integrity

Understanding Hash Chains

Audit logs use cryptographic hash chains to prevent tampering:

Each entry includes:

Entry Hash: SHA-256 hash of the entry content
Previous Hash: Hash of the preceding entry
Chain Sequence: Entry position in the chain

Per-Tenant Chains

Each tenant has its own hash chain for data isolation:

Global Chain (system events):
  [System Entry 1] → [System Entry 2] → [System Entry 3]

Tenant "Acme Corp" Chain:
  [Acme Entry 1] → [Acme Entry 2] → [Acme Entry 3]

Tenant "Beta Inc" Chain:
  [Beta Entry 1] → [Beta Entry 2] → [Beta Entry 3]

Verifying Integrity

# Verify hash chain integrity for a tenant (by tenant UUID)
mantisctl audit verify --tenant-id 019b937d-4862-84ae-9c2a-6ac230cc4c7e

# Output:
# Audit Chain Integrity Check
# ════════════════════════════════════════
# Status: VALID
# Entries checked: 1247
# Checked at: 2024-12-20T02:00:00.123456789

Integrity Violations

A violation over entries written before an upgrade may be the hash change rather than tampering: the entry hash is computed over microsecond timestamps and previously used milliseconds, so a pre-change chain cannot be recomputed. See Upgrades. Entries written after the upgrade verify normally.

If tampering is detected:

┌─────────────────────────────────────────────────────────────┐
│  ⚠ Integrity Violation Detected                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Chain: Tenant "Acme Corp"                                  │
│  Entry: #1,245                                              │
│  Expected Hash: a1b2c3d4...                                 │
│  Actual Hash: x9y8z7w6...                                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ This indicates potential tampering with the audit log.│ │
│  │ Contact your security team immediately.               │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Common Event Types

Authentication Events

Event Type	Description
`auth.login_success`	Successful user login
`auth.login_failure`	Failed login attempt
`auth.logout`	User logged out
`auth.token_issued`	Authentication token issued
`auth.token_revoked`	Token revoked
`auth.token_refresh`	Access token refreshed
`auth.token_refresh_failed`	Token refresh was rejected
`auth.token_grant_refused`	OAuth token grant refused
`auth.password_changed`	Password was changed
`auth.session_revoked`	A session was revoked
`auth.sessions_revoked_all`	Every other session revoked
`auth.2fa_enabled`	Two-factor enrolment completed
`auth.2fa_verified`	Second factor checked at login
`auth.api_key_created`	API key created

Deployment Events

Event Type	Description
`deployment.created`	Deployment initiated
`deployment.started`	Deployment execution began
`deployment.completed`	Deployment finished
`deployment.cancelled`	An operator stopped a deployment
`deployment.freeze_override`	Freeze was overridden
`deployment.off_target_execution`	Ran on a Thorax instance
`deployment.instance_moved`	A failure handler moved to another member of its pool
`deployment.promoted`	Promoted to another environment
`deployment.rolled_back`	Deployment was rolled back

Per-step progress is not an audit event: steps are execution records, read through the deployment’s own detail and log endpoints.

Configuration Events

Event Type	Description
`config.solution_created`	Solution created
`config.solution_updated`	Solution modified
`config.solution_deleted`	Solution deleted
`config.sequence_created`	Sequence created
`config.action_created`	Action created
`config.environment_created`	Environment created
`config.imported`	Config documents imported
`config.repository_created`	Config repository connected

Target Events

Event Type	Description
`target.created`	Target created
`target.updated`	Target modified
`target.deleted`	Target deleted
`target.thorax_reassigned`	Moved to another Thorax instance
`auth.registration_approved`	An agent’s registration approved
`auth.registration_revoked`	An agent’s registration revoked

Retention

Audit entries are append-only and immutable — database triggers reject any UPDATE, DELETE or TRUNCATE, so the log cannot be tampered with or silently trimmed. Mantis keeps every entry until an administrator ages a quarter out; there is no schedule and no retention policy that runs on its own.

Ageing a completed quarter out is a single administrator-invoked operation: mantisctl audit archive (or POST /api/v1/audit/archives, both needing system:admin). It verifies every chain the quarter holds, writes the entries to your destination, reads them back to confirm they are retrievable, records the archive, and only then drops the partition — refusing, with the entries left in place, if the quarter is still open or any chain does not verify. See Database maintenance for the full procedure.

Deleting entries any other way means a database administrator using the mantis_audit_retention role, which the immutability triggers allow to delete. That keeps no archive and verifies no chain, so a tampered quarter is destroyed along with the evidence of the tampering.

Best Practices

1. Monitor Security Events

Set up alerts for security-related events:

Event	Alert Priority
`auth.login_failure` (repeated)	Critical
`auth.2fa_verified` (outcome other than success)	Critical
`promotion.approval_denied`	High
`authz.permission_denied` (unusual)	Medium
`deployment.freeze_override`	Medium

2. Regular Integrity Checks

Schedule periodic integrity verification:

# Add to cron (verify a tenant's chain nightly; alert on non-zero exit)
0 2 * * * mantisctl audit verify --tenant-id 019b937d-4862-84ae-9c2a-6ac230cc4c7e --json || notify-failure

3. Secure Exported Logs

Archives written by mantisctl audit archive, and any logs you export (below), hold the same entries as the live table and need the same protection:

Requirement	Recommendation
Encryption	Enable at-rest encryption
Access control	Restrict to security team
Immutability	Use write-once storage
Geographic redundancy	Store in multiple regions

4. Compliance Reporting

Export a date-bounded log set for compliance review or downstream report generation:

# Export a month of audit events for compliance review
mantisctl audit export \
  --from "2024-12-01T00:00:00Z" \
  --to "2024-12-31T23:59:59Z" \
  --format csv \
  --output compliance-dec-2024.csv

5. Document Retention Requirements

Regulation	Minimum Retention
PCI DSS	1 year (3 months immediately available)
HIPAA	6 years
SOC 2	Based on policy
GDPR	As long as necessary

Troubleshooting

Audit Logs Not Appearing

Cause: Async batch processing delay

Solution:

Logs are batched for performance (up to 1 second delay)
Check if audit service is running
Verify database connectivity

High Audit Queue Depth

Cause: Database write bottleneck

Solution:

Check database performance
Review batch size configuration
Consider scaling database

Hash Verification Failures

Cause: Potential tampering or data corruption

Solution:

Investigate immediately
Check for database issues
Review backup integrity
Contact security team

Missing Events

Cause: Channel overflow during high load

Solution:

Increase channel buffer size
Scale audit service
Review event volume

Next Steps

Tags - Organize resources
Deployment Freezes - Block deployments