​

Audit Logs

​

Critical Audit Chain

• SHA-256 hash-linked — each entry includes a prev_hash (SHA-256 of the prior entry’s canonical bytes) and a monotonic sequence_number. Tampering with any entry breaks its hash and every subsequent prev_hash link, making the tampered row identifiable.
• Append-only forever — database triggers prevent UPDATE and DELETE at the Postgres level. There is no retention pruning on this table.
• Serialized writes — an advisory lock on every write ensures monotonic, gap-free sequence_number values; a gap indicates a deletion attempt.

​

Overview

• 👤 Who made the change (user email)
• 📝 What was changed (resource type and name)
• ⏰ When it happened (timestamp)
• 🔄 What changed (before/after values)
• 🎯 Action performed (create, update, delete, enable, disable)

• API Logs = Requests proxied through routes
• Audit Logs = Changes to KnoxCall configuration

​

What’s Tracked

​

Routes

• ✅ Route created
• ✏️ Route updated (target URL, headers, body, etc.)
• 🗑️ Route deleted
• 🔓 Route enabled/disabled
• 🔄 Route duplicated

​

Secrets

• ✅ Secret created
• 🔄 Secret version added (rotation)
• ✏️ Secret name updated
• 🗑️ Secret deleted

​

Clients

• ✅ Client created (IP address added)
• ✏️ Client updated (IP changed, type changed)
• 🗑️ Client deleted
• 🔓 Client enabled/disabled
• 🔗 Client assigned to route
• ❌ Client unassigned from route

​

Environments

• ✅ Environment created
• ✏️ Environment updated (overrides changed)
• 🗑️ Environment deleted
• 🔄 Environment duplicated

​

Alerts

• ✅ Alert created
• ✏️ Alert updated (conditions, channels)
• 🗑️ Alert deleted
• 🔓 Alert enabled/disabled

​

API Keys

• ✅ API key created
• 🗑️ API key revoked

​

Tenant Settings

• ✏️ Tenant name/slug updated
• ⚙️ Feature settings changed

​

Team Members

• ✅ Team member invited
• 🗑️ Team member removed
• ✏️ Team member role changed

​

Tenant KMS / BYOK

• 🔑 Customer KMS provider onboarded (byok.kms.onboard)
• 🔄 Tenant master key rotated (byok.kms.rotate)
• 🔓 Tenant unsealed (byok.kms.unseal)
• 💣 Tenant master key version revoked — cryptographic erasure (byok.kms.revoke)

​

Secret Store Migrations

• ✅ Migration created (migration.create)
• ❌ Migration cancelled (migration.cancel)
• 🔍 Migration item plaintext revealed to reviewer (migration.item.reveal)
• ✔️ Migration item approved by reviewer (migration.item.approve)
• ✘ Migration item rejected by reviewer (migration.item.reject)
• ⏱️ Migration item expired after 7-day TTL (migration.item.expire)
• ✅ Migration committed as complete (migration.commit)
• 🔌 DB proxy route created for migration (migration.db_proxy_route.create)
• 🗑️ DB proxy route deleted (migration.db_proxy_route.delete)

​

Tenant Impersonation

• 👤 Admin impersonated tenant (tenant.impersonate) — support actions only

​

Viewing Audit Logs

​

Step 1: Navigate to Audit Logs

1. Click Logs in the sidebar
2. Select Audit Logs
3. See recent changes (most recent first)

​

Step 2: Use Filters

☐ Create
☐ Update
☐ Delete
☐ Enable
☐ Disable

☐ Route
☐ Secret
☐ Client
☐ Environment
☐ Alert
☐ API Key
☐ Tenant
☐ Team Member
☐ Tenant KMS Config
☐ Migration

​

Step 3: View Change Details

Action: Route Updated
Resource: stripe-payments (route_abc123)
User: john@example.com
Timestamp: 2025-01-15 10:30:45 EST

target_url:
- https://api.stripe.com/v1/charges
+ https://api.eu.stripe.com/v1/charges

inject_headers_json:
  Authorization:
-   Bearer {{secret:stripe-test-key}}
+   Bearer {{secret:stripe-prod-key}}

IP Address: 203.45.67.89
User Agent: Mozilla/5.0 (Windows NT 10.0)
Session ID: sess_xyz789

​

Common Use Cases

​

Use Case 1: Troubleshooting Configuration Issues

1. Navigate to Audit Logs
2. Filter by Resource Type: Route
3. Filter by Resource Name: broken-route
4. See recent changes:
   2 hours ago: john@example.com updated target_url
   Old: https://api.service.com/v1
   New: https://api.service.com/v2 (typo: should be v1)
   
5. Identify issue: Incorrect URL
6. Fix: Revert URL to v1

​

Use Case 2: Security Audit

1. Export audit logs for last 90 days
2. Filter by Action: Delete, Disable
3. Review all deletions/disablements
4. Verify authorized by appropriate users
5. Document for auditor

​

Use Case 3: Secret Rotation Tracking

1. Filter by Resource Type: Secret
2. Filter by Action: Update (new version)
3. Check last rotation date for each secret
4. Identify secrets due for rotation
5. Rotate overdue secrets

​

Use Case 4: Unauthorized Changes

1. Filter by User: (specific team member)
2. Review all changes by that user
3. Check timestamps (after hours?)
4. Verify changes were authorized
5. Take action if unauthorized

​

Use Case 5: Change Correlation

1. Note time of spike: 10:30 AM
2. Filter audit logs by time: 10:00-10:45 AM
3. See changes during that window:
   10:25 AM: sarah@example.com updated stripe-payments route
   Changed: rate_limit from 100/min to 10/min
   
4. Identified: Rate limit too restrictive
5. Fix: Revert rate limit

​

Deep Links

• “View History” button → Audit logs for that route

• “View History” button → Secret rotation history

• “View History” button → Client assignment changes

• “View History” button → Alert configuration changes

​

Audit Log Entry Details

​

Full Information Captured

• Email address
• User ID
• IP address (where request originated)
• Session ID

• Resource type (route, secret, client, etc.)
• Resource ID
• Resource name
• Tenant ID

• Action (create, update, delete, etc.)
• Timestamp (with timezone)
• Before values (for updates)
• After values (for updates)
• Full diff (JSON format)

{
  "id": "audit_abc123",
  "action": "update",
  "resource_type": "route",
  "resource_id": "route_xyz789",
  "resource_name": "stripe-payments",
  "user_id": "user_def456",
  "user_email": "john@example.com",
  "timestamp": "2025-01-15T15:30:45Z",
  "ip_address": "203.45.67.89",
  "changes": {
    "target_url": {
      "old": "https://api.stripe.com/v1",
      "new": "https://api.eu.stripe.com/v1"
    },
    "rate_limit_requests": {
      "old": 100,
      "new": 150
    }
  }
}

​

Export Options

​

CSV Export (Pro/Enterprise Only)

• Timestamp
• User email
• Action
• Resource type
• Resource name
• Summary of changes

1. Apply filters to select logs
2. Click Export button
3. CSV downloads automatically

audit-logs-{tenant-slug}-{timestamp}.csv

​

JSON Export (Enterprise Only)

• Complete JSON for each entry
• Includes before/after values
• All metadata preserved

​

Retention Policies

• Audit logs automatically deleted
• Export before expiration for permanent records

​

Compliance Features

​

SOC 2 / ISO 27001 Requirements

• ✅ Who: User identification
• ✅ What: Resource and action
• ✅ When: Timestamp with timezone
• ✅ How: Change details (before/after)
• ✅ Integrity: Immutable (cannot be edited)
• ✅ Export: CSV/JSON for auditors

​

GDPR Compliance

• User email addresses (can be pseudonymized)
• IP addresses (can be anonymized)
• Configuration changes (no PII)

• Audit logs deleted per retention policy
• Can export before deletion

​

Best Practices

​

1. Regular Review

• Review all changes
• Verify authorized
• Identify unauthorized activity

• Export audit logs
• Archive for compliance
• Review trends

​

2. Document Standard Changes

2025-01-15:
- Updated stripe-payments target URL for EU region
- Rotated stripe-prod-key secret (scheduled)
- Added client: production-server-03

​

3. Monitor High-Risk Actions

• Deletions (routes, secrets, clients)
• Disablements (routes, alerts)
• Secret rotations (ensure scheduled)
• API key revocations (verify authorized)

​

4. Use Filters for Investigations

1. All changes today
2. Filter by resource type (e.g., routes)
3. Filter by specific route
4. View detailed changes

​

5. Export for Compliance

1. Export full audit log history
2. Store securely (encrypted)
3. Provide to auditors when required
4. Maintain for legal retention period

​

Troubleshooting

​

Issue: “Audit log missing”

• Change happened before audit logging enabled
• Entry expired (past retention period)
• System issue (rare)

• Verify retention period
• Confirm timestamp within retention

​

Issue: “Can’t see changes by other users”

​

Issue: “Export button disabled”

​

Issue: “Diff not showing”

​

Related Features

• API Logs: Track API request activity (different from config changes)
• Alerts: Set up alerts for specific configuration changes (coming soon)
• Team Management: Control who can make changes

​

Next Steps