Первичная настройка

В этом разделе описана настройка объектов платформы через веб-интерфейс StarGuard Base: подключение моделей и путей, создание шлюзов, конфигурирование детекторов и обработки вложений, управление политиками SafeGuard и Tool Call, пользователями и лимитами, OIDC, сканированием, API-токенами и лицензией.

Все операции выполняются в интерфейсе StarGuard Base (https://<DOMAIN>;). Перед настройкой убедитесь, что платформа запущена, лицензия активирована и вы вошли в систему под учётной записью с необходимыми правами.

Рекомендуемый порядок первичной настройки:

Активируйте лицензию (Управление лицензией).
Создайте API-токен для шлюза (Управление API-токенами).
Настройте OIDC-провайдер для пользователей шлюза.
Создайте цели шлюза — Модели (Управление моделями) или Пути (Управление путями).
Создайте шлюз, выберите его режим и настройте детекторы (Управление шлюзами).
Создайте пользователей и группы, задайте лимиты (Управление пользователями и группами).
Разверните экземпляр StarGuard Gate с полученными UUID шлюза и API-токеном (Развертывание StarGuard Gate).

1. Настройка детекторов

Детекторы настраиваются в контексте шлюза (глобальные настройки) или конкретной цели — Модели либо Пути (переопределение). Настройки цели имеют приоритет над глобальными.

Для каждого детектора, заданного на уровне цели, доступны три варианта:

Наследовать — использовать настройки уровня шлюза.
Отключить — полностью отключить детектор для данной цели.
Настроить — задать собственные параметры детектора (заменяют глобальные целиком).

Переопределение заменяет настройку целиком. Если для цели выбран вариант «Настроить», от шлюза не наследуется ни один параметр этого детектора: незаполненные поля принимают значения по умолчанию, а не значения шлюза.

Для каждого детектора задаётся режим действия.

Режим Описание

Режим	Описание
Выключен (`disabled`)	Детектор отключён
Мониторинг (`monitor`)	Детектор работает, результат фиксируется в событии, запрос не блокируется
Блокировать (`block`)	При срабатывании запрос блокируется, пользователю возвращается сообщение об ошибке
Добавить сообщение (`message`)	Запрос не блокируется, к ответу добавляется предупреждение (требуется заполнить поле «Сообщение при срабатывании»)
Перенаправить (`redirect`)	Запрос перенаправляется на другой бэкенд (требуется выбрать целевой бэкенд). Недоступно для выходных детекторов

Выключен (disabled)

Детектор отключён

Мониторинг (monitor)

Детектор работает, результат фиксируется в событии, запрос не блокируется

Блокировать (block)

При срабатывании запрос блокируется, пользователю возвращается сообщение об ошибке

Добавить сообщение (message)

Запрос не блокируется, к ответу добавляется предупреждение (требуется заполнить поле «Сообщение при срабатывании»)

Перенаправить (redirect)

Запрос перенаправляется на другой бэкенд (требуется выбрать целевой бэкенд). Недоступно для выходных детекторов

1.1. Детектор языка

Определяет язык последнего пользовательского сообщения с помощью трансформерной модели классификации.

Параметр Описание

Параметр	Описание
Режим	Режим действия из таблицы режимов
Разрешённые языки	Whitelist языков (коды ISO 639-1, например `ru`, `en`). Запросы на других языках блокируются
Запрещённые языки	Blacklist языков. Запросы на этих языках блокируются
Минимальная уверенность	Порог уверенности модели (0–1). Запросы с уверенностью ниже порога считаются языком `unknown`

Режим

Режим действия из таблицы режимов

Разрешённые языки

Whitelist языков (коды ISO 639-1, например ru, en). Запросы на других языках блокируются

Запрещённые языки

Blacklist языков. Запросы на этих языках блокируются

Минимальная уверенность

Порог уверенности модели (0–1). Запросы с уверенностью ниже порога считаются языком unknown

1.2. Детектор регулярных выражений

Проверяет все сообщения запроса на совпадение с набором regex-шаблонов. Проверка выполняется без учёта регистра.

Параметр	Описание
Режим	Режим действия из таблицы режимов
Блокирующие шаблоны	Список regex-выражений. При совпадении хотя бы с одним детектор срабатывает

Параметр

Описание

Режим

Режим действия из таблицы режимов

Блокирующие шаблоны

Список regex-выражений. При совпадении хотя бы с одним детектор срабатывает

Пример шаблонов: /bconfidential/b, /d{2}/s*/d{2}/s*/d{6} (серия и номер паспорта), (?i)/bpassword/s*=/s*/S+.

1.3. Детектор чувствительной информации

Обнаруживает персональные и конфиденциальные данные с помощью NLP-движка и нейросетевого распознавателя именованных сущностей. Поддерживает русский и английский языки.

Параметр Описание

Параметр	Описание
Режим	Режим действия из таблицы режимов
Маскировать PII	Включает замену найденных сущностей на анонимизированные метки (`<PERSON_0>`, `<PHONE_NUMBER_1>` и т.п.) перед отправкой в LLM с автоматическим демаскированием ответа
Минимальная уверенность	Порог (0–1) для признания сущности чувствительной. Значение по умолчанию — 0,75
Анализируемые классы информации	Раскрывающийся список классов, сгруппированных в «Общие классы» и «Документы отдельных стран». Кнопки «Выбрать все» и «Снять все» задают весь набор сразу
Расширенная валидация (LLM)	Дополнительная проверка найденных сущностей через Guard LLM Inference для снижения ложных срабатываний

Режим

Режим действия из таблицы режимов

Маскировать PII

Включает замену найденных сущностей на анонимизированные метки (<PERSON_0>, <PHONE_NUMBER_1> и т.п.) перед отправкой в LLM с автоматическим демаскированием ответа

Минимальная уверенность

Порог (0–1) для признания сущности чувствительной. Значение по умолчанию — 0,75

Анализируемые классы информации

Раскрывающийся список классов, сгруппированных в «Общие классы» и «Документы отдельных стран». Кнопки «Выбрать все» и «Снять все» задают весь набор сразу

Расширенная валидация (LLM)

Дополнительная проверка найденных сущностей через Guard LLM Inference для снижения ложных срабатываний

Снятый класс не ищется. Распознаватель для него не запускается: такие данные не попадут ни в аудит события, ни под маскирование. Пока список классов не изменён вручную, действует набор по умолчанию — все общие классы включены, классы документов отдельных стран выключены.

Параметры расширенной валидации.

Подпараметр	Описание
Включить	Активировать расширенную валидацию
Базовый URL LLM API	Базовый URL API Guard LLM Inference
Модель	Имя модели для валидации найденных сущностей
API-токен	Bearer-токен для аутентификации запросов к Guard LLM Inference (опционально)

Подпараметр

Описание

Включить

Активировать расширенную валидацию

Базовый URL LLM API

Базовый URL API Guard LLM Inference

Модель

Имя модели для валидации найденных сущностей

API-токен

Bearer-токен для аутентификации запросов к Guard LLM Inference (опционально)

Режим маскирования. Маскирование работает независимо от выбранного режима действия — если включён переключатель «Маскировать PII», сущности чувствительных данных будут заменены на метки перед отправкой в LLM, а после получения ответа будут восстановлены оригинальные значения.

1.4. Input Safe Guard (семантическая фильтрация входящих запросов)

Семантический детектор на основе LLM. Работает по одной из двух стратегий: тяжёлой (по SafeGuard-политикам) или лёгкой (по одному текстовому критерию).

Параметр Описание

Параметр	Описание
Режим	Режим действия из таблицы режимов
Стратегия проверки	«Тяжёлая» — глубокий анализ по набору политик, выше расход ресурсов; «Лёгкая» — быстрая проверка по одному критерию
При сбое SG	«Блокировать (fail-closed)» — по умолчанию; «Пропускать (fail-open)» — при недоступности Guard LLM Inference запрос проходит без семантической проверки
Доп. попыток	Число повторных обращений к Guard LLM Inference при ошибке (по умолчанию 0)
Backoff, с	Базовая пауза между повторными попытками (по умолчанию 0,2)
Базовый URL LLM API	URL API Guard LLM Inference (vLLM)
Модель	Имя модели для семантического анализа
API-токен	Bearer-токен для аутентификации запросов к Guard LLM Inference (опционально)
Политики безопасности	Только для тяжёлой стратегии: список slug’ов SafeGuard-политик (тип `input` или `both`)
Критерий	Только для лёгкой стратегии: текст единственного критерия нарушения. Если поле пустое, применяется встроенный критерий (prompt injection / jailbreak)
Think-режим	Только для лёгкой стратегии: пошаговое рассуждение модели. При включении задайте Max tokens не менее 4047 — иначе рассуждение может обрезаться до вердикта и запрос будет заблокирован
Temperature, Max tokens	Только для лёгкой стратегии: параметры генерации (по умолчанию 0,7 и 1024)

Режим

Режим действия из таблицы режимов

Стратегия проверки

«Тяжёлая» — глубокий анализ по набору политик, выше расход ресурсов; «Лёгкая» — быстрая проверка по одному критерию

При сбое SG

«Блокировать (fail-closed)» — по умолчанию; «Пропускать (fail-open)» — при недоступности Guard LLM Inference запрос проходит без семантической проверки

Доп. попыток

Число повторных обращений к Guard LLM Inference при ошибке (по умолчанию 0)

Backoff, с

Базовая пауза между повторными попытками (по умолчанию 0,2)

Базовый URL LLM API

URL API Guard LLM Inference (vLLM)

Модель

Имя модели для семантического анализа

API-токен

Bearer-токен для аутентификации запросов к Guard LLM Inference (опционально)

Политики безопасности

Только для тяжёлой стратегии: список slug’ов SafeGuard-политик (тип input или both)

Критерий

Только для лёгкой стратегии: текст единственного критерия нарушения. Если поле пустое, применяется встроенный критерий (prompt injection / jailbreak)

Think-режим

Только для лёгкой стратегии: пошаговое рассуждение модели. При включении задайте Max tokens не менее 4047 — иначе рассуждение может обрезаться до вердикта и запрос будет заблокирован

Temperature, Max tokens

Только для лёгкой стратегии: параметры генерации (по умолчанию 0,7 и 1024)

1.5. Пользовательский детектор (WebHook)

Передаёт нормализованный текст запроса или ответа во внешний HTTP-сервис и применяет его вердикт. Детектор представляет собой список сервисов: каждая строка — самостоятельный экземпляр со своим адресом и режимом.

Добавление сервиса:

В форме шлюза, Модели или Пути включить блок Пользовательский детектор (в разделе «Детекторы входящих запросов» или «Детекторы ответов»).
Нажмите Добавить сервис и заполнить поля.

Поле Описание Пример

Поле	Описание	Пример
Имя	Идентификатор сервиса; попадает в аудит и в поле «Детектор» события	`dlp`
URL	Адрес эндпоинта. Разрешены схемы `http` и `https`; адреса link-local запрещены	`https://dlp.corp.local/v1/inspect`
Таймаут, мс	Предельное время ожидания ответа (по умолчанию 3000)	`3000`
Режим	Режим действия из таблицы режимов. Если не задан, наследуется от детектора	`Блокировать`
При сбое	«Блокировать (fail-closed)» или «Пропускать (fail-open)». Повторных попыток нет	`Блокировать`
Аутентификация	«Без аутентификации», «Bearer-токен», «Свой заголовок» или «Подпись HMAC»	`Bearer-токен`
Имя заголовка	Заголовок для передачи секрета (только для способа «Свой заголовок»)	`X-Api-Key`
Секрет	Значение токена или ключа подписи. Хранится в зашифрованном виде; при редактировании пустое поле означает «не менять»	—
Разрешить правку запроса	Только для входного детектора: сервис может заменять текст присланных ему фрагментов	выкл
Отправлять фрагменты, Отправлять диалог	Состав данных, передаваемых сервису	вкл
Сообщение при срабатывании	Текст для пользователя (требуется в режимах «Блокировать» и «Добавить сообщение»)	—
Целевой бэкенд	Куда перенаправить запрос (требуется в режиме «Перенаправить»)	—

Имя

Идентификатор сервиса; попадает в аудит и в поле «Детектор» события

dlp

URL

Адрес эндпоинта. Разрешены схемы http и https; адреса link-local запрещены

https://dlp.corp.local/v1/inspect

Таймаут, мс

Предельное время ожидания ответа (по умолчанию 3000)

3000

Режим

Режим действия из таблицы режимов. Если не задан, наследуется от детектора

Блокировать

При сбое

«Блокировать (fail-closed)» или «Пропускать (fail-open)». Повторных попыток нет

Блокировать

Аутентификация

«Без аутентификации», «Bearer-токен», «Свой заголовок» или «Подпись HMAC»

Bearer-токен

Имя заголовка

Заголовок для передачи секрета (только для способа «Свой заголовок»)

X-Api-Key

Секрет

Значение токена или ключа подписи. Хранится в зашифрованном виде; при редактировании пустое поле означает «не менять»

—

Разрешить правку запроса

Только для входного детектора: сервис может заменять текст присланных ему фрагментов

выкл

Отправлять фрагменты, Отправлять диалог

Состав данных, передаваемых сервису

вкл

Сообщение при срабатывании

Текст для пользователя (требуется в режимах «Блокировать» и «Добавить сообщение»)

—

Целевой бэкенд

Куда перенаправить запрос (требуется в режиме «Перенаправить»)

—

Порядок строк меняется стрелками, лишняя строка удаляется кнопкой «Удалить сервис».

Внимание. Внешний сервис получает текст до маскирования персональных данных: его журналы и хранилище становятся хранилищем ПДн. Включённая настройка «Разрешить правку запроса» дополнительно отменяет маскирование для изменённых сервисом фрагментов — немаскированные данные уйдут и к провайдеру модели. Адрес по http означает передачу этого текста по сети открытым текстом.

Переименование сервиса. Секрет хранится по имени сервиса. Переименование строки создаёт новый сервис с пустым секретом — секрет потребуется ввести заново.

Переопределение на уровне цели заменяет список целиком, а не дополняет глобальный список шлюза.

1.6. Детектор лимитов пользователя

Контролирует лимит потребления по токенам или по стоимости. Активен только при включённой аутентификации через OIDC.

Параметр	Описание
Режим	Режим действия из таблицы режимов
URL сервиса состояния пользователей	URL сервиса User State, хранящего счётчики потребления

Параметр

Описание

Режим

Режим действия из таблицы режимов

URL сервиса состояния пользователей

URL сервиса User State, хранящего счётчики потребления

1.7. Output Safe Guard (семантическая фильтрация ответов LLM)

Аналог Input Safe Guard, применяемый к ответу, полученному от LLM. Настраивается в разделе Детекторы ответов формы шлюза, Модели или Пути. В тяжёлой стратегии использует SafeGuard-политики типа output или both.

Параметр Описание

Параметр	Описание
Режим	Режим действия из таблицы режимов (без режима «Перенаправить»)
Стратегия проверки, При сбое SG, Доп. попыток, Backoff	Аналогично Input Safe Guard
Базовый URL LLM API	URL API Guard LLM Inference
Модель	Имя модели для семантического анализа
API-токен	Bearer-токен для аутентификации запросов к Guard LLM Inference (опционально)
Политики безопасности	Список slug’ов SafeGuard-политик (тип `output` или `both`)
Критерия, Think-режим, Temperature, Max tokens	Параметры лёгкой стратегии, аналогичные Input Safe Guard

Режим

Режим действия из таблицы режимов (без режима «Перенаправить»)

Стратегия проверки, При сбое SG, Доп. попыток, Backoff

Аналогично Input Safe Guard

Базовый URL LLM API

URL API Guard LLM Inference

Модель

Имя модели для семантического анализа

API-токен

Bearer-токен для аутентификации запросов к Guard LLM Inference (опционально)

Политики безопасности

Список slug’ов SafeGuard-политик (тип output или both)

Критерия, Think-режим, Temperature, Max tokens

Параметры лёгкой стратегии, аналогичные Input Safe Guard

Внимание. Включение любого выходного детектора переводит потоковый режим (stream=true) в буферизованный — Gate собирает весь ответ полностью перед прогоном выходных детекторов, что увеличивает время до первого фрагмента.

1.8. Tool Policies Detector (контроль вызовов инструментов)

Выходной детектор, проверяющий вызовы инструментов, генерируемые LLM в ответе, на соответствие набору tool-политик.

Параметр	Описание
Режим	Режим действия из таблицы режимов (без режима «Перенаправить»)
Политики инструментов	Список slug’ов tool-политик, применяемых к вызовам инструментов в ответе
Сообщение при срабатывании	Текст, возвращаемый пользователю при блокировке (требуется для режимов «Блокировать» и «Добавить сообщение»)

Параметр

Описание

Режим

Режим действия из таблицы режимов (без режима «Перенаправить»)

Политики инструментов

Список slug’ов tool-политик, применяемых к вызовам инструментов в ответе

Сообщение при срабатывании

Текст, возвращаемый пользователю при блокировке (требуется для режимов «Блокировать» и «Добавить сообщение»)

2. Настройка обработки вложений

Блок Обработка вложений определяет, что шлюз делает с файлами и изображениями, приложенными к запросу. Настраивается на уровне шлюза (полный набор параметров) и переопределяется на уровне Модели или Пути (первые три параметра).

Параметр	Уровень	Описание
Документы	шлюз, цель	«Подставлять текст» (по умолчанию) — вместо вложения в запрос уезжает распознанный текст; «Отклонять» — вложения не принимаются
Картинки	шлюз, цель	«OCR-текст» (по умолчанию) — изображение распознаётся и проверяется детекторами; «Пропускать без проверки» — изображение уходит в модель без инспекции; «Отклонять» — изображения не принимаются
При сбое распознавания	шлюз, цель	«Блокировать (fail-closed)» (по умолчанию) — при недоступности или ошибке File Recognizer запрос отклоняется; «Пропускать (fail-open)» — нечитаемый файл уйдёт в модель непроверенным
Таймаут распознавания, с	шлюз	Предельное время ожидания ответа File Recognizer (по умолчанию 120)
Параллельных конвертаций	шлюз	Количество одновременных обращений к File Recognizer на процесс шлюза. Бюджет общий для всех целей шлюза (по умолчанию 4)

Параметр

Уровень

Описание

Документы

шлюз, цель

«Подставлять текст» (по умолчанию) — вместо вложения в запрос уезжает распознанный текст; «Отклонять» — вложения не принимаются

Картинки

шлюз, цель

«OCR-текст» (по умолчанию) — изображение распознаётся и проверяется детекторами; «Пропускать без проверки» — изображение уходит в модель без инспекции; «Отклонять» — изображения не принимаются

При сбое распознавания

шлюз, цель

«Блокировать (fail-closed)» (по умолчанию) — при недоступности или ошибке File Recognizer запрос отклоняется; «Пропускать (fail-open)» — нечитаемый файл уйдёт в модель непроверенным

Таймаут распознавания, с

шлюз

Предельное время ожидания ответа File Recognizer (по умолчанию 120)

Параллельных конвертаций

шлюз

Количество одновременных обращений к File Recognizer на процесс шлюза. Бюджет общий для всех целей шлюза (по умолчанию 4)

Внимание. Режим «Пропускать без проверки» для картинок — единственный канал, по которому через шлюз проходит неинспектированный бинарный контент: OCR не выполняется, персональные данные на скриншотах не маскируются, инъекции в изображениях не детектируются. Режим «Пропускать (fail-open)» при сбое распознавания означает, что нечитаемый файл уйдёт в модель непроверенным.

Распознанный текст хранится сервисом File Recognizer бессрочно и до маскирования персональных данных.

Ограничение объёма. Размер вложений в интерфейсе не настраивается. Единственный ограничитель — переменная окружения MAX_REQUEST_BYTES на стороне шлюза, применяемая ко всему телу запроса.

Любое изменение блока «Обработка вложений» перезапускает процесс шлюза.

3. Настройка OIDC для шлюзов

OIDC-интеграция позволяет пользователям StarGuard Gate авторизоваться через корпоративный Identity Provider (StarVault, Keycloak, Microsoft Entra ID, Okta и др.).

Предварительные требования:

В Identity Provider создан клиент с типом confidential или public.
Известен URL эмитента (issuer) — как правило, https://<idp-host>/realms/<realm>; — и URL метаданных.

Создание OIDC-конфигурации:

Перейдите в раздел Доступ → OpenID Connect → Создать.
Заполните поля.

Поле Описание Пример

Поле	Описание	Пример
Имя	Отображаемое название провайдера	`Keycloak`
URL провайдера (`issuer`)	URL эмитента токенов	`https://keycloak.corp.example.com/realms/corp`
Client ID	Идентификатор клиента в Identity Provider	`sg-gate`
Well-known URL	URL `.well-known/openid-configuration` провайдера	`https://keycloak.corp.example.com/realms/corp/.well-known/openid-configuration`
Client Secret	Секрет клиента. Хранится в зашифрованном виде; при редактировании пустое поле означает «не менять»	—
Схема redirect_uri	Схема, с которой портал самообслуживания собирает адрес возврата: `https` или `http`	`https`
Проверять aud	Проверка поля `aud` в токене. Значение по умолчанию для новых записей — включено	вкл
Claim имени пользователя	Путь к claim с именем пользователя	`preferred_username`
Claim групп	Путь к claim со списком групп	`groups`
Назначение шлюзов	Шлюзы, к которым применяется данная OIDC-конфигурация	—

Имя

Отображаемое название провайдера

Keycloak

URL провайдера (issuer)

URL эмитента токенов

https://keycloak.corp.example.com/realms/corp

Client ID

Идентификатор клиента в Identity Provider

sg-gate

Well-known URL

URL .well-known/openid-configuration провайдера

https://keycloak.corp.example.com/realms/corp/.well-known/openid-configuration

Client Secret

Секрет клиента. Хранится в зашифрованном виде; при редактировании пустое поле означает «не менять»

—

Схема redirect_uri

Схема, с которой портал самообслуживания собирает адрес возврата: https или http

https

Проверять aud

Проверка поля aud в токене. Значение по умолчанию для новых записей — включено

вкл

Claim имени пользователя

Путь к claim с именем пользователя

preferred_username

Claim групп

Путь к claim со списком групп

groups

Назначение шлюзов

Шлюзы, к которым применяется данная OIDC-конфигурация

—

Привяжите OIDC-конфигурацию к нужным шлюзам.

После привязки StarGuard Gate будет валидировать id_token пользователей через JWKS-эндпоинт указанного Identity Provider.

Пути к claim. Значения полей «Claim имени пользователя» и «Claim групп» — это путь к claim в токене: точка разделяет уровни вложенности (resource_access.aisp.roles), точка внутри имени claim экранируется обратной косой чертой (users\.sgai — claim с именем users.sgai). Если claim не найден, именем пользователя становится sub, а список групп остаётся пустым (доступ при этом не расширяется).

Проверка aud. Пользователи присылают id_token, у которого поле aud равно Client ID, поэтому проверку рекомендуется оставить включённой.