Audit Logs

Turqoa maintains an immutable, append-only audit log of all system events, user actions, and automated decisions. The audit log is a critical component for regulatory compliance, security investigations, and operational accountability.

Audit Log Structure

Every audit record contains a standardized set of fields:

Field	Type	Description
`id`	UUID	Unique identifier for the audit entry
`timestamp`	ISO 8601	UTC timestamp with millisecond precision
`event_type`	String	Category of the event (see Event Types below)
`action`	String	Specific action performed
`actor_type`	Enum	`user`, `system`, or `integration`
`actor_id`	String	User email, service name, or integration ID
`resource_type`	String	Type of resource affected
`resource_id`	String	Unique ID of the affected resource
`details`	JSON	Action-specific metadata
`ip_address`	String	Source IP (for user actions)
`session_id`	String	Session identifier (for user actions)
`checksum`	String	SHA-256 hash for tamper detection

Event Types

Event Type	Examples
`auth`	Login, logout, SSO authentication, failed login attempt
`gate`	Transaction created, approved, rejected, overridden
`security`	Incident created, acknowledged, resolved, escalated
`admin`	User created, role changed, configuration updated
`system`	Service started, model deployed, integration connected
`drone`	Mission dispatched, completed, aborted

Example Audit Record

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-03-15T14:32:07.123Z",
  "event_type": "gate",
  "action": "transaction.override.approve",
  "actor_type": "user",
  "actor_id": "jsmith@terminal.example.com",
  "resource_type": "gate_transaction",
  "resource_id": "TXN-2026-0315-00847",
  "details": {
    "original_decision": "rejected",
    "override_reason": "OCR misread container number",
    "corrected_container_number": "MSCU1234567",
    "confidence_score": 0.42
  },
  "ip_address": "10.0.5.23",
  "session_id": "sess_8a7b6c5d4e3f2g1h",
  "checksum": "a1b2c3d4e5f6..."
}

Querying Logs

Via Admin Panel

Navigate to Admin > Audit Logs. Use the filter panel to narrow results:

Date range --- Select start and end dates
Event type --- Filter by category (auth, gate, security, admin, system)
Actor --- Search by user email or system service name
Resource --- Search by resource type or ID
Action --- Filter by specific action (e.g., transaction.override)

Via API

# Query audit logs with filters
curl -s "https://turqoa.example.com/api/v1/admin/audit-logs" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -G \
  --data-urlencode "start=2026-03-01T00:00:00Z" \
  --data-urlencode "end=2026-03-31T23:59:59Z" \
  --data-urlencode "event_type=gate" \
  --data-urlencode "action=transaction.override*" \
  --data-urlencode "limit=100" | jq .

Via CLI

# Recent gate overrides
turqoa admin audit query \
  --event-type gate \
  --action "transaction.override*" \
  --since 7d \
  --format table

# All actions by a specific user
turqoa admin audit query \
  --actor jsmith@terminal.example.com \
  --since 30d \
  --format json

Export Formats

Audit logs can be exported for external analysis, compliance reporting, or legal proceedings.

Format	Use Case	Command
JSON	Programmatic analysis, SIEM ingestion	`turqoa admin audit export --format json`
CSV	Spreadsheet analysis, compliance reports	`turqoa admin audit export --format csv`
PDF	Legal proceedings, regulatory submissions	`turqoa admin audit export --format pdf`

Scheduled Exports

Configure automatic exports on a recurring schedule:

audit:
  exports:
    - schedule: "0 2 * * *"      # Daily at 2 AM UTC
      format: json
      destination: s3://terminal-audit-bucket/daily/
      retention_days: 365
    - schedule: "0 6 1 * *"      # Monthly on the 1st at 6 AM
      format: pdf
      destination: /mnt/compliance/monthly-reports/
      include_summary: true

Retention Policies

Audit log retention is configurable per event type. Records beyond the retention period are archived (not deleted) to cold storage.

Event Type	Default Retention (Hot)	Archive Retention	Regulatory Minimum
`auth`	180 days	7 years	Varies by jurisdiction
`gate`	365 days	7 years	180 days (MTSA)
`security`	365 days	7 years	365 days (MTSA)
`admin`	365 days	7 years	180 days
`system`	90 days	3 years	None
`drone`	365 days	7 years	365 days

audit:
  retention:
    hot_storage_days: 365
    archive_storage_days: 2555   # 7 years
    archive_backend: s3           # s3, azure-blob, gcs, or local
    archive_bucket: terminal-audit-archive
    compression: zstd

Compliance Reporting

Turqoa includes built-in compliance report templates aligned with common port security regulations:

Report	Regulation	Frequency	Content
MTSA Access Control	Maritime Transportation Security Act	Monthly	Gate access logs, denied entries, security incidents
ISPS Audit	International Ship and Port Facility Security Code	Quarterly	Security events, drills, system changes
CTPAT Compliance	Customs-Trade Partnership Against Terrorism	Annual	Supply chain security controls, access logs
Custom	Organization-specific	Configurable	User-defined filters and aggregations

Generate a compliance report:

turqoa admin reports generate \
  --template mtsa-access-control \
  --period 2026-03 \
  --output /reports/mtsa-march-2026.pdf

Note: Audit logs are cryptographically chained using SHA-256 checksums. Each record's checksum includes the previous record's checksum, creating a tamper-evident chain. Any modification to historical records is detectable through checksum verification.