Prompt Injection Guard¶

AegisAI включает низколатентный Prompt Guard, который проверяет промпты до передачи их ИИ-агентам.

Архитектура¶

Client → Guard Middleware → Guard Service
                              ├─ Rule detector (regex / banlist)
                              ├─ ML detector (TF-IDF + Isolation Forest)
                              └─ OPA Rego (policies/templates/guard.rego)
                         → Redis cache (TTL 300s)
                         → Audit Logger (SHA-256) при аномалиях

Целевая задержка: < 100ms (правила + кешированный ML; таймаут OPA 2s с локальным fallback).

Агрегация взвешивает детекторы. Сильные сигналы rules/OPA могут жёстко блокировать независимо от мягкого ML-скора. Итог: max(weighted, rule, opa × 0.95) против GUARD_THRESHOLD_BLOCK / GUARD_THRESHOLD_WARN.

Обнаруживаемые угрозы¶

Категория	Примеры
Prompt injection	`ignore previous instructions`, переопределение system prompt
Jailbreak	`jailbreak`, `bypass security`, DAN / developer mode
Data leakage	`extract all data`, dump паролей / API keys
Token smuggling	Закодированные / обфусцированные инструкции

API¶

`GET /api/v1/guard/health`¶

Публичный health + текущий конфиг (без auth).

`POST /api/v1/guard/validate`¶

Требует tenant X-API-Key.

{
  "agent_id": "uuid-or-name",
  "prompt": "Сообщение пользователя…",
  "context": { "intent": "chat" }
}

Ответ:

{
  "threat_level": "blocked",
  "score": 0.86,
  "reasons": ["Matched pattern: system_override"],
  "blocked": true,
  "detected_patterns": ["Matched pattern: system_override"],
  "processing_time_ms": 12.4,
  "audit_id": "…",
  "cached": false
}

threat_level: safe, suspicious, blocked.

`GET /api/v1/guard/stats`¶

Счётчики процесса: blocked / suspicious / safe, средняя задержка, топ паттернов. На дашборде те же поля через GET /api/v1/stats (guard_blocked, guard_avg_ms, guard_top_patterns).

Middleware¶

При ENABLE_GUARD=true перехватываются:

POST /api/v1/agents/{id}/chat
POST /api/v1/agents/{id}/action
POST /api/v1/agents/{id}/completions
POST /api/v1/chat

Заблокированные промпты возвращают 403. Подозрительные логируются и пропускаются с заголовками X-Guard-*. Ошибки детекторов — fail-open (запрос проходит), чтобы сохранить доступность.

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

Переменная	По умолчанию	Описание
`ENABLE_GUARD`	`true`	Главный переключатель
`GUARD_ENABLE_ML`	`true`	ML-детектор
`GUARD_ENABLE_RULES`	`true`	Regex / banlist
`GUARD_ENABLE_OPA`	`true`	Запрос OPA `guard.main`
`GUARD_ML_THRESHOLD`	`0.7`	Мягкий порог ML
`GUARD_RULE_THRESHOLD`	`0.8`	Жёсткая блокировка по правилам
`GUARD_THRESHOLD_BLOCK`	`0.7`	Агрегат → block
`GUARD_THRESHOLD_WARN`	`0.4`	Агрегат → suspicious
`GUARD_RULE_WEIGHT`	`0.3`	Вес в агрегации
`GUARD_ML_WEIGHT`	`0.5`	Вес в агрегации
`GUARD_OPA_WEIGHT`	`0.2`	Вес в агрегации
`GUARD_CACHE_TTL_SECONDS`	`300`	TTL Redis-кеша
`GUARD_MODEL_PATH`	`./models/guard/guard_model.pkl`	Артефакт ML
`GUARD_MODEL_BACKEND`	`hybrid`	`sklearn` / `onnx` / `hybrid`
`GUARD_MIN_TRAINING_SAMPLES`	`100`	Минимум сэмплов для API-обучения
`GUARD_EXTERNAL_ENABLED`	`false`	Внешний API при неопределённости

Обучение ML-модели¶

CLI (офлайн)¶

poetry run python scripts/generate_prompt_dataset.py
poetry run python scripts/train_guard_model.py \
  --dataset data/prompt_dataset.csv \
  --model models/guard/guard_model.pkl
poetry run python scripts/benchmark_guard_model.py

Модель по умолчанию: TF-IDF + LogisticRegression (supervised). Isolation Forest используется как fallback без меток.

API (per-tenant, из audit + feedback)¶

POST /api/v1/guard/detector/train?days=30
GET /api/v1/guard/detector/status
GET /api/v1/guard/detector/versions
POST /api/v1/guard/detector/rollback/{version}
DELETE /api/v1/guard/detector/cancel

UI: страница Prompt Guard ML (/guard-ml) в дашборде.

ONNX (опционально)¶

pip install onnxruntime transformers torch
poetry run python scripts/export_guard_onnx.py --dataset data/prompt_dataset.csv

Установите GUARD_MODEL_BACKEND=onnx или hybrid.

Без сохранённой модели детектор поднимает небольшой seed-корпус при старте.

SDK¶

from aegisai.sdk import AegisAIClient

async with AegisAIClient(api_key="…", agent_name="CustomerAgent") as client:
    await client.register()
    if await client.guard.is_safe(prompt):
        ...
    else:
        result = await client.guard.validate(prompt)

OPA-политика¶

Модуль Rego: policies/templates/guard.rego (package guard.main).

Загружается вместе с остальными шаблонами при OPA_ENABLED=true. Если OPA недоступен, используется локальный regex-fallback (fail-open по доступности, известные атаки всё равно сигнализируются).