Настройка изолированного инструмента Bash

​

Начало работы

/sandbox

​

Настройка Linux и WSL2

• bubblewrap: инструмент непривилегированной изоляции, который применяет изоляцию файловой системы
• socat: ретранслятор, используемый для маршрутизации сетевого трафика через прокси sandbox

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

​

Sandbox modes

• Явные правила отказа всегда соблюдаются
• Команды rm или rmdir, которые нацелены на /, ваш домашний каталог или другие критические пути системы, по-прежнему вызывают запрос разрешения
• Правила ask с областью действия контента, такие как Bash(git push *), по-прежнему требуют запроса даже для изолированных команд
• Простое правило Bash ask, или эквивалентная форма Bash(*), пропускается для команд, которые выполняются в изолированном режиме; оно по-прежнему применяется к командам, которые возвращаются к обычному потоку разрешений

​

Настройка sandboxing

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

​

Защита учётных данных

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

​

Как работает sandboxing

​

Изоляция файловой системы

• Поведение записи по умолчанию: доступ на чтение и запись к текущему рабочему каталогу и его подкаталогам, а также к временному каталогу сеанса, на который указывает $TMPDIR
• Поведение чтения по умолчанию: доступ на чтение ко всему компьютеру, кроме определённых запрещённых каталогов. Обратите внимание, что эта политика по умолчанию всё ещё разрешает чтение файлов учётных данных, таких как ~/.aws/credentials и ~/.ssh/. Используйте sandbox.credentials для блокировки чтения этих файлов и отмены установки переменных окружения с секретами, или добавьте пути в denyRead.
• Заблокированный доступ: невозможно изменять файлы вне текущего рабочего каталога и временного каталога сеанса без явного разрешения, включая файлы конфигурации оболочки, такие как ~/.bashrc, и системные двоичные файлы в /bin/
• Git worktrees: когда рабочий каталог является связанным git worktree, sandbox также разрешает запись в общий каталог .git основного репозитория, чтобы команды, такие как git commit, могли обновлять ссылки и индекс. Запись в hooks/ и config внутри этого каталога остаётся запрещённой.
• Настраиваемо: определите пользовательские разрешённые и запрещённые пути через параметры

​

Сетевая изоляция

• Ограничения домена: домены не предварительно разрешены. Первый раз, когда команде требуется новый домен, Claude Code запрашивает одобрение. Начиная с версии 2.1.191, выбор «Да» разрешает хост для остальной части текущего сеанса, поэтому более поздние подключения к тому же хосту больше не запрашивают подтверждение. Предварительно разрешите домены с помощью allowedDomains, чтобы избежать запроса полностью.
• Управляемая блокировка: если allowManagedDomainsOnly установлен в управляемых параметрах, неразрешённые домены автоматически блокируются вместо запроса, и только allowedDomains из управляемых параметров учитываются.
• Поддержка пользовательского прокси: продвинутые пользователи могут реализовать пользовательские правила для исходящего трафика
• Полное покрытие: ограничения применяются ко всем скриптам, программам и подпроцессам, порожденным командами

​

Применение на уровне ОС

• macOS: использует Seatbelt для применения sandbox
• Linux: использует bubblewrap для изоляции
• WSL2: использует bubblewrap, как и Linux

​

Как sandboxing связан с разрешениями и режимами разрешений

​

Правила разрешений

• Правила разрешений контролируют, какие инструменты может использовать Claude Code, и оцениваются перед запуском любого инструмента. Они применяются ко всем инструментам: Bash, Read, Edit, WebFetch, MCP и другим.
• Sandboxing обеспечивает применение на уровне ОС, которое ограничивает, к чему могут получить доступ команды Bash на уровне файловой системы и сети. Это применяется только к командам Bash и их дочерним процессам.

​

Режимы разрешений

​

Настройка sandbox для вашей организации

​

Применение sandboxing с управляемыми параметрами

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable: отсутствующая зависимость, такая как bubblewrap на Linux, блокирует запуск Claude Code вместо показа предупреждения и возврата к выполнению без изоляции
• allowUnsandboxedCommands: false: механизм выхода dangerouslyDisableSandbox игнорируется, поэтому команды, которые не выполняются в sandbox, не могут быть повторены вне него

​

Препятствование разработчикам расширять политику

​

Конфигурация пользовательского прокси

• Расшифровки и проверки трафика HTTPS
• Применения пользовательских правил фильтрации
• Логирования всех сетевых запросов
• Интеграции с существующей инфраструктурой безопасности

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

​

Troubleshooting

• Команды не выполняются с ошибкой host-not-allowed: многие инструменты CLI должны достичь определённых хостов. Предоставление разрешения при запросе добавляет хост в ваш список разрешённых, поэтому инструмент выполняется внутри sandbox в будущем.
• jest зависает или не выполняется: watchman несовместим с sandbox. Вместо этого запустите jest --no-watchman.
• Go-based CLIs не выполняют проверку TLS на macOS: инструменты, такие как gh, gcloud и terraform, могут не выполнять проверку TLS под Seatbelt. Перечислите эти инструменты в excludedCommands, чтобы запустить их вне sandbox. Если вы используете httpProxyPort с MITM прокси и пользовательским CA, установите enableWeakerNetworkIsolation в true вместо этого.
• open, osascript или потоки аутентификации на основе браузера не выполняются с ошибкой -600 на macOS: sandbox по умолчанию блокирует Apple Events. Установите allowAppleEvents в true в ваших пользовательских, управляемых или CLI параметрах, чтобы разрешить их. Параметры проекта игнорируются для этого ключа. Включение его удаляет изоляцию выполнения кода, так как изолированные команды могут затем запускать другие приложения без изоляции без запроса пользователя и отправлять команды AppleScript запущенным приложениям, подлежащим запросу автоматизации macOS (TCC). Кроме того, добавьте команду в excludedCommands, чтобы запустить её вне sandbox.
• Команды docker не выполняются: docker несовместим с sandbox. Добавьте docker * в excludedCommands, чтобы запустить его вне sandbox.
• Bubblewrap не запускается внутри контейнера: в непривилегированном контейнере bubblewrap не может смонтировать свежую файловую систему /proc. Установите enableWeakerNestedSandbox в true, чтобы внутренний sandbox привязал существующий /proc контейнера вместо этого. Используйте этот параметр только когда внешний контейнер уже обеспечивает границу изоляции, которая вам требуется, так как это раскрывает информацию о процессе для изолированных команд, которую свежее монтирование /proc скрыло бы.
• Фильтр seccomp на Linux: фильтр seccomp требуется для блокировки Unix domain sockets. Вкладка Dependencies в /sandbox показывает, доступен ли он. Если он отсутствует, запустите npm install -g @anthropic-ai/sandbox-runtime для установки помощника.
• --dangerously-skip-permissions не выполняется как root: этот флаг блокируется при запуске как root или через sudo на Linux и macOS, потому что доступ root в сочетании с отсутствием запросов разрешений может изменять любой файл или сервис в системе. Проверка автоматически пропускается внутри признанного sandbox. Чтобы запустить автономно в контейнере, используйте конфигурацию dev container, которая запускает Claude Code как непривилегированного пользователя.

​

Ограничения

​

Ограничения безопасности

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

• Повышение привилегий через Unix sockets: конфигурация allowUnixSockets может случайно предоставить доступ к мощным системным сервисам, которые могут привести к обходам sandbox. Например, разрешение доступа к /var/run/docker.sock фактически предоставляет доступ к хост-системе через сокет Docker. Тщательно рассмотрите любые Unix sockets, которые вы разрешаете через sandbox.
• Повышение привилегий разрешений файловой системы: чрезмерно широкие разрешения на запись в файловую систему могут включить атаки повышения привилегий. Разрешение записи в каталоги, содержащие исполняемые файлы в $PATH, каталоги конфигурации системы или файлы конфигурации оболочки пользователя, такие как .bashrc или .zshrc, может привести к выполнению кода в разных контекстах безопасности, когда другие пользователи или системные процессы получают доступ к этим файлам.
• Сила Linux sandbox: реализация Linux обеспечивает сильную изоляцию файловой системы и сети, но включает режим enableWeakerNestedSandbox, который позволяет ему работать внутри окружений Docker без привилегированных пространств имён или на хостах Linux, где непривилегированные пользовательские пространства имён отключены sysctl. Эта опция значительно ослабляет безопасность и должна использоваться только когда дополнительная изоляция иным образом применяется.
• Apple Events на macOS: sandbox на macOS по умолчанию блокирует Apple Events. Параметр allowAppleEvents снимает это ограничение, чтобы инструменты, такие как open и osascript, работали, но он удаляет изоляцию выполнения кода: изолированные команды могут запускать другие приложения без изоляции без запроса пользователя и могут отправлять команды AppleScript запущенным приложениям, в соответствии с запросом согласия на автоматизацию macOS для каждого приложения (TCC). Это учитывается только из пользовательских, управляемых или CLI параметров. Параметры проекта не могут включить это.
• Файлы параметров защищены: sandbox автоматически запрещает доступ на запись к файлам settings.json Claude Code в каждой области и к каталогу управляемых параметров, поэтому изолированная команда не может изменять свою собственную политику.

​

Совместимость платформ и инструментов

• Поддержка платформ: поддерживает macOS, Linux и WSL2. WSL1 и нативная Windows не поддерживаются.
• Накладные расходы производительности: минимальные, но некоторые операции файловой системы могут быть немного медленнее.
• Совместимость инструментов: некоторые инструменты, требующие определённых шаблонов доступа к системе, могут потребовать корректировки конфигурации или могут потребовать запуска вне sandbox.

​

Область

• Встроенные инструменты файлов: Read, Edit и Write используют систему разрешений напрямую, а не работают через sandbox. См. permissions.
• Использование компьютера: когда Claude открывает приложения и управляет вашим экраном, он работает на вашем фактическом рабочем столе, а не в изолированной среде. Запросы разрешений для каждого приложения контролируют каждое приложение. См. computer use in the CLI или computer use in Desktop.
• Переменные окружения: изолированные команды Bash наследуют окружение родительского процесса по умолчанию, включая любые учётные данные, установленные там. Используйте sandbox.credentials для удаления определённых переменных для изолированных команд или установите CLAUDE_CODE_SUBPROCESS_ENV_SCRUB для удаления учётных данных Anthropic и поставщика облака из всех подпроцессов.
• Subagents: subagents работают в том же процессе, что и родительский сеанс, и используют ту же конфигурацию sandbox. Команды Bash внутри subagent изолированы, когда sandboxing включен в родительском сеансе.

​

См. также

• Sandbox environments: сравните встроенный sandbox с dev containers, контейнерами и ВМ
• Security: комплексные функции безопасности и лучшие практики
• Permissions: конфигурация разрешений и контроль доступа
• Settings: полная справка по конфигурации
• CLI reference: параметры командной строки