Anomaly Detection

Agent Action Firewall monitors agent behavior patterns and alerts when activity deviates from established baselines. This helps detect compromised agents, misconfigurations, and security incidents.

How It Works

1. Learning Phase: AAF observes agent behavior for 7 days
2. Baseline Creation: Statistical model of normal behavior
3. Real-time Monitoring: Each action compared against baseline
4. Alerting: Anomalies trigger notifications and audit events

Monitored Behaviors

Risk Scoring

Each agent receives a real-time risk score (0.0 - 1.0):

Configuration

Organization Settings

await api.put('/anomaly-detection/settings', {
  enabled: true,
  learning_period_days: 7,
  sensitivity: 'medium', // 'low' | 'medium' | 'high'
  alert_threshold: 0.5,
  auto_block_threshold: 0.9
});

Per-Agent Settings

await api.put('/agents/{id}/anomaly-settings', {
  sensitivity: 'high', // More sensitive for critical agents
  baseline_refresh_days: 14,
  excluded_patterns: [
    'GET https://api.github.com/*' // Ignore GitHub API variability
  ]
});

Alert Configuration

Notification Channels

await api.post('/anomaly-detection/alerts', {
  threshold: 0.6,
  channels: ['email', 'slack'],
  slack_channel: '#security-alerts',
  email_recipients: ['security@example.com'],
  cooldown_minutes: 30 // Prevent alert storms
});

Alert Payload

{
  "alert_type": "anomaly.detected",
  "timestamp": "2024-01-15T10:30:00Z",
  "agent": {
    "id": "agent-001",
    "name": "Data Sync Agent",
    "risk_score": 0.75
  },
  "anomalies": [
    {
      "type": "volume_spike",
      "baseline": 50,
      "actual": 500,
      "deviation": 10.0
    },
    {
      "type": "new_resource",
      "resource": "https://prod-db.internal/admin",
      "first_seen": "2024-01-15T10:28:00Z"
    }
  ],
  "recommended_action": "Review recent actions and consider blocking agent"
}

Response Actions

Configure automatic responses to anomalies:

Auto-Block

await api.put('/anomaly-detection/responses', {
  auto_block: {
    enabled: true,
    threshold: 0.9,
    duration_minutes: 60, // Temporary block
    notify: ['admin@example.com']
  }
});

Require Approval

await api.put('/anomaly-detection/responses', {
  require_approval: {
    enabled: true,
    threshold: 0.7,
    // All actions require approval when anomalous
  }
});

Viewing Anomalies

Dashboard

Navigate to Agents → Select Agent → Anomaly Timeline

API

# Get agent's anomaly history
GET /api/v1/agents/{id}/anomalies

# Get all recent anomalies
GET /api/v1/anomalies?since=2024-01-01T00:00:00Z

Response:

{
  "anomalies": [
    {
      "id": "anom-123",
      "agent_id": "agent-001",
      "timestamp": "2024-01-15T10:30:00Z",
      "risk_score": 0.75,
      "types": ["volume_spike", "new_resource"],
      "details": { ... },
      "status": "acknowledged"
    }
  ]
}

Baseline Management

View Current Baseline

GET /api/v1/agents/{id}/baseline

# Response
{
  "agent_id": "agent-001",
  "created_at": "2024-01-08T00:00:00Z",
  "last_updated": "2024-01-15T00:00:00Z",
  "metrics": {
    "actions_per_hour": {
      "mean": 25,
      "std_dev": 8,
      "p95": 45
    },
    "unique_resources_per_day": {
      "mean": 12,
      "std_dev": 3
    },
    "error_rate": {
      "mean": 0.02,
      "std_dev": 0.01
    }
  }
}

Reset Baseline

POST /api/v1/agents/{id}/baseline/reset
{
  "reason": "Agent behavior intentionally changed after upgrade"
}

Manual Adjustment

PATCH /api/v1/agents/{id}/baseline
{
  "actions_per_hour": {
    "mean": 100,  // Increase expected volume
    "std_dev": 20
  }
}

Suppression Rules

Temporarily suppress alerts for expected changes:

await api.post('/anomaly-detection/suppressions', {
  agent_id: 'agent-001',
  types: ['volume_spike'],
  reason: 'Expected high volume during monthly report generation',
  expires_at: '2024-01-16T00:00:00Z'
});

Integration with Policies

Use anomaly data in policies:

# Require approval if agent is anomalous
decision = "require_approval" {
  input.agent.risk_score > 0.5
}

# Block high-risk agents from sensitive operations
decision = "deny" {
  input.agent.risk_score > 0.8
  input.action.params.url == "https://prod-db.internal/admin"
}

Best Practices

Tip: Allow sufficient learning time. The 7-day default captures weekly patterns. For agents with monthly cycles, extend to 30 days.

Tip: Start with medium sensitivity. High sensitivity generates more alerts; tune based on your tolerance.

Tip: Review baselines after changes. When agent behavior intentionally changes, reset or adjust baselines.

Tip: Use suppression rules. For expected anomalies (maintenance windows, batch jobs), suppress alerts rather than ignoring them.

Next Steps

• Policy Engine — Use risk scores in policies
• Audit Trail — Review anomaly detection events