Часто задаваемые вопросы¶

Провайдеры и маршрутизация¶

Почему провайдер не появляется в списке при создании профиля?¶

В списке доступных провайдеров при создании профиля отображаются только провайдеры со статусом ACTIVE. Если вы только что создали провайдера, он находится в статусе DRAFT и не виден в выпадающем списке.

Решение:

Перейдите на страницу Providers в Admin UI.
Найдите провайдера в списке — его статус будет DRAFT.
Нажмите кнопку «Активировать» (или отправьте POST /api/v1/providers/{id}/activate через API).
После активации провайдер появится в списке при создании профиля.

Дополнительные причины:

Tenant ID не совпадает — провайдер создан в другом тенанте. Проверьте tenant_id провайдера и текущего пользователя.
Провайдер уже привязан к профилю — один провайдер может быть привязан только к одному активному профилю.

Почему запросы не проходят через Gateway?¶

Если запросы к LLM через API Gateway возвращают ошибки или не обрабатываются, проверьте следующий чеклист:

#	Проверка	Как проверить	Решение
1	Провайдер в статусе ACTIVE	Admin UI → Providers → столбец Status	Активируйте провайдера
2	Профиль в статусе ACTIVE	Admin UI → Profiles → столбец Status	Активируйте профиль
3	Профиль привязан к провайдеру	Admin UI → Providers → столбец Profile	Привяжите профиль к провайдеру
4	`match_value` провайдера совпадает с запросом	Сравните URL/Host/Header запроса с `match_value`	Исправьте паттерн провайдера
5	`X-Original-URI` передаётся Nginx	Логи Gateway: `grep "original_uri"`	Добавьте `proxy_set_header X-Original-URI $request_uri;`
6	`X-Tenant-ID` совпадает с tenant провайдера	Сравните значение заголовка с `tenant_id` провайдера	Исправьте заголовок или tenant провайдера
7	Gateway запущен и здоров	`curl http://localhost:8085/health/ready`	`docker-compose up -d api-gateway`
8	Детекторы доступны	`curl http://localhost:8083/health/ready` и т.д.	Перезапустите недоступные сервисы

Быстрая диагностика через API:

# Проверить, как Gateway сопоставляет провайдера
curl -s -X POST http://localhost:8085/chat \
  -H "Content-Type: application/json" \
  -H "X-Original-URI: /openai/v1/chat/completions" \
  -H "X-Tenant-ID: production" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}' \
  -w "\nHTTP: %{http_code}\n" 2>&1

# Если HTTP 502 с NO_BACKEND_CONFIGURED — провайдер не найден
# Если HTTP 500 с PROVIDER_MISSING_TARGET — провайдер найден, но нет target_base_url
# Если HTTP 500 с MISSING_FIELD_MAPPING — нет mapping preset
# Если HTTP 200 — всё работает корректно

Что означает ошибка "NO_BACKEND_CONFIGURED"?¶

Эта ошибка (HTTP 502) означает, что Gateway не смог определить, куда проксировать запрос. Произошло два последовательных сбоя:

Ни один провайдер не совпал — match_value ни одного активного провайдера не совпадает с URL / Host / Header запроса.
Fallback-заголовки отсутствуют — заголовки X-Real-Backend и X-Real-Backend-Path не переданы Nginx.

Решение (пошагово):

Проверьте, какой X-Original-URI приходит в Gateway (добавьте временный лог или проверьте через curl -v).

Сравните с match_value ваших провайдеров:

curl -s http://localhost:8001/api/v1/providers | jq '.[] | {name, match_type, match_value, status}'

Убедитесь, что паттерн совпадает (например, match_value: "/openai/*" не совпадёт с /v1/openai/chat).
Как временное решение — добавьте fallback-заголовки в Nginx.

Можно ли использовать один профиль для нескольких провайдеров?¶

Нет. Архитектура системы предполагает связь 1 провайдер ↔ 1 активный профиль. Это сделано намеренно: разные LLM-провайдеры имеют разные модели угроз, разные форматы запросов и ответов, разные требования к порогам детекции.

Как настроить одинаковые параметры для нескольких провайдеров:

Создайте профиль для первого провайдера с нужными настройками.
Запишите или экспортируйте настройки (через API: GET /api/v1/profiles/{id}).
Создайте профили для остальных провайдеров с аналогичными параметрами.

Совет: Если у вас 5+ провайдеров с одинаковыми настройками, используйте API для автоматизации:

# Получить настройки эталонного профиля
SETTINGS=$(curl -s http://localhost:8001/api/v1/profiles/{template_id} \
  | jq 'del(.id, .provider_id, .status, .created_at, .updated_at)')

# Создать профиль для нового провайдера
echo $SETTINGS | jq '. + {"name": "New Provider Profile", "provider_id": "new-provider-uuid"}' \
  | curl -s -X POST http://localhost:8000/api/v1/profiles \
    -H "Content-Type: application/json" -d @-

Как настроить увеличенный таймаут для медленной модели?¶

Таймауты настраиваются на трёх уровнях, и все три должны быть согласованы:

Уровень	Параметр	Где настроить	Значение по умолч.
Провайдер	`request_timeout_ms`	Admin UI → Providers → Edit	30000 мс (30с)
Nginx	`proxy_read_timeout`	nginx.conf	60s
Gateway	`GATEWAY_SERVER_WRITE_TIMEOUT`	docker-compose env	660s

Правило согласования:

proxy_read_timeout (Nginx) > request_timeout_ms (провайдер) + 30s (запас на инспекцию)
GATEWAY_SERVER_WRITE_TIMEOUT > proxy_read_timeout

Пример для GPT-4 с длинными ответами (2 минуты):

Провайдер: request_timeout_ms = 120000 (120с).
Nginx: proxy_read_timeout 180s; (150с + запас).
Gateway: GATEWAY_SERVER_WRITE_TIMEOUT=660 (оставить по умолчанию, хватит).

Если увеличить только request_timeout_ms провайдера, но не поднять proxy_read_timeout в Nginx — клиент получит HTTP 504 Gateway Timeout от Nginx до того, как Gateway получит ответ от LLM.

Профили и детекция¶

Как работает Monitor Mode?¶

Monitor Mode — режим «только наблюдение», при котором система анализирует запросы, но никогда не блокирует их. Это позволяет безопасно внедрить AppSec.AIGate без риска нарушить работу приложений.

Полный цикл обработки в Monitor Mode:

1. Запрос приходит в Gateway.
2. Нормализация, перевод (если нужно).
3. Все детекторы работают в полном объёме:
   - Threat Detector (jailbreak) → score 0.92.
   - PII Detector → найден CREDIT_CARD.
   - Content Safety → violence detected.
   - Content Policy → keyword match.
4. PDP принимает решение на основе порогов → BLOCK.
5. Monitor Mode перехватывает решение:
   BLOCK → заменяется на MONITOR_ONLY.
   SANITIZE → заменяется на MONITOR_ONLY.
   ALLOW → остаётся ALLOW.
6. Запрос проходит к LLM без изменений.
7. Событие MONITOR_ALERT записывается с полными деталями
   (что было бы заблокировано и почему).

Когда использовать:

Этап	Режим	Зачем
Первые 1–2 недели	Monitor Mode (ON)	Собрать статистику, определить пороги, оценить false positives
Настройка порогов	Monitor Mode (ON)	Корректировать `jailbreak_threshold`, `pii_types`, категории Content Safety
Production	Monitor Mode (OFF)	Реальная блокировка угроз

Как включить: В настройках профиля установите monitor_only: true.

Совет: В режиме мониторинга просматривайте Dashboard ежедневно. Если MONITOR_ALERT событий с action WOULD_BLOCK слишком много — вероятно, пороги слишком агрессивные. Если их нет совсем — пороги слишком мягкие или атак нет.

Что произойдёт, если один из детекторов упадёт?¶

Поведение при недоступности детектора зависит от двух параметров профиля:

action_on_timeout — что делать, если детектор не ответил в отведённое время:

Значение	Поведение	Рекомендация
`"pass"`	Запрос проходит без результата от этого детектора	Для начала, при внедрении
`"block"`	Запрос блокируется (fail-closed)	Для production с высокими требованиями безопасности

action_on_detector_error — что делать, если детектор вернул ошибку (500, невалидный ответ):

Значение	Поведение	Рекомендация
`"pass"`	Запрос проходит	По умолчанию, безопасно для доступности
`"block"`	Запрос блокируется	Для критических систем

fail_safe.mode — что делать, если PDP (Policy Decision Point) недоступен:

Значение	Поведение	Рекомендация
`"fail-open"`	Запрос проходит (ALLOW)	По умолчанию, приоритет доступности
`"fail-closed"`	Запрос блокируется (BLOCK)	Приоритет безопасности

Пример: Threat Detector перегружен и не отвечает за 15с (таймаут). При action_on_timeout: "pass" запрос продолжит обработку с jailbreak_score: 0.0 — PDP пропустит его. При action_on_timeout: "block" запрос будет заблокирован с событием FAIL_SAFE_TRIGGERED.

Как отличить false positive от реальной атаки?¶

При анализе события безопасности на Dashboard обратите внимание на следующие поля:

Поле	Что искать	Признак false positive	Признак реальной атаки
`jailbreak_score`	Значение 0.5–0.7	Пограничный score, пользователь задал легитимный вопрос о безопасности	Score > 0.9, классический jailbreak-паттерн
`user_prompt`	Текст запроса	Обычный вопрос с "триггерными" словами	Явная попытка обхода: "Ignore instructions", "DAN mode"
`pii_entities`	Типы PII	INN без checksum validation (10-значное число ≠ ИНН)	Реальный номер карты (Luhn validated) с именем
`source_ip`	Источник	Внутренний IP разработчика	Неизвестный IP, массовые запросы
`trace_id`	Корреляция	Единичный запрос	Серия запросов с одного IP за короткий период

Действия при false positive:

Jailbreak false positive (score 0.5–0.7): Увеличьте jailbreak_threshold в профиле (например, с 0.5 до 0.7).
PII false positive (число похоже на ИНН/телефон): Уточните pii_types в профиле — исключите типы с высоким FPR в вашем контексте.
Content Policy false positive (keyword match): Пересмотрите правила политики — добавьте исключения через allowlist или используйте regex вместо keyword для большей точности.
Content Safety false positive: Уменьшите набор blocked_categories или включите controversial_as_unsafe: false.

Контентные политики¶

Как создать контентную политику для блокировки упоминаний конкурентов?¶

Пошаговая инструкция для создания blocklist-политики:

Перейдите в Content Policies → кнопка «+ Создать политику».
Заполните:
- Название: «Блокировка конкурентов».
- Тип: blocklist.
- Описание: «Блокировка запросов с упоминанием конкурентных продуктов».

Добавьте правила:

Тип: keyword    Значение: "продукт-конкурент-1"    Action: block    Severity: medium
Тип: keyword    Значение: "продукт-конкурент-2"    Action: block    Severity: medium
Тип: regex      Значение: "(?i)компания[-\s]конкурент"   Action: flag     Severity: low

Настройте:
- Scope: request (проверять только запросы пользователя, не ответы LLM).
- Case Sensitive: false (регистронезависимо).
- Priority: 10 (выше = раньше проверяется).
Нажмите «Создать» → политика создастся в статусе DRAFT.
Нажмите «Активировать» → статус ACTIVE.
Привяжите к нужным профилям в разделе Profiles → Edit → Content Policies.

Результат: Запрос с текстом «Сравни наш продукт с продукт-конкурент-1» будет заблокирован (HTTP 403, событие CUSTOM_POLICY_BLOCK). Запрос с «Расскажи про компанию-конкурент» будет пропущен, но помечен (событие CUSTOM_POLICY_FLAG).

В чём разница между keyword и regex в контентных политиках?¶

Параметр	`keyword`	`regex`
Формат	Точная строка	Регулярное выражение (RE2 синтаксис)
Пример	`"номер карты"`	`"\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b"`
Скорость	Быстрый (простое сравнение строк)	Медленнее (компиляция и выполнение regex)
Гибкость	Только точное совпадение подстроки	Шаблоны, группы, alternation, lookahead
Case Sensitive	Контролируется полем `case_sensitive`	Встройте `(?i)` в regex или используйте поле `case_sensitive`
Когда использовать	Конкретные слова и фразы	Паттерны (номера, форматы, вариации написания)

Примеры regex-паттернов:

# Любое упоминание "промпт" в разных формах
(?i)промпт[-\s]?инъекц[а-я]*|prompt[-\s]?inject[a-z]*

# Запрос на генерацию кода для SQL injection
(?i)(sql\s+inject|union\s+select|drop\s+table|;\s*delete\s+from)

# Попытка извлечь system prompt
(?i)(system\s+prompt|initial\s+instruction|hidden\s+instruction|reveal.*prompt)

Как работает приоритет контентных политик?¶

Контентные политики оцениваются в порядке убывания priority (чем выше число, тем раньше проверяется). Если несколько политик срабатывают на один запрос, результат определяется так:

Приоритет оценки:  priority 100 → priority 50 → priority 10 → priority 1

Приоритет действий:  block > flag > trust_pii

Результат: применяется САМОЕ строгое действие

Пример: На запрос «Мой ИНН 7707083893, отправь на email» срабатывают:

Политика «Доверенные данные» (priority 50, action: trust_pii) — INN в контексте «мой» = доверенный.
Политика «Утечка PII» (priority 10, action: block) — любое упоминание ИНН = блокировка.

Результат: block (более строгое действие), несмотря на trust_pii с более высоким приоритетом. Поле trust_pii работает иначе — оно не отменяет блокировку, а лишь помечает PII-сущности как доверенные для PII-детектора.

Response Scanning и Content Safety¶

Что такое Response Scanning и как настроить?¶

Response Scanning — модуль инспекции ответов LLM. Он проверяет ответ модели перед отправкой клиенту на наличие PII, нарушений Content Safety и срабатывание контентных политик.

Зачем нужен: LLM может «утечь» конфиденциальные данные из обучающей выборки (номера карт, API-ключи, персональные данные), сгенерировать вредоносный контент или нарушить compliance-требования — даже если входящий запрос был безобидным.

Как включить:

Откройте профиль безопасности в Admin UI → Edit.

В секции Response Scanning установите:

enabled: true — включить сканирование ответов.
pii_mode — действие при обнаружении PII в ответе:

Значение	Поведение	Пример
`disabled`	PII в ответах не проверяется	—
`monitor`	PII обнаруживается, логируется, но ответ не изменяется	Для оценки масштаба проблемы
`mask`	PII заменяется на маски (`**--**-1234`)	Рекомендуется для production
`block`	Ответ с PII полностью блокируется (HTTP 451)	Для максимальной защиты

Опционально — Content Safety для ответов:
- content_safety_enabled: true — проверять ответ на 9 категорий вредоносного контента
- response_blocked_categories: ["violence", "illegal_acts"] — какие категории блокировать в ответах
- action_on_content_violation: "block" или "monitor"
Активируйте профиль.

Влияние на задержку: Response Scanning добавляет 50–300 мс к времени ответа (зависит от размера ответа и включённых детекторов). Для приложений, где TTFT (Time To First Token) критичен, рассмотрите monitor вместо block.

Как работает Output PII Detection?¶

Output PII Detection — часть Response Scanning, которая ищет утечки конфиденциальных данных в ответах LLM. Обнаруживает:

Категория	Примеры	Метод детекции
Финансовые данные	Номера кредитных карт, IBAN	Regex + Luhn validation
API-ключи и токены	OpenAI `sk-...`, GitHub `ghp_...`, JWT	Regex (5 форматов GitHub, OpenAI, Anthropic, Google)
Персональные данные	ИНН, СНИЛС, паспорт РФ	Regex + checksum validation
Строки подключения к БД	`postgresql://user:pass@host/db`	Regex
Системные промпты	Утечка system prompt в ответе	Тип `SYSTEM_PROMPT_LEAK`

Пример: LLM отвечает: «Вот пример конфигурации: DATABASE_URL=postgresql://admin:secret@prod-db:5432/main». Output PII Detection обнаружит credentials в строке подключения.

Действие при обнаружении (зависит от pii_mode):

mask: DATABASE_URL=postgresql://***:***@***:***/***.
block: HTTP 451, клиент не получит ответ.
monitor: Ответ проходит как есть, но записывается событие RESPONSE_REDACTED (severity: high).

Что такое Content Safety и какие категории проверяются?¶

Content Safety — ML-модуль на основе Qwen3Guard-Gen-4B, который классифицирует текст по 9 категориям вредоносного контента:

#	Категория	Описание	Пример
1	`violence`	Насилие, физический вред	Инструкции по причинению вреда
2	`illegal_acts`	Незаконная деятельность	Инструкции по изготовлению запрещённых веществ
3	`sexual`	Сексуальный контент	NSFW-контент
4	`pii`	Персональные данные	Запрос на поиск личной информации
5	`self_harm`	Самоповреждение	Суицидальный контент
6	`unethical`	Неэтичное поведение	Манипуляции, мошенничество
7	`political_sensitive`	Политически чувствительный контент	Экстремизм, пропаганда
8	`copyright`	Нарушение авторских прав	Воспроизведение защищённых текстов
9	`jailbreak`	Попытка обхода ограничений	Prompt injection через Content Safety

Каждая категория получает вердикт:

Вердикт	Score	Описание
`Safe`	0.0	Контент безопасен
`Controversial`	0.5	Пограничный случай
`Unsafe`	0.95	Контент определён как вредоносный

Настройка: В профиле безопасности:

content_safety.enabled: true — включить.
content_safety.blocked_categories: ["violence", "jailbreak"] — какие категории блокировать для запросов.
content_safety.controversial_as_unsafe: false — считать ли Controversial за Unsafe.
content_safety.response_enabled: true — проверять также ответы LLM.
content_safety.response_blocked_categories: ["violence", "sexual"] — категории для ответов.

Требование: Content Safety работает только на GPU (Qwen3Guard-Gen-4B — генеративная модель на 4B параметров). Без GPU сервис вернёт 503, и Gateway пропустит эту проверку (graceful degradation).

PII-детекция¶

Какие типы PII обнаруживает система?¶

Система обнаруживает два класса PII: Input PII (в запросах пользователя) и Output PII (в ответах LLM). Полный перечень см. в Типы PII, основные типы:

Финансовые:

CREDIT_CARD — номера карт (16 цифр, Luhn validation).
INN — ИНН (10 или 12 цифр, checksum validation ФНС).
SNILS — СНИЛС (11 цифр, checksum validation).

Контактные:

PHONE_NUMBER — телефоны (libphonenumber, международные форматы).
EMAIL — email (RFC 5322 validation).

Документы:

PASSPORT_RF — паспорт РФ (серия + номер).

Секреты и токены (Output PII):

API_KEY — ключи OpenAI (sk-...), Anthropic, Google.
GITHUB_TOKEN — токены GitHub (5 форматов: ghp_, gho_, ghu_, ghs_, ghr_).
JWT — JSON Web Tokens.
DATABASE_URL — строки подключения к БД.
PRIVATE_KEY — приватные ключи (PEM format).
SYSTEM_PROMPT_LEAK — утечка системного промпта.

Как работает маскирование PII (SANITIZE)?¶

Когда PDP принимает решение SANITIZE, Gateway заменяет найденные PII-сущности на маски перед отправкой запроса в LLM:

Оригинальный запрос:
"Мой номер карты 4111-2222-3333-4444, отправь на john@company.com"

После маскирования (SANITIZE):
"Мой номер карты ****-****-****-4444, отправь на j***@***.com"

→ LLM получает замаскированный текст
→ LLM отвечает, не видя реальных данных
→ Событие REQUEST_SANITIZED записывается с деталями маскирования

Маски по типам PII:

Тип	Исходное значение	Маска
`CREDIT_CARD`	`4111-2222-3333-4444`	`**--**-4444` (последние 4 цифры сохраняются)
`PHONE_NUMBER`	`+7 (903) 123-45-67`	`+7 (*) -*-67`
`EMAIL`	`john@company.com`	`j*@*.com`
`INN`	`7707083893`	`**********`
`API_KEY`	`sk-proj-abc123...xyz`	`sk-proj-*...*`

События и мониторинг¶

Как быстро найти все события по конкретному запросу?¶

Каждый запрос через Gateway получает уникальный trace_id. По нему можно найти все связанные события (включая входящую инспекцию, Response Scanning и ошибки):

# Получить trace_id из заголовка ответа
curl -s -D - -X POST https://llm-gateway.company.com/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}' \
  -o /dev/null 2>&1 | grep "X-LLM-Firewall-Trace-ID"

# Найти все события по trace_id
curl -s "http://localhost:8001/api/v1/security-events?trace_id=550e8400-e29b-41d4-a716-446655440000" | jq .

В Dashboard: откройте любое событие → поле trace_id → нажмите для фильтрации по этому идентификатору.

Как настроить подавление неинформативных событий?¶

Если Dashboard перегружен событиями PROVIDER_ERROR (например, LLM-бэкенд временно недоступен) или DETECTOR_ERROR, используйте конфигурацию Event Logging в профиле:

# Отключить логирование PROVIDER_ERROR и DETECTOR_ERROR
curl -s -X PUT http://localhost:8000/api/v1/profiles/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "event_logging": {
      "log_allow_decisions": false,
      "disabled_event_types": ["PROVIDER_ERROR", "DETECTOR_ERROR"]
    }
  }'

Подавляемые типы (можно отключить): RATE_LIMIT, FAIL_SAFE_TRIGGERED, MONITOR_ALERT, DETECTOR_ERROR, SERVICE_UNAVAILABLE, REQUEST_ERROR, PROVIDER_ERROR.

Неподавляемые типы (всегда логируются): REQUEST_BLOCKED, REQUEST_SANITIZED, JAILBREAK_DETECTED, PII_DETECTED, POLICY_VIOLATION, CUSTOM_POLICY_BLOCK.

Как настроить логирование всех пропущенных запросов (ALLOW)?¶

По умолчанию система логирует только блокировки, маскирования и алерты мониторинга. Если вам нужно видеть все запросы (включая пропущенные):

curl -s -X PUT http://localhost:8000/api/v1/profiles/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "event_logging": {
      "log_allow_decisions": true,
      "disabled_event_types": []
    }
  }'

Внимание: При высокой нагрузке (100+ RPS) логирование всех запросов быстро заполнит базу данных. Используйте совместно с retention settings (раздел 11) — установите event_retention_days: 7 для таких профилей.

SIEM и экспорт¶

Как настроить экспорт событий в SIEM?¶

Пошаговая инструкция для подключения SIEM через syslog:

Перейдите в Exporters → кнопка «+ Создать экспортер».
Заполните:
- Название: «SIEM Syslog».
- Тип: syslog.

Настройте подключение:

{
    "address": "siem.company.com:514",
    "transport": "tcp",
    "format": "rfc5424",
    "facility": "local0"
}

Настройте фильтры (опционально):
- Severity: high, critical (только важные события).
- Event Types: REQUEST_BLOCKED, JAILBREAK_DETECTED, PII_DETECTED (только определённые типы).
Нажмите «Test» — система отправит тестовое событие на SIEM.
Убедитесь, что событие появилось в SIEM.
Нажмите «Создать» → активируйте экспортер.

Доступные типы экспорта: syslog (RFC 3164 / RFC 5424), CEF (ArcSight), webhook (HTTP POST), Kafka, файл (с ротацией).

Как проверить, что экспорт работает?¶

Три метода проверки:

Кнопка Test в UI: Exporters → выберите экспортер → «Test». Система отправит тестовое событие.

Через API:

curl -s -X POST http://localhost:8001/api/v1/exporters/{id}/test

Проверка логов Event Exporter:

docker-compose logs event-exporter | grep -i "export\|error\|sent"

Если события не доходят до SIEM:

Проверьте сетевую связность: docker exec event-exporter nc -zv siem.company.com 514.
Проверьте формат: некоторые SIEM требуют RFC 5424, другие — RFC 3164.
Проверьте facility: syslog facility должен совпадать с настройками SIEM (обычно local0–local7).

Отчёты и compliance¶

Как генерировать отчёт 152-ФЗ?¶

Перейдите в Reports → кнопка «+ Создать отчёт».

Настройте:

Параметр	Значение	Описание
Тип	PII/DLP (152-ФЗ)	Отчёт по обнаружениям персональных данных
Формат	PDF	С кириллическим форматированием
Начало периода	Первый день квартала	Например, 2026-01-01
Конец периода	Последний день квартала	Например, 2026-03-31

Нажмите «Создать» → статус PENDING.
Дождитесь генерации (обычно 10–60 секунд) → статус COMPLETED.
Нажмите «Скачать» → PDF-файл с разделами:
- Сводная статистика (общее количество обнаружений PII).
- Разбивка по типам PII (CREDIT_CARD, PHONE_NUMBER, INN и т.д.).
- Разбивка по действиям (BLOCK, SANITIZE, MONITOR).
- Топ-10 провайдеров по количеству PII-инцидентов.
- Детализация по дням.

Для аудиторов: Дополнительно сгенерируйте отчёт Incidents (все типы событий безопасности) и LLM Usage (статистика использования моделей). Три отчёта вместе дают полную картину для проверки.

Какой минимальный срок хранения аудитных данных для 152-ФЗ?¶

Для соответствия Федеральному закону №152-ФЗ «О персональных данных» рекомендуется:

Тип данных	Минимальный срок	Параметр retention
Журнал аудита	3 года (1095 дней)	`audit_retention_days: 1095`
События безопасности с PII	3 года	`event_retention_days: 1095`
Детальная информация (сами PII)	30 дней (минимум для расследования)	`detail_retention_days: 30`
Отчёты	3 года	`report_retention_days: 1095`

Важно: detail_retention_days контролирует, когда из событий удаляются конкретные PII-значения (PII scrub). После scrub событие сохраняется, но поля с PII заменяются на маски. Это позволяет хранить статистику 3 года, не храня сами персональные данные дольше необходимого.

Производительность¶

Какой overhead добавляет AppSec.AIGate к latency?¶

Overhead зависит от включённых детекторов и доступного оборудования:

Конфигурация	CPU overhead	GPU overhead	Примечание
Только Threat Detector	50–200 мс	10–30 мс	Минимальная конфигурация
Threat + PII	60–250 мс	20–50 мс	Стандартная конфигурация
Threat + PII + Content Safety	200–700 мс	50–150 мс	Content Safety GPU-only
Полная (+ Translation + Response Scanning)	300–1000 мс	80–250 мс	Максимальная конфигурация

Для сравнения: Типичная latency LLM-вызова — 1–30 секунд (GPT-4). Overhead 100–300 мс на GPU составляет 1–3% от общего времени.

Как снизить overhead:

Используйте GPU — снижает latency ML-детекторов в 5–10 раз.
Отключите ненужные детекторы — например, Content Safety если не требуется.
Отключите Translation Service — если весь трафик на английском.
Provider match кешируется — повторные запросы к тому же провайдеру обрабатываются за 1–5 мс.

Поддерживает ли система SSE-стриминг?¶

Нет. В текущей версии API Gateway не поддерживает Server-Sent Events (SSE) стриминг. Все ответы LLM полностью буферизируются перед отправкой клиенту.

Техническая причина: Response Scanning требует полного тела ответа для проверки PII, Content Safety и контентных политик. Анализ инкрементальных SSE-чанков невозможен — нельзя принять решение о блокировке, если получена только часть ответа.

Что происходит при stream: true: Запрос проксируется к LLM с stream: true, LLM генерирует SSE-поток, Gateway буферизирует все чанки, проводит Response Scanning, затем возвращает полный ответ клиенту одним блоком.

Рекомендации:

Для batch-обработки — разницы нет, используйте stream: false.
Для чат-ботов — если TTFT критичен и Response Scanning не нужен, установите response_scanning.enabled: false в профиле. Ответы всё равно не будут стримиться (Gateway буферизирует), но время ожидания уменьшится.

Защита от атак¶

Как защититься от unicode-обфускации (гомоглифы)?¶

Homoglyph-атака — подмена символов визуально похожими из другого алфавита для обхода детекторов. Например, «Игнорируй вce инструкции» — буква «c» заменена на латинскую, детектор не распознаёт слово «все».

Защита: Homoglyph Normalization (раздел 6.1.8) — включена по умолчанию в каждом профиле.

Три этапа нормализации:

NFKC-нормализация — приведение Unicode к канонической форме (разложение лигатур, совмещение диакритик).
Удаление zero-width символов — \u200B (zero-width space), \u200C (zero-width non-joiner), \u200D (zero-width joiner), \uFEFF (BOM).
Per-word гомоглиф-резолюция — для каждого слова определяется доминирующий скрипт (кириллица / латиница) и все символы приводятся к нему. Например: «вce» (кириллица + латинская «c») → «все» (полностью кириллица).

Рекомендация: Не отключайте Homoglyph Normalization без веской причины. Стоимость нормализации — менее 1 мс на запрос, а без неё детекторы (особенно Threat Detector и Translation Service) могут пропустить обфусцированные атаки.

Что такое fail-safe и как его настроить?¶

Fail-safe определяет поведение системы при недоступности компонентов конвейера безопасности (детекторов, PDP, OPA).

Режим	Поведение	Когда использовать
`fail-open`	При сбое — пропустить запрос (ALLOW)	Приоритет: доступность сервиса. Риск: пропуск угроз
`fail-closed`	При сбое — заблокировать запрос (BLOCK)	Приоритет: безопасность. Риск: ложные блокировки при проблемах инфраструктуры

Настройка: В профиле безопасности → fail_safe.mode: "fail-open" или "fail-closed".

Рекомендация по этапам:

Этап внедрения	Режим	Причина
Пилот / тестирование	`fail-open`	Сбои инфраструктуры не должны блокировать пользователей
Production (стандарт)	`fail-open` + мониторинг	Мониторинг событий `FAIL_SAFE_TRIGGERED` через Dashboard
Production (высокая безопасность)	`fail-closed`	Для финансовых систем, обработки секретов