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, Client
Resource	What was affected	Target, Deployment
Outcome	Result of action	`success`, `denied`
Timestamp	When it occurred	`2024-12-20 14:30:00`

Event Categories

Category	Description	Example Events
Authentication	Login, logout, tokens	`auth.login_success`, `auth.token_revoked`
Authorization	Permissions, roles	`authz.permission_denied`, `authz.role_assigned`
Deployment	Deployment lifecycle	`deployment.created`, `deployment.completed`
Configuration	System configuration	`config.solution_created`, `config.variable_updated`
User Management	User administration	`user.created`, `user.locked`
Tenant Management	Tenant operations	`tenant.created`, `tenant.solution_attached`
Target Management	Target operations	`target.registered`, `target.approved`
Certificate	Certificate operations	`cert.created`, `cert.rotated`
Storage	Storage backends	`storage.created`, `storage.accessed`
System	System operations	`system.startup`, `system.config_changed`

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.approved      │ 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
Client	Tarsus agent	Target heartbeat, registration
API Key	API key access	External integrations
Service	Internal service	Thorax orchestration

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 auth \
  --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-20 14:32:15 UTC
# 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 ID, an integer)
mantisctl audit verify --tenant-id 42

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

Integrity Violations

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.session_created`	New session started
`auth.token_issued`	Authentication token issued
`auth.token_revoked`	Token revoked
`auth.password_changed`	Password was changed
`auth.account_locked`	Account locked due to failures
`auth.brute_force_detected`	Brute force attack detected
`auth.api_key_created`	API key created

Deployment Events

Event Type	Description
`deployment.created`	Deployment initiated
`deployment.started`	Deployment execution began
`deployment.step_started`	Step execution started
`deployment.step_completed`	Step completed successfully
`deployment.step_failed`	Step failed
`deployment.completed`	Deployment finished successfully
`deployment.failed`	Deployment failed
`deployment.cancelled`	Deployment was cancelled
`deployment.freeze_override`	Freeze was overridden
`deployment.rolled_back`	Deployment was rolled back

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.variable_created`	Variable created
`config.variable_updated`	Variable modified

Target Events

Event Type	Description
`target.created`	Target created
`target.registered`	Target registration request
`target.approved`	Registration approved
`target.revoked`	Target certificate revoked
`target.command_executed`	Command executed on target

Retention and Archival

Retention Policy

Configure how long to retain audit logs:

┌─────────────────────────────────────────────────────────────┐
│  Audit Log Retention                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Retention Period: [365         ] days                      │
│                                                             │
│  Archive Before Delete: [✓]                                 │
│  Archive Location: [s3://backups/audit-archive   ]          │
│                                                             │
│  Compliance Hold:                                           │
│  ○ None                                                     │
│  ● Security events: [730] days                              │
│  ○ All events: [___] days                                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Security events are retained longer for compliance.   │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│                                     [Cancel]  [Save]        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Archival

There is no dedicated archive/restore subcommand. To retain logs for long-term storage, export a date range and move the output to your archive of choice:

# Export everything before a cutoff for archival
mantisctl audit export \
  --to "2024-01-01T00:00:00Z" \
  --format ndjson \
  --output audit-archive-pre-2024.ndjson

# Then copy the file to long-term storage, e.g.:
# aws s3 cp audit-archive-pre-2024.ndjson s3://backups/audit-archive/

Best Practices

1. Monitor Security Events

Set up alerts for security-related events:

Event	Alert Priority
`auth.brute_force_detected`	Critical
`auth.account_locked`	High
`auth.login_failure` (repeated)	Medium
`authz.permission_denied` (unusual)	Medium
`authz.privilege_escalation`	Critical

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 42 --json || notify-failure

3. Secure Archive Storage

Store audit archives securely:

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