API gateway: серверная проверка tool call до выполнения

Считайте tool call недоверенным входом

Даже если модель вернула объект с корректным именем, приложение должно воспринимать его как внешний ввод. Не запускайте действие прямо из ответа и не передавайте объект в shell, SQL, CRM или платежную систему без собственного слоя проверки. Сохраните минимальную запись: локальный request ID, tenant, имя предложенного инструмента и результат policy. Полный prompt, скрытое рассуждение, заголовки и ключи не нужны для аудита. Такой подход полезен и без внешнего gateway: он делает видимой разницу между текстом модели и полномочием сервера. Сначала определите, какие операции вообще допустимы в продукте, кто может их запускать и какие данные разрешено передавать каждому внутреннему сервису.

Соберите allowlist по tenant и роли

Allowlist — это не список красивых названий в prompt, а серверная таблица разрешений. Для каждого tenant, роли и окружения храните допустимые tool name, версию схемы, максимальный размер аргументов и класс риска. Например, чтение статуса заказа может быть автоматическим после авторизации, а отправка письма, изменение карточки или публикация требуют дополнительного подтверждения. Не делайте универсальный инструмент вроде execute_anything: его невозможно разумно проверить и отозвать. Если модели предложен неразрешённый инструмент, верните контролируемую ошибку и не пытайтесь угадать похожее имя. Версию allowlist включайте в журнал, чтобы после обновления можно было объяснить решение и быстро откатить policy.

Проверяйте JSON-схему до бизнес-операции

Проверка типа должна быть строгой и понятной: неизвестные поля отклоняются, обязательные присутствуют, строки имеют ожидаемую длину, идентификаторы принадлежат текущему tenant. Не используйте аргумент URL как свободный адрес для серверного fetch, не позволяйте модели передавать произвольные пути файлов и не собирайте SQL-конструкции из строк. После JSON-схемы нужна предметная проверка: пользователь может иметь форматно корректный orderId, но не иметь права смотреть или менять этот заказ. Если ответ не проходит контроль, оставьте действие неисполненным и покажите пользователю безопасное пояснение. Это лучше, чем исправлять аргумент «наиболее вероятным» значением и создавать скрытое действие.

Разделите чтение, подготовку и побочный эффект

Удобная policy различает три этапа. На первом можно получить безопасные данные, на втором сформировать черновик действия, на третьем выполнить изменение только после авторизации и явного подтверждения. Для письма это означает: модель может предложить тему и текст, интерфейс показывает адресата и итог, а сервер отправляет сообщение лишь после клика уполномоченного пользователя. Для CRM или публикации применяйте тот же принцип. Не берите наличие tool call за согласие человека. Перед выполнением снова проверьте актуальность сессии, объект и tenant: между предложением и кликом данные могли измениться. Такая пауза также позволяет применить лимиты и не допустить серию массовых действий из одного ответа.

Создайте журнал решений без секретов

Аудит нужен не для накопления содержания диалогов, а для восстановления решения policy. Записывайте request ID, идентификатор проекта, имя инструмента, версию схемы, allowlist decision, пользователя-подтверждающего и короткий код результата. Аргументы лучше минимизировать или хешировать, если они не требуются для расследования. Не кладите в лог API key, cookie, токены, полный prompt, вложения и персональные данные. Определите срок хранения и доступ к журналу отдельно от обычных логов. При отказе сохраняйте причину класса, например unknown_tool, schema_error, tenant_denied или confirmation_required. Это помогает команде улучшать схему и policy, не превращая observability в новый источник утечки.

Тестируйте обходные и аварийные сценарии

До запуска проведите отрицательные тесты: неизвестное имя инструмента, лишнее поле, другой tenant, просроченная сессия, двойной клик, отмена подтверждения и timeout между подготовкой и выполнением. Убедитесь, что действие не выполняется дважды и что повтор использует локальный idempotency key. Добавьте лимит на число подготовок и действий за период, а для критичных операций — ручной review. При изменении модели, SDK или схемы запускайте те же тесты в CI на обезличенных fixtures. Не обещайте, что policy делает внешнюю модель безопасной сама по себе: она снижает риск в вашем приложении при корректной реализации, а актуальные требования и права доступа должны проверяться отдельно.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. В нём нет реального ключа: это логика приложения, а не текущая спецификация внешнего API. До интеграции подтвердите маршрут, схему и ограничения в документации.

const allowedTools = new Map([
  ['viewer', new Set(['get_order_status'])],
  ['editor', new Set(['get_order_status', 'prepare_order_note'])],
]);

export function validateToolCall(role, call) {
  if (!call || typeof call.name !== 'string') return { ok: false, reason: 'invalid_call' };
  if (!allowedTools.get(role)?.has(call.name)) return { ok: false, reason: 'tool_not_allowed' };
  if (!call.arguments || typeof call.arguments !== 'object' || Array.isArray(call.arguments)) {
    return { ok: false, reason: 'invalid_arguments' };
  }
  return { ok: true, requiresConfirmation: call.name !== 'get_order_status' };
}
// Authorize the tenant and confirm side effects separately on the server.

Проверьте синтаксис через node --check, добавьте аутентификацию, лимиты и отрицательные тесты. Не помещайте тело запроса, ответ целиком или заголовки авторизации в журнал.

Граница ответственности и данных

Это инженерное руководство для вашего приложения, а не описание гарантированной функции внешнего поставщика. Не помещайте в браузер, тикет, статью или журнал API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt или персональные данные. Для регулируемых данных, договорных условий и прав на контент проверяйте применимые требования с ответственным специалистом.

Материалы для сверки

Внешние источники объясняют общие инженерные принципы. Они не подтверждают функции, тарифы, доступность или SLA RussiaAPI и сторонних моделей.

• OWASP: риски для LLM-приложений
• OWASP: проверка авторизации