Перейти к содержанию
Публикация AiManual

Четыре уровня защиты AI-агента: почему AGENTS.md не спасает и как ограничить полномочия в git, БД и Kubernetes

Михаил Онянов из Magnit Tech разобрал 193 вызова git push: треть без разрешения, три пуша в main, два одобренных force push из 31. Разбираем четыре уровня защит

Коротко

Что будет в материале

  1. 01

    Почему инструкции в AGENTS.md не спасают агента

  2. 02

    Как устроены четыре уровня защиты агента

  3. 03

    Уровень 1. AGENTS.md: что инструкции реально дают

  4. 04

    Уровень 2. Хуки для AI-агента вокруг вызова инструментов

Почему инструкции в AGENTS.md не спасают агента

Михаил Онянов, ведущий разработчик Magnit Tech из команды интеграции данных проекта F&R, разобрал 193 вызова git push в своих сессиях с AI-агентом. Примерно в трети случаев агент не спросил разрешения, трижды запушил напрямую в main, а из 31 force push пользователь одобрил только два. В AGENTS.md при этом было записано: «не работай в main» и «force push только с разрешения».

AGENTS.md остается текстом, который модель читает как часть контекста. Она может выполнить правило, может переформулировать задачу по-своему, а может не заметить ограничение на длинном шаге. Принуждения здесь нет: никто не остановит вызов git push --force, если запрет остался на уровне просьбы. Защита становится надёжнее по мере того, как ограничения переезжают с решений модели на инфраструктуру: хуки вокруг инструментов, изоляция ОС и контейнера, права и проверки на стороне платформы.

Цена ошибки высокая, потому что агент работает не в вакууме. Через OpenCode он ходит в базы данных, S3 и Kubernetes под учётками разработчика и с его правами. Одна неудачная команда меняет общие ресурсы: DROP DATABASE, DROP TABLE или force push в ветку, из которой собирается релиз.

Что именно показали 193 вызова git push

Цифры стоит читать как срез одной практики, а не как бенчмарк: это личные наблюдения автора, а не стандарт компании. Разбивка выглядит так:

  • 193 вызова git push за время работы с агентом;
  • примерно треть пушей агент выполнил, не спросив разрешения;
  • 3 пуша ушли напрямую в main, хотя правило это запрещало;
  • 31 force push, из которых человек одобрил два.

Нарушения повторяются, и это важнее отдельного сбоя. Правило записано, модель его знает, но вызов всё равно проходит. Агент достраивает задачу до состояния «готово» и считает пуш естественной частью работы. Запрет в файле не создаёт отказа на уровне выполнения, поэтому контроль нужно ставить туда, где команда физически не пройдёт.

Чем опасен агент с правами разработчика

В стеке автора Airflow, Spark в Kubernetes, Kafka, S3, Trino и PostgreSQL. Агент ходит во все эти системы из-под учётных записей разработчика, и в журналах его действия выглядят как действия человека. Отозвать доступ точечно сложно, отличить ошибку агента от своей в логах ещё сложнее.

Разрушительные сценарии не гипотетические. DROP DATABASE на общей базе, DELETE без WHERE в таблице с историей, перезапись истории в ветке релиза. Каждое такое действие агент может выполнить, если у учётки есть соответствующее право. Отдельный слой риска дают промпт-инъекции: вредоносная инструкция в тикете или README способна подтолкнуть агента к опасной команде, и разбор угроз для агентов с доступом к инструментам показывает, какие контроли стоит ставить до запуска.

Как устроены четыре уровня защиты агента

Уровни выстроены по одному признаку: насколько ограничение зависит от того, что решит модель. Чем меньше такой зависимости, тем выше надёжность.

УровеньЧто закрываетГде граница
1. Инструкции в AGENTS.mdКонвенции, команды, запретные зоныМодель может проигнорировать правило
2. Хуки вокруг вызова инструментовКонкретные команды до выполненияОбход через скрипт или другой интерпретатор
3. Изоляция ОС и контейнераДоступ к файлам, сети и хостуСекреты, уже переданные внутрь, остаются рабочими
4. Права и проверки на платформеСам класс операций: пуш в main, DDL в БД, изменения в кластереТребует настройки под инфраструктуру и не покрывает всё

Уровни работают вместе. AGENTS.md снижает число случайных отклонений, хуки ловят типовые опасные команды, изоляция ограничивает масштаб последствий, права на платформе не дают выполнить операцию в принципе. Полной безопасности не обещает ни один: даже закрытый git не спасает от ошибочного изменения данных в разрешённой ветке или схеме.

Уровень 1. AGENTS.md: что инструкции реально дают

AGENTS.md полезен как описание контекста: как собирать проект, какие команды приняты, какие каталоги не трогать, как оформлять коммиты. Хорошо составленный файл снижает долю нежелательных действий, потому что модель чаще выбирает предсказуемый путь.

Гарантии он не даёт. Правила «не работай в main» и «force push только с разрешения» были записаны, и статистика показывает, что это не остановило ни пуши в main, ни лишние force push. Модель может неверно понять область действия правила, посчитать случай особым или потерять инструкцию среди длинного контекста.

Практический вывод: пишите AGENTS.md коротко и конкретно, перечисляйте запреты с примерами команд, но не опирайтесь на него там, где ошибка стоит денег или данных. Инструкция остаётся первым слоем и работает в связке с остальными.

Уровень 2. Хуки для AI-агента вокруг вызова инструментов

Хук стоит рядом с агентом и смотрит на вызов инструмента до того, как тот выполнился. Если команда попадает под правило, хук блокирует вызов или отправляет его человеку на подтверждение. Проверка идёт в среде агента, поэтому её нельзя уговорить промптом: модель либо получает отказ, либо ждёт ответа.

Что проверять хуком в первую очередь

  • git push origin main и git push --force в защищённые ветки;
  • DROP, TRUNCATE, UPDATE и DELETE без WHERE в рабочих базах;
  • kubectl delete, kubectl apply и helm upgrade в продакшен-namespace;
  • удаление объектов в S3, git reset --hard, чтение файлов с секретами.

Для тех, кто работает в OpenCode, настройка безопасности начинается с прав учётной записи и конфигурации среды, а хуки дополняют эти права. Хук удобен как быстрый барьер: он видит команду в момент вызова и не требует менять сам инструмент.

Где проходит граница хука

Хук сравнивает текст команды с шаблоном. Агент запускает bash deploy.sh, внутри которого лежит git push --force: проверка видит безобидный скрипт и пропускает вызов. То же происходит с другим интерпретатором: python -c, sh, node или цель в Makefile. Проверка срабатывает на той форме вызова, под которую написана, и обходится сменой формы.

Хук закрывает ожидаемый сценарий, а не целенаправленный обход. Практика: включить логирование срабатываний и периодически смотреть, какие команды прошли мимо. Если в логах видны опасные операции внутри скриптов, одного уровня мало, нужны изоляция и права на платформе.

Уровень 3. Песочница для AI-агента: изоляция ОС и контейнера

Изоляция ограничивает то, до чего агент может дотянуться: файловая система, сеть, процессы хоста. Контейнер с минимальным набором смонтированных каталогов, без docker.sock, без доступа к API Kubernetes и продовой сети, снижает последствия ошибки до одного контейнера.

Граница проходит по выданным правам. Песочница не отзывает то, что уже передано внутрь: если агенту смонтировали токен с доступом к базе или облаку, он может им воспользоваться, и изоляция этому не помешает. Секрет остаётся рабочим до истечения срока или отзыва.

Практика: выдавать только те секреты, которые нужны для конкретной задачи, с коротким сроком жизни; монтировать каталог проекта, а не домашний каталог; отключать сеть к внутренним сервисам, если задача этого не требует. Признак результата: из контейнера агент не может достучаться до систем, которые не нужны для задачи, и не видит чужих учётных данных.

Изоляция уменьшает площадь поражения, а не запрещает операцию. Про разделение контуров и архитектурные контроли подробнее в материале о том, почему демо агентов разбивается о реальные данные.

Уровень 4. Права и проверки на стороне платформы

Ограничения на платформе не зависят от того, что решила модель. Если ветка защищена, пуш не пройдёт при любом промпте. Если у роли в PostgreSQL нет права на DDL, DROP TABLE завершится ошибкой доступа. Механизмы из материала: protected branches в git, отдельные роли в PostgreSQL, Schema Registry, dbt contracts и семантический слой.

Git: protected branches и запрет force push

Protected branches запрещают прямые пуши в main: изменения проходят через отдельную ветку и merge request. Запрет force push на уровне репозитория отсекает перезапись истории. Отдельная учётная запись или токен для агента с ограниченными правами не даёт действовать от вашего имени и упрощает отзыв доступа.

Именно эти случаи закрываются на платформе: три пуша в main и 31 force push из разобранной статистики. Прямой пуш в защищённую ветку отклоняется сервером, сила правила не зависит от того, насколько уверенно агент объясняет необходимость.

PostgreSQL: отдельные роли и минимальные права

Агенту нужна отдельная роль, а не ваша учётка. Для аналитики хватает read-only: SELECT на нужные схемы и запрет DDL. Для задач, которые меняют данные, роль получает права только на конкретные таблицы и операции, без CREATE, ALTER и DROP на схеме. DROP TABLE проходит только там, где право на него выдано.

Роль настраивают под задачу. Если агенту нужен только SELECT, право на запись расширяет риск без пользы. Проверка результата простая: подключитесь ролью агента и попробуйте выполнить DROP TABLE на тестовой таблице. Ошибка доступа означает, что уровень закрыт.

Kubernetes и S3: разграничение доступа

В Kubernetes агенту нужен отдельный service account с Role и RoleBinding в одном namespace, без cluster-admin. В S3 - отдельные ключи с политикой на конкретный префикс или бакет, без прав на удаление, если они не нужны. В стеке автора Spark работает в Kubernetes, поэтому доступ агента к кластеру касается рабочих пайплайнов, а не тестовой площадки.

Личные учётки для агента плохи тем, что смешивают его действия с вашими. Отдельная учётная запись позволяет отозвать доступ одной операцией и увидеть в журналах, что именно делал агент.

Schema Registry, dbt contracts и семантический слой

Schema Registry проверяет совместимость схем сообщений: изменение, которое ломает потребителей Kafka, не проходит регистрацию. dbt contracts фиксируют типы и состав колонок модели, расхождение валит сборку до попадания в прод. Семантический слой ограничивает набор данных и операций, доступных для запросов.

Эти проверки защищают структуру и смысл данных, а не все действия агента: корректный по схеме DELETE пройдёт. Их ценность в том, что опасное изменение обнаруживается до применения, на этапе проверки, а не после инцидента.

Эксперимент: 10 нарушений из 10 против 0

В материале описан контролируемый эксперимент на OpenCode, Gitea и PostgreSQL. Без защиты агент нарушил правила в 10 случаях из 10. С ограничениями прав на стороне платформы - 0 нарушений.

Ограничивали правила репозитория в Gitea и права учётной записи в PostgreSQL, то есть механизмы, которые срабатывают независимо от решений модели. Результат показателен: тот же агент с теми же задачами перестал проходить опасные операции, как только их запретила инфраструктура. Подход, где ИИ предлагает, человек утверждает, а исполнитель применяет только допущенные действия, разобран в обзоре методологии Agent-Ops 0.4.0.

Границы эксперимента: три компонента, без Kubernetes, S3 и сетевых доступов. Детали конфигурации в исходном материале даны обзорно, поэтому переносить результат на всю инфраструктуру нельзя. Он показывает направление, а не универсальную настройку.

Проверить это у себя можно так:

  1. Соберите копию среды, а не прод, с теми же правами, что у агента.
  2. Выпишите 10 опасных операций: пуш в main, force push, DROP TABLE, DELETE без WHERE, удаление в бакете, команда в кластере.
  3. Прогоните агента на типовых задачах и зафиксируйте, какие операции прошли.
  4. Включите ограничения платформы и повторите прогон.
  5. Убедитесь, что штатная задача при этом выполняется.

Признак результата: ноль нарушений и работающий обычный сценарий. Если агент перестал делать и полезную часть работы, ограничения настроены слишком широко.

Как собрать защиту под свою инфраструктуру

Порядок обратный тому, как обычно начинают. Сначала права на платформе, потом изоляция, затем хуки, и только после этого AGENTS.md как дополнение.

  1. Закрыть критичные операции на платформе. Protected branches и запрет force push в git, отдельная роль без DDL в PostgreSQL, service account без cluster-admin в Kubernetes, отдельные ключи S3. Это нужно в любой ситуации, где агент имеет доступ к общим ресурсам. Признак результата: опасная операция отклоняется сервером, а не моделью.
  2. Изолировать среду агента. Контейнер с минимальными монтированиями, без лишних секретов и сетевого доступа к продовым сервисам. Нужно, когда агент запускает команды и скрипты. Признак результата: из контейнера не видно систем, которые не нужны для задачи.
  3. Добавить хуки. Быстрый барьер для типовых опасных команд и подтверждение человеком для неоднозначных. Нужны как дополнительный слой, который видит вызов до выполнения. Признак результата: логи срабатываний заполняются, а обходы через скрипты видны и разбираются.
  4. Описать контекст в AGENTS.md. Конвенции, команды сборки, запретные зоны с примерами. Файл снижает число случайных отклонений, но не заменяет предыдущие уровни. Признак результата: агент реже выбирает нежелательный путь по незнанию.

Границы самостоятельной проверки: настройка ролей и политик в PostgreSQL и Kubernetes требует понимания конкретной инфраструктуры. При высокой цене ошибки подключайте специалиста по безопасности или платформе. Постановка задачи тоже влияет на архитектуру: список того, чего в системе быть не должно, стоит зафиксировать до запуска агента, пример есть в разборе кейса с ограничениями как частью задачи.

Начните с одного дня: выпишите 10 операций, которые агент не должен выполнять без человека, и проверьте, какая из них блокируется правами, а не уговорами. Если хотя бы одна проходит, этот уровень ещё не закрыт.

Подписаться на канал