> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.governanceaicore.com/core-concepts/audit-logs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.governanceaicore.com/_mcp/server.

# Audit & Activity Logs

> Complete audit trail and activity logging for compliance and security

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

```json
{
  "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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
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

```bash
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

* **[Compliance Frameworks](./04-compliance-frameworks.mdx)** - Map logs to compliance
* **[Running Scans](/usage-guides/scans)** - Monitor scan activity
* **[API Reference](/api)** - Audit API endpoints

> Complete audit trail and activity logging for compliance and security