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

# Threat Alerts

> Configure anomaly detection rules in Essal Guard to automatically detect and route security threats.

Essal Guard includes a rule-based **threat detection engine** that monitors activity across all apps for anomalous or suspicious patterns. When a rule matches, Guard creates an **alert** and routes it to configured notification channels.

## Alert Rules

An alert rule defines what to watch for and what to do when it fires.

```bash theme={null}
POST /v1/guard/alert-rules
{
  "name": "Excessive Failed Logins",
  "description": "Triggers when a single user fails login more than 10 times in 5 minutes.",
  "condition": {
    "event": "access.user.login",
    "outcome": "failure",
    "threshold": 10,
    "window_seconds": 300,
    "group_by": "actor_id"
  },
  "severity": "high",
  "channels": ["slack_security", "email_secops"]
}
```

## Built-In Rule Templates

Guard ships with pre-built rule templates for common threat patterns. Apply a template to quickly add coverage:

```bash theme={null}
POST /v1/guard/alert-rules/from-template
{ "template": "impossible_travel" }
```

Available templates:

| Template                | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `impossible_travel`     | User logs in from two geographically distant IPs within a short window |
| `mass_download`         | A single user downloads more than N files within a time window         |
| `privilege_escalation`  | A user is granted `workspace:admin` outside of business hours          |
| `policy_disabled`       | A Guard policy is deactivated                                          |
| `api_key_mass_creation` | More than 5 API keys created in a short period                         |

## Alert Lifecycle

Alerts move through the following states:

```
triggered → acknowledged → investigating → resolved
                                         └→ false_positive
```

Update an alert's state via the API:

```bash theme={null}
PATCH /v1/guard/alerts/alrt_01HXYZALRT1
{
  "status": "investigating",
  "assignee_id": "usr_01HXYZ5678",
  "note": "Reviewing login logs. Appears to be a failed automation script."
}
```

## Notification Channels

Configure where alerts are routed:

```bash theme={null}
POST /v1/guard/notification-channels
{
  "name": "slack_security",
  "type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
    "channel": "#security-alerts"
  },
  "min_severity": "medium"
}
```

Supported channel types: `slack`, `email`, `pagerduty`, `webhook`, `ms_teams`.

<Tip>
  Route high-severity alerts (`high`, `critical`) to PagerDuty or an on-call system, and medium-severity alerts to a Slack channel for async review.
</Tip>

## Viewing Active Alerts

```bash theme={null}
GET /v1/guard/alerts?status=triggered&severity=high&sort=triggered_at:desc
```