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

Агент, подвергшийся prompt injection, неправильно настроенный или просто получивший слишком большую свободу, может вызывать инструменты, которых он никогда не должен был касаться — или вызывать законный инструмент с опасными аргументами: shell.exec с rm -rf /, платёжный API с чрезмерной суммой перевода, инструмент базы данных, нацеленный на production-реплику. Это злоупотребление инструментами агента — один из наиболее значимых рисков в агентных системах, потому что вызовы инструментов имеют последствия в реальном мире, которые часто необратимы. Agent Firewall имеет три уровня защиты. Вы можете развёртывать их независимо или в комбинации.

1. Allow-listing: запрещайте всё, что явно не разрешено

Самый сильный контроль — allow-list. Вместо попыток перечислить каждый опасный инструмент вы перечисляете инструменты, которые этот агент законно использует — и запрещаете всё остальное. Это базовый уровень нулевого доверия. Политика с default_verdict: deny и явными правилами allow для каждого одобренного инструмента достигает этого. Пример: агент, который должен только читать из CRM:

[
  {
    "priority": 10,
    "label": "allow crm reads",
    "tool_name_glob": "crm.get*",
    "verdict": "allow"
  },
  {
    "priority": 20,
    "label": "allow crm search",
    "tool_name_glob": "crm.search",
    "verdict": "allow"
  },
  {
    "priority": 9999,
    "label": "deny everything else",
    "tool_name_glob": "*",
    "verdict": "deny"
  }
]

Любой вызов shell.exec, db.delete, payment.transfer — инициированный намеренно или запущенный внедрённой инструкцией — попадает в * catch-all и возвращает ошибку HTTP 400 firewall_blocked. Агент видит структурированную ошибку инструмента и не может повторить попытку (блокировка помечена skip-retry), так что он не может обойти запрет циклом.

Установите default_verdict вашей политики в deny для полного применения allow-list. При дефолтном вердикте audit несовпавшие вызовы разрешаются и логируются, но не блокируются — полезно при выкатывании, но само по себе не является контролем безопасности.

Паттерны glob позволяют разрешать целые семейства инструментов одним правилом. Распространённые паттерны:

Паттерн	Что покрывает
`crm.*`	Все инструменты в пространстве имён `crm`
`*.read`	Любой инструмент с глаголом read во всех серверах
`db.query`	Ровно этот один инструмент
`*`	Всё (используйте для catch-all deny)

Сопоставление инструментов — first-match-wins в порядке возрастания приоритета. Ставьте конкретные правила allow на низкие номера приоритетов, а catch-all deny — на высокий.

2. Валидация аргументов: разрешите инструмент, блокируйте опасный вызов

Allow-list на именах инструментов грубый — он полностью блокирует shell.exec. Иногда нужно разрешить инструмент, но ограничить способ его вызова. Клаузы аргументов позволяют сопоставлять конкретные поля внутри аргументов вызова инструмента, используя JSONPath и набор операторов. Пример: разрешить shell.exec, но блокировать rm -rf

{
  "priority": 10,
  "label": "block destructive rm",
  "tool_name_glob": "shell.exec",
  "args_match": {
    "clauses": [
      {
        "path": "$.command",
        "op": "regex",
        "value": "rm\\s+-[^\\s]*r[^\\s]*f|mkfs|dd\\s+if=|:\\(\\)\\{.*\\}"
      }
    ]
  },
  "verdict": "deny"
}

Это правило срабатывает только когда вызывается shell.exec и аргумент $.command совпадает с regex деструктивной команды. Обычный вызов shell.exec с безопасной командой проваливается к следующему правилу (или к вердикту по умолчанию). Ставьте это правило на меньший номер приоритета, чем любое общее правило allow shell.exec, чтобы оно срабатывало первым. Полный набор операторов аргументов:

Оператор	Используйте когда
`eq`	Точное совпадение со скалярным значением (строка или число)
`contains`	Сопоставление подстроки — например, `$.query` `contains` `DROP TABLE`
`regex`	Сопоставление паттерна RE2 — безопасно на горячем пути, без обратного отслеживания
`in`	Значение должно быть в заданном массиве — например, разрешать только конкретные окружения
`cidr_match`	IP-адрес в блоке CIDR — полезно для проверок egress-адресов назначения
`gt` / `lt`	Числовое сравнение — например, `$.amount` `gt` `10000` для ограничений платежей

Все клаузы в блоке args_match объединяются через AND. Если путь не существует в аргументах вызова, клауза оценивается как false и правило не срабатывает — вызов проваливается к следующему правилу или к дефолту. Пример защиты платежей — запретить любой вызов платёжного инструмента с суммой, превышающей порог:

{
  "priority": 5,
  "label": "cap payment amount",
  "tool_name_glob": "payment.*",
  "args_match": {
    "clauses": [
      { "path": "$.amount_cents", "op": "gt", "value": 100000 }
    ]
  },
  "verdict": "deny"
}

3. Human-in-the-loop: удержание высокорисковых вызовов для подтверждения

Для инструментов, которые действительно необходимы, но высокорисковы — запуск деплоя, одобрение возврата, отправка массового email — вы можете потребовать подписи человека до выполнения вызова. Вердикт pending_approval удерживает вызов и возвращает ответ firewall_approval_pending агенту:

{
  "priority": 20,
  "label": "hold deployment calls for review",
  "tool_name_glob": "deploy.*",
  "verdict": "pending_approval"
}

Агент (или ваш фреймворк) опрашивает id подтверждения. Проверяющий одобряет или отклоняет из консоли или через webhook-колбэк. Если одобрено, агент повторно отправляет оригинальный вызов с одноразовым токеном подтверждения, и шлюз пропускает его один раз. pending_approval совместим с клаузами аргументов — вы можете удерживать только вызовы, соответствующие порогу, и пропускать обычные через:

[
  {
    "priority": 10,
    "label": "hold large deploys",
    "tool_name_glob": "deploy.release",
    "args_match": {
      "clauses": [
        { "path": "$.environment", "op": "eq", "value": "production" }
      ]
    },
    "verdict": "pending_approval"
  },
  {
    "priority": 20,
    "label": "allow staging deploys",
    "tool_name_glob": "deploy.*",
    "verdict": "allow"
  }
]

4. Как выглядит заблокированный вызов

Запрещённый вызов на поверхности inbound (инструмент, рекламируемый в запросе) возвращает HTTP 400 с кодом ошибки firewall_blocked. Ответ включает структурированные metadata — метку совпавшего правила, код причины и факторы риска — и помечается skip-retry, так что цикл не может бомбардировать один и тот же запрещённый вызов. Вызов, заблокированный на поверхности response (модель уже выпустила tool_calls), возвращает ошибку инструмента, видимую модели, давая ей шанс среагировать — выбрать другой инструмент, спросить пользователя или остановиться — вместо краша.

5. Порядок first-match-wins

Порядок приоритетов важен. Движок проходит правила в порядке возрастания приоритета и останавливается на первом совпадении. Распространённый паттерн:

Приоритет	Правило	Вердикт
5	`shell.exec` + деструктивный regex	`deny`
10	`shell.*` (общий)	`allow`
20	`crm.*`	`allow`
9999	`*` (catch-all)	`deny`

Приоритет 5 срабатывает раньше приоритета 10 — поэтому shell.exec с деструктивной командой запрещается, несмотря на наличие общего allow для shell.*. Без deny с низким приоритетом правило allow shell.* выиграло бы первым.

6. Безопасное выкатывание с shadow mode

Перед переключением новой политики на применение включите shadow mode. Политика оценивает каждый вызов инструмента и логирует вердикт ровно так же, как в production, но каждый применяющий вердикт (deny, pending_approval, sanitize) понижается до audit — ничего не блокируется. Причина в логе событий имеет префикс [shadow] would deny, так что вы можете измерить воздействие в представлениях Events и Runs. Как только вы убедились, что политика срабатывает на том, что вы ожидаете — и ни на чём, чего вы не намеревались — выключите shadow mode. Следующий вызов применяется.

Уровень автономии tight автоматически применяет пресет block_destructive_shell. Если вам нужна быстрая позиция без написания правил, примените tight из консоли, и он поставляет политику запрета деструктивных shell-вызовов за один шаг. Затем можно накладывать собственные правила allow-list поверх. См. Уровни автономии.

7. Связанные угрозы

Злоупотребление инструментами агента редко приходит в изоляции. Несанкционированный вызов инструмента зачастую является следствием другого вектора атаки:

Prompt injection — злоумышленник встраивает инструкции в извлечённый контент, направляющие агента к инструментам, которые он не должен был вызывать.
Excessive agency — агент получил больший доступ к инструментам, чем требует его задача, делая любую инъекцию или неправильную конфигурацию немедленно опасной.
Модель угроз — как злоупотребление инструментами вписывается в полную поверхность атаки агентных систем.

Agent Firewall — слой применения; принцип минимальных привилегий (узкие allow-листы инструментов, ограниченные ключи) — это проектная позиция, делающая его эффективным.

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

Полный язык сопоставления — глобы инструментов, клаузы аргументов, все операторы, вердикты и API.

Обзор Firewall

Политики, поверхности, уровни автономии, HITL-подтверждение и наблюдаемость.

​1. Allow-listing: запрещайте всё, что явно не разрешено

​2. Валидация аргументов: разрешите инструмент, блокируйте опасный вызов

​3. Human-in-the-loop: удержание высокорисковых вызовов для подтверждения

​4. Как выглядит заблокированный вызов

​5. Порядок first-match-wins

​6. Безопасное выкатывание с shadow mode

​7. Связанные угрозы

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

Обзор Firewall

1. Allow-listing: запрещайте всё, что явно не разрешено

2. Валидация аргументов: разрешите инструмент, блокируйте опасный вызов

3. Human-in-the-loop: удержание высокорисковых вызовов для подтверждения

4. Как выглядит заблокированный вызов

5. Порядок first-match-wins

6. Безопасное выкатывание с shadow mode

7. Связанные угрозы