Правила
Язык сопоставления — глобы инструментов, клаузы аргументов, списки
egress, очистители и последовательности.
MCP-серверы
Регистрируйте и управляйте серверами Model Context Protocol за единым
аудируемым шлюзом.
Навыки
Сканируйте и оценивайте по риску возможности, которые ваши агенты
устанавливают, прежде чем они смогут запуститься.
1. Что такое Firewall
ИИ-агент не просто генерирует текст — он действует. Он вызываетshell.exec, запрашивает db.query, извлекает URL, загружает
community-навык или маршрутизирует вызов инструмента через сторонний
MCP-сервер. Каждое из этих действий имеет последствия в реальном мире, и
guardrails уровня промпта их не видят.
Firewall — это именованная политика в рамках рабочего
пространства, которую шлюз вычисляет на каждом вызове инструмента. Вы
сохраняете политику один раз, привязываете к ней API-ключ (или назначаете
её default’ом рабочего пространства), и с этого момента каждый вызов
инструмента, который выпускает этот ключ, проверяется по политике — до
того, как он достигнет инструмента.
Каждая политика — это упорядоченный список правил. Правило решает
одну вещь — к каким вызовам инструментов оно применяется (глоб имени
инструмента, опционально ограниченный навыком и поверхностью применения)
и что с ними делать (вердикт: allow, audit, deny, sanitize, hold
for approval или cap cost). Движок проходит правила в порядке приоритета,
побеждает первое совпадение, и откатывается к default-вердикту
политики, если ничего не совпало.
Редактирование политики вступает в силу на каждом привязанном к ней
ключе уже на следующем вызове. Никакого передеплоя. Никаких изменений
кода агента. Политика применяется в шлюзе — ваш агент продолжает выпускать
вызовы инструментов ровно так же, как раньше.
Детектирование происходит в шлюзе, при первом использовании. Firewall
сидит на пути ретрансляции LLM, а не внутри пакетного менеджера или
файловой системы вашего агента. Инструмент, MCP-сервер или навык, который
агент устанавливает сам, ловится в тот момент, когда его вызов впервые
пересекает шлюз, — а не во время установки. Это сделано намеренно: это
единственная узловая точка, которая видит каждого провайдера, каждого
агента и каждый вызов инструмента независимо от того, как возможность туда
попала.
2. Четыре поверхности применения
Каждый вызов инструмента вычисляется ровно по одной поверхности — точке в жизненном цикле запроса, где firewall его видит:| Поверхность | Что она видит |
|---|---|
inbound | Инструменты, которые агент рекламирует модели в запросе (определения инструментов). Позволяет заблокировать опасный инструмент до того, как модель сможет его выбрать. |
response | tool_calls, которые модель выдаёт в своём ответе. |
mcp | tools/call, диспетчеризованный через MCP-шлюз Firewall или вычисленный через SDK-хук. |
egress | Исходящее сетевое назначение (host / IP / CIDR), сообщённое инструментом, — поверхность SSRF и эксфильтрации данных. |
3. Основные концепции
| Концепция | Определение |
|---|---|
| Политика | Именованный набор правил в рамках рабочего пространства. Имеет enabled, is_default, default_verdict и флаг shadow_mode. |
| Правило | Одна проверка внутри политики: приоритет, сопоставление инструмента/навыка, опциональная поверхность, опциональный предикат аргумента и вердикт. См. Правила. |
| Вердикт | Действие, которое производит правило (или default) — см. §4. |
| Default-вердикт | Применяется, когда ни одно правило не совпало. Одно из allow, audit (по умолчанию) или deny. |
| Shadow-режим | Политика вычисляется и логируется, но никогда не блокирует — каждый применяющий вердикт понижается до audit, а причина получает префикс [shadow] would …. Ваш переключатель безопасного развёртывания. |
| Observe-режим | Настройка уровня рабочего пространства. Когда запрос разрешается в отсутствие политики и observe-режим включён, вызов разрешается, но логируется как пробел в покрытии — именно это наполняет представление Discovered tools. |
Область видимости и разрешение
Политики разрешаются ровно как Guardrails и API-ключи — общие в рамках рабочего пространства, когда оно активно. Для любого вызова инструмента шлюз разрешает политику в этом порядке:- Привязка ключа — если у вызывающего ключа есть
firewall_policy_id, применяется эта политика (когда она существует и включена). - Default рабочего пространства — иначе применяется включённая
политика с
is_defaultрабочего пространства. - Ни то, ни другое — нет применения. При включённом observe-режиме вызов разрешается и логируется как пробел; при выключенном вызов разрешается молча (побайтно идентично рабочему пространству, которое никогда не включало эту функцию).
Fail-open на неизвестном, fail-closed на неоднозначном. Если
разрешение политики упирается в переходную ошибку, шлюз деградирует до
observe/allow, а не кладёт трафик. Но там, где неприменение свело бы на
нет правило — egress-отчёт без пригодного назначения, недостижимое
хранилище подтверждений, навык, чьё владение не удаётся разрешить, —
движок fail closed (deny или hold). Доступность сохраняется;
безопасность не пропускается молча в случаях, которые важны.
4. Вердикты
Правило (или default-вердикт) производит один из:| Вердикт | Что делает |
|---|---|
allow | Пропустить вызов. Логируется. |
audit | Разрешить, но записать для разбора. Дефолтный default_verdict — наблюдать всё, не блокировать ничего, пока вы не готовы. |
deny | Заблокировать вызов. Агент видит ошибку инструмента (или HTTP 400 на поверхности inbound). |
sanitize | Отредактировать совпавшие подстроки из аргументов инструмента (секреты, PII) и переслать очищенный вызов. См. очистители. На поверхности inbound, где ещё нет аргументов времени вызова, sanitize эскалирует до блокировки. |
pending_approval | Удержать вызов для человека. Агент получает ответ «held»; ревьюер одобряет или отклоняет вне основного канала; агент повторно отправляет с одноразовым токеном подтверждения. См. §7. |
cap_cost | Отклонить, как только накопленные траты прогона агента превысят пороговый лимит правила в центах. Предохранитель для зацикленных прогонов. |
deny / sanitize / pending_approval все понижаются до
audit, так что вы можете измерить влияние политики до того, как она
изменит трафик.
5. Как вычисляется вызов инструмента
- Вызов инструмента достигает шлюза (рекламируется на inbound, выдаётся в ответе, диспетчеризуется через MCP-шлюз или сообщается как egress).
- Движок разрешает активную политику (§3).
- Он проходит правила политики в порядке приоритета (сначала меньший приоритет; ничьи разрешаются по id правила). Правило совпадает, когда его поверхность, глоб имени инструмента, опциональный глоб имени навыка, опциональные клаузы аргументов и опциональная область egress все совпадают.
- Побеждает первое совпадение → применяется вердикт правила. Если ни
одно правило не совпало →
default_verdictполитики. - Если вызов принадлежит управляемому навыку,
режим применения навыка накладывается сверху — навык в режиме
blockпринудительно даёт deny; навык в режимеquarantineэскалирует всё, что меньше deny, доpending_approval. - Решение логируется как событие firewall (если это не dry run), коррелированное с прогоном и сессией агента.
6. Как выглядит блокировка
Отклонённый вызов на поверхности inbound возвращает HTTP 400 с телом ошибки в форме OpenAI, кодом ошибкиfirewall_blocked и сообщением,
называющим инструмент и причину — например, tool "shell.exec" blocked by firewall: destructive shell command. Ошибка несёт структурированные
metadata (код причины, факторы риска, оценку) и помечается
skip-retry (повторный прогон того же вызова просто снова заблокируется).
Вызов, диспетчеризованный через MCP-шлюз, блокируется как ошибка
инструмента (firewall deny: <reason>), а не как сбой транспорта, так
что модель видит отказ и может среагировать — выбрать другой инструмент,
спросить пользователя или остановиться — вместо падения.
Удержанный вызов (pending_approval) возвращает HTTP 400 с кодом
firewall_approval_pending и id подтверждения, который клиент опрашивает.
7. Подтверждение человеком (HITL)
Вердиктpending_approval превращает вызов инструмента в разбор вне
основного канала:
- Движок ставит запись подтверждения в очередь и возвращает ответ «held», несущий её id; вызов не достигает инструмента.
- Ревьюер разрешает его — из консоли (Developer+) или через подписанный HMAC вебхук-колбэк к вашей собственной системе подтверждений.
- Ваш агент (или MCP SDK) опрашивает id подтверждения; после
одобрения он повторно отправляет исходный вызов с одноразовым
заголовком
X-OrcaRouter-Firewall-Approval, и шлюз пропускает его этот один раз.
rule_changed, чтобы ревьюеры знали, что контекст сместился.
8. Уровни автономии — один переключатель для всей вашей политики
Тонкая настройка политик правило за правилом — точный путь; уровни автономии — быстрый. Один элемент управления атомарно заменяет позицию Firewall и Guardrails вашего рабочего пространства в одной транзакции, с отменой в один клик:| Уровень | Позиция |
|---|---|
tight | Блокировать деструктивный shell, секреты в аргументах и SSRF-egress (default deny); guardrails PII Shield + Secrets Blocker включены; observe-режим выключен. |
balanced | Аудировать деструктивный shell, флагировать PII; observe-режим выключен. Рекомендуемая стартовая позиция. |
permissive | Нет применяющей политики, нет guardrails; observe-режим включён, так что вы всё равно видите всё. |
9. Детектирование аномалий
Помимо статических правил, Firewall обучается нормальной форме использования инструментов каждого рабочего пространства и флагирует отклонения в читаемой ленте:- Всплески частоты / стоимости — активность по каждому инструменту
оценивается относительно обученного базиса по часу недели
(14-дневное скользящее среднее), так что «100 вызовов
db.queryв 3 часа ночи в воскресенье» выделяется, даже если каждый вызов сам по себе разрешён. retry_loop— агент, долбящий один и тот же сбойный инструмент.novel_path— переход от инструмента к инструменту, которого это рабочее пространство никогда раньше не делало.
10. Наблюдаемость
Firewall оставляет след, по которому можно действовать, весь в рамках рабочего пространства:| Поверхность | Что она вам даёт |
|---|---|
| Events | Каждое вычисление, фильтруемое по вердикту, поверхности, инструменту, прогону и сессии. Сырая запись, стоящая за всем остальным. |
| Runs & sessions | События, свёрнутые по прогону или диалогу агента — разбивка по вердиктам, различимые инструменты и модели, первое/последнее появление. Представление «что этот агент на самом деле сделал». |
| Discovered tools | Каждый инструмент, который видело рабочее пространство, помеченный covered (применяется правило) или gap (ничего не применяется). Управляет написанием политики из реального трафика. |
| Simulate | Предпросмотр того, что изменил бы уровень автономии, до его применения. |
| Test | Dry-run политики по образцу вызова инструмента с выводом вердикта, совпавшего правила и причины — ничего не сохраняется, ничего не диспетчеризуется. |
| Audit | Каждое изменение политики, правила и настроек пишет строку аудита (рабочее пространство + центральная) после коммита изменения. Секреты и блобы правил никогда не логируются. |
11. Отношение к остальной части шлюза
| Поверхность | Как сочетается с Firewall? |
|---|---|
| Guardrails | Взаимодополняющие плоскости. Guardrails проверяют текст промпта/ответа; Firewall управляет действиями инструментов. Оба могут применяться к одному запросу. Уровни автономии задают оба сразу. |
| Routing | Независимы. Маршрутизация выбирает модель/канал; firewall судит вызовы инструментов независимо от того, какая модель их обслужила. |
| API-ключи | Ключ привязывается к политике через firewall_policy_id; привязка живёт на ключе в шлюзе. Отсутствие привязки откатывается к default’у рабочего пространства. |
| MCP-шлюз | Firewall и есть MCP-шлюз — каждый зарегистрированный вами сервер диспетчеризует свой tools/call через движок. |
| Навыки | Режим применения управляемого навыка накладывается поверх вердикта правила, так что карантинный навык удерживается, даже если ни одно правило не называет его инструменты. |
12. Подключение агента к шлюзу Firewall
Есть два способа, которыми вызов инструмента достигает движка:- MCP-шлюз — направьте ваш MCP-клиент (Claude Desktop, Cursor,
агентский фреймворк) на
https://api.orcarouter.ai/api/v1/firewall/mcp. Шлюз выставляет инструменты каждого достижимого зарегистрированного сервера в пространстве имён<server>.<tool>и вычисляет каждыйtools/callinline. См. MCP-серверы. - Хук evaluate — вызывайте
POST /api/v1/firewall/evaluateиз собственного цикла агента перед диспетчем вызова инструмента и действуйте по вердикту.
403 на этих маршрутах.
13. API-справочник
Все консольные маршруты ограничены рабочим пространством через контекст рабочего пространства и применяют RBAC последовательно: чтения и песочницы test/simulate открыты каждому участнику; записи требуют Developer+.Политики и настройки
| Метод и путь | Роль | Назначение |
|---|---|---|
GET /api/workspace/firewall/settings | Member | Прочитать настройки firewall рабочего пространства (observe-режим, дефолты). |
PUT /api/workspace/firewall/settings | Developer+ | Обновить настройки. |
GET /api/workspace/firewall/policies | Member | Список политик (со счётчиками правил + привязанных ключей). |
GET /api/workspace/firewall/policies/:id | Member | Детали одной политики. |
POST /api/workspace/firewall/policies | Developer+ | Создать политику. |
PUT /api/workspace/firewall/policies | Developer+ | Обновить политику. |
DELETE /api/workspace/firewall/policies/:id | Developer+ | Удалить политику (409, если ключи всё ещё привязаны). |
Позиция, пресеты и песочницы
| Метод и путь | Роль | Назначение |
|---|---|---|
GET /api/workspace/firewall/presets | Member | Встроенные пресеты правил. |
POST /api/workspace/firewall/autonomy | Developer+ | Применить уровень автономии. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | Отменить изменение автономии. |
GET /api/workspace/firewall/simulate | Member | Предпросмотр уровня автономии (?level=). |
POST /api/workspace/firewall/test | Developer+ | Dry-run политики по образцу вызова инструмента. |
Наблюдаемость
| Метод и путь | Роль | Назначение |
|---|---|---|
GET /api/workspace/firewall/discovered-tools | Member | Увиденные инструменты, помеченные covered / gap. |
GET /api/workspace/firewall/events | Developer+ | Список событий firewall (фильтруемый). |
GET /api/workspace/firewall/events/by-request/:request_id | Developer+ | События для одного запроса. |
GET /api/workspace/firewall/events/aggregate | Developer+ | Свёртка по прогонам / сессиям. |
GET /api/workspace/firewall/trace/by-run | Developer+ | Узлы трассировки для прогона (?run_id=). |
GET /api/workspace/firewall/anomalies | Member | Лента аномалий (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | Отложить ленту аномалий. |
Шлюз (machine-to-machine)
Эти работают на токене с областью firewall-gateway, а не на консольной сессии:| Метод и путь | Назначение |
|---|---|
POST /api/v1/firewall/evaluate | Pre-dispatch вердикт для одного вызова инструмента. |
POST /api/v1/firewall/evaluate_plan | Pre-execution проверка многошагового плана. |
ANY /api/v1/firewall/mcp | Единый эндпоинт MCP-шлюза. |
GET /api/v1/firewall/approvals/:id | Опросить состояние подтверждения удержанного вызова. |
POST /api/v1/firewall/approvals/:id/callback | Подписанный HMAC колбэк подтверждения. |
14. FAQ
Что если на вызове инструмента не разрешается ни одна политика?
Что если на вызове инструмента не разрешается ни одна политика?
При выключенном observe-режиме поведение побайтно идентично
рабочему пространству, которое никогда не включало эту функцию —
ничего не блокируется и не логируется. При включённом
observe-режиме вызов разрешается, но записывается как пробел в
покрытии, так что он появляется в Discovered tools.
Как безопасно развернуть политику?
Как безопасно развернуть политику?
Включите shadow-режим. Политика вычисляется и логируется ровно
так, как делала бы в production, но каждый применяющий вердикт
понижается до
audit, а причина получает префикс [shadow] would ….
Наблюдайте представления events и runs, убедитесь, что она срабатывает
на том, на чём вы ожидаете, и ни на чём, на чём не ожидаете, затем
выключите shadow-режим, чтобы начать применять.Стоит ли заблокированный вызов инструмента квоты?
Стоит ли заблокированный вызов инструмента квоты?
Блокировка на inbound срабатывает до вызова вышестоящей модели, так
что она не стоит токенов модели. Вердикты audit / allow не меняют
тарификацию. Правило
cap_cost само по себе является контролем
биллинга — оно отклоняет, как только траты прогона пересекают ваш
лимит в центах.Firewall или Guardrails — что использовать?
Firewall или Guardrails — что использовать?
Оба, для разных слоёв. Guardrails проверяют текст в промптах и
ответах (PII, секреты, jailbreak). Firewall управляет действиями,
которые совершает агент (какие инструменты, какие MCP-серверы, какие
хосты). Запрос может пройти через оба. Уровень автономии
tight
настраивает их вместе.Гарантировано ли применение для каждого инструмента, который запускает агент?
Гарантировано ли применение для каждого инструмента, который запускает агент?
Firewall применяется к вызовам инструментов, которые пересекают шлюз —
путь ретрансляции, MCP-шлюз и хук evaluate. Инструмент, который ваш
агент выполняет целиком внутри собственного процесса, никогда не
касаясь шлюза, находится вне поля зрения firewall. Цель дизайна —
сделать шлюз единственным аудируемым путём для вызовов, которые важны
(инструменты, опосредованные моделью, диспетч MCP, сетевой egress);
маршрутизируйте их через него, и они управляемы.
Смотрите также
Хотите глубже разобраться в безопасности агентов? Руководства «Защитите агентов — Zero Trust» встраивают эту функцию в рабочий процесс нулевого доверия.Защитите агентов (Zero Trust)
Плейбук firewall для агентов с нулевым доверием — allow-листы инструментов, проверки аргументов и контроль исходящего трафика.
Базовый уровень Secure Agents
Один переключатель, который одновременно задаёт позицию вашего Firewall и Guardrails.