Core Concepts

Audit & Activity Logs

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:

User Actions

  • 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:

1{
2  "log_id": "log_1234567890",
3  "timestamp": "2024-01-15T10:30:45.123Z",
4  "organization_id": "org_123",
5  "workspace_id": "ws_456",
6  "actor": {
7    "type": "user",
8    "id": "user_789",
9    "email": "admin@company.com",
10    "ip_address": "192.168.1.1",
11    "user_agent": "Mozilla/5.0..."
12  },
13  "resource": {
14    "type": "policy",
15    "id": "policy_abc",
16    "name": "Production Governance"
17  },
18  "action": "policy_updated",
19  "severity": "medium",
20  "status": "success",
21  "changes": {
22    "before": {"version": "1.0"},
23    "after": {"version": "2.0"}
24  },
25  "details": {
26    "change_description": "Added jailbreak detection guardrail",
27    "reason": "Security hardening after red-team findings"
28  }
29}

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

PlanRetentionSearchableArchival
Pro90 days30 days1 year (cold storage)
Enterprise1 year1 year3 years (cold storage)
Compliance3 years3 years7 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

GDPR Right to Audit

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