Audit Logging

Controlinfra records an audit trail of every authenticated mutation taken within your organization, plus the auth events that book-end a session. Audit logs help with compliance (SOC 2, ISO 27001), security investigations, and understanding who changed what.

Coverage

Audited automatically — by default, authenticated POST, PUT, PATCH, and DELETE requests land in the audit log, except for the skipped-by-design endpoints listed below. The middleware captures the matched route, redacted body, status code, actor, IP, and a timestamp. Action names are auto-derived from the route pattern (e.g. PUT /api/orgs/:orgId → http.put.orgs.orgId, or PUT /api/orgs/:orgId/roles/:roleId → http.put.orgs.orgId.roles.roleId); when a controller has explicit handling the auto-name is suppressed and a curated name (scan.triggered, member.role_changed, etc.) is used instead.

Auth events with explicit names:

Event	Action
Login (email/password)	auth.login
Login (GitHub OAuth)	auth.login (metadata authMethod: github_oauth)
Login (SAML SSO)	auth.login
Logout	auth.logout
Signup	auth.signup
GitHub account linked	auth.github_account_added
CLI token issued / revoked	auth.cli_token_created / auth.cli_token_revoked

Skipped by design (would multiply audit volume by ~50× without security signal):

• All GET / HEAD / OPTIONS requests (reads)
• High-frequency telemetry: /api/csrf-token, /api/stats/*, /api/analytics/*, /api/status/*
• Health probes: /health, /api/auth/me
• Notification ping endpoints

Body redaction — fields whose key matches password, *token*, *secret*, *key*, *authorization*, webhookUrl, cookie, csrf (case-insensitive substring match) are replaced with [REDACTED] in the stored metadata. Nested objects redact recursively.

What's Logged

Authentication & Access

• User login (GitHub OAuth, SSO/SAML)
• Login failures
• API token creation and revocation
• Session management

Organization Management

• Member added, removed, or role changed
• Member moved between organizations
• Organization settings updated
• IP allowlist changes
• Plan upgrades/downgrades

Repository Operations

• Repository connected or disconnected
• Repository configuration updated
• Scan triggered (manual or scheduled)
• Scan completed or failed

Drift Management

• Drift detected
• Fix generated (AI)
• Pull request created
• Pull request merged
• Drift resolved

Cloud Discovery

• Discovery scan triggered
• Resources discovered
• Resource ignored or resolved
• Terraform code generated
• Terraform import validated

Drift Watch

• Watch created or removed
• Watch enabled/disabled
• Watch snoozed/unsnoozed
• Baseline accepted or reverted
• Drift watch check results

Guardrails

• Guardrail created, updated, or deleted
• Rule added, updated, or removed
• Guardrail deployed or undeployed
• Break-glass activated or revoked
• Approval request approved or denied

Runner Operations

• Runner created or deleted
• Runner token regenerated
• Runner online/offline status changes
• Runner moved between organizations

Workspace Operations

• Workspace created, updated, or deleted
• Repository moved between workspaces
• Access permissions changed

---

Accessing Audit Logs

Audit logs are available to organization owners and admins.

Via Settings

1. Go to Settings > Security > Audit Log
2. Filter by date range, action type, or user
3. Export as CSV for compliance reporting

Via API

GET /api/audit-logs?from=2026-01-01&to=2026-04-01&action=drift_watch.snoozed&limit=100

Query parameters:

• from / to — Date range (ISO 8601)
• action — Filter by action type (e.g., scan.triggered, guardrail.deployed)
• userId — Filter by acting user
• limit / page — Pagination

---

Retention

Plan	Retention
Free	7 days
Pro	30 days
Team	90 days
Enterprise	1 year (configurable)

Audit logs older than the retention period are permanently deleted by an automated cleanup job.

---

Log Entry Format

Each audit log entry contains:

Field	Description
timestamp	When the action occurred (UTC)
userId	Who performed the action
action	Action type (e.g., guardrail.deployed)
resourceType	What was acted on (e.g., guardrail, scan)
resourceId	ID of the affected resource
details	Additional context (varies by action)
ipAddress	Source IP of the request
userAgent	Browser/client information

---

Security Considerations

• Audit logs are immutable — they cannot be edited or deleted by users
• Logs are stored in a separate collection with restricted access
• Enterprise plans support log forwarding to external SIEM systems (Splunk, Datadog, Elastic, etc.)
• All sensitive fields (tokens, secrets) are masked in log entries