Observability

SafeClaw provides comprehensive audit logging, real-time alerting, and a centralized event bus for security monitoring.

Audit System

Audit Events

pub enum AuditSeverity {
    Info,
    Warning,
    High,
    Critical,
}

pub enum LeakageVector {
    OutputChannel,       // AI output contained tainted data
    ToolCall,            // Tool call arguments contained tainted data
    DangerousCommand,    // Dangerous command pattern detected
    NetworkExfil,        // Network exfiltration attempt
    FileExfil,           // File write with tainted data
    AuthFailure,         // Channel authentication failure
}

pub struct AuditEvent {
    pub id: String,
    pub session_id: String,
    pub severity: AuditSeverity,
    pub vector: LeakageVector,
    pub description: String,
    pub taint_labels: Vec<String>,
    pub timestamp: i64,
}

Audit Log

pub struct AuditLog {
    events: VecDeque<AuditEvent>,
    capacity: usize,
    total_count: u64,
}

impl AuditLog {
    pub fn record(&mut self, event: AuditEvent);
    pub fn recent(&self, limit: usize) -> Vec<&AuditEvent>;
    pub fn by_session(&self, session_id: &str) -> Vec<&AuditEvent>;
    pub fn by_severity(&self, severity: AuditSeverity) -> Vec<&AuditEvent>;
}

Default capacity is 10,000 events (configurable via audit.log_capacity).

Event Bus

Centralized event distribution for all security subsystems:

pub struct AuditEventBus {
    // Broadcast channel for audit events
}

All components publish to the event bus:

Privacy classifier → PII detection events
Taint registry → Taint registration events
Output sanitizer → Redaction events
Injection detector → Injection detection events
Tool interceptor → Tool block events
Network firewall → Network block events
Channel auth → Authentication events

Alerting

pub struct AlertMonitor {
    // Monitors audit events and triggers alerts
}

pub struct Alert {
    // Alert with severity, message, and context
}

pub struct AlertConfig {
    // Alert thresholds and notification targets
}

Alerts are triggered when:

Critical severity events occur (immediate)
High severity events exceed a threshold within a time window
Multiple Warning events from the same session (cumulative risk)

REST API

Audit Endpoints

Prop

Type

Events Endpoints

Prop

Type

Health and Status

Prop

Type

Example: Audit Events Response

{
  "events": [
    {
      "id": "evt-001",
      "session_id": "sess-abc",
      "severity": "High",
      "vector": "OutputChannel",
      "description": "Tainted email detected in AI output, redacted",
      "taint_labels": ["taint-email-001"],
      "timestamp": 1707734460
    },
    {
      "id": "evt-002",
      "session_id": "sess-abc",
      "severity": "Critical",
      "vector": "DangerousCommand",
      "description": "Blocked curl command with tainted API key in arguments",
      "taint_labels": ["taint-apikey-003"],
      "timestamp": 1707734465
    }
  ],
  "total_count": 2
}

Configuration

[audit]
enabled = true
log_capacity = 10000

[audit.alert_config]
# Alert thresholds and notification settings

Structured Logging

SafeClaw uses the tracing crate for structured logging:

# Set log level
safeclaw --config safeclaw.toml --log-level debug

# Environment variable
RUST_LOG=safeclaw=debug safeclaw --config safeclaw.toml

Log output includes:

Session ID for correlation
Sensitivity level for each message
Routing decisions (local vs. TEE)
Taint registration and detection events
Injection detection results
Tool interception decisions
Network firewall decisions

Observability

On this page