Маскирование трафика

Что такое маскирование

Содержимое запроса, отправленного через ProxyAPI, в итоге попадает к конечному сервису. В этом содержимом часто оказываются персональные данные пользователей и секреты — номера паспортов, телефоны, email, банковские карты, ИНН, API-ключи, JWT-токены. Проконтролировать это удаётся не всегда: пользователь приложения просто пишет произвольный текст.

Маскирование трафика от ProxyAPI решает эту задачу на уровне прокси. Сервис анализирует каждый запрос, находит в нём персональные данные и секреты и — в зависимости от выбранного режима — либо блокирует запрос, либо заменяет найденные значения на синтетические до отправки конечному сервису. В режиме маскирования оригинальные значения автоматически восстанавливаются в ответе модели перед возвратом клиенту — пользователь приложения получает корректный ответ на свой реальный вопрос, а конечный сервис так и не увидит настоящих данных.

Маскирование можно включить для всех или определённых API-ключей аккаунта. Сервис доступен бесплатно всем пользователям.

Режимы работы

Маскирование поддерживает два режима.

Блокировать запрос

Запрос с обнаруженными персональными данными отклоняется маскированием — конечному сервису ничего не отправляется. Клиент получает HTTP 400 с перечислением сработавших типов данных в поле detail:

{"detail": "Request blocked by masking policy: email, phone"}
{"detail": "Request blocked by masking policy: email, phone"}

Этот режим подходит, когда само появление персональных данных в трафике — инцидент, а не штатная ситуация.

Маскирование

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

Рассмотрим пошагово на примере.

Шаг 1. Пользователь приложения отправляет запрос:

Составь доверенность на имя Иванов Иван Иванович, паспорт 4509 123456.
Составь доверенность на имя Иванов Иван Иванович, паспорт 4509 123456.

Шаг 2. Маскирование обнаруживает номер паспорта и заменяет его на синтетический. Пара «оригинал → замена» запоминается на время обработки этого запроса:

4509 123456  →  77 12 998844
4509 123456  →  77 12 998844

Конечному сервису уходит уже изменённый текст:

Составь доверенность на имя Иванов Иван Иванович, паспорт 77 12 998844.
Составь доверенность на имя Иванов Иван Иванович, паспорт 77 12 998844.

Шаг 3. Модель генерирует ответ, используя тот номер, который видит. Настоящего номера она никогда не видела:

ДОВЕРЕННОСТЬ

Я, Иванов Иван Иванович, паспорт 77 12 998844, доверяю ...
ДОВЕРЕННОСТЬ

Я, Иванов Иван Иванович, паспорт 77 12 998844, доверяю ...

Шаг 4. Маскирование находит синтетический номер в ответе модели и подставляет обратно оригинал — по той самой паре, которую запомнил на шаге 2. Клиенту возвращается уже восстановленный ответ:

ДОВЕРЕННОСТЬ

Я, Иванов Иван Иванович, паспорт 4509 123456, доверяю ...
ДОВЕРЕННОСТЬ

Я, Иванов Иван Иванович, паспорт 4509 123456, доверяю ...

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

Этот режим — основной. Он сохраняет полезную функциональность для конечного пользователя и одновременно обеспечивает приватность по отношению к конечному сервису.

Как включить

В разделе «Маскирование данных» личного кабинета активируется продукт, выбирается режим, отмечаются типы данных и — при необходимости — действие маскирования ограничивается выбранными API-ключами. Новые запросы начинают маскироваться сразу после активации.

Что обнаруживается

Маскирование от ProxyAPI распознаёт 10 типов данных. Для каждого типа применяется собственный детектор с набором правил — в разных случаях это может быть проверка контрольной суммы, контекстные слова рядом или структурная валидация.

Проверка контрольных сумм для ИНН, ОГРН, ОГРНИП, СНИЛС и банковских карт существенно снижает количество ложных срабатываний — случайные последовательности цифр не попадают в маскирование.

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

Пользовательский словарь

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

Каждая запись словаря — это пара «слово» + «замена»:

Правила:

• До 50 записей в словаре
• Слово — минимум 3 символа, до 200 символов
• Замена — обязательна, не пустая, до 200 символов
• Совпадение сравнивается без учёта регистра
• Совпадение происходит по границам слова: запись user сработает на user, но не на username
• Слова в словаре не повторяются, и замены тоже: две разные записи не могут использовать одну и ту же замену

В режиме маскирования словарные замены так же восстанавливаются в ответе модели.

Область применения

Маскирование работает только для текстовых чат-эндпоинтов:

• /v1/chat/completions
• /v1/responses
• /v1/messages
• /v1beta/models/<модель>:generateContent и :streamGenerateContent

Маскирование не применяется к запросам генерации изображений, генерации видео, синтеза речи, распознавания речи, эмбеддингов, моделей решений и к пакетной обработке — семантика этих эндпоинтов делает замену текста некорректной или бессмысленной.

Внутри поддерживаемых эндпоинтов маскируются:

• Содержимое пользовательских и системных сообщений
• История диалога (предыдущие пользовательские сообщения)
• Результаты вызова инструментов (tool results / function results) — включая вложенные текстовые поля

Демаскирование в ответе модели работает не только на обычном текстовом содержимом, но и на аргументах вызовов инструментов — в том числе в стриминговых ответах. Если модель передала синтетическое значение в аргумент вызова инструмента, обработчик инструмента на стороне приложения получит уже восстановленное оригинальное значение.

Масштаб применения по API-ключам

По умолчанию маскирование действует для всех API-ключей аккаунта. Его можно ограничить подмножеством ключей — это удобно, если сначала нужно включить маскирование только на тестовом ключе, а потом распространить на продакшн.

Заголовки ответа

Когда маскирование действительно сработало на запросе, в ответ добавляются два заголовка:

X-ProxyAPI-Masked: true
X-ProxyAPI-Masked-Types: email,phone
X-ProxyAPI-Masked: true
X-ProxyAPI-Masked-Types: email,phone

X-ProxyAPI-Masked-Types — это список типов данных (через запятую), которые были обнаружены и обработаны в этом запросе. Если маскирование настроено, но в запросе не было ничего подходящего, заголовки не добавляются.

По этим заголовкам на стороне приложения можно отличать запросы, прошедшие через маскирование, и при необходимости логировать факт срабатывания.

Стриминг

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

Есть небольшой побочный эффект: перед отправкой удерживается хвост длиной с самое длинное синтетическое значение в этом запросе, поэтому первые символы ответа приходят чуть позже. Буфер держится минимально достаточным, чтобы исключить утечку фрагментов синтетических значений между токенами.

Взаимодействие с логированием

Если одновременно включено логирование, в логи попадают только маскированные значения — оригинальные персональные данные не сохраняются в инфраструктуре логирования ни в какой форме.

То есть если пользователь отправил в запросе свой паспорт, а включены оба продукта:

• Конечный сервис получает синтетический паспорт
• В логах сохраняется синтетический паспорт
• Клиент получает реальный ответ с реальным паспортом (в режиме маскирования)

Это означает, что маскирование защищает данные не только от конечного сервиса, но и от попадания в логи.

Если сервис маскирования недоступен

Если по какой-то причине сервис маскирования временно недоступен, ProxyAPI отклоняет запрос с HTTP 503 — запрос не отправляется конечному сервису в обход маскирования. Это сознательное решение: безопасность по умолчанию важнее доступности. Такие ситуации редки и кратковременны.

Ограничения

• В режиме «Маскирование» синтетическая замена генерируется каждый раз заново, поэтому кэш промпта не совпадает. Чтобы кэш работал, отключите маскирование или переключитесь в режим «Блокировать запрос».
• Маскирование работает только на текстовых чат-эндпоинтах, перечисленных выше.
• При стриминге в формате OpenAI с n > 1 (несколько вариантов ответа одновременно) демаскируется только первый вариант (choices[0]).
• Маскирование контекстно: для некоторых типов («голый» номер телефона, паспорт, произвольный секрет) требуется контекстное слово в пределах примерно 100 символов. контекста нет — значение может быть пропущено.
• Детекторы работают по шаблонам и словарю. Данные, описанные произвольной формулировкой (например, номер паспорта, записанный словами или с нестандартными разделителями), могут быть не распознаны.