# Настроить маскирование чувствительных данных для AI-агентов и AI-операций

> [HTML Version](masking.html)

Вы можете настроить для AI‑агента или AI‑операции маскирование, чтобы языковая модель не получала доступ к персональным и корпоративным данным.

Для поиска чувствительных данных в запросах применяются:

- встроенный детектор **ELMA Cortex** — используется всегда при включении маскирования и подходит для защиты базового уровня. Предусматривает распознавание всех распространенных типов персональных данных;

- дополнительные детекторы — вы можете настроить пользовательские проверки на чувствительные данные с помощью регулярных выражений или внешних сервисов маскирования.

Для настройки маскирования выполните шаги:

1. [Включите маскирование для AI‑агента или AI-операции](#enable-masking).

2. [Задайте общие настройки маскирования](#general-settings).

3. [Добавьте дополнительные детекторы](#add-detector).

## Шаг 1. Включить маскирование 

1. При [настройке AI‑агента](cortex-configure-agent.md) или [AI‑операции](configure-ai-action.md) откройте вкладку **Маскирование** и нажмите **Включить**.

2. Отметьте типы персональных данных, которые нужно маскировать для языковой модели. Чтобы маскировать все встроенные типы данных, включите опцию **Обнаруживать все поддерживаемые типы данных**.

**(cortex-masking-1.png)**

3. Оставьте опцию **Демаскирование ответов** включённой, чтобы в ответе AI‑агента или AI‑операции для пользователя отображались исходные значения из запроса. При отключении опции данные остаются замаскированными.

4. Нажмите внизу страницы кнопку **Сохранить**.

Теперь к запросам автоматически применяется встроенный детектор чувствительных данных **ELMA Cortex**. 

Вы можете изменить настройки маскирования и добавить дополнительные детекторы.

## Шаг 2. Задать общие настройки маскирования

Чтобы задать свои настройки маскирования, нажмите кнопку **Дополнительные настройки** и заполните поля:

- **Режим маскирования** — выберите вариант:

	- **Замена на токен** — обнаруженные значения заменяются на структурированные токены, формат которых зависит от типа данных, например **\[PERSON-1\]** или **\[EMAIL\_ADDRESS-1\]**. Этот режим удобен, когда важно явно показать языковой модели, где в тексте находятся замаскированные данные;

	- **Замена на похожие данные** — используются правдоподобные условные значения вместо реальных данных;

- **Метаданные токенов** — включите опцию, чтобы при использовании токенов сохранялась дополнительная информация о падеже, роде исходного слова и т. п. Это помогает языковой модели корректно использовать замаскированные данные в ответах пользователю и при вызове инструментов;

- **Пользовательский фрагмент промпта** — опционально добавьте свои требования для маскирования данных, которые используются как дополнение к стандартной инструкции **ELMA Cortex** для выбранного режима маскирования.

После заполнения полей закройте окно и нажмите внизу страницы кнопку **Сохранить**.

## Шаг 3. Добавить дополнительные детекторы

В блоке **Дополнительные детекторы** можно добавить другие способы распознавания чувствительной информации, например, чтобы находить тип данных, который не поддерживается по умолчанию.

Для этого нажмите **Добавить детектор**, укажите тип детектора и заполните его настройки:

1. **Regex-детектор** — находятся фрагменты текста, соответствующие определённым регуляным выражениям. Подходит для маскирования корпоративных идентификаторов, номеров заявок и договоров, а также других данных со строгим форматом:

- **Название** — введите имя детектора;

- **Тип сущности **— укажите, какой тип чувствительных данных распознаётся с помощью детектора, например, паспортные данные, номера договоров и т. п. Для этого введите название типа, используя заглавные латинские буквы и знак **\_** для разделения слов. Вы можете ввести название одного из [встроенных типов чувствительных данных](#embedded-types) или задать пользовательский тип, например **CONTRACT\_NUMBER**.

От типа данных зависит, на что заменяется исходная информация, найденная по регулярному выражению, в выбранном [режиме маскирования](#general-settings):

	- при замене на токены — название типа используется для формирования токенов, например **\[PERSON-1\]** или **\[CONTRACT\_NUMBER-1\]**;

	- при замене на похожие данные — для встроенных типов формируются условные значения. Для пользовательских типов и встроенного типа **UNKNOWN** используется замещающий текст **<MASKED>**, т. к. генерация условных значений не настроена в системе. 

Встроенные типы данных

- **PERSON** — Ф. И. О. или полное имя;

- **EMAIL\_ADDRESS** — электронная почта;

- **PHONE\_NUMBER** — номер телефона;

- **ADDRESS** — адрес;

- **CREDIT\_CARD** — банковская карта;

- **RU\_INN** — ИНН;

- **RU\_SNILS** — СНИЛС;

- **RU\_PASSPORT** — паспорт РФ;

- **RU\_ZIPCODE** — почтовый индекс РФ;

- **UNKNOWN** — неизвестный тип данных. Используйте это значение, если определить тип чувствительных данных невозможно или это не требуется для обработки запросов. 

- **Паттерны** — введите регулярные выражения, которым соответствует формат чувствительных данных;

- **Флаги regex** — при необходимости укажите флаги дополнительных опций, например включите регистронезависимый или многострочный поиск.

Подробнее о синтаксисе регулярных выражений читайте в документации [MDN Web Docs](https://developer.mozilla.org/ru/docs/Web/JavaScript/Guide/Regular_Expressions). 

2. **Внешний сервис** — текст анализируется с помощью корпоративного классификатора, словаря, модели машинного обучения или сервиса безопасности:

- **Скачать OpenAPI схему** — нажмите на ссылку и загрузите на компьютер файл с JSON‑схемой, на основе которой нужно настроить сервис распознавания чувствительных данных;

- **Название** — введите имя детектора;

- **URL вебхука** — укажите полный адрес, по которому вызывается внешний сервис; 

- **Заголовки запроса** — добавьте HTTP-заголовки, например `Authorization: Bearer <token>`;

- **Таймаут запроса (секунды) **— укажите время ожидания маскирования;

- **Максимум повторных попыток** — укажите число повторов при ошибках сети;

- **Политика при ошибке** — выберите действие в случае, если не удалось выполнить маскирование с помощью внешнего сервиса:

	- **Блокировать** — обработка запроса остановится, пользователь увидит сообщение об ошибке;

	- **Пропустить** — обработка запроса не остановится;

- **Режим замены** — выберите вариант:

	- **Замена пайплайна** — внешний сервис только сообщает, где находятся чувствительные данные. Маскирование происходит на стороне **ELMA Cortex**;

	- **Использовать замену вебхука** — фиксируются значения для замены, сгенерированные внешним сервисом;

- **Дополнительные параметры **— включите опцию и задайте JSON-объект с дополнительной информацией по выполнению проверки.

Когда вы заполните все поля, сохраните настройки детектора, затем нажмите внизу страницы кнопку **Сохранить**.

После этого добавленный детектор чувствительных данных будет применяться ко всем запросам, отправленным AI‑агенту или AI‑операции. Если несколько детекторов находят пересекающиеся фрагменты с персональной информацией, в **ELMA Cortex** применится одна итоговая замена.

Обратите внимание, маскирование по умолчанию также используется для данных, которые отправляются в систему трассировки. Вы можете его отключить. Подробнее читайте в [статье об отладке AI‑агентов](cortex-agent-calibration.md#tracing) или [AI‑операций](ai-action-calibration.md#tracing).

## Управление детекторами чувствительных данных

Дополнительные детекторы чувствительных данных, которые вы настраиваете, отобразятся в списке на вкладке **Маскирование**. Вы можете:

**(cortex-masking-2.png)**

- создать новый детектор — нажмите кнопку **+ Добавить детектор** и [задайте настройки](#add-detector);

- временно отключить детектор — нажмите на переключатель рядом с его названием;

- изменить настройки детектора — нажмите на три точки в правом верхнем углу блока и выберите опцию **Настроить**;

- поменять порядок применения детекторов — зажмите значок перемещения и перетащите блок с проверкой или нажмите на три точки и выберите опцию **Переместить вверх** или **Переместить вниз**;

- удалить детектор — нажмите на три точки и выберите **Удалить**. Восстановить удалённый детектор нельзя.