> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Anomaly Detection

> Automatic detection of rate spikes and destructive tool call patterns, with per-type cooldowns and SSE broadcast.

# Anomaly Detection

Igris includes built-in anomaly detection that monitors tool call patterns and alerts when suspicious activity is detected. Anomaly events are written to the audit trail and broadcast via SSE for real-time dashboard updates.

Source: `packages/proxy/src/anomaly.ts`, `apps/api/src/index.ts`.

## Detection Methods

### Rate Spike Detection

Monitors the rate of tool calls per session and fires when the count exceeds a flat threshold within a sliding time window.

**How it works:**

1. Igris maintains a sliding window of tool call timestamps per session
2. On each tool call, expired timestamps are evicted from the window
3. If the number of calls still in the window exceeds the threshold, a rate spike anomaly is triggered

**Default configuration** (verified at `apps/api/src/index.ts` line 279):

* Threshold: **more than 50 calls within any 60-second window**

### Destructive Pattern Detection

Watches for tool calls that match known destructive name patterns, regardless of the policy action applied to that call.

Monitored patterns (verified at `apps/api/src/index.ts` line 282):

* `delete_*` — deletion operations
* `drop_*` — schema/table drops
* `rm_*` — remove-style operations
* `remove_*` — removal operations
* `destroy_*` — resource destruction

A destructive pattern anomaly fires after **5 matching calls** accumulate within a session. Even if a policy allows these calls, the anomaly detector flags them for visibility.

<Note>
  Anomaly detection and policies are independent systems. A tool call can be allowed by policy but still trigger an anomaly alert. This gives you defense in depth.
</Note>

## Cooldowns

After an anomaly alert fires, a per-type cooldown prevents alert fatigue (verified at `packages/proxy/src/anomaly.ts` lines 24–25):

| Anomaly type        | Cooldown                            |
| ------------------- | ----------------------------------- |
| Rate spike          | **5 minutes** after an alert fires  |
| Destructive pattern | **10 minutes** after an alert fires |

During cooldown, the same anomaly type for the same session will not fire again. This prevents a burst of destructive calls from generating dozens of separate alerts.

## Anomaly Events

When an anomaly is detected, Igris:

1. **Writes an audit event** with type `anomaly` to the `audit_events` table, including:
   * `alertType` in the `details` field: `"rate_spike"` or `"destructive_pattern"`
   * Connection slug
   * Tool name that triggered it
   * Call count and human-readable message

2. **Broadcasts via SSE** to all connected dashboard clients for the organization

## Viewing Anomalies

* **Observe dashboard** — risk heat map highlights connections with recent anomalies
* **Audit Events** — filter by `type: anomaly` to see all anomaly events

## Relationship to Policies

| System            | Purpose                                                                  |
| ----------------- | ------------------------------------------------------------------------ |
| Policies          | Decide whether a tool call is allowed, denied, alerted, or redacted      |
| Anomaly detection | Monitors patterns across **all** tool calls regardless of policy outcome |

A tool call allowed by policy can still trigger an anomaly alert. Policies enforce rules; anomaly detection catches unexpected patterns.

## Related

* [Policies](/govern/policies) — rule-based allow/deny/alert/redact governance
* [Sessions](/govern/sessions) — session lifecycle and kill switch
* [Tool Calls](/govern/tool-calls) — how tool calls are logged and audited