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

Узнайте, как изолированный инструмент Bash в Claude Code обеспечивает изоляцию файловой системы и сети для более безопасного и автономного выполнения агента.

Bash sandbox позволяет Claude выполнять большинство команд оболочки без остановки для запроса разрешения. Вместо одобрения каждой команды вы определяете, какие файлы и сетевые домены могут использовать команды, и операционная система применяет эту границу для каждой команды Bash и её дочерних процессов.

На этой странице рассматривается, как:

• Включить sandbox и выбрать способ одобрения изолированных команд
• Настроить доступные пути и сетевые домены для команд
• Объединить sandboxing с правилами разрешений и режимами разрешений
• Применить sandboxing во всей организации с управляемыми параметрами

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

Sandbox встроен в Claude Code и работает на macOS, Linux и WSL2. Нативная Windows не поддерживается. На Windows запустите Claude Code внутри дистрибьютива WSL2.

На macOS нет необходимости в установке: sandboxing использует встроенную платформу Seatbelt. На Linux и WSL2 sandbox зависит от двух пакетов, описанных в разделе Настройка Linux и WSL2. Даже если вы их ещё не установили, вы можете начать с /sandbox, так как его панель показывает, что-либо отсутствует.

/sandbox

Выбор режима на панели записывает в локальные параметры вашего проекта в .claude/settings.local.json, которые применяются к текущему проекту и не проверяются в git. Чтобы включить sandbox во всех ваших проектах, установите sandbox.enabled в true в ваших пользовательских параметрах в ~/.claude/settings.json. Чтобы применить sandboxing для каждого разработчика в организации, используйте управляемые параметры.

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

На Linux и WSL2 sandbox зависит от двух пакетов:

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

Установите их с помощью менеджера пакетов вашего дистрибьютива:

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

После установки вкладка Dependencies в /sandbox показывает, доступны ли ripgrep, bubblewrap, socat и фильтр seccomp на вашей платформе. Ripgrep поставляется в комплекте с нативным двоичным файлом Claude Code. Фильтр seccomp является опциональным и добавляет блокировку Unix domain socket. Установите его с помощью npm install -g @anthropic-ai/sandbox-runtime, если он отсутствует.

Когда отсутствует требуемая зависимость, вкладка Dependencies является единственной показываемой вкладкой до её установки. Проверка зависимостей выполняется при запуске, поэтому перезагрузите Claude Code после установки пакетов, чтобы /sandbox их обнаружил.

Чтобы проверить, применяется ли это ограничение в вашей среде, включая внутри WSL2, выполните `sysctl kernel.apparmor_restrict_unprivileged_userns`. Если ключ не существует или возвращает `0`, пропустите этот шаг. Если он возвращает `1`, добавьте профиль AppArmor, который предоставляет `bwrap` эту возможность:

```bash theme={null}
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
```

Профиль применяется только к самому `bwrap`, а не к командам, которые он выполняет внутри sandbox. Перезагрузите AppArmor, чтобы применить его:

```bash theme={null}
sudo systemctl reload apparmor
```

Sandbox modes

Claude Code предлагает два режима sandbox:

Режим автоматического разрешения: Команды Bash будут пытаться выполняться внутри sandbox и автоматически разрешаются без требования разрешения. Команды, которые не могут быть изолированы, такие как те, которые требуют сетевого доступа к неразрешённым хостам, возвращаются к обычному потоку разрешений, где Claude Code проверяет ваши правила разрешений и запрашивает у вас разрешение для любой команды, которую эти правила не разрешают.

Даже в режиме автоматического разрешения применяется следующее:

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

Режим обычных разрешений: Все команды Bash проходят через обычный поток разрешений, даже когда они изолированы. Это обеспечивает больше контроля, но требует больше одобрений.

В обоих режимах sandbox применяет одни и те же ограничения файловой системы и сети. Разница только в том, разрешены ли изолированные команды автоматически или требуют явного разрешения.

Каталог временных файлов сеанса доступен для записи внутри sandbox по умолчанию, наряду с рабочим каталогом. Claude Code устанавливает $TMPDIR в этот каталог для изолированных команд, поэтому инструменты, которые записывают временные файлы, работают без дополнительной конфигурации. Неизолированные команды наследуют $TMPDIR вашей оболочки без изменений, что означает, что изолированные и неизолированные команды разрешают $TMPDIR в разные каталоги. Чтобы передавать временные файлы между ними, записывайте их в рабочий каталог вместо этого.

Некоторые команды вообще не могут выполняться внутри sandbox, такие как инструменты, несовместимые с ним, или те, которые требуют хоста, который вы не разрешили. Вместо того чтобы не выполнить задачу или потребовать отключения sandboxing, Claude Code включает механизм выхода: когда команда не выполняется из-за ограничений sandbox, Claude анализирует сбой и может повторить команду с параметром dangerouslyDisableSandbox. Повторная команда выполняется вне sandbox, поэтому она проходит через обычный поток разрешений и требует вашего одобрения.

Вы можете отключить этот механизм выхода, установив "allowUnsandboxedCommands": false в ваши параметры sandbox. При отключении, что панель Overrides в /sandbox показывает как Strict sandbox mode, параметр dangerouslyDisableSandbox полностью игнорируется и все команды должны выполняться в sandbox или быть явно указаны в excludedCommands.

Настройка sandboxing

Настройте поведение sandbox через ваш файл settings.json. Полную справку по конфигурации см. в разделе Settings.

По умолчанию изолированные команды могут писать только в текущий рабочий каталог и временный каталог сеанса. Если команды подпроцесса, такие как kubectl, terraform или npm, должны писать вне этих каталогов, используйте sandbox.filesystem.allowWrite для предоставления доступа к определённым путям:

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

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

Когда один и тот же массив файловой системы определён в нескольких областях параметров, массивы объединяются: пути из каждой области объединяются, а не заменяются.

Префиксы пути контролируют способ разрешения путей:

Этот синтаксис отличается от правил разрешений Read и Edit, которые используют //path для абсолютных и /path для относительных к проекту. Пути файловой системы sandbox используют стандартные соглашения: /tmp/build — это абсолютный путь.

Вы также можете запретить доступ на запись или чтение, используя sandbox.filesystem.denyWrite и sandbox.filesystem.denyRead, и повторно разрешить определённые пути в запрещённой области, используя sandbox.filesystem.allowRead.

Пример ниже блокирует чтение из всего домашнего каталога, но при этом разрешает чтение из текущего проекта. Поместите его в .claude/settings.json вашего проекта, потому что относительный путь . разрешается в корень проекта только когда конфигурация находится в параметрах проекта:

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

. в allowRead разрешается в корень проекта, потому что эта конфигурация находится в параметрах проекта. Если вы поместили ту же конфигурацию в ~/.claude/settings.json, . разрешился бы в ~/.claude вместо этого, и файлы проекта остались бы заблокированы правилом denyRead.

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

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

Изолированный инструмент Bash ограничивает доступ к файловой системе определёнными каталогами:

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

Вы можете предоставить доступ на запись к дополнительным путям, используя sandbox.filesystem.allowWrite в ваших параметрах. Эти ограничения применяются на уровне ОС, поэтому они применяются ко всем командам подпроцесса, включая инструменты, такие как kubectl, terraform и npm, а не только к инструментам файлов Claude.

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

Доступ в сеть контролируется через прокси-сервер, работающий вне sandbox:

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

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

Изолированный инструмент Bash использует примитивы безопасности операционной системы:

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

WSL1 не поддерживается, потому что bubblewrap требует функций ядра, доступных только в WSL2. Эти ограничения на уровне ОС гарантируют, что все дочерние процессы, порожденные командами Claude Code, наследуют одни и те же границы безопасности.

Эти же примитивы доступны как отдельный пакет @anthropic-ai/sandbox-runtime, который страница Sandbox environments описывает как отдельный подход для обёртывания всего процесса Claude Code.

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

Sandboxing, правила разрешений и режимы разрешений являются дополняющими друг друга слоями. Разделы ниже описывают, как sandbox взаимодействует с каждым.

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

Правила разрешений и sandboxing контролируют разные вещи:

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

Два слоя также отличаются способом их применения. Claude Code оценивает решения разрешений перед запуском команды на основе строки команды и, в режиме auto, отдельного классификатора, который судит о безопасности команды. Операционная система применяет границу sandbox к работающему процессу, поэтому она действует независимо от того, что выбрала модель для запуска, и даже если разрешённая команда делает больше, чем предполагает её имя.

Ограничения файловой системы и сети настраиваются как через параметры sandbox, так и через правила разрешений:

Пути из обоих параметров sandbox.filesystem и правил разрешений объединяются в окончательную конфигурацию sandbox.

Репозиторий claude-code, каталог примеров включает начальные конфигурации параметров для распространённых сценариев развёртывания, включая примеры, специфичные для sandbox. Используйте их как отправные точки и адаптируйте их в соответствии с вашими потребностями.

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

/sandbox не является режимом разрешений. Режимы разрешений решают, выполняется ли вызов инструмента и запрашивается ли вас сначала, в то время как sandbox ограничивает, к чему может получить доступ команда Bash после её запуска. Они отличаются в том, что они контролируют и что заменяет запрос для каждого действия:

Режим автоматического разрешения sandbox отличается от режима auto: автоматическое разрешение одобряет команды Bash, потому что граница sandbox их содержит, в то время как режим auto использует классификатор для проверки действий. Два работают независимо и могут быть объединены. Чтобы выбрать границу изоляции для автоматических запусков, см. Sandbox environments.

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

Администраторы могут требовать sandboxing для каждого пользователя, препятствовать разработчикам расширять политику и маршрутизировать трафик sandbox через корпоративный прокси.

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

Чтобы требовать sandbox для каждого разработчика, доставьте ключи sandbox через управляемые параметры, либо как файл, управляемый вашей MDM, либо через управляемые параметры сервера на Claude.ai.

Следующая конфигурация управляемых параметров включает sandbox, отказывает запустить Claude Code, если sandbox не может инициализироваться, и препятствует модели повторять команды вне sandbox:

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

Два ключа помимо enabled контролируют, что происходит, когда sandbox не может выполнить команду:

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

Два дополнения стоит рассмотреть вместе с ними. Добавьте excludedCommands для любых одобренных организацией инструментов, которые должны выполняться без изоляции. Добавьте записи denyRead для каталогов учётных данных, таких как ~/.aws и ~/.ssh, которые политика чтения по умолчанию всё ещё разрешает.

Sandbox не работает на нативной Windows, поэтому если ваш парк включает хосты Windows, ограничьте эту конфигурацию macOS и Linux или попросите этих пользователей запустить Claude Code внутри WSL2 или контейнера.

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

Для логических ключей, таких как enabled и failIfUnavailable, Claude Code использует управляемое значение и игнорирует всё, что разработчик устанавливает локально. Для ключей массива, таких как excludedCommands и allowRead, Claude Code объединяет записи из каждой области, поэтому разработчик может добавлять записи, которые расширяют политику.

Установите allowManagedReadPathsOnly в true в управляемых параметрах, чтобы только записи allowRead из управляемых параметров учитывались. Записи allowRead пользователя, проекта и локальные игнорируются. Это препятствует разработчикам расширять доступ на чтение за пределы одобренных организацией путей. Чтобы заблокировать сетевые домены таким же образом, установите allowManagedDomainsOnly.

excludedCommands не имеет эквивалентной блокировки только для управляемых, поэтому разработчик всегда может добавлять записи, которые выполняют дополнительные команды вне sandbox. Держите управляемый список узким.

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

Для организаций, требующих продвинутой сетевой безопасности, вы можете реализовать пользовательский прокси для:

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

Чтобы указать Claude Code на ваш прокси, установите порты прокси в параметрах sandbox:

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

Troubleshooting

Некоторые команды не выполняются внутри sandbox, хотя они работают вне его. Исправления ниже охватывают наиболее распространённые случаи.

• Команды не выполняются с ошибкой 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 вместо этого.
• Команды 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 как непривилегированного пользователя.

Ограничения

Sandboxing снижает риск, но не является полной границей изоляции. Просмотрите ограничения ниже перед тем, как полагаться на него как на жёсткий контроль безопасности.

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

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

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

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

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

Область

Sandbox изолирует подпроцессы Bash. Другие инструменты работают в разных границах:

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

См. также

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