Файрвол агента

Справочник синтаксиса глоб-шаблонов

Грамматика глоба имени инструмента, которую правило firewall использует для сопоставления вызовов инструментов на шлюзе OrcaRouter: намеренно маленький, чувствительный к регистру набор шаблонов — точные, префиксные, суффиксные и инфиксные wildcard’ы — линейного времени и безопасный на горячем пути.

Каждое правило firewall начинается с ответа на вопрос к каким вызовам инструментов я применяюсь? Первая половина этого ответа — глоб имени инструмента — поле tool_name_glob на правиле. Это намеренно маленькая, чувствительная к регистру грамматика (без regex, без backtracking), так что правило читается так же, как вы набрали бы имя инструмента из вкладки Discovered tools, а сопоставление остаётся линейного времени на горячем пути ретрансляции. Эта страница — сфокусированный справочник грамматики для этого одного поля. О том, где глоб сидит внутри полного правила — поверхность, клаузы аргументов, egress-списки, вердикт — см. Схему правил и глубокий справочник движка в Правилах Firewall.

1. Почему `глоб имени инструмента` вместо regex

Инструменты традиционно именуются server.tool или category.action (shell.exec, db.query, community.http_fetch). Глоб позволяет одному правилу поймать целое семейство — shell.* для каждого shell-глагола, *.delete для глагола по серверам — без подножек regex на пути, который выполняется на каждом вызове инструмента.

Грамматика намеренно крошечная. Сопоставление чувствительно к регистру — имена MCP-инструментов традиционно lowercase-с-точками, так что сворачивание регистра удивило бы автора, который копирует имя прямо из представления Discovered tools. Нет катастрофического backtracking, потому что за ним нет regex-движка; каждый шаблон ниже — это горстка строковых операций.

2. Пять форм шаблона

глоб имени инструмента — это ровно одна из этих форм. Всё, что не вписывается в wildcard-формы, трактуется как литеральное, точное совпадение.

Шаблон	Форма	Совпадает
`""` или `*`	любой	Каждый вызов инструмента.
`foo.*`	префикс	`foo.bar`, `foo.exec` — не голый `foo`.
`*.exec`	суффикс	`shell.exec`, `db.exec`, и голый `exec`.
`.shell.`	инфикс	`local.shell.exec`, `byo.shell.run`.
`shell.exec`	точный	Только литеральная строка `shell.exec`.

Прочитайте следующие разделы про один край каждой формы, на котором люди спотыкаются.

3. Префикс — `foo.*`

Совпадает с любым инструментом, чьё имя начинается с foo. и имеет хотя бы один ещё символ после точки.

Совпадает

shell.exec, shell.run, shell.rm для шаблона shell.*

Не совпадает

голый shell (префикс требует завершающую точку и что-то после неё)

Используйте префиксный глоб, чтобы управлять целым сервером или категорией сразу — один deny shell.* покрывает каждый shell-глагол, который сервер может добавить позже.

4. Суффикс — `*.exec`

Совпадает с любым инструментом, чьё имя заканчивается на .exec, привязанным к точке — и также совпадает с голым, без пространства имён глаголом exec самим по себе.

Совпадение с голым глаголом намеренно. Provider-native вызовы функций и MCP-серверы, которые не используют пространства имён, выставляют инструмент под его голым глаголом (просто exec, а не shell.exec). Правило *.exec покрывает обе формы, так что инструмент без пространства имён не пропускается молча.

Суффикс остаётся привязанным — он не совпадёт с частью слова:

Шаблон	`shell.exec`	голый `exec`	`shell.execute`
`*.exec`	совпадает	совпадает	нет совпадения

*.execute понадобился бы для shell.execute; суффикс срабатывает только на границе точки или в начале строки, никогда в середине слова.

5. Инфикс — `.shell.`

Совпадает с любым именем инструмента, которое содержит .shell. как инфикс, с хотя бы одним символом с каждой стороны. Так одно правило покрывает глагол, где бы BYO-MCP сервер ни поместил его в пространство имён.

{
  "label": "gate every shell tool, any server",
  "tool_name_glob": "*.shell.*",
  "verdict": "deny"
}

Это правило совпадает с local.shell.exec, byo.shell.run и любой другой формой <server>.shell.<verb>. Оно не совпадает с голым shell или голым .shell. без ничего вокруг — требование символа с каждой стороны держит инфикс честным.

Инфикс-форма — это только симметричная форма *.X.*. Шаблон со звездой в середине — foo.*.bar — не инфикс-глоб; он проваливается в точное строковое совпадение (он совпадает только с инструментом, буквально названным foo.*.bar, которого не будет). Чтобы совпасть с «начинается с foo., заканчивается на .bar», вам нужны два правила или клауза аргумента, а не один глоб.

6. Точный — `shell.exec`

Всё, что не является одной из wildcard-форм выше, — это литеральное строковое совпадение. shell.exec совпадает с shell.exec и ничем больше. Это правильный выбор, когда вы хотите назвать один конкретный инструмент — сочетайте его с клаузой аргумента, чтобы сузить дальше («блокировать shell.exec только когда команда — rm -rf»).

7. Один конкретный пример

Допустим, вы хотите отклонить каждый деструктивный shell-глагол независимо от того, как MCP-сервер помещает его в пространство имён, при этом позволяя всему остальному аудироваться. В консольном редакторе правил (записи требуют Developer+) половина-сопоставление правила — это единственный инфикс-глоб:

{
  "label": "deny shell across servers",
  "stage": "response",
  "tool_name_glob": "*.shell.*",
  "verdict": "deny"
}

Привяжите ключ к политике (firewall_policy_id на ключе), и правило теперь ловит local.shell.exec, byo.shell.run и acme.shell.rm — три сервера, один глоб. Хотите подтвердить, что оно срабатывает на том, что вы ожидаете, до того как полагаться на него? Используйте Тестирование правил — оно возвращает вердикт, совпавшее правило и причину, ничего не диспетчеризуя.

Глоб сужает, какой инструмент. Чтобы сузить с какими аргументами, объедините по AND клаузу аргумента с тем же правилом; чтобы управлять инструментом только когда им владеет конкретный навык, добавьте глоб имени навыка (та же грамматика, сопоставляется с владеющим навыком). Оба покрыты в Правилах Firewall.

8. Быстрый справочник

Покрыт ли голый глагол суффиксным глобом?

Да. *.exec совпадает с shell.exec, db.exec и голым, без пространства имён exec. Префиксные глобы (foo.*) не совпадают с голым пространством имён foo — только с именами, у которых есть что-то после точки.

Работает ли средняя звезда в foo.*.bar?

Нет. Единственная форма wildcard-в-середине, которую понимает движок, — это симметричный инфикс *.X.*. foo.*.bar проваливается в точное литеральное совпадение. Используйте два правила или клаузу аргумента вместо этого.

Чувствительно ли сопоставление к регистру?

Да. Shell.Exec и shell.exec — разные инструменты. Копируйте имена дословно из вкладки Discovered tools.

Что если глоб некорректен?

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

Связанное

Allow-листинг инструментов

Используйте глобы, чтобы разрешить известный набор и отклонить остальное.

Проверять аргументы

Объедините по AND JSONPath-клаузу аргумента с глобом.

Схема правил

Каждое поле правила, в одном месте.

О полном языке сопоставления — вердикты, поверхности, egress-списки и последовательности — см. Правила Firewall. Новичок в плоскости? Начните с обзора Firewall.

Блокировать инструменты Проверять аргументы

​1. Почему глоб имени инструмента вместо regex

​2. Пять форм шаблона

​3. Префикс — foo.*