Основные понятия и сущности¶

В этом разделе описаны ключевые сущности AppSec.AIGate — объекты, которые вы создаёте, настраиваете и связываете между собой для защиты LLM-трафика. Понимание этих сущностей и их взаимосвязей необходимо для эффективной работы с системой.

Карта связей между сущностями¶

  Tenant (организация)
    │
    ├── Provider (LLM backend)           ◄── Routing Method + Mapping Preset
    │     │
    │     └── Profile (набор детекторов) ◄── Content Policies (many-to-many)
    │           │
    │           ├── Threat Detection config
    │           ├── PII Detection config
    │           ├── Content Safety config
    │           ├── Response Scanning config
    │           ├── Output PII config
    │           ├── Homoglyph Normalization config
    │           ├── Fail-Safe / Monitor Mode
    │           └── Event Logging config
    │
    ├── Content Policy (правила)  ──────►  привязывается к Profile(s)
    │
    ├── Event Exporter (SIEM)
    │
    ├── Reports (отчёты)
    │
    └── Data Retention (хранение)
                                          Security Events ◄── генерируются автоматически
                                          Audit Trail     ◄── генерируется автоматически

Провайдер (Provider)¶

Что это: провайдер — это конфигурация подключения к одному LLM backend. Каждый LLM API, к которому обращаются ваши пользователи (OpenAI, Anthropic, Azure OpenAI, GigaChat, self-hosted Ollama и т.д.), регистрируется как отдельный провайдер.

Зачем нужен: AppSec.AIGate должен знать, куда направляется запрос, чтобы:

Правильно извлечь текст промпта из структуры запроса (у каждого LLM API свой формат).
Применить соответствующий профиль безопасности.
Проксировать запрос на целевой URL после проверки.
Мониторить доступность backend и отображать health status.

Ключевые атрибуты:

Атрибут	Описание	Подробности
Название	Уникальное имя провайдера	Используется для идентификации в UI, логах и API. Например: `openai-production`, `gigachat-internal`. Нельзя изменить после создания.
Тип	Тип LLM API	Допустимые значения: `openai`, `anthropic`, `azure`, `google`, `cohere`, `huggingface`, `ollama`, `vllm`, `gigachat`, `custom`. Тип определяет набор доступных mapping presets. Для нестандартных API используйте `custom` с ручной настройкой field mapping.
Target URL	URL целевого LLM backend	Полный URL, куда AppSec.AIGate проксирует запрос после проверки. Примеры: `https://api.openai.com`, `http://ollama.internal:11434`, `https://gigachat.devices.sberbank.ru/api/v1`. Должен быть доступен из сети, где развёрнут AIGate.
Метод роутинга	Как Gateway определяет, что запрос относится к этому провайдеру	Три варианта (см. Метод роутинга). Определяет, по какому признаку входящий запрос сопоставляется с данным провайдером.
Mapping Preset	Формат API для извлечения промпта	Предустановленная конфигурация JSONPath-выражений, описывающая, где в теле запроса находится текст пользователя и где в теле ответа — текст модели. См. Mapping Presets.
Request Timeout	Таймаут запроса к LLM (мс)	Максимальное время ожидания ответа от LLM backend. По умолчанию: 30000 мс (30 секунд). Если LLM не ответил за это время — запрос завершается ошибкой. Для моделей с длинной генерацией (например, o1) рекомендуется увеличить до 120000 мс.
Health Status	Состояние доступности backend	Автоматически определяется системой: `HEALTHY` (backend отвечает), `UNHEALTHY` (backend недоступен или возвращает ошибки), `UNKNOWN` (проверка ещё не выполнялась). Не редактируется вручную.
Статус	Жизненный цикл провайдера	`DRAFT` → `ACTIVE` → `ARCHIVED`. Подробнее см. ниже.

Жизненный цикл провайдера:

DRAFT — провайдер создан, но ещё не используется. Запросы к нему не обрабатываются. Используйте этот статус для подготовки конфигурации.
ACTIVE — провайдер активен, запросы проксируются и проверяются. Переключение в этот статус возможно только если привязан хотя бы один профиль безопасности.
ARCHIVED — провайдер деактивирован. Запросы к нему отклоняются. Историческая конфигурация сохраняется для аудита.

Связь с другими сущностями: провайдер связан с одним или несколькими профилями безопасности (Profile). К одному провайдеру может быть привязано несколько профилей (например, разные профили для разных tenant). Провайдер принадлежит tenant.

Подробная настройка — см. Управление провайдерами.

Профиль безопасности (Profile)¶

Что это: профиль — это центральная сущность системы, определяющая какие проверки и с какими параметрами применяются к трафику конкретного провайдера. Профиль объединяет настройки всех детекторов, контентные политики и режимы работы в единую конфигурацию.

Зачем нужен: разные LLM-сервисы и разные подразделения организации могут требовать разного уровня защиты. Например:

Внутренний чат-бот для HR — строгий PII Detection (режим block), мягкий Threat Detection.
API для разработчиков — мягкий PII Detection (режим mask), строгий Content Safety.
Тестовый стенд — Monitor Mode (все детекторы работают, но ничего не блокируется).

Ключевые атрибуты:

Атрибут	Описание	Подробности
Название	Уникальное имя профиля	Используется в UI, логах и событиях. Рекомендуется осмысленное имя: `prod-openai-strict`, `dev-gigachat-monitor`.
Tenant ID	Идентификатор организации	Профиль принадлежит конкретному tenant. Изолирует конфигурацию между организациями в мультитенантной среде.
Provider ID	Связь с провайдером	Каждый профиль привязан к одному провайдеру. Определяет, к трафику какого LLM backend применяются эти настройки.
Threat Detection	Настройки обнаружения jailbreak/injection	Включает: `enabled` (вкл/выкл), `threshold` (порог score 0.0–1.0), `action` (block/monitor). Детальная настройка — см. Управление профилями.
PII Detection	Настройки обнаружения ПДн	Включает: `enabled`, `mode` (mask/redact/block), список активных типов PII, исключения. Детально — см. Управление профилями.
Content Safety	Категории контентной безопасности	Включает: `enabled`, пороги для каждой из 9 категорий, глобальный порог. Применяется к ответам LLM. Детально — см. Управление профилями.
Response Scanning	Общий переключатель сканирования ответов	Включает/выключает весь блок проверки ответов LLM (Content Safety + Output PII + Content Policy output). Если выключен — ответы проходят без проверки.
Output PII	Обнаружение секретов в ответах	Включает: `enabled`, список типов секретов (api_key, jwt, db_uri, private_key и др.), `action` (redact/block).
Content Policies	Привязанные контентные политики	Many-to-many связь. К профилю можно привязать несколько политик. Политики оцениваются по приоритету. См. Управление контентными политиками.
Homoglyph Normalization	Unicode-нормализация	Включает: `enabled`, уровни нормализации (nfkc, zero_width, homoglyph). Применяется до всех детекторов.
Event Logging	Настройки логирования	Что записывать в события: полный текст запроса, маскированный текст, только метаданные. Влияет на объём хранимых данных и приватность.
Fail-Safe Mode	Поведение при сбое детектора	`fail_closed` — блокировать запрос, если детектор недоступен (безопаснее, но может вызвать false positive). `fail_open` — пропускать запрос при сбое (рискованнее, но не прерывает работу пользователей).
Monitor Mode	Режим наблюдения	Если включён — все детекторы работают и генерируют события, но ни один запрос не блокируется. Используется для тюнинга порогов перед включением блокировки.
Статус	Жизненный цикл профиля	`DRAFT` → `ACTIVE` → `DEPRECATED` → `ARCHIVED`.

Жизненный цикл профиля:

DRAFT — профиль создан, детекторы настраиваются. Трафик не обрабатывается.
ACTIVE — профиль активен, детекторы применяются к трафику. У провайдера может быть только один активный профиль на tenant.
DEPRECATED — профиль помечен как устаревший (например, при переходе на новую версию настроек). Продолжает работать, но в пользовательском интерфейсе отображается предупреждение.
ARCHIVED — профиль деактивирован. Трафик по нему не обрабатывается. Конфигурация сохраняется для аудита.

Связь с другими сущностями: профиль привязан к одному провайдеру и одному tenant. К профилю можно привязать несколько контентных политик (many-to-many). Профиль генерирует события безопасности при срабатывании детекторов.

Подробная настройка — см. Управление профилями.

Контентная политика (Content Policy)¶

Что это: контентная политика — это набор текстовых правил, которые определяет администратор для реализации бизнес-требований и регуляторных ограничений конкретной организации. В отличие от ML-детекторов (Threat Detection, Content Safety), которые используют обученные модели, контентные политики работают на основе точных правил: ключевых слов и регулярных выражений.

Зачем нужна: ML-детекторы хорошо справляются с общими угрозами (jailbreak, насилие, NSFW), но не знают о специфике вашей организации. Контентные политики закрывают этот пробел:

Запретить обсуждение конкретных конкурентов по названию.
Заблокировать упоминание внутренних кодовых имён проектов.
Ограничить языки запросов (например, только русский и английский).
Пометить запросы с медицинской или юридической тематикой для ручной проверки.
Разрешить определённые PII-паттерны (например, публичные email-домены), чтобы снизить false positive.

Ключевые атрибуты:

Атрибут	Описание	Подробности
Название	Уникальное имя политики	Рекомендуется отражать назначение: `block-competitors`, `allow-public-emails`, `lang-ru-en-only`.
Тип	Категория политики	`blocklist` — запрещающие правила (блокировка или пометка при совпадении). `allowlist` — разрешающие правила (пропуск PII при совпадении). `language` — ограничение по языкам. Тип определяет логику обработки.
Правила (rules)	Массив правил с паттернами	Каждое правило содержит: `pattern` (текст для поиска), `pattern_type` (keyword или regex), `action` (block/flag/trust_pii), `severity` (low/medium/high/critical).
Scope	Направление проверки	`input` — только входящие запросы. `output` — только ответы LLM. `both` — оба направления. Определяет, на каком этапе конвейера применяется политика.
Приоритет (priority)	Порядок оценки	Целое число. Меньшее значение = более ранняя оценка. Политики оцениваются в порядке возрастания приоритета. Если две политики конфликтуют — побеждает та, что оценена раньше (с меньшим приоритетом).
Статус	Жизненный цикл	`DRAFT` → `ACTIVE` → `ARCHIVED`. Только политики в статусе `ACTIVE` применяются к трафику.

Связь с другими сущностями: политики связаны с профилями через many-to-many отношение. Одна политика может быть привязана к нескольким профилям (например, политика block-competitors применяется ко всем провайдерам). Один профиль может иметь несколько политик (например, blocklist + allowlist + language). Политика принадлежит tenant.

Подробное описание с примерами — см. Управление контентными политиками.

Событие безопасности (Security Event)¶

Что это: событие безопасности — запись, которая автоматически создаётся системой при каждом срабатывании детектора, применении политики или принятии решения PDP. События — это основной источник информации для мониторинга, расследования инцидентов и формирования отчётов.

Зачем нужно: события позволяют:

В реальном времени видеть, что происходит с LLM-трафиком.
Расследовать инциденты: кто, когда, какой запрос, почему заблокирован.
Формировать статистику и отчёты для руководства и регулятора.
Экспортировать данные в SIEM для корреляции с другими источниками.

Типы событий:

Тип	Когда создаётся	Severity	Описание
`THREAT_DETECTED`	Threat Detector вернул `unsafe`	high / critical	Обнаружена попытка jailbreak или prompt injection. Событие содержит score детектора и текст запроса.
`PII_DETECTED`	PII Detector нашёл персональные данные	medium / high	Обнаружены PII в запросе пользователя. Событие содержит типы найденных PII, их количество и применённое действие (mask/redact/block).
`POLICY_VIOLATION`	Сработало правило Content Policy	low — critical	Запрос или ответ совпал с правилом контентной политики. Severity определяется в правиле. Событие содержит имя политики и сработавший паттерн.
`CONTENT_SAFETY_VIOLATION`	Content Safety обнаружил опасный контент	medium — critical	Ответ LLM содержит контент, превысивший порог по одной или нескольким категориям. Событие содержит категории и score.
`OUTPUT_PII_DETECTED`	Output PII нашёл секреты в ответе	high / critical	В ответе LLM обнаружены технические секреты (API-ключи, токены, приватные ключи). Событие содержит типы секретов.
`REQUEST_BLOCKED`	PDP принял решение BLOCK	high / critical	Запрос заблокирован. Событие содержит причину блокировки и результаты всех детекторов.
`REQUEST_SANITIZED`	PDP принял решение SANITIZE	medium	Запрос прошёл после маскирования PII. Событие содержит количество замаскированных элементов.
`RESPONSE_BLOCKED`	PDP (output) принял решение BLOCK	high / critical	Ответ LLM заблокирован. Пользователь получает стандартное сообщение об ошибке вместо ответа модели.
`RESPONSE_REDACTED`	PDP (output) принял решение REDACT	medium	Из ответа LLM удалены секреты перед отправкой пользователю.
`FAIL_SAFE_TRIGGERED`	Детектор недоступен или вернул ошибку	high	Один из детекторов не смог обработать запрос. Решение принято по fail-safe правилу (closed или open).
`MONITOR_ALERT`	Обнаружена угроза в Monitor Mode	medium — critical	Детектор обнаружил нарушение, но запрос пропущен, потому что профиль работает в режиме наблюдения.

Структура события: каждое событие содержит timestamp, tenant_id, provider_id, profile_id, тип события, severity, IP-адрес клиента, request_id (для корреляции) и детальный payload с результатами детектора.

Полное описание полей и работа с событиями — см. События безопасности.

Экспортер событий (Event Exporter)¶

Что это: экспортер — это конфигурация отправки событий безопасности во внешнюю систему. AppSec.AIGate поддерживает пять типов экспортеров, каждый из которых рассчитан на свой сценарий интеграции.

Зачем нужен: события безопасности хранятся внутри AppSec.AIGate, но в большинстве организаций уже есть централизованная система мониторинга (SIEM, SOAR, ELK). Экспортер позволяет автоматически отправлять события в эти системы для:

Корреляции с другими источниками (WAF, IDS, Endpoint).
Построения единых дашбордов в SOC.
Автоматической реакции на инциденты (SOAR playbooks).
Долгосрочного хранения в соответствии с регуляторными требованиями.

Типы экспортеров:

Тип	Протокол	Типичное применение	Подробности
syslog	UDP/TCP (RFC 5424)	Классические SIEM (QRadar, ArcSight, KUMA)	Отправляет события по протоколу syslog. Настраивается адрес, порт, facility, severity mapping. Поддерживает TLS для TCP.
cef	CEF over Syslog	ArcSight, системы с поддержкой CEF	Common Event Format — стандартизированный формат Micro Focus. Автоматическое маппирование полей события в CEF-атрибуты.
webhook	HTTP POST (JSON)	Любая система с HTTP API, Slack, PagerDuty	Отправляет JSON-payload на указанный URL. Поддерживает custom headers (для авторизации), retry с exponential backoff, и опциональную подпись HMAC.
kafka	Apache Kafka	Высоконагруженные инсталляции, стриминг	Публикует события в Kafka topic. Настраиваются brokers, topic, key (для партиционирования), сериализация (JSON/Avro).
file	Файл на диске	Отладка, backup, air-gapped среды	Записывает события в файл. Поддерживает ротацию по размеру и времени. Формат: JSON Lines (по одному событию на строку).

Фильтрация: каждый экспортер может фильтровать события по severity (например, только high и critical), по типу события (например, только THREAT_DETECTED и REQUEST_BLOCKED) и по tenant_id. Это позволяет направлять разные типы событий в разные системы.

Маппинг полей: определяет, как поля события преобразуются в формат целевой системы. Три варианта: generic (стандартный JSON), ecs (Elastic Common Schema — для ELK Stack), custom (ручное определение маппинга полей).

Подробная настройка — см. Экспорт событий.

Отчёт (Report)¶

Что это: отчёт — автоматически генерируемый документ (PDF или CSV) с агрегированной аналитикой событий безопасности за указанный период. Отчёты формируются по расписанию или по запросу администратора.

Зачем нужен: отчёты решают три задачи:

Регуляторная отчётность — предоставление данных регулятору (например, Роскомнадзору для 152-ФЗ) о мерах защиты ПДн
Управленческая отчётность — руководство видит статистику использования LLM, количество инцидентов, тренды
Операционная аналитика — SOC-команда анализирует типы угроз, top-N заблокированных запросов, эффективность политик

Типы отчётов:

Тип	Содержимое	Типичный получатель
Incident Report	Все события с severity high/critical: jailbreak-попытки, блокировки, срабатывания fail-safe. Включает timeline, top атакующих IP, статистику по типам угроз.	SOC-аналитик, CISO
PII / DLP Report	Статистика обнаруженных ПДн: типы PII, количество, применённые действия (mask/redact/block), динамика по дням. Формат соответствует требованиям 152-ФЗ.	DPO, GRC, Роскомнадзор
LLM Usage Report	Статистика использования LLM: количество запросов по провайдерам, средняя задержка, процент заблокированных, top пользователей.	Руководство, Product Owner

Подробная настройка — см. Отчёты.

Журнал аудита (Audit Trail)¶

Что это: журнал аудита — автоматический, неизменяемый лог всех административных действий в системе. Каждый раз, когда администратор создаёт, изменяет или удаляет любую сущность (провайдер, профиль, политику, экспортер, пользователя и т.д.), система записывает: кто выполнил действие, когда, что именно было изменено (значения до и после).

Зачем нужен: журнал аудита отвечает на вопрос «кто и когда изменил конфигурацию?», что критически важно для:

Расследования инцидентов — если защита не сработала, нужно понять, не были ли изменены пороги или отключён детектор.
Соответствия стандартам — ISO 27001, PCI DSS, ГОСТ 57580 требуют журналирования административных действий.
Контроля доступа — отслеживание, какие операторы и администраторы вносят изменения.

Что фиксируется: все HTTP-мутации в Admin API (POST, PUT, PATCH, DELETE). Чувствительные данные (пароли, API-ключи, токены) автоматически редактируются в логе — вместо значения записывается [REDACTED].

Что не фиксируется: операции чтения (GET) и действия самой системы (решения PDP, работа детекторов) — они отражаются в событиях безопасности.

Подробная настройка — см. Аудит.

Tenant (Арендатор)¶

Что это: tenant — это изолированная организация или подразделение в мультитенантной архитектуре AppSec.AIGate. Каждый tenant имеет собственное пространство данных: свои провайдеры, профили, политики, экспортеры, пользователи и события.

Зачем нужен: мультитенантность позволяет:

Managed-сервис провайдерам — обслуживать несколько клиентов на одной инсталляции, при этом данные и конфигурации клиентов полностью изолированы друг от друга.
Крупным организациям — изолировать подразделения (например, HR и разработка используют разные политики).
Разделение prod/staging — использовать разные tenant для продакшен и тестовой среды.

Изоляция данных: tenant_id является обязательным атрибутом всех сущностей. Пользователь с ролью operator видит только данные своего tenant. Пользователь с ролью admin может управлять несколькими tenant.

Важно

При создании провайдера, профиля или политики tenant_id устанавливается автоматически на основе текущей сессии пользователя. Изменить tenant_id существующей сущности нельзя.

Метод роутинга (Routing Method)¶

Что это: метод роутинга определяет, как API Gateway сопоставляет входящий HTTP-запрос с конкретным провайдером. Когда клиент отправляет запрос, Gateway должен понять: к какому LLM backend он направлен, чтобы применить правильный профиль и field mapping.

Зачем нужен: в реальных инсталляциях к AppSec.AIGate обращаются клиенты, работающие с разными LLM API. Gateway должен маршрутизировать каждый запрос к правильному backend.

Три метода:

URL Pattern — роутинг по URL-пути запроса. Gateway проверяет path входящего запроса и сопоставляет его с паттерном. Поддерживает wildcard (*). Пример: паттерн /api/openai/* → запрос направляется к провайдеру OpenAI. Наиболее распространённый метод. Когда использовать: когда клиенты обращаются к разным LLM через разные URL-пути на одном домене. Наиболее распространённый метод.
Host / Domain — роутинг по заголовку Host. Gateway проверяет HTTP-заголовок Host и сопоставляет его с доменом провайдера. Пример: openai.company.com → запросы на этот поддомен направляются к OpenAI. Когда использовать: когда для каждого LLM-провайдера выделен отдельный поддомен. Требует настройки DNS.
HTTP Header — роутинг по произвольному HTTP-заголовку. Gateway проверяет значение указанного заголовка в запросе. Пример: X-LLM-Provider: gigachat → запрос направляется к GigaChat. Когда использовать: когда клиенты не могут менять URL или хост (например, SDK с фиксированным base_url), но могут добавить кастомный заголовок.

Приоритет: если запрос подходит под несколько провайдеров, применяется тот, чей метод роутинга более специфичен: Header > Host > URL Pattern.

Mapping Preset (Формат извлечения данных)¶

Что это: mapping preset — это предустановленная конфигурация, описывающая структуру API конкретного LLM-провайдера. Preset определяет, откуда извлечь текст пользователя из тела запроса и откуда извлечь текст ответа модели из тела ответа. Извлечение выполняется с помощью JSONPath-выражений.

Зачем нужен: каждый LLM-провайдер использует свой формат API. Например:

OpenAI: промпт находится в messages[-1].content.
Anthropic: промпт в messages[-1].content[0].text.
Google (Gemini): промпт в contents[-1].parts[0].text.
GigaChat: промпт в messages[-1].content, но авторизация через OAuth2.

AppSec.AIGate должен знать, где именно в JSON-структуре запроса искать текст, чтобы передать его детекторам. Без правильного mapping preset детекторы не получат текст для анализа, и проверка не состоится.

Готовые presets: система включает 14+ предустановленных presets для популярных LLM API. При выборе типа провайдера (openai, anthropic и т.д.) соответствующий preset подставляется автоматически.

Custom mapping: для нестандартных API (внутренние LLM, нестандартные обёртки) вы можете указать JSONPath-выражения вручную:

request_body_path — путь к тексту промпта в теле запроса.
response_body_path — путь к тексту ответа в теле ответа.
model_field_path — путь к имени модели (опционально).

Пример custom mapping:

{
  "request_body_path": "$.input.messages[-1].text",
  "response_body_path": "$.output.generated_text",
  "model_field_path": "$.input.model_name"
}

Важно

Если mapping preset настроен неправильно, детекторы получат пустой текст и проверка фактически не состоится. При этом система не заблокирует запрос (если не включён fail_closed), а только создаст событие FAIL_SAFE_TRIGGERED. Всегда проверяйте mapping на тестовом запросе перед активацией провайдера.

Полный список presets — см. Mapping Presets.

PDP — Policy Decision Point¶

Что это: PDP (Policy Decision Point) — это движок принятия финального решения о судьбе запроса или ответа. PDP получает результаты от всех сработавших детекторов и контентных политик, вычисляет совокупную серьёзность угрозы и принимает одно из решений: ALLOW, BLOCK, SANITIZE (для запросов) или ALLOW, BLOCK, REDACT (для ответов).

Зачем нужен: один запрос может вызвать срабатывание нескольких детекторов одновременно. Например, запрос содержит и PII (email), и подозрительный паттерн jailbreak, и нарушение контентной политики. PDP агрегирует все сигналы и принимает единое решение.

Как работает (severity boost accumulation):

Каждый детектор возвращает результат со своим severity: low (0.1), medium (0.3), high (0.5), critical (0.8).
PDP суммирует severity-boost от всех сработавших детекторов.
Если сумма превышает порог 0.5 — решение BLOCK.
Если есть PII и режим mask — решение SANITIZE (маскирование).
Если ни один детектор не сработал — решение ALLOW.

Правила решения написаны на языке Rego (Open Policy Agent). Это позволяет при необходимости кастомизировать логику принятия решений.

Пример: Threat Detector вернул unsafe с severity medium (boost 0.3), PII Detector нашёл один email (severity low, boost 0.1). Сумма = 0.4, что ниже порога 0.5 → решение SANITIZE (маскировать email и пропустить запрос). Если бы Threat Detector вернул severity high (boost 0.5) — сумма была бы 0.6 → решение BLOCK.