Безопасность Pi Agent и доверие к проекту
Pi Agent работает с правами вашего текущего пользователя.
В этой главе описываются механизм доверия к проекту, границы безопасности и варианты контейнеризованного выполнения.
Модель безопасности Pi Agent
Pi Agent — этолокальный агент для программирования—он работает с правами пользователя, которые были у вас при его запуске, и может читать, записывать, редактировать файлы и выполнять команды оболочки.
Это означает:
- Он может получить доступ ко всем файлам, к которым имеет доступ ваша учётная запись пользователя
- Набор команд, которые он может выполнять, в точности совпадает с тем, что вы запускали бы вручную в терминале
- У негонет встроенногомеханизма изоляции песочницы
Это сделано намеренно — Pi Agent должен вызывать инструментальные цепочки проекта, запускать тесты и устанавливать зависимости, и всё это требует реальных системных разрешений.
Философия дизайна Pi Agent такова: не предоставлять недоделанную песочницу, которая «выглядит безопасной, но её легко понять неправильно».
Настоящая изоляция должна обеспечиваться на уровне ОС или на границах виртуализации/контейнеров.
Механизм доверия к проекту
Доверие к проекту определяет, загружает ли Pi Agent локальную конфигурацию и расширения проекта.
Это не песочница — она только контролируетто, что загружается при запуске, и не ограничивает то, что модель может делать во время разговора.
Когда срабатывает проверка доверия?
Pi Agent запускает проверку доверия, когда обнаруживает любой из следующих элементов в каталоге проекта:
- .pi/settings.json (файл конфигурации проекта)
- .pi/extensions, .pi/skills, .pi/prompts, .pi/themes (каталоги ресурсов проекта)
- .pi/SYSTEM.md или .pi/APPEND_SYSTEM.md (системные промпты проекта)
- .agents/skills (каталог Skills проекта)
Пустой каталог .pi сам по себе не вызовет проверку доверия.
Процесс принятия решения о доверии
Pi Agent решает, загружать ли ресурсы текущего проекта, в фиксированном порядке.
- Проверяет, содержит ли trust.json сохранённое решение (поиск вверх от текущего каталога)
- Если да, использует сохранённое решение
- Если нет, следует поведению настройки defaultProjectTrust (по умолчанию: ask)
- После того как пользователь принимает решение, он может выбрать «Запомнить», чтобы записать его в trust.json
Решения о доверии сохраняются для каждого каталога в глобальном ~/.pi/agent/trust.json.
При поиске выполняется сопоставление с этим файлом уровень за уровнем вверх по родительским каталогам; только если сохранённое решение не найдено, происходит возврат к логике defaultProjectTrust.
При первом входе в недоверенный проект интерфейс показывает следующий запрос:
检测到项目本地配置 .pi/settings.json 是否信任此项目并加载其配置与扩展？(y/n/always/never)
Текст запроса и варианты могут различаться в зависимости от версии; ориентируйтесь на фактический интерфейс.
Доверие к проекту управляет только загрузкой защищённых ресурсов, таких как расширения и навыки.
Контекстные файлы, такие как AGENTS.md и CLAUDE.md, загружаются независимо от статуса доверия.
Настройка defaultProjectTrust
Эта настройка определяет выбор Pi Agent по умолчанию, когда никто не подтверждает; поведение различается в интерактивном и неинтерактивном режимах.
| Значение | Поведение в интерактивном режиме | Поведение в неинтерактивном режиме |
|---|---|---|
| "ask" (по умолчанию) | Показать запрос на подтверждение доверия | Не загружать ресурсы проекта (поведение такое же, как при "never") |
| "always" | Автодоверие | Автодоверие |
| "never" | Автоотклонение | Автоотклонение |
Способ конфигурации:
Примеры
"defaultProjectTrust": "always"
}
Вы также можете переопределить поведение при каждом вызове с помощью аргументов командной строки:
# 本次运行信任项目 $ pi --approve $ pi -a # 本次运行不信任项目 $ pi --no-approve $ pi -na
Используйте команду /trust для сохранения решений
В интерактивном режиме вы можете в любое время использовать команду /trust, чтобы сохранить решение о доверии для текущего проекта:
/trust
Эта команда записывает в~/.pi/agent/trust.json, где хранятся решения о доверии, сохранённые для каждого каталога.
/trust сохраняет текущее решение, но не перезагружает текущий сеанс.
Если вы измените решение о доверии, вам нужно перезапустить Pi Agent, чтобы изменение вступило в силу.
Соображения безопасности для неинтерактивного режима
В режиме Print (-p), режиме JSON (--mode json) и режиме RPC (--mode rpc) Pi Agent не отображает запросы доверия.
Поведение в этом случае полностью зависит от настройки defaultProjectTrust:
- Если установлено "ask" или "never": ресурсы проекта игнорируются
- Установлено в "always": ресурсы проекта загружаются.
Используйте --approve или --no-approve, чтобы временно переопределить это поведение.
Запуск недоверенного кода
Когда вам нужно работать с недоверенными репозиториями или автоматизированными задачами, рекомендуется запускать Pi Agent в контейнере или песочнице:
- Контейнерный подход: Запустите весь процесс pi в контейнере Docker или VM
- Подход Gondolin: Запустите pi на хосте и направляйте выполнение инструментов в микро-VM Gondolin
- Подход OpenShell: Запустите весь процесс pi в песочнице с управлением политиками NVIDIA, создавая песочницы через шлюз
- Контроль монтирования: Монтируйте только те рабочие каталоги, к которым агенту нужен доступ
- Управление учётными данными: Избегайте монтирования каталога ~/.pi/agent/ хоста; передавайте временный API-ключ с минимальными привилегиями
- Сетевая изоляция: Если задаче не нужен доступ к сети, ограничьте сеть контейнера
- Проверка результатов: Проверяйте различия и изменения перед копированием вывода обратно в доверенную систему
Gondolin — это отдельный проект микро-VM с открытым исходным кодом (локальная микро-VM Linux, требующая поддержки QEMU); Pi направляет выполнение встроенных инструментов в неё с помощью примера расширения.
OpenShell черезopenshell sandbox create --from piчтобы создать песочницы, сначала нужно зарегистрироваться и выбрать шлюз.
Режим удалённого шлюза не выполняет bind-mount локальных каталогов; нужно использовать команды upload/download для передачи файлов между внутренней и внешней частью песочницы. Учётные данные модели могут оставаться вне песочницы.
Если вы монтируете рабочий каталог хоста в контейнер с доступом на чтение и запись, операции записи внутри контейнера всё равно будут влиять на файлы хоста.
Если нужна более строгая защита, используйте монтирование только для чтения или копируйте файлы в песочницу и из неё.
Советы по безопасности
Следующие рекомендации по безопасности упорядочены по типичным сценариям использования; проверьте их перед началом работы.
| Сценарий | Рекомендация |
|---|---|
| Проверка стороннего кода | Запуск в контейнере с монтированием только для чтения |
| Автоматизированный CI/CD | Используйте временные учётные данные и ограничьте список разрешённых инструментов |
| Общая конфигурация команды | Используйте .pi/settings.json проекта, но не помещайте в него конфиденциальную информацию |
| Установка сторонних пакетов расширений | Проверьте исходный код перед установкой; расширения могут выполнять произвольный код |
| Установка сторонних Skills | Проверьте содержимое SKILL.md; Skills могут инструктировать модель выполнять произвольные действия |