Глоссарий вердиктов, действий и маскирования

Когда вы читаете событие firewall или совпадение guardrail, строка говорит вам, что шлюз решил — deny, sanitize, [EMAIL]. Эта страница — таблица поиска для этих слов: что каждое означает, что оно делает с вызовом и куда идти за полной механикой. Держите её открытой, пока создаёте правила или разбираете ленту событий. Две плоскости управления производят два словаря. Firewall управляет действиями инструментов и выдаёт вердикт. Guardrails проверяют текст промпта и ответа и выдают действие плюс, на маске, типизированный тег маскирования. Они никогда не делят слово — guardrail никогда не говорит deny, firewall никогда не говорит mask.

Это справочный индекс, а не how-to. Об use-case за каждым контролем см. Guardrails против Firewall; об HTTP-телах см. Коды ошибок безопасности.

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

Правило firewall (или default_verdict политики) разрешает каждый вызов инструмента ровно в один из этих шести вердиктов. Движок проходит правила в порядке приоритета, побеждает первое совпадение, и откатывается к default’у, если ничего не совпало.

allow — пропустить вызов

Вызов проходит к инструменту. Всё равно логируется как событие firewall, так что появляется в Runs и ленте событий. Это то, что вам нужно для инструментов, которым агенту явно доверено пользоваться.

audit — разрешить, но записать для разбора

Трафик идентичен allow, но помечен как нечто, что вы хотели наблюдать. Это рекомендуемый default_verdict: наблюдать всё, не блокировать ничего, пока ваши правила не настроены. Уровень автономии balanced поставляет guardrail PII Shield как flag-only (audit), так что PII записывается без удержания вызова.

deny — заблокировать вызов

Вызов никогда не достигает инструмента. На поверхности inbound это возвращает HTTP 400 firewall_blocked; через MCP-шлюз он приходит обратно как ошибка инструмента (firewall deny: <reason>), так что модель может среагировать вместо падения. Помечено skip-retry. Стоит нуля токенов модели.

sanitize — отредактировать аргументы, переслать очищенный вызов

Заменяет совпавшие подстроки (секреты, PII) в аргументах вызова инструмента токеном [redacted:<preset>], затем пересылает вызов с очищенными аргументами. Он редактирует только аргументы — никогда содержимое, которое инструмент возвращает. На поверхности inbound, где ещё нет аргументов времени вызова, sanitize эскалирует до deny.

pending_approval — удержать для человека

Вызов ставится в очередь на разбор, и агент получает held-ответ с id подтверждения (HTTP 400 firewall_approval_pending). Ревьюер разрешает его в консоли или через HMAC вебхук-колбэк; агент опрашивает id и переотправляет один раз с одноразовым заголовком подтверждения. См. Подтверждение человеком.

cap_cost — заблокировать, как только прогон перетратит

Создаётся как правило с потолком в центах на правило. Разрешается в allow, пока прогон агента в рамках бюджета, и в deny, как только накопленные траты пересекают лимит — так что событие показывает allow или deny, а не буквальное слово cap_cost. Предохранитель для зацикленных прогонов.

В shadow-режиме deny / sanitize / pending_approval все понижаются до audit, а причина получает префикс [shadow] would …. Событие записывает вердикт, который сработал бы, но трафик не меняется — в этом весь смысл безопасного развёртывания.

Default-вердикт

default_verdict принимает только три неинтерактивных вердикта:

Значение	Значение, когда ни одно правило не совпало
`allow`	Молча разрешать непокрытые вызовы инструментов.
`audit`	Разрешать, но записывать — по умолчанию.
`deny`	Блокировать всё, что ни одно правило явно не разрешает (позиция default-deny).

Уровень автономии tight задаёт default_verdict: deny; balanced и поставляемый default используют audit.

2. Действия guardrail

Правило guardrail срабатывает одним из пяти действий. Это текстовый эквивалент вердиктов — и правило guardrail никогда не производит вердикт firewall.

Действие	Что оно делает	Квота
`block`	Отклонить весь запрос с HTTP 400 `guardrail_blocked`.	Нет — блокировки на входе срабатывают до учёта; блокировки на выходе возвращают.
`mask`	Отредактировать каждое совпадение в типизированный тег (см. §3) и переслать очищенный текст.	Обычная — вызов продолжается.
`flag`	Только лог. Записывает совпадение; ничего не меняет в трафике.	Обычная.
`annotate`	Неблокирующее. Прикрепляет человекочитаемую заметку к запросу (вставленную вверх по потоку как уведомление о безопасности) без маскирования или блокировки текста.	Обычная.
`spotlight`	Неблокирующее. Оборачивает совпавший (недоверенный) текст в разделители и говорит модели обращаться с ограниченной областью как с данными, никогда инструкциями — защита от prompt-injection «spotlighting».	Обычная.

Заблокированный запрос guardrail помечен skip-retry — повторный прогон того же промпта на другом канале просто снова заблокируется.

Используйте flag, чтобы измерить новое правило против реального трафика до того, как переключите его на block или mask. Лента совпадений показывает, что было бы поймано, с нулевым влиянием на трафик — guardrail-аналог shadow-режима firewall.

Одно правило pii может применять разные действия к разным сущностям через entity_actions — маскировать email и телефоны, но блокировать на credit_card и ssn, из одного правила. Ключи должны быть сущностью, включённой на правиле; значения должны быть block / mask / flag / annotate.

3. Глоссарий тегов маскирования

На действии mask каждая совпавшая сущность заменяется inline типизированным тегом — [<UPPERCASE_ENTITY_NAME>] — так что модель (стадия входа) или вызывающий (стадия выхода) видит форму данных без значения. Маскирование работает на обеих стадиях, включая потоковые ответы: token-aware сканер потока маскирует совпадения, оседлавшие границы чанков, до того как они достигнут клиента.

Сущность	Тег
`email`	`[EMAIL]`
`phone`	`[PHONE]`
`credit_card`	`[CREDIT_CARD]`
`ssn`	`[SSN]`
`ip`	`[IP]`
`iban`	`[IBAN]`
`mac_address`	`[MAC_ADDRESS]`
`jwt`	`[JWT]`
`aws_access_key`	`[AWS_ACCESS_KEY]`
`api_key_openai`	`[API_KEY_OPENAI]`
`bitcoin_address`	`[BITCOIN_ADDRESS]`

Три региональных идентификатора поставляются поверх базового набора:

Сущность	Тег	Регион
`jp_mynumber`	`[JP_MYNUMBER]`	Япония
`kr_rrn`	`[KR_RRN]`	Южная Корея
`cn_resident_id`	`[CN_RESIDENT_ID]`	Китай

Кастомные сущности следуют той же конвенции. Кастомная сущность с именем employee_id маскируется в [EMPLOYEE_ID], если вы не зададите явную замену mask_with. До 25 кастомных сущностей на правило, каждая — RE2-regex с опциональной контрольной суммой luhn. См. Детектирование PII.

4. Один разобранный пример

Один вызов инструмента db.query, прочитанный сверху вниз, касается обоих словарей:

firewall verdict : sanitize        # secret stripped from the SQL argument
guardrail action : mask            # an email in the prompt redacted
masking tag      : [EMAIL]         # what the model actually receives

Firewall sanitize очистил аргументы инструмента; guardrail mask очистил текст промпта; тег [EMAIL] — это то, что модель видит вместо адреса. Тот же запрос, три разных слоя, три слова из этого глоссария.

5. Слова позиции, которые вы увидите рядом с вердиктами

Это не вердикты и не действия, но они решают, применяется ли вердикт вообще — так что они показываются в тех же представлениях событий и настроек.

Слово	Плоскость	Значение
Shadow-режим	Firewall	Флаг на политику. Понижает каждый применяющий вердикт до `audit`, добавляет к причине префикс `[shadow] would …`.
Observe-режим	Firewall	Настройка рабочего пространства. Когда ни одна политика не разрешается, разрешает вызов, но логирует его как пробел в покрытии (Discovered tools).
Enforce	Firewall	Shadow выключен + политика привязана: вердикты вступают в силу.
Fail-open	Guardrails	Default для продвинутых правил (`llm_judge`, `grounding`, `external`) — таймаут наблюдается, запрос продолжается. Переключите на fail-closed на правило.
Log raw content	Guardrails	Выключено по умолчанию. Когда выключено, совпадение записывает, что правило сработало, но не совпавшую подстроку.

О различии deny-против-audit-против-shadow в глубину см. Режимы применения.

6. Где определено каждое слово

Поверхность	Словарь	Домашняя страница
Политика firewall	`allow` `audit` `deny` `sanitize` `pending_approval` `cap_cost`	Firewall
Сопоставление правил firewall	`tool_name_glob`, `args_match`, egress, последовательность	Правила Firewall
Правило guardrail	`block` `mask` `flag` `annotate` `spotlight`	Guardrails
Guardrail PII	имена сущностей + теги маскирования	Guardrails
MCP и навыки	risk-band’ы навыков, режимы `quarantine` / `block`	Firewall MCP, Навыки Firewall
HTTP-тела ошибок	`guardrail_blocked`, `firewall_blocked`, `firewall_approval_pending`	Коды ошибок

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

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

Почему это было заблокировано?

Проследите один отклонённый вызов до точного правила и вердикта, которые его остановили.

Режимы применения

Как audit, shadow, observe и enforce соотносятся — и как развёртывать безопасно.

Guardrails против Firewall

Какая плоскость владеет каким решением, и почему запрос может пройти через обе.

Опасные вызовы инструментов

Угроза, ради остановки которой существуют вердикты deny и sanitize.

​1. Глоссарий вердиктов firewall

​Default-вердикт

​2. Действия guardrail

​3. Глоссарий тегов маскирования

​4. Один разобранный пример

​5. Слова позиции, которые вы увидите рядом с вердиктами

​6. Где определено каждое слово

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

Почему это было заблокировано?

Режимы применения

Guardrails против Firewall

Опасные вызовы инструментов

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

Default-вердикт

2. Действия guardrail

3. Глоссарий тегов маскирования

4. Один разобранный пример

5. Слова позиции, которые вы увидите рядом с вердиктами

6. Где определено каждое слово

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