Если вы предпочитаете не использовать --shell-install, добавьте строку самостоятельно:```bash

zsh / bash

eval "$(cplt --shell-setup --agent opencode)"

fish

alias opencode 'cplt --agent opencode'

Тот же шаблон, который используют mise, direnv и starship.
</details>

**Почему каждый алиас называет своего агента.** `alias opencode=cplt` не сделал бы того, на что это похоже. Обычный `cplt` выбирает своего агента из `--agent`, затем из файла конфигурации, затем из того, что найдёт в PATH — а определение через PATH предпочитает `copilot`. Ввод `opencode` вместо этого изолировал бы Copilot, и на экране не было бы ничего, что говорило бы об этом. Алиас передаёт `--agent`, поэтому команда, которую вы вводите, — это агент, который вы получаете.

**Почему алиас, а не симлинк?** cplt и Copilot CLI устанавливаются в один и тот же bin-каталог Homebrew (`/opt/homebrew/bin/`), и там может находиться только один файл с именем `copilot`, поэтому симлинк вызвал бы конфликт. Алиас обходит это. Настоящий бинарник `copilot` остаётся в PATH, где cplt может его найти и обернуть, а алиас перенаправляет вашу команду.

> **Примечание:** cplt отказывается вкладываться. Если он обнаружит, что уже работает внутри песочницы (через переменную окружения `__CPLT_WRAPPED`), он не будет запускаться снова. Подкоманды только для чтения, такие как `--print-profile` и `cplt doctor`, всё ещё работают внутри существующей песочницы.

## Использование```
cplt [OPTIONS] [-- <AGENT_ARGS>...]

Всё после -- передаётся напрямую процессу агента (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh или shell).

Пресеты политик

Пресет задаёт базовый уровень для пяти основных переключателей песочницы одним флагом вместо их списка. Отдельные флаги всё равно имеют приоритет над пресетом, так что --preset permissive --no-allow-tmp-exec делает именно то, что написано. Также задаётся как [sandbox] preset = "..." в конфиге.

Полная матрица пресетов и порядок разрешения: docs/configuration.md.

Доступ к файлам

Каталог проекта — это записываемое рабочее пространство, плюс узкий allowlist, необходимый для аутентификации, среды выполнения и инструментов (см. таблицу выше). Ядро блокирует всё остальное, включая SSH-ключи и облачные учётные данные.

Переменные окружения

cplt по умолчанию санирует окружение дочернего процесса. Проходят только безопасные переменные, а облачные учётные данные, URL баз данных и токены пакетов удаляются. Он также внедряет переменные укрепления, которые блокируют lifecycle-скрипты npm/yarn/pnpm (хуки postinstall, вектор атак на цепочку поставок номер один), отключают подпись git-коммитов и тегов (поскольку ~/.ssh и ~/.gnupg недоступны внутри песочницы) и отказываются от телеметрии инструментов разработчика (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1 и другие).

Что проходит:

Allowlist по префиксу с защитой от секретных суффиксов. Переменная, совпадающая с разрешённым префиксом вроде COPILOT_* или YARN_*, всё равно отбрасывается, если она заканчивается суффиксом, несущим секрет: _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD или _CREDENTIALS. Так COPILOT_DEBUG проходит, а COPILOT_API_KEY — нет.

Всегда блокируются: AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, переменные Docker, токены CI и всё, чего нет в allowlist.

Переключатели песочницы

Поддерживаемые среды выполнения

cplt автоматически обнаруживает установленные инструменты и пишет соответствующие правила песочницы. Обычно правила получают только каталоги, существующие на диске, так что фантомных путей нет. В macOS записываемые каталоги приложений включаются при обнаружении, даже если они ещё не существуют, так что их можно создать при первом использовании. Linux не может разрешить запись в несуществующий путь, поэтому там создание должно происходить вне песочницы.

Запустите cplt doctor, чтобы увидеть, будет ли cplt работать здесь для вашего агента, и cplt doctor --verbose для всего, что он обнаружил на вашей машине.

Отладка

Флаги сессии

Они транслируются в собственные флаги сессии агента, так что разделитель -- не нужен.

--continue и --resume также отображаются для OpenCode, Antigravity и Claude Code:

¹ Ни у OpenCode, ни у Antigravity нет интерактивного выбора сессии, так что голый --resume означает «продолжить последнюю сессию». У Claude Code он есть, поэтому отображается напрямую.

--remote и --name только для Copilot. Pi и режим shell не получают никакой трансляции вообще, так что все четыре флага для них отбрасываются. Автовозобновление — отдельный механизм: когда вы вызываете cplt без сквозных аргументов и без флагов сессии, он добавляет --resume за вас, и это применяется только к Copilot.

Комбинируйте их с флагами песочницы и сквозными аргументами --:```bash cplt --resume=my-task # resume by name cplt --remote --name my-task -- -p "fix tests" # remote + named + prompt

### Агенты

Выберите один с помощью `--agent <name>` или сделайте его значением по умолчанию с помощью `cplt config set sandbox.agent <name>`. Copilot, OpenCode и Antigravity автоматически определяются из `PATH` в указанном порядке, если вы не назвали агента явно.

| Агент | Значение `--agent` | Автоопределение | Аутентификация |
| --- | --- | --- | --- |
| GitHub Copilot CLI | `copilot` | да, приоритет 1 | Токен GitHub, из Keychain или `gh` |
| [OpenCode](https://opencode.ai/) | `opencode` | да, приоритет 2 | Подписка Copilot через `/connect` или `--pass-env ANTHROPIC_API_KEY` |
| [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) | `antigravity`, псевдонимы `agy` и `agi` | да, приоритет 3 | Google OAuth в браузере |
| [Pi](https://github.com/earendil-works/pi) | `pi` | нет | `--pass-env ANTHROPIC_API_KEY` и другие |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude`, псевдонимы `cc` и `claude-code` | нет | OAuth подписки в `~/.claude` или Keychain, `CLAUDE_CODE_OAUTH_TOKEN` (отменяет разрешение Keychain) или `--pass-env ANTHROPIC_API_KEY` |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh`, псевдонимы `deepseek` и `deepseek-harness` | нет | `--pass-env DEEPSEEK_API_KEY` или `$DSH_HOME/.env` (`~/.dsh/.env`) |
| Ваша оболочка | `shell` | нет | нет |

- **Pi, Claude Code, goose и DeepSeek Harness никогда не определяются автоматически.** `pi` и `dsh` — это общие имена бинарных файлов, которые могут конфликтовать с чем-то другим на вашей машине, а Claude Code нужно выбирать осознанно.
- **Сторонние API-ключи передаются только по желанию.** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` и переменные маршрутизации Bedrock/Vertex (`CLAUDE_CODE_USE_BEDROCK`, `AWS_BEARER_TOKEN_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `ANTHROPIC_VERTEX_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`) никогда не передаются, если вы не назовёте их с помощью `--pass-env`.
- **Аутентификация по подписке не требует переменной окружения.** Поток устройства `/connect` в OpenCode сохраняет свой токен в `~/.local/share/opencode/auth.json`, а OAuth-токен Claude Code находится в `~/.claude` (`.credentials.json` в Linux) или в macOS Keychain. Оба доступны внутри песочницы, поэтому cplt не будет придираться к отсутствию API-ключа ни для одного из них.
- **Браузерным OAuth-потокам нужен `--allow-browser`**, когда появляется запрос на вход. Это касается Antigravity; все остальные агенты здесь используют поток устройства, который выводит код и URL и не требует браузера. Этот флаг позволяет агенту запускать любое приложение вне песочницы и не может быть ограничен URL-адресами, поэтому включайте его для входа и снова выключайте — см. [таблицу флагов](#sandbox-toggles) и [docs/security.md](https://github.com/navikt/cplt/blob/main/docs/security.md#--allow-browser-is-a-sandbox-escape-and-cannot-be-scoped).
- **Автообновление Claude Code отключено** с помощью `DISABLE_AUTOUPDATER=1`. У Claude Code нет флага `--no-auto-update`, самообновление внутри песочницы является вектором персистентности и в любом случае не сработало бы при путях установки, доступных только для чтения.
- **`CLAUDE_CONFIG_DIR` учитывается.** Когда он задан, cplt предоставляет доступ к этому каталогу вместо `~/.claude` и передаёт переменную дальше, поэтому перемещённый корень конфигурации продолжает работать.
- OpenCode — [официально поддерживаемый клиент Copilot](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/), поэтому ваша существующая подписка Copilot работает с `/connect` внутри OpenCode.

Каталоги конфигурации для каждого агента, использование Keychain, разрешения на выполнение и изоляция окружения описаны в [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md#supported-agents).

### Поддержка goose

cplt может поместить в песочницу [goose](https://github.com/aaif-goose/goose), открытый AI-агент (бинарный файл `goose`). Проверено на goose 1.48.0.```bash
# Run goose (must be explicit — not auto-detected)
cplt --agent goose

# goose is provider-agnostic — pass your provider's API key
cplt --agent goose --pass-env ANTHROPIC_API_KEY
cplt --agent goose --pass-env OPENAI_API_KEY

# Skip the keyring entirely: keep the key in the environment
GOOSE_DISABLE_KEYRING=1 cplt --agent goose --pass-env OPENAI_API_KEY --pass-env GOOSE_DISABLE_KEYRING

# Set goose as your default agent
cplt config set sandbox.agent goose

Замечания по безопасности для goose:

• Не обнаруживается автоматически: выбирайте явно с помощью --agent goose или задайте sandbox.agent = "goose" в конфигурации
• Не зависит от провайдера: goose направляет трафик модели к настроенному пользователем провайдеру (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Распространённые ключи провайдеров (ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY, DATABRICKS_HOST/DATABRICKS_TOKEN, GROQ_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, AWS_BEARER_TOKEN_BEDROCK) распознаются как подсказки аутентификации и должны передаваться через --pass-env. goose читает , а не . Любой провайдер вне этого подмножества всё равно работает: укажите имя его переменной с помощью

Поддержка DeepSeek Harness

cplt может изолировать DeepSeek Harness (бинарник dsh), ориентированный на плагины агентный харнесс от DeepSeek. Upstream поставляет его как предварительную версию для разработчиков, и его собственный SAFETY.md говорит не полагаться на его средства контроля как на единственную границу, — именно для этого и существует cplt.```bash

Run DSH (must be explicit — not auto-detected)

cplt --agent dsh

Pass the API key, or keep it in $DSH_HOME/.env

cplt --agent dsh --pass-env DEEPSEEK_API_KEY

Set DSH as your default agent

cplt config set sandbox.agent dsh

**Замечания по безопасности для DSH:**
- **Не обнаруживается автоматически**: выберите его с помощью `--agent dsh` (алиасы `deepseek`, `deepseek-harness`) или установите `sandbox.agent = "dsh"`. `dsh` — это короткое, общее имя команды, которое может принадлежать чему-то другому на вашей машине
- **Отключите собственный sandbox DSH внутри cplt**: DSH оборачивает каждый вызов shell и файловых инструментов в свой собственный процессный sandbox — Seatbelt на macOS, bwrap или Landlock на Linux. Ни один из них не вкладывается в cplt. macOS не поддерживает вложенные вызовы `sandbox-exec` (то же ограничение, из-за которого cplt отключает внутренний sandbox Gradle, см. [Ограничения](#limitations)), а bwrap строит своё пространство имён с помощью `unshare`, который блокируется seccomp-фильтром cplt. В любом случае cplt является принудительной границей, поэтому для сессий в sandbox выбирайте поставляемый с DSH пресет разрешений `danger-full-access`. Оставьте внутренний runner включённым — и вызовы инструментов будут завершаться ошибкой sandbox runner, а не ошибкой задачи
- **Один корень home, и cplt следует за переопределением**: DSH хранит сессии, настройки, кэш и профили в `$DSH_HOME` (`~/.dsh` по умолчанию). `DSH_HOME` находится в списке разрешённых переменных окружения, поэтому дочерний процесс разрешает тот же корень, который предоставляет cplt. Значение, указывающее на системный корень или ваш домашний каталог, отклоняется до запуска — тот же запрет, через который проходит `CLAUDE_CONFIG_DIR`
- **Защита от сохранения на хосте**: `$DSH_HOME/cordis.patch.yml`, оверлей уровня home, который Loader читает при загрузке, запрещён для записи. `$DSH_HOME/profiles/` остаётся доступным для записи, поскольку DSH перезаписывает include-root `cordis.yml` каждого профиля при каждой загрузке, поэтому `cordis.patch.yml` для каждого профиля и установленные плагины являются документированным остаточным риском — вносите изменения в профили и `dsh plugin` вне cplt и всегда запускайте `dsh` через cplt, чтобы всё внедрённое всё равно выполнялось в sandbox
- **Домены по умолчанию**: только `deepseek.com`. Поставляемый адаптер `dsh-llm-deepseek` по умолчанию использует `https://api.deepseek.com`. Направьте `DEEPSEEK_BASE_URL` на шлюз — и вам придётся добавить домен этого шлюза через `allowed_domains`
- **Аутентификация**: передайте ключ с помощью `--pass-env DEEPSEEK_API_KEY` или храните его в `$DSH_HOME/.env`. Ключ, сохранённый через собственный интерфейс моделей DSH, попадает в `$DSH_HOME/.credentials.yaml`, внутрь того же доступного для записи корня. macOS Keychain запрещён, поэтому `git push` по HTTPS требует токена `gh` в `hosts.yml` или `--pass-env GH_TOKEN`

### Режим shell

Запустите обычный shell в sandbox без AI-агента и с теми же ограничениями. Удобно для тестирования инструментов сборки, отладки проблем sandbox или просто аккуратной ручной работы.```bash
# Interactive sandboxed shell (uses $SHELL: fish, zsh, bash)
cplt --agent shell

# Inspect what's allowed without entering the shell
cplt --agent shell --print-profile

Применяются те же правила запрета по умолчанию: изоляция файловой системы, сетевые ограничения, очистка окружения. Каталоги конфигурации оболочки (переменные и история fish, история zsh) остаются доступными для записи.

Для одной команды cplt exec удобнее, чем cplt --agent shell -- -c 'cmd'.

Режим exec

Запуск любой команды внутри песочницы без запуска агента. Без стартового баннера, без запроса подтверждения, поэтому он подходит для скриптов, конвейеров и псевдонимов оболочки.```bash

Sandbox a single command

cplt exec -- npm install cplt exec -- make build cplt exec -- go test ./...

Compound commands via $SHELL -c

cplt exec -c "npm install && npm test"

Pass sandbox flags as usual

cplt exec --allow-lifecycle-scripts -- npm install cplt exec --project-dir /path/to/repo -- make build cplt exec --with-proxy -- curl https://example.com

Shell aliases for sandboxed tools

alias npm="cplt exec -- npm" alias node="cplt exec -- node" alias python="cplt exec -- python"

К каждому флагу верхнего уровня `cplt` применимо: `--project-dir`, `--allow-read`, `--deny-path`, `--with-proxy`, `--pass-env` и остальные. Добавьте `--no-quiet`, чтобы увидеть полную сводку конфигурации песочницы перед запуском команды.

### Примеры```bash
# The common case: Copilot in the sandbox
cplt -- -p "fix the tests"

# Sessions
cplt --resume                                   # pick one interactively
cplt --resume=my-refactor                       # by name
cplt --continue                                 # most recent in this directory
cplt --remote --name my-task -- -p "fix tests"  # named remote session

# Check the environment before the first run
cplt doctor

# Let Copilot read a shared library directory
cplt --allow-read ~/shared-libs -- -p "use shared-libs"

# Block a path you don't want Copilot to see
cplt --deny-path ~/.config/gh -- -p "refactor auth"

# Extra outbound port, e.g. an external API
cplt --allow-port 8443 -- -p "test the API"

# Localhost for MCP servers or dev servers
cplt --allow-localhost 3000 --allow-localhost 8080 -- -p "use the MCP server"

# All of localhost, needed by Next.js/Turbopack and Vite builds
cplt --allow-localhost-any -- -p "fix the build"

# Pass specific env vars through
cplt --pass-env MY_CUSTOM_VAR --pass-env ANOTHER_VAR -- -p "run with custom config"

# Inherit the full environment (dangerous, debugging only)
cplt --inherit-env -- -p "debug the build"

# Network
cplt --no-proxy -- -p "fix the tests"                    # proxy is on by default
cplt --blocked-domains ./blocked-domains.txt -- -p "refactor"
cplt --allow-private-domain intern.nav.no -- -p "use mcp-onboarding"

# Non-interactive / CI (skip the confirmation prompt)
cplt --yes -- -p "fix the tests"

# Inspect and debug the sandbox itself
cplt --print-profile
cplt --show-denials -- -p "fix the tests"

Конфигурация

Конфигурация происходит на двух уровнях: глобальном — для предпочтений разработчика, и на уровне репозитория — для командной политики.```bash

Browse and change settings interactively

cplt settings

Set global preferences

cplt config set sandbox.quiet true cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt" cplt config set git_guard.mode warn # observe pushes instead of blocking them cplt config set gh_guard.enabled false # opt out of the gh guard entirely

Set per-repo policy (committed to .cplt.toml)

cplt config set --repo sandbox.allow_jvm_attach true cplt config set --repo deny.paths "~/secrets"

Inspect

cplt config show # effective config (file + defaults) cplt config explain # every key with its description

`cplt settings` — это интерактивный редактор с представлениями Effective, Global и Repository, поиском, поэтапными изменениями и явным подтверждением перед сохранением всего, что связано с безопасностью. `cplt config` остаётся стабильным неинтерактивным интерфейсом для скриптов и CI. Предложения репозитория по-прежнему фиксируются и одобряются отдельно с помощью `cplt trust`. Редактор никогда не фиксирует и не одобряет их автоматически.

Приоритет применяется в порядке: флаги CLI, затем глобальный файл конфигурации `~/.config/cplt/config.toml`, затем встроенные значения по умолчанию. Конфигурация для конкретного репозитория в `.cplt.toml` — это отдельный слой, а не ступень на этой лестнице: `[deny]` ужесточает безусловно, а одобренные разрешения только добавляются, поэтому репозиторий может включить функцию, но никогда не может отключить что-то, заданное флагом CLI или глобальной конфигурацией.

`.cplt.toml` в корне репозитория содержит политику команды:```toml
[deny]                    # Applied automatically, no opt-in needed
paths = ["~/secrets", "~/.vault-token"]
env = ["VAULT_TOKEN", "DATABASE_URL"]

[propose]                 # Requires developer approval (cplt trust accept)
gh_guard = true
git_push_prevention = true
allow_jvm_attach = true
allow_docker = true

[propose.allow]
ports = [5432]
localhost = [3000]
socket = ["/var/run/docker.sock"]

cplt читает его из git HEAD, поэтому агент не может изменить свою собственную политику в середине сессии, а одобрения доверия привязаны к содержимому файла. Незакоммиченный .cplt.toml ничего не даёт, пока не будет закоммичен, хотя его ключи [deny] всё равно применяются. В CI и скриптах, где никто не может ответить на запрос, --accept-repo-config одобряет предложения закоммиченного файла для одного запуска, не сохраняя никакого доверия. cplt init создаёт его для вас, определяя инструментарий проекта:```bash cplt init # preview detected permissions cplt init --write # write .cplt.toml to disk cplt init --quiet # output only TOML (pipe-friendly) cplt init --global # generate a personal ~/.config/cplt/config.toml

Он знает JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress и секреты окружения из `.env.example`. Опасные разрешения выдаются генератором с прикреплённым предупреждением о риске. `--global` вместо этого смотрит на вещи уровня машины: браузеры Playwright, подпись GPG, учётные данные реестра, альтернативные агенты.

Некоторые ключи являются только глобальными и отклоняются из `.cplt.toml`, поскольку они специфичны для машины или являются локальным предпочтением: `sandbox.agent`, `sandbox.quiet`, `sandbox.yes`, `sandbox.validate`, `sandbox.scratch_dir`, `sandbox.pass_env`, `sandbox.inherit_env`, `sandbox.allow_cache_exec`, `sandbox.allow_cache_exec_any`, `proxy.enabled`, `proxy.port`, `proxy.log_file`, `proxy.log_level`, `proxy.blocked_domains`, `proxy.allowed_domains`, а также все ключи `[gh_guard]` и `[git_guard]`.

Полные сведения, включая модель доверия, правила раскрытия путей и полный справочник по файлу конфигурации: [docs/configuration.md](https://github.com/navikt/cplt/blob/main/docs/configuration.md).

## Архитектура```
┌──────────────────────────────────┐
│  cplt (Rust binary)              │
│  ┌───────────┐  ┌─────────────┐  │
│  │ Policy    │  │ CONNECT     │  │
│  │ Generator │  │ Proxy       │  │
│  └─────┬─────┘  │ (optional)  │  │
│        │        └─────────────┘  │
│        ▼                         │
│  ┌─────────────┬────────────┐    │
│  │   macOS     │   Linux    │    │
│  │  Seatbelt   │  Landlock  │    │
│  │  sandbox-   │  + seccomp │    │
│  │  exec       │  pre_exec  │    │
│  └─────────────┴────────────┘    │
│        │                         │
│        ▼                         │
│  copilot (sandboxed)             │
│  ├── All child processes         │
│  ├── Cannot read ~/.ssh          │
│  ├── Network port-restricted     │
│  ├── SSH agent blocked           │
│  └── Filesystem = primary ctrl   │
└──────────────────────────────────┘

Модель безопасности — это файловая система с запретом по умолчанию и принудительным применением на уровне ядра. В macOS и в Linux с ядром 6.7+ (Landlock ABI v4) сеть по умолчанию ограничена портом 443, а --allow-port добавляет дополнительные. На более старых ядрах Linux эту роль выполняет CONNECT-прокси, поэтому он включён по умолчанию. Доступ к SSH-агенту и исходящие соединения на localhost блокируются на уровне ядра в macOS. В Linux ни то, ни другое не блокируется: правила Landlock на основе портов не отличают localhost от удалённого хоста, а connect() для unix-сокетов не контролируется Landlock до ядра 7.1, поэтому помимо сокетов, которые маскирует bubblewrap, удержанный SSH_AUTH_SOCK — единственное, что стоит между агентом и вашими загруженными ключами. Генератор профиля обнаруживает ваше окружение (cplt doctor --verbose показывает те же результаты проверки) и создаёт правила только для тех каталогов инструментов, которые действительно существуют на диске. Меньше правил — теснее песочница.

• macOS: генерируется профиль Seatbelt/SBPL и передаётся в sandbox-exec
• Linux: правила Landlock LSM плюс фильтр seccomp-BPF, применяемые через pre_exec (ядро 5.13+, фильтрация TCP-портов на 6.7+)

Внутреннее устройство и структура модулей: docs/architecture.md. Модель угроз, уровни защиты и честно признанные пробелы: SECURITY.md.

Безопасность

Один бинарник, минимум зависимостей, никаких runtime-сервисов, никакой телеметрии. Три уровня защиты с чёткими границами между ними:

От чего cplt защищает:

• Эксфильтрация секретов (SSH-ключи, облачные учётные данные, файлы .env): блокируется ядром
• Несанкционированное выполнение кода из временных каталогов: блокируется ядром
• Закрепление через бинарники в каталогах кэша: блокируется ядром, поскольку этим каталогам запрещён exec
• Закрепление через git-хуки в проекте: .git/hooks защищён от записи на уровне ядра в macOS. В Linux с Landlock и без Bubblewrap он остаётся доступным для записи, и тогда собственный родительский git в cplt запускается с core.hooksPath=/dev/null, поэтому он никогда не выполняет подложенный хук, хотя git, запущенный вами самостоятельно, всё же выполнит
• Закрепление через каталоги инструментов пакетных менеджеров, которые одновременно доступны для записи и исполнения (shims mise, PNPM_HOME, ~/.deno/bin, ~/.bun/bin): запись туда разрешена, чтобы pnpm add -g и подобные команды работали внутри песочницы, поэтому агент может оставить после себя бинарник, который позже подхватит оболочка из вашего PATH
• Подложенный бинарник, перехватывающий агента, которого запускает cplt: при запуске и аудите cplt разрешает вспомогательные программы, которые запускает сам (, , , и тот , из которого читается токен), из фиксированных системных каталогов, а не из , но сам бинарник агента запускается оттуда, где он был обнаружен, а для глобальной установки через npm это обычно дерево mise или node, доступное для записи. cplt не может разрешить его из фиксированного каталога — он законно находится там, куда его поместил ваш менеджер версий — поэтому он проверяет разрешённый путь на соответствие правилам записи, которые песочница собирается применить, и , называя бинарник и дерево, доступное для записи, после чего продолжает

От чего cplt не защищает:

• Вредоносный код, уже находящийся в каталоге проекта. У агента там полный доступ на чтение и запись
• Логические ошибки, которые вносит агент. Вы всё ещё проверяете код
• Искушённый противник, обходящий защиту команд. Используйте серверную защиту веток
• Сетевые атаки на разрешённые домены. Если github.com разрешён, агент может там читать и писать
• Доступ к macOS Keychain для агентов, которые хранят там аутентификационные данные. Содержимое защищено паролем, а sandbox.keychain_substitute может отказаться от этого разрешения там, где у агента есть другие учётные данные

Наши приоритеты по порядку: корректность (каждое утверждение протестировано, у каждого крайнего случая есть ссылка на CVE или исследование), прозрачность (SECURITY.md ничего не скрывает), простота (один бинарник, конфигурация не требуется, разумные значения по умолчанию) и полезность (не мешать и позволять агенту работать безопасно).

Подробнее: docs/security.md · SECURITY.md

Сеть и прокси

Прокси включён по умолчанию. Весь исходящий трафик от Copilot CLI, gh и curl идёт через локальный CONNECT-прокси посредством HTTP_PROXY/HTTPS_PROXY и NODE_USE_ENV_PROXY=1. Он слушает эфемерный порт, назначенный ОС, поэтому ничего не конфликтует. Вы получаете логирование соединений в реальном времени, блокировку доменов, белый список доменов, постоянный журнал аудита и ту же политику портов, которую применяет песочница (443 плюс всё, что указано в allow.ports).```bash cplt --proxy-forced -- -p "fix tests" # force all egress through the proxy cplt --no-proxy -- -p "fix tests" # disable for one run cplt --blocked-domains blocked-domains.txt -- -p "x" # block known-bad domains cplt --allowed-domains allowed-domains.txt -- -p "x" # allowlist mode cplt --default-allowlist -- -p "x" # fail-closed: only the agent's own domains cplt --observe-domains -- -p "x" # record what the agent contacts, block nothing cplt --proxy-upstream http://proxy.corp:8080 -- -p "x" # chain through a corporate proxy

`--observe-domains-out <FILE>` записывает наблюдаемый набор по одному домену на строку, а
`--proxy-upstream-no-proxy <HOST>` перечисляет хосты, к которым следует обращаться напрямую, а не через
upstream.```bash
cplt config set proxy.enabled false
cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt"
cplt config set proxy.allowed_domains "~/.config/cplt/allowed-domains.txt"
cplt config set proxy.log_file "~/.config/cplt/proxy.log"

Принудительный режим прокси включается по желанию. Он ограничивает исходящий трафик ядра портом прокси, так что сокет, открытый напрямую, или env -u HTTPS_PROXY не могут проскользнуть мимо. Принуждение полноценно на macOS, где оно привязывается к localhost:<proxy_port>. На Linux оно блокирует прямой TCP :443, а правило seccomp разрешает только SOCK_STREAM с протоколом 0 или IPPROTO_TCP для AF_INET/AF_INET6, так что UDP, raw, SCTP и DCCP тоже закрыты — ценой всего, что открывает такой сокет, а не только кода, отправляющего UDP. Остаётся остаток на основе порта, evil.com:<proxy_port>, до #114.

Вне принудительного режима прокси Linux не ограничивает UDP. Сетевые права Landlock ограничены только TCP до ABI v10, cplt обрабатывает только AccessNet::ConnectTcp, а правило seccomp выше намеренно не применяется — запрет SOCK_DGRAM там сломал бы getaddrinfo(3), а значит и весь DNS, для каждого непроксируемого инструмента. Исходящий UDP к любому хосту, входящий bind UDP, DNS-туннелирование и QUIC/HTTP-3 поэтому не опосредованы в режиме по умолчанию, а CONNECT-прокси переносит только TCP, так что ничего из этого не появляется в логе прокси. macOS ограничивает UDP в режиме по умолчанию, но тоже не маршрутизирует его: remote ip "*:443" покрывает UDP, так что QUIC/HTTP-3 на 443 уходит, не касаясь прокси, и там тоже. При proxy.forced лог прокси — это полная запись исходящего трафика на macOS. На Linux он полон, за исключением остатка evil.com:<proxy_port> выше, который не проходит через прокси и потому не появляется в его логе.

Оба списка сопоставляются одинаково: example.com покрывает точный домен и все поддомены, сопоставление нечувствительно к регистру, а завершающие точки отбрасываются. Файлы блоклиста и аллоулиста перечитываются каждые пять секунд, так что вы можете редактировать их на лету. Трафик localhost обходит прокси через NO_PROXY и никогда не появляется в журнале аудита. --proxy-timeout <SECONDS> ограничивает чтение запросов и заголовков (по умолчанию 60) и не разрывает установленные CONNECT-туннели, которые могут простаивать до часа.

Каждый флаг прокси, детали фильтрации доменов, цепочка через корпоративный прокси вышестоящего уровня и формат журнала соединений: docs/proxy.md.

Command guards

Включите их, и cplt перехватывает gh и git через скрипты-обёртки в $PATH:

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

С включённой защитой gh cplt также кэширует токен GitHub при запуске и выдаёт его один раз через callback gh auth token, после чего удаляет кэш. Это сокращает случайные утечки и утечки через окружение. Это не граница против враждебного агента, потому что кэш живёт в собственном TMPDIR агента, и агент, который прочитает его до легитимного потребителя, всё равно получит токен. В SECURITY.md есть полное заявление о block_auth_token.

Полное поведение: docs/gh-guard.md · docs/git-guard.md

Known impacts

Песочница намеренно блокирует некоторые рабочие процессы. Распространённые из них и их исправления:

Playwright Chromium требует cplt config set sandbox.allow_cache_exec ms-playwright, и Chromium должен работать без собственной вложенной песочницы. На macOS его вспомогательные процессы не могут инициализировать вторую песочницу Seatbelt внутри cplt (forbidden-sandbox-reinit); на Linux фильтр seccomp в cplt блокирует системные вызовы пространств имён, которые нужны этой песочнице. Playwright как библиотека уже запускается с --no-sandbox, и тот же самый opt-in устанавливает PLAYWRIGHT_MCP_SANDBOX=false для Playwright MCP, который иначе включил бы её обратно. Любому другому лаунчеру Chromium нужен --no-sandbox самостоятельно. cplt остаётся принудительной границей ядра, но скомпрометированный рендерер тогда получает полный профиль Playwright от cplt вместо более узкого дочернего профиля Chromium. См. Cache exec и SECURITY.md.

Git commit работает для любого агента; работает ли git push по HTTPS, зависит от агента. Три предварительных условия: используйте HTTPS-ремоуты вместо SSH (git remote set-url origin https://github.com/org/repo.git, или перепишите глобально с помощью git config --global url."https://github.com/".insteadOf "[email protected]:"), один раз выполните gh auth login вне песочницы и выполните gh auth setup-git, если credential helper ещё не настроен. Тогда push запускает gh auth git-credential, которому нужен токен, доступный gh изнутри песочницы — это различается для каждого агента, см. Git workflow. Push в ветку по умолчанию и все force push по умолчанию отклоняются защитой git; отправляйте feature-ветку. Сокет SSH-агента заблокирован, потому что он разблокирует каждый загруженный ключ и может аутентифицироваться на любом хосте, тогда как credential helper gh ограничен областью GitHub.

JVM учитывает прокси, поэтому внутренний репозиторий Maven на приватном IP теперь нужно разрешать. cplt внедряет http(s).proxyHost/proxyPort в JAVA_TOOL_OPTIONS, так что разрешение зависимостей Gradle и Maven идёт через CONNECT-прокси и появляется в логе прокси вместо обхода его. Затем SSRF-защита прокси отклоняет внутренний Nexus или Artifactory, который разрешается в приватное адресное пространство, точно так же, как она уже делает для curl, npm и pip. Добавьте его DNS-имя в proxy.allow_private_domains. URL репозитория, записанный как голый IP-литерал (https://10.20.30.40/repository/maven-public/), нельзя разрешить никаким ключом — эта проверка выполняется до обращения к списку разрешённых — так что такому репозиторию нужно DNS-имя. Форки плагина WorkerExecutor и демон Gradle, запущенный вне cplt и переиспользованный внутри, не проксируются. См. Internal Maven/Gradle repositories on private IPs.

Gradle 9+ запускает собственную вложенную песочницу, и cplt отключает её. Начиная с Gradle 8.8 демон оборачивает себя в sandbox-exec (управляется GRADLE_MACOS_SANDBOX, ранее свойством org.gradle.daemon.sandbox). macOS не поддерживает вложенные вызовы sandbox-exec, поэтому внутренняя песочница падает с "Operation not permitted" на операциях с сокетами. cplt внедряет GRADLE_MACOS_SANDBOX=off, поскольку он уже обеспечивает песочницу на уровне ядра. Это известная проблема вышестоящего проекта, которая затрагивает любой инструмент, оборачивающий Gradle во внешнюю песочницу. Переопределите с помощью --pass-env GRADLE_MACOS_SANDBOX, если вы действительно хотите собственную песочницу Gradle.

Copilot CLI 1.0.83 запускает собственную вложенную песочницу, и cplt отключает её. На Linux эта песочница строит сетевое пространство имён — slirp4netns, iptables, /dev/net/tun — и фильтр seccomp в cplt запрещает unshare, который она использует. cplt также устанавливает HTTP_PROXY/HTTPS_PROXY, что в 1.0.83 ставит песочницу Linux на путь исходящего трафика через прокси, хотите вы того или нет, так что они конфликтуют при каждом запуске. Симптом: [cplt] Starting Copilot in sandbox... и затем ничего. cplt внедряет собственный opt-out Copilot, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported; Copilot отступает на сессию, сообщает об этом и оставляет ваш сохранённый sandbox.enabled в покое. cplt — это граница, как и для Gradle и Chromium. Переопределите с помощью --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. Корпоративная управляемая политика, требующая песочницу, переопределяет всё это — см. Copilot CLI's own command sandbox.

Каждое влияние, с таблицами по инструментам, заметками о демонах JVM и Kotlin, устранением неполадок GPG и различиями платформ для приватных реестров: docs/known-impacts.md.

Limitations

macOS

• sandbox-exec устарел. Apple не удалила его, но может в будущей версии macOS.
• В SBPL нет фильтрации по доменам. Опциональный CONNECT-прокси вместо этого обеспечивает блокировку доменов.
• У lsopen в SBPL тоже нет фильтра, так что --allow-browser — это либо весь Launch Services, либо ничего из него. С ним агент может запустить любое приложение вне песочницы, и никакая обёртка не может это сузить — см. docs/security.md.

Linux

• Требуется ядро 5.13+ с включённым Landlock LSM.
• Фильтрация TCP-портов требует ядра 6.7+. Более старые ядра получают принуждение только для файловой системы.
• Landlock не может запретить подпути внутри разрешённых путей, поэтому чтение/запись/удаление .env внутри каталога проекта не обеспечивается ядром. Запись в .git/hooks блокируется, когда активен Bubblewrap.
• --deny-path требует Bubblewrap. Он обеспечивается через маски монтирования, когда bwrap активен. Без него Landlock работает только по аллоулисту, и cplt предупреждает о запрете вместо его применения.

Подробнее: docs/security.md

Contributing

Вклад приветствуется.```bash git clone https://github.com/navikt/cplt.git && cd cplt git config core.hooksPath hack # enables pre-commit fmt + clippy checks mise run check # runs fmt, clippy, and tests

Откройте issue перед началом крупного изменения. Каждый PR должен проходить CI (fmt, clippy, тесты).

## Ссылки

- [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md) — полная модель безопасности, анализ угроз, стратегия тестирования и предшествующие наработки
- [Apple sandbox-exec(1)](https://keith.github.io/xcode-man-pages/sandbox-exec.1.html)
- [Chromium Seatbelt V2 Design](https://chromium.googlesource.com/chromium/src/sandbox/+show/refs/heads/main/mac/seatbelt_sandbox_design.md)
- [Документация Landlock LSM](https://docs.kernel.org/userspace-api/landlock.html)
- [Документация seccomp-BPF](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)
- [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
- [michaelneale/agent-seatbelt-sandbox](https://github.com/michaelneale/agent-seatbelt-sandbox)

## Лицензия

[MIT](https://github.com/navikt/cplt/blob/main/LICENSE)