Аудит расширений CLI-ИИ-агента: разрешения, песочница и решение до установки
Как проверить разрешения расширения CLI-ИИ-агента: чтение манифеста, пять осей доступа, прогон в песочнице с ловушками и матрица «ставить / ограничить / отклонить».

Расширение для CLI-ИИ-агента — это не тема оформления. Оно приносит в ваш терминал чужие промпты, команды, хуки и подключения к внешним сервисам, а агент действует от вашего имени в вашей файловой системе. Поэтому вопрос «полезное ли расширение» вторичен по отношению к вопросу «что именно оно получит в доступ».
Короткий ответ: перед установкой проведите аудит по трём шагам — прочитайте манифест и выпишите заявленные права, прогоните расширение в изолированной копии репозитория с ловушками и примите решение по матрице «ставить / ограничить / отклонить». Ниже — как это сделать практически.
Зачем аудит разрешений до установки
ИИ-агент в командной строке работает иначе, чем автодополнение в редакторе: он читает файлы проекта, выполняет команды и меняет код по вашей формулировке задачи. Расширение расширяет поверхность, на которой агент принимает решения. Чем шире права, тем больше последствий у одной неточной формулировки или неудачного промпта внутри расширения.
Аудит нужен не для того, чтобы отказаться от расширений, а чтобы отделить необходимое от избыточного. Часто оказывается, что расширению достаточно доступа к одной папке и одной команде, а ставится оно с правами на весь домашний каталог — просто потому, что так проще установить.
Из чего состоит расширение CLI-агента
По официальной документации Gemini CLI, расширения упаковывают промпты, MCP-серверы, пользовательские команды, темы, хуки, субагентов и навыки агента в единый устанавливаемый формат. Управлять ими можно интерактивной командой /extensions и группой команд gemini extensions в терминале. Установка обычно идёт по URL GitHub-репозитория.
Для аудита важны не все компоненты одинаково, а те, что расширяют возможности агента:
- Промпты и навыки — задают поведение агента; могут подталкивать его к действиям за пределами задачи.
- Пользовательские команды — сокращают рутину, но выполняются с теми же правами, что и агент.
- MCP-серверы — подключают внешние источники контекста и инструменты; это отдельный канал доступа.
- Хуки — срабатывают на события и могут выполнять действия без вашего прямого участия в моменте.
- Субагенты — получают свои задачи и могут действовать параллельно основному.
Практический вывод: расширение с одними промптами и расширение с MCP-сервером и хуками — разные уровни риска, даже если устанавливаются одной командой.
Пять осей разрешений: ФС, сеть, команды, env/секреты, MCP
Удобно раскладывать любой запрос доступа по пяти осям. Для каждой оси заранее решите, что считаете широким правом.
| Ось | Узкое право | Широкое право — повод насторожиться |
|---|---|---|
| Файловая система | Чтение и запись внутри папки проекта | Доступ к домашнему каталогу, к путям вне проекта, следование по symlink |
| Сеть | Обращения к конкретному документированному домену | Произвольные исходящие запросы, неописанные адресаты |
| Команды | Фиксированный набор команд с аргументами | Запуск произвольных команд оболочки, установка пакетов |
| env/секреты | Чтение явно перечисленных переменных | Чтение всех переменных окружения и файлов .env |
| MCP-серверы | Один сервер с понятным набором инструментов | Несколько серверов без описания, что они отдают агенту |
Оси связаны. Право на произвольные команды фактически означает и доступ к файлам, и доступ к сети, и чтение окружения — через саму оболочку. Поэтому «широкое право» по одной оси стоит оценивать как потенциально широкое по остальным.
Чтение манифеста: где заявлены права
Манифест — первый документ, который стоит открыть. Точный набор полей зависит от формата конкретного агента, поэтому сверяйтесь с актуальной документацией на момент чтения: форматы расширений меняются.
- Найдите раздел, описывающий компоненты: промпты, команды, MCP-серверы, хуки.
- Выпишите все пути файловой системы, которые упоминаются, — и отдельно отметьте те, что выходят за папку проекта.
- Выпишите сетевые адреса и домены, к которым предполагаются обращения.
- Отметьте, какие команды или скрипты расширение запускает и с какими аргументами.
- Проверьте, запрашивается ли доступ к переменным окружения или файлам с секретами.
- Сопоставьте заявленное с ожидаемым поведением: если расширение «форматирует коммиты», ему не нужен доступ ко всему домашнему каталогу.
Если манифест не описывает права вовсе, это не значит, что прав нет. Это значит, что вы не можете их проверить по документации — и тогда решающую роль играет прогон в песочнице.
Песочница: тестовый репозиторий с ловушками
Ниже — учебный пример, а не результат исследования. Он показывает логику проверки; конкретные команды и поведение зависят от вашего агента и версии расширения.
Соберите отдельную копию проекта, которую не жалко испортить, и добавьте в неё две ловушки:
- symlink за пределы проекта — ссылка внутри тестовой папки, ведущая в отдельный каталог с «важными» файлами-заглушками.
- фиктивный
.env— файл с очевидно ненастоящими значениями, чтобы увидеть, пытается ли расширение их прочитать.
Порядок прогона:
- Запустите агента в тестовой папке и дайте расширению типовую задачу, для которой вы его ставите.
- Наблюдайте, какие файлы оно читает и меняет: затронуло ли содержимое за symlink, открывался ли
.env. - Зафиксируйте сетевые обращения и запущенные команды, если ваш агент показывает журнал действий.
- Сравните фактическое поведение с тем, что обещал манифест. Расхождения — главный сигнал.
- Повторите прогон с суженными правами и проверьте, что задача всё ещё решается.
Если при сужении прав расширение перестаёт работать, это повод уточнить, какое именно право ему действительно нужно, а не возвращать сразу полный доступ.
Матрица «ставить / ограничить / отклонить»
Решение удобно принимать по трём статусам с явными условиями перехода.
| Статус | Когда выбирать | Что сделать |
|---|---|---|
| Ставить | Права совпадают с ожидаемым поведением, прогон в песочнице не выявил расхождений | Установить, зафиксировать версию и дату проверки |
| Ограничить | Задача решается, но запрошенные права шире необходимого | Сузить доступ по осям, повторить прогон, оставить только нужное |
| Отклонить | Манифест не описывает права, прогон показал обращения за пределы проекта или к секретам без объяснения | Не устанавливать; при необходимости искать альтернативу |
Переход из «ограничить» в «ставить» возможен только после успешного повторного прогона. Переход из «отклонить» — только при появлении новой информации: обновлённого манифеста или разъяснения от авторов.
Типичные ошибки при подключении расширений
Самая частая — установить расширение с правами на весь домашний каталог ради одной команды. Причина обычно в том, что сужение прав требует времени, а установка «как есть» занимает минуту. Цена такой экономии — постоянный доступ агента к файлам, которые к задаче не относятся.
Другие распространённые ошибки:
- Оценивать расширение по описанию в каталоге, не открывая манифест.
- Проверять на рабочем репозитории, а не на копии.
- Забывать, что хуки и субагенты действуют без вашего участия в моменте.
- Считать, что «открытый исходный код» автоматически означает безопасные права по умолчанию.
Пересмотр при обновлении: diff манифеста и повторный прогон
Расширение, проверенное месяц назад, — не то же расширение после обновления. Права могут расшириться незаметно, а вместе с ними и поверхность доступа.
Правило пересмотра простое: при каждом обновлении сравнивайте манифест с сохранённой копией и повторяйте прогон в песочнице. Если появились новые пути, домены, команды или доступ к окружению — аудит проводится заново, а статус возвращается к «ограничить» до подтверждения.
Чек-лист перед установкой
- Манифест прочитан, права выписаны по пяти осям.
- Заявленные права сопоставлены с ожидаемым поведением.
- Прогон выполнен на копии репозитория с symlink и фиктивным
.env. - Фактическое поведение сверено с манифестом, расхождения зафиксированы.
- Права сужены до необходимого минимума, задача при этом решается.
- Решение принято по матрице и записано вместе с версией и датой.
- Для обновлений назначено правило пересмотра.
Смежные темы, которые могут пригодиться: агентские среды разработки с ИИ и оркестрация ИИ-инфраструктуры. Официальное описание расширений Gemini CLI — в документации проекта; сверяйте детали там, поскольку форматы и права быстро меняются.


