Ограничения агента

По умолчанию агент работает так же, как другие агенты для кода: запускает команды без песочницы, видит весь диск и интернет. Ключи и пароли в домашней папке по умолчанию закрыты для него во всех режимах, а файлы .env он открывает только с вашего разрешения. Когда нужна изоляция, например в чужом коде, включите набор «Осторожно» или «Строго». На этой странице — что можно настроить и как это работает на разных системах.

#Как открыть

1. Откройте настройки: шестерёнка в шапке окна или ⌘ , (на Windows и Linux в раскладке по умолчанию — Ctrl Alt S).
2. Выберите «Безопасность агента» в группе «Безопасность».
3. Откройте нужную вкладку: «Действия» — о чём агент спрашивает; «Где работает» — песочница, папки и сеть; «Исключения» — ваши правила и запомненные ответы.

Изменения на вкладках «Действия» и «Где работает» копятся внизу, в панели «Изменения не сохранены». Нажмите «Сохранить»: изменения начнут действовать со следующего вызова инструмента, перезапуск не нужен.

#Действия и ступени

Каждое действие агента стоит на одной из четырёх ступеней:

Как ступени работают в каждом режиме — на странице Режимы агента.

Что на каких ступенях стоит по умолчанию (примеры):

• «Запрещено»: ключи и пароли в домашней папке; менеджеры паролей и связки ключей; история оболочки и профили браузеров; пропуск хуков (--no-verify); установка скриптом из интернета; внутренние адреса и метаданные облака; удаление в кластере с меткой prod; terraform destroy и pulumi destroy.
• «Спрашивать всегда»: удаление корня диска и домашней папки; стирание дисков; чтение .env; вывод переменных окружения и ключей; изменения, exec и helm на prod; запись в базы; DROP, TRUNCATE, ALTER; удаление в облаках; права доступа в облаках; публикация пакетов; платные ресурсы; установка и удаление навыков.
• «Спрашивать в Авто»: push в защищённые ветки; перезапись истории на сервере; sudo и системные настройки; удаление вне проекта; новые адреса в сети; запуск вне песочницы; изменения и удаление на stage; логи prod; изменение контейнеров.
• «Без вопросов»: push в обычные ветки; удаление локальных веток; запуск пайплайнов; создание merge request; чтение кластеров и облаков; изменения и логи на dev.

Есть действия, о которых агент спрашивает даже в чате «Без ограничений»: удаление корня и домашней папки, стирание дисков, .env, вывод переменных окружения и ключей, установка и удаление навыков. На вкладке «Действия» они помечены щитом рядом с именем; если навести на щит, появится подсказка «Спросит даже без ограничений».

#Как поменять ступень

1. Откройте вкладку «Действия». Наверху — карточки режимов «Авто», «Полный» и «Без ограничений» с числом действий, о которых агент спросит в этом режиме. Карточки только для обзора: режим чата выбирают у поля ввода.
2. Ниже — шкала по темам: «Файлы и папки», «Ключи и секреты», «Git и репозитории», «Сеть», «Kubernetes», «Базы данных» и другие. Нажмите на ступень в строке темы, и на неё перейдут все действия темы, которым эта ступень доступна. Остальные останутся на своих ступенях: и те, которым она недоступна, и закреплённые организацией, и закрытые всегда. Если на ступень не может перейти ни одно действие темы, нажать на неё нельзя.
3. Чтобы переставить одно действие, раскройте тему и нажмите на имя действия: откроется меню с параметрами и пунктом «По умолчанию».
4. Нажмите «Сохранить» внизу. Над шкалой видна строка «Изменено: N · Сбросить всё».

У некоторых действий есть параметры: «Защищённые ветки» (если список не задан, это main, master и release/*), «Разрешённые хосты» для ssh, «Разрешённые реестры» Docker (Docker Hub, ghcr.io, quay.io и другие известные реестры разрешены и так).

Сдвинуть можно не всё. Подпись «Закрыто всегда. Это не настраивается.» стоит у действий, для которых возможна только одна ступень. Подпись «Задано организацией …» — у действий, которые закрепила организация. «Ключи и пароли в домашней папке» и «История оболочки…» можно перевести только на «Без вопросов», и тогда каждое обращение попадает в журнал.

#Проверить команду

Вставьте команду в поле «Найдите действие или проверьте команду», например git push --force. Под полем появится ответ, как поступит агент в каждом режиме: «Не выполнит ни в одном режиме», «Спросит и в Авто, и в Полном», «Авто спросит, Полный выполнит сам» или «Выполнит сам в любом режиме». Там же видно, какие правила сработали и чьи они: «продукт», «вы», «организация», «проект». Кнопка «Создать правило» сразу заводит ваше правило для этой команды.

#Режим новых чатов

В строке «Режим новых чатов» выберите, в каком режиме открывается новый чат: «Авто» (по умолчанию) или «Полный». Выбор сохраняется сразу. «Без ограничений» режимом по умолчанию не бывает: его включают только для одного чата.

#Где работает агент

На вкладке «Где работает» вы решаете, какие папки видит агент, куда он ходит в сеть и запускает ли команды в песочнице. Вверху — «Набор ограничений»:

Набор выставляет переключатели ниже. Любой из них можно поменять отдельно — тогда набор будет называться «Свой набор».

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

Если выключить «Прятать от модели значения из .env» или «Скрывать ключи и токены в ответах инструментов», модель увидит значения, и каждый такой случай попадёт в журнал.

#Папки

Под переключателем «Только папка проекта и выбранные папки» — списки «Где агент читает», «Где агент пишет», «Закрыто для агента» и «Проекты, где агенту открыт .env». В каждой строке — одна папка: {project} означает открытый проект, ~ — домашнюю папку. Временные файлы и кэши пакетов открыты всегда.

#Песочница команд

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

Windows. Под переключателем появится блок «Песочница Windows» с кнопкой «Настроить песочницу Windows». Windows один раз запросит права администратора: песочнице нужно читать системные папки над вашими проектами и папки программ из PATH. Больше ничего не меняется. Если откажетесь, команды будут выполняться без песочницы. Чтобы вернуть всё как было, нажмите «Убрать изменения песочницы». Известное ограничение: внутри песочницы не работают curl.exe из системной папки Windows и Invoke-WebRequest; git, node, bun, Python и curl из Git for Windows работают.

Где песочницы нет, приложение пишет «Без песочницы», а щит в шапке становится жёлтым. Файловые инструменты агента там проверяются полностью, а команды — только по путям, которые в них написаны. Ограничение сети на команды там не действует. Если включено «Не запускать команды без песочницы», команды агента там не выполняются вовсе.

Когда команда упирается в песочницу, приходит уведомление «Агент обратился к … — заблокировано». В нём есть кнопка «Открыть «Безопасность агента»», а где можно — «Открыть .env этого проекта» или «Разрешить чтение».

Переменные окружения. Из настроек вашей оболочки приложение берёт только PATH и пути к инструментам, поэтому токены из ~/.zshrc до агента не доходят. В песочнице приложение вдобавок убирает из окружения команд переменные, похожие на ключи и пароли.

#Сеть агента

По умолчанию сеть агента не ограничена. Ограничение работает, только когда включены и «Ограничивать сеть агента», и песочница. Пока песочница выключена, под названием «Ограничивать сеть агента» написано «Работает, когда включена песочница.» Ниже можно выбрать один из двух режимов:

• «По списку» — «Команды агента ходят только по адресам ниже. О другом адресе агент спросит в чате.»
• «Сеть запрещена» — «Команды агента никуда не ходят. Даже к службам этого компьютера.»

В режиме «По списку» есть «Готовые адреса»: npm, PyPI, Maven Central, crates.io, Модули Go, GitHub, GitLab.com, реестры контейнеров, документация, российские зеркала, сервер ADE. Выключите то, чем ваши проекты не пользуются. В разделе «Ваши адреса» пишите хост или *.домен, если нужно — с портом; внутренний хост — обязательно с портом.

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

Если выключить ограничение, приложение переспросит: «Выключить ограничение? Команды агента смогут ходить по любым адресам.»

#Карточка «Агент просит адрес»

Если агенту нужен адрес не из списка, он показывает карточку «Агент просит адрес» и пишет причину в строке «Зачем: …». Варианты ответа:

• «На задачу» (Enter) — адрес открыт до конца этой сессии;
• «Для проекта» — адрес попадёт в список «Разрешено для проектов», убрать его оттуда можно кнопкой «Убрать»;
• «Отклонить» (Esc).

Если организация задала свой список адресов, адреса не из него отклоняются без карточки. Открыть такой адрес может только администратор.

Поиск в интернете идёт через сервер DevMachine и от списка не зависит. Страницы по ссылкам агент читает по тем же правилам, что и команды. В режиме «Сеть запрещена» нет ни поиска, ни чтения страниц.

#Запросы из Ignition

Внизу вкладки — группа «Ignition: HTTP-запросы агента». Здесь задают, куда агент может отправлять запросы через API-клиент Ignition. По умолчанию запросы закрыты. Разрешите нужные хосты в поле «Хосты»; если «Порты» и «Пути» пустые, подходят любые. Подробнее — на странице Ignition.

#Что закрыто всегда

• Ключи и пароли в домашней папке: ~/.ssh, ~/.gnupg, ~/.aws, ~/.azure, ~/.kube, ~/.docker/config.json, настройки облачных клиентов (gcloud, yandex-cloud, gh и других), ~/.netrc, ~/.git-credentials, ~/.npmrc, ~/.pypirc, ~/.vault-token, связки ключей. По умолчанию агент их не читает и не монтирует в контейнеры ни в одном режиме. Если на вкладке «Действия» перевести «Ключи и пароли в домашней папке» на «Без вопросов», агент получит к ним доступ, и каждое обращение попадёт в журнал.
• Настройки самого DevMachine (~/.koder) и данные приложения закрыты, что бы ни стояло в настройках.
• Сокеты Docker и ssh-agent командам в песочнице недоступны.
• Файлы .env и ключи проекта. Сам агент их не читает и не меняет ни в одном режиме. Когда файл нужен, агент показывает карточку «Агент просит файлы с секретами проекта» с кнопками «На задачу», «Для проекта» и «Отклонить». Проект, которому вы открыли .env, попадает в список «Проекты, где агенту открыт .env» — там его можно закрыть. Пока включено «Прятать от модели значения из .env», вместо значений модель видит ‹.env:ИМЯ›. Исходники вроде secrets.ts и публичные ключи секретами не считаются.
• Данные других программ на macOS. Сначала агент показывает карточку «Агент просит данные другой программы». Если нажать «Продолжить», macOS задаст свой системный вопрос.

#Docker и запуск вне песочницы

• Docker. Команды docker, docker compose, podman и nerdctl выполняются вне песочницы, с вашими настройками Docker и входом в реестры; это отмечено и на их карточке. Смотреть (ps, logs, inspect) агент может без вопросов. «Изменение контейнеров» стоит на ступени «Спрашивать в Авто», «Удаление томов и очистка Docker» — на «Спрашивать всегда». Смонтировать в контейнер корень диска, домашнюю папку, ~/.ssh, сокет Docker или другие закрытые места нельзя.
• «Выполнить команду вне песочницы?» Агент может попросить один запуск вне песочницы, и на такой карточке стоит метка «Полный доступ к компьютеру». Действие «Запуск вне песочницы» стоит на «Спрашивать в Авто». Переключатель «Не выпускать команды из песочницы» запрещает такие запуски, и тогда Docker тоже остаётся в песочнице. С телефона такой запуск разрешить нельзя.
• «Выполнить команду в обход модуля?» Так агент спрашивает, если обращается к базе или кластеру напрямую, например через psql. Подробнее — на странице Доступ к базам, кластерам и очередям.

#Исключения

На вкладке «Исключения» собрано всё, что меняет правила для отдельных команд, проектов и чатов.

• «Предупреждения режимов». Если вы отметили «Больше не спрашивать» в предупреждении режима «Полный» или «Без ограничений», здесь можно вернуть предупреждение кнопкой «Спрашивать снова».

• «Запомненные ответы». Здесь хранятся ответы «Больше не спрашивать», которые вы дали на карточках. Ответ «Всегда» действует во всех чатах этого репозитория и во всех его рабочих копиях, «В этом чате» — только в этом чате. Кнопки «Отозвать» и «Отозвать все» срабатывают сразу. Подробнее — на странице Разрешения и вопросы.

• «Ваши правила». Нажмите «Добавить правило» и задайте: «Что проверяет правило» («Команда», «Путь», «Адрес» или «Regex» — регулярное выражение по тексту команды), «Шаблон», «Что делает агент» («Разрешать», «Записывать», «Спрашивать», «Запрещать»), «Где действует» (везде, в проекте или в чате), «Срок» («Бессрочно», «До даты», «До конца чата») и «Зачем». Шаблон можно проверить на примерах. Если на команду сработало несколько правил, побеждает самое строгое: строже всего «Запрещать», за ним «Спрашивать», «Записывать» и «Разрешать». Исключение — точное «Разрешать»: без * в шаблоне и без «Regex». Оно снимает вопросы по правилам продукта для команды, которую называет шаблон, но правила, которые закрепила организация, правила проекта и самые опасные правила не снимает. Создать правило можно и из проверки команды, и из строки журнала.

• «Файл проекта». Файл .ade/security.yaml в репозитории делает правила строже для всех, кто работает с проектом, а ослабить их не может. Приложение берёт этот файл из основной папки репозитория. Если новая версия файла мягче, она ждёт кнопки «Принять», а до тех пор действует прежняя. Проект может добавить защищённые ветки, но не может открыть агенту ssh-хосты и реестры. Писать в папку .ade/ агент не может.

  Поля файла:

  • version: 1 — обязательное поле, без него файл не читается;
  • rules — встроенные правила: идентификатор и действие ask, deny или log;
  • custom — свои правила проекта: kind (command, path или net), pattern — шаблон, в котором можно ставить * (регулярные выражения не принимаются), action (ask, deny или log) и, если нужно, comment;
  • params — списки, которые добавляются к вашим, например защищённые ветки;
  • deny — пути, закрытые для агента в этом проекте;
  • comment — комментарий к файлу до 140 знаков, без ссылок.

  allow в файле не действует. Файл — не больше 64 КБ и 200 правил. Например, чтобы агент спрашивал, прежде чем выполнить git push в main:

  version: 1
  comment: Пуш в main — только с вопросом
  custom:
    - kind: command
      pattern: git push * main
      action: ask
  

  Звёздочка в шаблоне команды заменяет любое слово.

• «Импорт и экспорт». Чтобы выгрузить свои настройки, нажмите «Сохранить JSON», «Сохранить YAML» или «Скопировать». Загрузить настройки можно вставкой или кнопкой «Открыть файл». Прежде чем их применить, приложение покажет «Что изменит импорт» — там видно и то, сколько правил станут мягче. Правила на один чат не выгружаются.

Ни ответ «Всегда», ни ваши правила не отменяют того, что закрепила организация, правил проекта и самых опасных правил.

#Ограничения

• В проекте на сервере по SSH действуют не все правила: агент на сервере получает только основные ограничения.
• На Linux без bubblewrap и на Windows, где песочницу не настроили, её нет. Ограничение сети там тоже не действует.
• Без песочницы проверка по словам не ловит путь, который команда собирает во время работы. На Linux bubblewrap не закрывает файлы, созданные после запуска команды.
• Карточка «Агент просит данные другой программы» есть только на macOS.
• Всё, что закрепила организация, подписано «Задано организацией …» или «Задано администратором компьютера», и изменить это нельзя. Подробнее — на странице Организации.
• Если на компьютере нет системной связки ключей, настройка «Режим новых чатов» действует до закрытия приложения.

#Что дальше

• Режимы агента — как ступени работают в «Авто», «Полном» и «Без ограничений».
• Разрешения и вопросы — как отвечать на карточки.
• Доступ к базам, кластерам и очередям — уровни подключений.
• Аварийная остановка и журнал — где видно каждое действие агента.