Anomalies¶

The Anomalies page surfaces behavioral deviations detected by AegisAI's hybrid anomaly detection system — supervised tabular ML (Gradient Boosting / Logistic Regression when labels exist), Isolation Forest fallback, optional ONNX, rule heuristics, and optional external escalate.

Anomaly Reports¶

The anomalies table lists detected reports:

Click a row to expand event data including action, resource, and detection metadata.

Feedback (FP / TP)¶

Mark false positives or confirm true positives from the anomalies table. Feedback writes training samples and can trigger auto-retrain:

curl -X POST http://localhost:8000/api/v1/anomalies/detector/feedback \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_data": {"action": "bulk_export", "resource": "users", "risk_score": 0.4},
    "label": 0,
    "source": "manual",
    "report_id": null
  }'

Feedback increments anomaly_false_positive_reports_total for FP labels and may schedule auto-retrain every ANOMALY_AUTO_RETRAIN_EVENTS samples.

Detector Status¶

The Detector Status panel shows the current state of the per-tenant ML anomaly detector:

curl http://localhost:8000/api/v1/anomalies/detector/status \
  -H "X-API-Key: <your-api-key>"

How Detection Works¶

flowchart TD
    A[Agent Action] --> B[Security Service]
    B --> C[Feature Schema FEATURE_DIM]
    C --> D{Backend}
    D -->|sklearn / hybrid| E[Supervised or Isolation Forest]
    D -->|onnx / hybrid| F[ONNX tabular scorer]
    B --> G[Rule heuristics]
    E --> H[Score]
    F --> H
    G --> H
    H --> I{External band?}
    I -->|uncertain + enabled| J[External API]
    I -->|else| K[Anomaly Report]
    J --> K
    H -->|timeout| L[Rule fallback]

Live inference uses the tenant model (anomaly_detector_service.get_detector), with a hard ML timeout (ANOMALY_ML_TIMEOUT_SECONDS, default 0.3s). On timeout the path falls back to rules.

Anomalies are also created during enhanced policy checks when result.anomaly.is_anomaly is true:

curl -X POST http://localhost:8000/api/v1/anomalies/report \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<uuid>",
    "event_data": {
      "action": "bulk_export",
      "resource": "user_database",
      "reason": "Unusual export volume"
    },
    "source": "manual"
  }'

Orphan anomaly reports (no agent_id) can create Shadow AI discovery candidates — see Agents.

Model Training¶

Prefer supervising with FP/TP labels; Isolation Forest is used when labels are insufficient.

curl -X POST http://localhost:8000/api/v1/anomalies/detector/train \
  -H "X-API-Key: <your-api-key>"

curl http://localhost:8000/api/v1/anomalies/detector/training/status \
  -H "X-API-Key: <your-api-key>"

Model Version Management¶

Configuration (env)¶

Export ONNX (optional): python scripts/export_anomaly_onnx.py --output models/anomaly/anomaly_model.onnx.

Metrics / Grafana¶

Prometheus (scraped from /metrics):

Panels are on the AegisAI Business Metrics Grafana dashboard. Alerts AnomalyLatencyHigh and ShadowAICandidateBacklog watch p95 latency and pending candidates.

Investigation Workflow¶

1. Triage — sort by risk score descending
2. Correlate — cross-reference audit logs for the same agent
3. Feedback — mark FP / TP to improve the supervised loop
4. Respond — update policies, block agent, or retrain

Permissions¶

Related Documentation¶

• Agents — registry search and Shadow AI discovery
• Dashboard — anomaly KPI
• Policies — policy checks trigger anomaly detection
• Audit — correlate anomalies with audit events
• Monitoring — Grafana / Prometheus