Аномалии¶

Раздел Аномалии — обнаружение и анализ подозрительного поведения ИИ-агентов.

Маршрут: /anomalies

Как работает обнаружение¶

AegisAI использует гибридный подход (как Prompt Guard): supervised tabular ML, Isolation Forest fallback, опциональный ONNX, правила и внешний escalate в зоне неопределённости.

graph LR
    A[Действие агента] --> B[Feature Schema]
    B --> C[Supervised / Isolation Forest / ONNX]
    B --> D[Rule Engine]
    C --> E[Score]
    D --> E
    E --> F{External band?}
    F -->|да| G[External API]
    F -->|нет| H{Порог}
    G --> H
    H -->|Выше| I[Алерт]
    H -->|Ниже| J[Норма]

Компонент	Описание
Supervised ML	Gradient Boosting / Logistic Regression при наличии меток
Isolation Forest	Fallback unsupervised (scikit-learn)
ONNX	Опциональный tabular scorer (`ANOMALY_MODEL_BACKEND=onnx\\|hybrid`)
Rule Engine	Частота, ресурсы, время суток
Risk Scorer	Blend keyword + ML prior (`ANOMALY_RISK_ML_WEIGHT`)
Timeout	`ANOMALY_ML_TIMEOUT_SECONDS` (по умолчанию 0.3s) → fallback на rules

Инференс — per-tenant модель. При timeout backend = timeout.

Feedback (ложные / истинные срабатывания)¶

В таблице аномалий можно отметить FP или TP. Это пишет anomaly_training_samples и может запустить auto-retrain:

curl -X POST http://localhost:8000/api/v1/anomalies/detector/feedback \
  -H "X-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"event_data": {"action": "export", "risk_score": 0.3}, "label": 0}'

`label`	Значение
`0`	False positive / норма
`1`	True positive / аномалия

Список аномалий¶

Колонка	Описание
ID	UUID отчёта
Агент	Имя и ID
Score	Anomaly score (0.0–1.0)
Действие	Действие, вызвавшее аномалию
Ресурс	Целевой ресурс
Статус	`open`, `confirmed`, `dismissed`
Время	Timestamp обнаружения

Действия с аномалией¶

Действие	Роль	Описание
Подтвердить / TP	Security Analyst+	Реальная угроза (+ training label)
Отклонить / FP	Security Analyst+	Ложное срабатывание (+ training label)
Детали	Все (чтение)	Features и контекст

Статистика и статус детектора¶

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

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

В статусе: версия модели, backend config, onnx_available, число training samples, метрики precision/recall.

Управление моделью¶

Обучение¶

curl -X POST http://localhost:8000/api/v1/anomalies/detector/train \
  -H "X-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"min_samples": 100}'

Автообучение

После каждых ANOMALY_AUTO_RETRAIN_EVENTS размеченных samples планируется background retrain. seed_data.py --reset прогревает демо-модель.

Откат версии¶

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

Конфигурация¶

Переменная	По умолчанию	Назначение
`ANOMALY_MODEL_BACKEND`	`hybrid`	`sklearn` / `onnx` / `hybrid`
`ANOMALY_ML_TIMEOUT_SECONDS`	`0.3`	Бюджет sync ML
`ANOMALY_ONNX_MODEL_PATH`	`./models/anomaly/anomaly_model.onnx`	ONNX-артефакт
`ANOMALY_EXTERNAL_ENABLED`	`false`	External escalate
`ANOMALY_RISK_ML_WEIGHT`	`0.4`	α в blend риска

Экспорт ONNX: python scripts/export_anomaly_onnx.py.

Метрики / Grafana¶

Метрика	Описание
`anomaly_ml_backend_total`	Инференсы по backend
`anomaly_processing_seconds`	Latency sync detect
`anomaly_score_histogram`	Распределение score
`anomaly_false_positive_reports_total`	FP feedback
`shadow_candidates_total`	Кандидаты Shadow AI
`shadow_time_to_confirm_seconds`	Время до confirm/dismiss

Панели — dashboard AegisAI Business Metrics. Алерт ShadowAICandidateBacklog при всплеске pending кандидатов.

Интеграция с политиками¶

При POST /policies/check поле anomaly содержит результат hybrid-детекции. Orphan-отчёты (без agent_id) могут создать кандидата на странице Агенты / Discovery.

Высокий anomaly score

Аномалии с score > 0.8 могут создавать HITL-запрос, если активна hitl.rego.

Real-time алерты¶

Новые аномалии доставляются через WebSocket (anomaly.detected).