Audit & Activity Logs

GovernanceAI maintains a complete, immutable audit trail of all system activities for compliance, security monitoring, and investigation.

What Gets Logged?

Every action in GovernanceAI generates an audit log entry:

Login/logout
API key creation/rotation/revocation
Policy changes
Guardrail modifications
Settings updates
Data exports
Report generation

API Calls

Guardrail evaluations
Policy enforcement decisions
Scan requests
Red-team campaigns
Report generation

System Events

Deployment changes
Integration connections/disconnections
Database operations
Error events
Security incidents

Data Access

Who accessed what data
When it was accessed
What operation was performed
From which IP/client

Log Entry Structure

Each audit log includes:

{
  "log_id": "log_1234567890",
  "timestamp": "2024-01-15T10:30:45.123Z",
  "organization_id": "org_123",
  "workspace_id": "ws_456",
  "actor": {
    "type": "user",
    "id": "user_789",
    "email": "admin@company.com",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  },
  "resource": {
    "type": "policy",
    "id": "policy_abc",
    "name": "Production Governance"
  },
  "action": "policy_updated",
  "severity": "medium",
  "status": "success",
  "changes": {
    "before": {"version": "1.0"},
    "after": {"version": "2.0"}
  },
  "details": {
    "change_description": "Added jailbreak detection guardrail",
    "reason": "Security hardening after red-team findings"
  }
}

Querying Audit Logs

Via Dashboard

Go to Settings → Audit Log
Filter by:
- Date range
- Action type
- User/actor
- Resource type
- Status (success/failure)
View details or export

Via API

# Get all audit logs
curl -H "Authorization: Bearer $API_KEY" \
  https://api.governanceai.com/v1/audit/logs
# Filter by date
curl -H "Authorization: Bearer $API_KEY" \
  'https://api.governanceai.com/v1/audit/logs?start_date=2024-01-01&end_date=2024-01-31'
# Filter by action
curl -H "Authorization: Bearer $API_KEY" \
  'https://api.governanceai.com/v1/audit/logs?action=guardrail_updated'
# Filter by user
curl -H "Authorization: Bearer $API_KEY" \
  'https://api.governanceai.com/v1/audit/logs?actor_id=user_123'
# Combine filters
curl -H "Authorization: Bearer $API_KEY" \
  'https://api.governanceai.com/v1/audit/logs?action=policy_updated&severity=high&status=success'

Pagination

# Get page 1, 100 results per page
curl -H "Authorization: Bearer $API_KEY" \
  'https://api.governanceai.com/v1/audit/logs?page=1&page_size=100'
# Response
{
  "entries": [...],
  "pagination": {
    "page": 1,
    "page_size": 100,
    "total_count": 5432,
    "total_pages": 55
  }
}

Activity Log Retention

Retention Policies

Plan	Retention	Searchable	Archival
Pro	90 days	30 days	1 year (cold storage)
Enterprise	1 year	1 year	3 years (cold storage)
Compliance	3 years	3 years	7 years (cold storage)

Archival & Export

# Export logs for archival
curl -H "Authorization: Bearer $API_KEY" \
  https://api.governanceai.com/v1/audit/logs/export \
  -d '{
    "format": "json",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31"
  }' \
  --output audit_logs_2023.json.gz
# Archive to long-term storage
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@audit_logs_2023.json.gz" \
  https://api.governanceai.com/v1/audit/archive

Security & Integrity

Immutable Logs

Once written, logs cannot be modified:

❌ Cannot edit existing entries
❌ Cannot delete entries
✅ Can only query/export
✅ Hash chain prevents tampering

Hash Verification

Each entry includes a cryptographic hash of the previous entry:

Entry N:
├─ log_id: log_n
├─ data: {...}
├─ hash: sha256(entry_n_data)
├─ previous_hash: sha256(entry_n-1_data)

This creates a tamper-evident chain. Any modification would break the hash chain.

Access Control

Who can view audit logs:

Organization Admin - All logs for organization
Workspace Admin - Logs for their workspace only
Security/Compliance - Logs relevant to their function
Regular Users - Their own action logs only
Auditors - Read-only access to all logs

# Configure access
curl -X POST https://api.governanceai.com/v1/rbac/roles/edit \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "role": "auditor",
    "permissions": {
      "audit": ["read"],
      "compliance": ["read"]
    }
  }'

SIEM Integration

Export logs to your Security Information and Event Management system:

Syslog Integration

# Configure syslog forwarding
curl -X POST https://api.governanceai.com/v1/integrations/syslog \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "enabled": true,
    "syslog_host": "siem.company.com",
    "syslog_port": 514,
    "protocol": "tcp",
    "facility": "local0",
    "format": "RFC3164"
  }'

CloudWatch Integration

# Forward to AWS CloudWatch
curl -X POST https://api.governanceai.com/v1/integrations/cloudwatch \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "enabled": true,
    "log_group": "/governanceai/audit",
    "aws_region": "us-east-1",
    "aws_access_key_id": "***",
    "aws_secret_access_key": "***"
  }'

Splunk Integration

# Forward to Splunk
curl -X POST https://api.governanceai.com/v1/integrations/splunk \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "enabled": true,
    "hec_token": "***",
    "hec_endpoint": "https://splunk.company.com:8088",
    "sourcetype": "_json"
  }'

Alerts & Notifications

Real-Time Alerts

Get notified of critical events:

# Alert on suspicious activity
curl -X POST https://api.governanceai.com/v1/alerts/rules \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "Unauthorized API Key Creation",
    "condition": {
      "action": "api_key_created",
      "actor_role": "not:admin"
    },
    "severity": "critical",
    "notification_channels": ["email", "slack"],
    "recipients": ["security@company.com"]
  }'
# Alert on bulk data export
curl -X POST https://api.governanceai.com/v1/alerts/rules \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "Large Data Export",
    "condition": {
      "action": "logs_exported",
      "entry_count_greater_than": 10000
    },
    "notification_channels": ["slack"],
    "recipients": ["security-team"]
  }'

Reports & Analysis

Audit Summary Report

curl -H "Authorization: Bearer $API_KEY" \
  https://api.governanceai.com/v1/audit/reports/summary \
  -d '{
    "period": "monthly",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }'
# Returns:
{
  "period": "January 2024",
  "total_events": 52430,
  "by_action": {
    "guardrail_evaluated": 50000,
    "policy_updated": 150,
    "user_login": 250,
    "api_key_created": 20,
    "scan_executed": 10
  },
  "by_severity": {
    "critical": 2,
    "high": 45,
    "medium": 380,
    "low": 52003
  },
  "failed_actions": 12,
  "failed_percentage": 0.02
}

User Activity Report

curl -H "Authorization: Bearer $API_KEY" \
  https://api.governanceai.com/v1/audit/reports/user-activity \
  -d '{"user_id": "user_123", "period": "2024-01"}'
# Returns activity summary for specific user

Compliance Use Cases

SOC2 Audit Trail

GovernanceAI’s audit logs provide evidence for SOC2 CC7.2 (Monitoring):

Control: CC7.2 - System Monitoring
Evidence:
├─ Audit logs enabled: ✅
├─ Retention period: 1 year ✅
├─ Immutable logs: ✅
├─ Access controls: ✅
└─ Regular review: ✅

HIPAA Audit Controls

Maps to HIPAA 45 CFR § 164.312(b) - Audit Controls:

Requirement: Log all accesses to ePHI
GovernanceAI Provides:
├─ User authentication logs
├─ Data access logs
├─ Change logs (policy/guardrail updates)
├─ Error and security event logs
└─ Immutable audit trail

Provides evidence for GDPR Article 32 (Security):

Requirement: Demonstrate appropriate security measures
Evidence:
├─ User access logs
├─ Data processing logs
├─ Encryption status
├─ Incident response logs
└─ Regular security reviews

Best Practices

✅ Do:

Review audit logs regularly
Set up alerts for critical events
Export logs regularly for backup
Archive old logs for compliance
Monitor for suspicious patterns
Integrate with SIEM
Test log integrity periodically

❌ Don’t:

Ignore audit logs
Delete or modify logs
Store logs without backup
Disable audit logging
Share logs without access control
Forget to review sensitive actions

Next Steps

Compliance Frameworks - Map logs to compliance
Running Scans - Monitor scan activity
API Reference - Audit API endpoints