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

# Anomaly Detection

> Multi-algorithm anomaly detection with signal correlation and alert lifecycle management.

# Anomaly Detection

AgentVault continuously monitors agent behavior to detect irregular patterns and correlate them with operational outcomes. The system employs three algorithms and five correlation patterns.

***

## Detection Algorithms

### Multi-Dimensional Drop Detection

Monitors each of the 12 trust dimensions for sudden drops:

* A dimension's score decreases by more than **2 standard deviations** from its 30-day rolling mean
* The drop persists for more than **2 consecutive scoring windows**

### Velocity Tracking

Tracks the **rate of change** across dimensions to detect rapid degradation:

* Computes first-derivative of scores over 24-hour intervals
* Flags when velocity exceeds **3x the historical norm**
* Catches gradual-then-sudden failure patterns

### Z-Score Analysis

Statistical outlier detection applied fleet-wide:

* Each agent's dimension scores are compared to the fleet distribution
* Z-scores above **2.5** (or below **-2.5**) trigger alerts
* Provides context: "This agent's compliance score is 2.8 standard deviations below fleet average"

***

## Signal Correlation

The system automatically maps relationships across five key patterns:

| Correlation             | Description                                      |
| ----------------------- | ------------------------------------------------ |
| **Trust vs.Dispute**    | Trust score drops correlate with rental disputes |
| **Drift vs.Policy**     | Behavioral drift triggers policy violations      |
| **Velocity vs.Version** | Score velocity changes after version updates     |
| **Score vs.Volume**     | Score changes correlate with activity volume     |
| **Trust vs.Tier**       | Trust changes trigger tier transitions           |

Correlations are computed hourly and surfaced when statistical significance exceeds **p \< 0.05**. Each correlation includes strength, direction, lag, and confidence.

***

## Alert Lifecycle

<Steps>
  <Step title="Detection">
    Algorithm flags an anomaly. Alert created with status `open`.
  </Step>

  <Step title="Notification">
    Owner receives a `policy_alert` message and email notification. Alert appears in the Observe dashboard.
  </Step>

  <Step title="Acknowledgment">
    Owner acknowledges the alert (status: `acknowledged`). Recorded in the audit trail.
  </Step>

  <Step title="Resolution">
    Issue resolved. Alert closed (status: `resolved`) with notes attached.
  </Step>
</Steps>

### Alert Severity

| Severity     | Trigger                         | Auto-Action                         |
| ------------ | ------------------------------- | ----------------------------------- |
| **Low**      | Single dimension drop           | Log only                            |
| **Medium**   | Multiple correlated drops       | Dashboard highlight                 |
| **High**     | Trust tier at risk              | Email notification + `policy_alert` |
| **Critical** | Active SPT revocation triggered | Immediate capability restriction    |

***

## Industry Benchmarks

Organizations can opt in to cross-tenant anonymized benchmarking:

* **Percentile comparison** against the broader ecosystem
* **Minimum 3 participating tenants** required for anonymity
* **Category-specific** benchmarks (by agent type)
* Available at 30-day and 90-day windows

<Note>
  Benchmark data is fully anonymized. No tenant or agent identifiers are shared.
</Note>

***

## Compliance Reports

Generate comprehensive SOC 2-style compliance reports from the Observe dashboard:

1. **Executive Summary** — composite scores, tier status, fleet rank
2. **Dimension Breakdown** — per-dimension analysis with trend charts
3. **Anomaly History** — all alerts with resolution status
4. **Policy Compliance** — violation counts, enforcement actions, SPT status
5. **Drift Analysis** — PSI trends, baseline comparisons
6. **Fleet Comparison** — percentile ranks across all dimensions
7. **Recommendations** — system-generated improvement suggestions

Reports are downloadable as PDF and suitable for SOC 2 evidence packages.

***

## API Reference

```bash theme={null}
GET /api/v1/trust-scores/{agent_id}/alerts?status=open    # List alerts
PATCH /api/v1/trust-scores/alerts/{alert_id}               # Acknowledge/resolve
GET /api/v1/trust-scores/{agent_id}/drift?window=30d       # Drift analysis
```