Справочник Firewall API

Agent Firewall настраивается двумя путями: через консоль (ваша сессия, тот же логин, что вы используете для дашборда) и через шлюз (выделенный API-ключ с областью firewall, который ваш агент предъявляет во время выполнения). Два семейства живут на разных префиксах путей, принимают разную аутентификацию и отвечают на разные вопросы — «отредактируй политику» против «вычисли этот вызов инструмента». Эта страница — карта обоих маршрут за маршрутом. О том, что политика означает — вердикты, поверхности, правила, разрешение — начните с Firewall и Правил Firewall. Эта страница — только API-поверхность.

1. Два семейства маршрутов

Консоль — настроить

/api/workspace/firewall/*. Аутентифицируется вашим session / access- токеном (UserAuth), ограничен вашим активным рабочим пространством. Авторство политик, чтение событий, регистрация MCP-серверов, разрешение подтверждений. Каждое действие защищено ролью.

Шлюз — применить

/api/v1/firewall/*. Аутентифицируется ключом с областью firewall-gateway (ключ с установленным is_firewall_gateway). Поверхность machine-to-machine, которую ваш агент или MCP-клиент вызывает во время выполнения. Обычный relay-ключ получает здесь 403.

Консольные маршруты никогда не принимают relay-ключ sk-orca-…, а маршруты шлюза никогда не принимают session-токен. Путаница между ними — самая частая причина 401/403 при первом подключении firewall. Единственный ключ sk-orca-…, которому место на вызове /v1/firewall/*, — это выпущенный с включённым is_firewall_gateway — см. Область, ключи и политики.

2. Роли с первого взгляда

Консольные маршруты разрешают вашу роль рабочего пространства и защищают соответственно. Чтения, не несущие происхождения вызова инструмента, открыты любому участнику; записи и всё, что выставляет аргументы вызова инструмента, требуют Developer+.

Роль	Может делать
Viewer / участник	Читать настройки, политики, пресеты, обнаруженные инструменты, simulate, аномалии.
Developer+	Всё вышеперечисленное, плюс каждую запись, поверхность `events`/`runs`/`trace` и dry-run `test`.
Admin+	Дополнительно — устанавливать флаг `is_firewall_gateway` на ключе и читать plaintext ключа шлюза.

Разделение намеренное: viewer может видеть, что политика существует и что бы она заблокировала, но не сырые аргументы вызова инструмента за событием. Если вы строите дашборды для не-разработчиков, маршруты с открытым чтением — безопасный набор.

3. Настройте политику из консоли

Консольные маршруты — это то, как вы создаёте и инспектируете политику. Вы настраиваете всё в UI дашборда — это те же эндпоинты, которые он вызывает.

Политики и настройки

Метод и путь	Роль	Назначение
`GET /api/workspace/firewall/settings`	Member	Observe-режим + счётчики.
`PUT /api/workspace/firewall/settings`	Developer+	Обновить настройки firewall рабочего пространства.
`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+	Удалить политику.
`POST /api/workspace/firewall/rules`	Developer+	Добавить правило.
`PUT /api/workspace/firewall/rules`	Developer+	Обновить правило.
`DELETE /api/workspace/firewall/rules/:id`	Developer+	Удалить правило.

Позиция, пресеты и песочницы

Метод и путь	Роль	Назначение
`GET /api/workspace/firewall/presets`	Member	Встроенные пресеты правил.
`GET /api/workspace/firewall/templates`	Member	Галерея шаблонов по use-case.
`POST /api/workspace/firewall/templates/apply`	Developer+	Применить шаблон → одна политика + её правила.
`POST /api/workspace/firewall/autonomy`	Developer+	Применить уровень автономии (`tight` / `balanced` / `permissive`).
`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	Лента аномалий.
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	Отложить ленту (≤ 7 дней).

MCP-серверы

Регистрируйте серверы Model Context Protocol, к которым обращаются ваши агенты, за единым аудируемым шлюзом. Учётные данные хранятся зашифрованными и маскируются при чтении.

Метод и путь	Роль	Назначение
`GET /api/workspace/firewall/mcp_servers`	Member	Список зарегистрированных серверов.
`GET /api/workspace/firewall/mcp_servers/:id`	Member	Детали сервера.
`POST /api/workspace/firewall/mcp_servers`	Developer+	Зарегистрировать сервер (`409` при дубликате `name`).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	Обновить сервер.
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	Удалить сервер.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	Достижимость + рукопожатие `tools/list`.

Сервер несёт уникальный name, endpoint, auth_mode (none / bearer / oauth / basic) и health-status (ok / degraded / down). См. Firewall MCP для полного жизненного цикла и карантина навыков.

4. Применяйте на шлюзе

Эти работают на ключе с областью firewall-gateway, а не на вашей сессии. Это то, что ваш цикл агента или MCP-клиент вызывает во время выполнения.

Метод и путь	Назначение
`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/mcp_servers`	Перечислить зарегистрированные серверы рабочего пространства.
`GET /api/v1/firewall/approvals/:id`	Опросить состояние подтверждения удержанного вызова.
`POST /api/v1/firewall/approvals/:id/callback`	Подписанный HMAC колбэк подтверждения.

Один конкретный пример: вычислить вызов инструмента

Перед тем как ваш агент диспетчеризует инструмент, попросите шлюз о вердикте. Передайте ключ с областью firewall-gateway — не ваш relay-ключ sk-orca-…:

curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'

Ответ несёт вердикт — allow, audit, deny, sanitize или pending_approval. На deny вы пропускаете вызов и показываете причину модели; на sanitize вы пересылаете очищенные аргументы, которые шлюз возвращает (sanitize редактирует только аргументы вызова инструмента — никогда содержимое, которое инструмент возвращает); на pending_approval вы входите в цикл подтверждения ниже.

Шлюз вычисляет вызовы, которые его пересекают — хук evaluate, MCP-шлюз и путь ретрансляции. Инструмент, который ваш агент запускает целиком in-process, никогда не касаясь OrcaRouter, находится вне его поля зрения. Маршрутизируйте вызовы, которые важны (инструменты, опосредованные моделью, диспетч MCP, сетевой egress), через шлюз, и они управляемы.

5. Рукопожатие подтверждения (HITL)

Вердикт pending_approval удерживает вызов для человека. HTTP-ошибка во время удержания — firewall_approval_pending. Очистка её — трёхшаговый цикл, разделённый между обоими семействами маршрутов:

Ревьюер разрешает удержание

Из консоли (PATCH /api/workspace/firewall/approvals/:id, Developer+) или ваша собственная система постит подписанный HMAC колбэк на POST /api/v1/firewall/approvals/:id/callback. Колбэк проверяет HMAC inline — никакая другая аутентификация не принимается.

Ваш агент опрашивает подтверждение

GET /api/v1/firewall/approvals/:id с ключом шлюза, пока состояние не перевернётся в approved или rejected.

Переотправьте с одноразовым токеном

После одобрения переотправьте исходный вызов с заголовком X-OrcaRouter-Firewall-Approval и id подтверждения. Шлюз распознаёт его и пропускает этот один вызов. Заголовок одноразовый.

Решения — first-writer-wins и идемпотентны: повторное разрешение того же удержания — no-op. См. Firewall — Подтверждение человеком для сквозного потока и Почему это было заблокировано? для чтения вердикта.

6. Как выглядит блокировка

Исход	HTTP	Код
Отклонённый вызов инструмента (поверхность inbound)	`400`	`firewall_blocked`
Отклонено через MCP-шлюз	ошибка инструмента	`firewall deny: <reason>`
Удержано для подтверждения	`400`	`firewall_approval_pending`

firewall_blocked помечен skip-retry — повторный прогон идентичного вызова просто снова заблокируется, так что повторяющий клиент отступает вместо того, чтобы долбить. Полный список кодов живёт в Кодах ошибок.

7. Сопутствующие справочники

Guardrail API

Собрат на плоскости контента — маршруты /api/guardrail/* для текстовой плоскости.

Глоссарий вердиктов

Каждый вердикт и что он делает с вызовом.

Глобы и JSONPath

Грамматика сопоставления за tool_name_glob и args_match.

Compliance API

Паки, подписанные отчёты, резидентность и стирание.

8. FAQ

Почему мой relay-ключ получает 403 на /api/v1/firewall/evaluate?

Маршруты шлюза требуют ключ с областью firewall-gateway — выпущенный с установленным is_firewall_gateway (действие Admin+). Обычный relay-ключ, даже валидный, получает 403. Выпустите выделенный ключ шлюза для рантайма вашего агента.

Может ли viewer читать события firewall?

Нет. Маршруты events, events/aggregate и trace — Developer+, потому что записи несут происхождение аргументов вызова инструмента. Viewer’ы могут читать настройки, политики, пресеты, обнаруженные инструменты, simulate и ленту аномалий.

Где мне разрешать удержанное подтверждение — в консоли или на шлюзе?

Где угодно. Человек разрешает его в консоли через PATCH /api/workspace/firewall/approvals/:id (Developer+), или ваша собственная система постит подписанное HMAC решение на POST /api/v1/firewall/approvals/:id/callback. Агент опрашивает GET /api/v1/firewall/approvals/:id независимо от того, какой путь его разрешил.

Очищает ли sanitize то, что возвращает инструмент?

Нет. Вердикт sanitize редактирует только аргументы вызова инструмента — никогда содержимое, которое инструмент возвращает. На поверхности inbound, где ещё нет аргументов времени вызова, sanitize эскалирует до блокировки. См. Правила Firewall.

О том, как эти контроли составляются с guardrails и остальной частью шлюза, см. Защита ИИ-агентов и Guardrails против Firewall.

​1. Два семейства маршрутов

Консоль — настроить

Шлюз — применить

​2. Роли с первого взгляда

​3. Настройте политику из консоли

​Политики и настройки

​Позиция, пресеты и песочницы

​Наблюдаемость

​MCP-серверы

​4. Применяйте на шлюзе

​Один конкретный пример: вычислить вызов инструмента

​5. Рукопожатие подтверждения (HITL)

​6. Как выглядит блокировка

​7. Сопутствующие справочники

Guardrail API

Глоссарий вердиктов

Глобы и JSONPath

Compliance API

​8. FAQ

1. Два семейства маршрутов

2. Роли с первого взгляда

3. Настройте политику из консоли

Политики и настройки

Позиция, пресеты и песочницы

Наблюдаемость

MCP-серверы

4. Применяйте на шлюзе

Один конкретный пример: вычислить вызов инструмента

5. Рукопожатие подтверждения (HITL)

6. Как выглядит блокировка

7. Сопутствующие справочники

8. FAQ