Sandboxing - Claude Code Docs

Обзор

Claude Code имеет встроенный sandbox для обеспечения более безопасной среды выполнения агента при одновременном снижении необходимости в постоянных запросах разрешения. Вместо запроса разрешения для каждой команды bash, sandboxing создает определенные границы заранее, где Claude Code может работать более свободно с меньшим риском. Изолированный инструмент bash использует примитивы уровня ОС для обеспечения как изоляции файловой системы, так и сетевой изоляции.

Почему sandboxing важен

Традиционная безопасность на основе разрешений требует постоянного одобрения пользователя для команд bash. Хотя это обеспечивает контроль, это может привести к:

Усталости от одобрения: Повторное нажатие кнопки “одобрить” может привести к тому, что пользователи будут меньше внимания уделять тому, что они одобряют
Снижению производительности: Постоянные прерывания замедляют рабочие процессы разработки
Ограниченной автономии: Claude Code не может работать эффективно при ожидании одобрений

Sandboxing решает эти проблемы путем:

Определения четких границ: Укажите точно, какие каталоги и сетевые хосты может использовать Claude Code
Снижения запросов разрешения: Безопасные команды в sandbox не требуют одобрения
Поддержания безопасности: Попытки доступа к ресурсам вне sandbox вызывают немедленные уведомления
Обеспечения автономии: Claude Code может работать более независимо в определенных пределах

Эффективный sandboxing требует как изоляции файловой системы, так и сетевой изоляции. Без сетевой изоляции скомпрометированный агент может экспортировать конфиденциальные файлы, такие как ключи SSH. Без изоляции файловой системы скомпрометированный агент может установить бэкдор в системные ресурсы для получения сетевого доступа. При настройке sandboxing важно убедиться, что ваши настроенные параметры не создают обходов в этих системах.

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

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

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

Поведение записи по умолчанию: Доступ на чтение и запись к текущему рабочему каталогу и его подкаталогам
Поведение чтения по умолчанию: Доступ на чтение ко всему компьютеру, кроме определенных запрещенных каталогов
Заблокированный доступ: Невозможно изменять файлы вне текущего рабочего каталога без явного разрешения
Настраиваемо: Определите пользовательские разрешенные и запрещенные пути через параметры

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

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

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

Ограничения домена: Доступны только одобренные домены
Подтверждение пользователем: Новые запросы домена вызывают запросы разрешения (если не включен allowManagedDomainsOnly, который автоматически блокирует неразрешенные домены)
Поддержка пользовательского прокси: Продвинутые пользователи могут реализовать пользовательские правила для исходящего трафика
Полное покрытие: Ограничения применяются ко всем скриптам, программам и подпроцессам, порожденным командами

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

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

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

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

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

Предварительные требования

На macOS sandboxing работает из коробки, используя встроенную платформу Seatbelt. На Linux и WSL2 сначала установите необходимые пакеты:

Ubuntu/Debian
Fedora

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

Включение sandboxing

Вы можете включить sandboxing, запустив команду /sandbox:

/sandbox

Это открывает меню, где вы можете выбрать между режимами sandbox. Если отсутствуют необходимые зависимости (такие как bubblewrap или socat на Linux), меню отображает инструкции по установке для вашей платформы. По умолчанию, если sandbox не может запуститься (отсутствуют зависимости, неподдерживаемая платформа или ограничения платформы), Claude Code показывает предупреждение и выполняет команды без sandboxing. Чтобы сделать это жестким отказом вместо этого, установите sandbox.failIfUnavailable в true. Это предназначено для управляемых развертываний, которые требуют sandboxing в качестве шлюза безопасности.

Режимы Sandbox

Claude Code предлагает два режима sandbox: Режим автоматического разрешения: Команды Bash будут пытаться выполняться внутри sandbox и автоматически разрешаются без требования разрешения. Команды, которые не могут быть изолированы (такие как те, которые требуют сетевого доступа к неразрешенным хостам), возвращаются к обычному потоку разрешений. Явные правила ask/deny, которые вы настроили, всегда соблюдаются. Режим обычных разрешений: Все команды bash проходят через стандартный поток разрешений, даже если они изолированы. Это обеспечивает больше контроля, но требует больше одобрений. В обоих режимах sandbox применяет одни и те же ограничения файловой системы и сети. Разница только в том, разрешены ли изолированные команды автоматически или требуют явного разрешения.

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

Настройка sandboxing

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

Предоставление доступа на запись подпроцесса к определенным путям

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

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

Эти пути применяются на уровне ОС, поэтому все команды, работающие внутри sandbox, включая их дочерние процессы, соблюдают их. Это рекомендуемый подход, когда инструменту требуется доступ на запись к определенному местоположению, вместо полного исключения инструмента из sandbox с помощью excludedCommands. Когда allowWrite (или denyWrite/denyRead/allowRead) определен в нескольких областях параметров, массивы объединяются, что означает, что пути из каждой области объединяются, а не заменяются. Например, если управляемые параметры разрешают запись в /opt/company-tools, а пользователь добавляет ~/.kube в своих личных параметрах, оба пути включены в окончательную конфигурацию sandbox. Это означает, что пользователи и проекты могут расширить список без дублирования или переопределения путей, установленных областями с более высоким приоритетом. Префиксы пути контролируют способ разрешения путей:

Префикс	Значение	Пример
`/`	Абсолютный путь от корня файловой системы	`/tmp/build` остается `/tmp/build`
`~/`	Относительно домашнего каталога	`~/.kube` становится `$HOME/.kube`
`./` или без префикса	Относительно корня проекта для параметров проекта или к `~/.claude` для параметров пользователя	`./output` в `.claude/settings.json` разрешается в `<project-root>/output`

Старый префикс //path для абсолютных путей все еще работает. Если вы ранее использовали одиночный слэш /path, ожидая разрешения относительно проекта, переключитесь на ./path. Этот синтаксис отличается от правил разрешений Read и Edit, которые используют //path для абсолютных и /path для относительных к проекту. Пути файловой системы Sandbox используют стандартные соглашения: /tmp/build — это абсолютный путь. Вы также можете запретить доступ на запись или чтение, используя sandbox.filesystem.denyWrite и sandbox.filesystem.denyRead. Они объединяются с любыми путями из правил разрешений Edit(...) и Read(...). Чтобы повторно разрешить чтение определенных путей в запрещенной области, используйте sandbox.filesystem.allowRead, который имеет приоритет над denyRead. Когда allowManagedReadPathsOnly включен в управляемых параметрах, уважаются только управляемые записи allowRead; записи allowRead пользователя, проекта и локальные игнорируются. Например, чтобы заблокировать чтение из всего домашнего каталога, но при этом разрешить чтение из текущего проекта, добавьте это в .claude/settings.json вашего проекта:

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

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

Не все команды совместимы с sandboxing из коробки. Некоторые примечания, которые могут помочь вам максимально использовать sandbox:

Многие инструменты CLI требуют доступа к определенным хостам. По мере использования этих инструментов они будут запрашивать разрешение на доступ к определенным хостам. Предоставление разрешения позволит им получить доступ к этим хостам сейчас и в будущем, позволяя им безопасно выполняться внутри sandbox.
watchman несовместим с работой в sandbox. Если вы запускаете jest, рассмотрите возможность использования jest --no-watchman
docker несовместим с работой в sandbox. Рассмотрите возможность указания docker в excludedCommands для принудительного запуска вне sandbox.

Claude Code включает преднамеренный механизм выхода, который позволяет командам выполняться вне sandbox при необходимости. Когда команда не выполняется из-за ограничений sandbox (таких как проблемы с сетевым подключением или несовместимые инструменты), Claude предлагается проанализировать сбой и может повторить команду с параметром dangerouslyDisableSandbox. Команды, использующие этот параметр, проходят через обычный поток разрешений Claude Code, требующий разрешения пользователя на выполнение. Это позволяет Claude Code обрабатывать граничные случаи, когда определенные инструменты или сетевые операции не могут функционировать в пределах ограничений sandbox.Вы можете отключить этот механизм выхода, установив "allowUnsandboxedCommands": false в ваших параметрах sandbox. При отключении параметр dangerouslyDisableSandbox полностью игнорируется и все команды должны выполняться в sandbox или быть явно указаны в excludedCommands.

Преимущества безопасности

Защита от инъекции подсказок

Даже если злоумышленник успешно манипулирует поведением Claude Code через инъекцию подсказок, sandbox гарантирует, что ваша система остается в безопасности: Защита файловой системы:

Невозможно изменять критические файлы конфигурации, такие как ~/.bashrc
Невозможно изменять файлы уровня системы в /bin/
Невозможно читать файлы, которые запрещены в ваших параметрах разрешений Claude

Защита сети:

Невозможно экспортировать данные на серверы, контролируемые злоумышленником
Невозможно загружать вредоносные скрипты с неавторизованных доменов
Невозможно делать неожиданные вызовы API к неодобренным сервисам
Невозможно контактировать с какими-либо доменами, которые не явно разрешены

Мониторинг и контроль:

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

Сокращенная поверхность атаки

Sandboxing ограничивает потенциальный ущерб от:

Вредоносных зависимостей: Пакеты NPM или другие зависимости с вредоносным кодом
Скомпрометированных скриптов: Скрипты сборки или инструменты с уязвимостями безопасности
Социальной инженерии: Атаки, которые обманывают пользователей, заставляя их запускать опасные команды
Инъекции подсказок: Атаки, которые обманывают Claude, заставляя его запускать опасные команды

Прозрачная работа

Когда Claude Code пытается получить доступ к сетевым ресурсам вне sandbox:

Операция блокируется на уровне ОС
Вы получаете немедленное уведомление
Вы можете выбрать:
- Отказать в запросе
- Разрешить один раз
- Обновить конфигурацию sandbox, чтобы постоянно разрешить это

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

Ограничения сетевого Sandboxing: Система фильтрации сети работает путем ограничения доменов, к которым процессы могут подключаться. Она не проверяет трафик, проходящий через прокси, и пользователи несут ответственность за обеспечение того, чтобы они разрешали только доверенные домены в своей политике.

Пользователи должны знать о потенциальных рисках, связанных с разрешением широких доменов, таких как github.com, которые могут позволить экспортировать данные. Также в некоторых случаях может быть возможно обойти фильтрацию сети через domain fronting.

Повышение привилегий через Unix Sockets: Конфигурация allowUnixSockets может случайно предоставить доступ к мощным системным сервисам, которые могут привести к обходам sandbox. Например, если она используется для разрешения доступа к /var/run/docker.sock, это фактически предоставит доступ к хост-системе путем эксплуатации сокета docker. Пользователям рекомендуется тщательно рассмотреть любые unix sockets, которые они разрешают через sandbox.
Повышение привилегий разрешений файловой системы: Чрезмерно широкие разрешения на запись в файловую систему могут включить атаки повышения привилегий. Разрешение записи в каталоги, содержащие исполняемые файлы в $PATH, каталоги конфигурации системы или файлы конфигурации оболочки пользователя (.bashrc, .zshrc) может привести к выполнению кода в разных контекстах безопасности, когда другие пользователи или системные процессы получают доступ к этим файлам.
Сила Linux Sandbox: Реализация Linux обеспечивает сильную изоляцию файловой системы и сети, но включает режим enableWeakerNestedSandbox, который позволяет ему работать внутри окружений Docker без привилегированных пространств имен. Эта опция значительно ослабляет безопасность и должна использоваться только в случаях, когда дополнительная изоляция иным образом применяется.

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

Sandboxing и разрешения являются дополняющими друг друга слоями безопасности, которые работают вместе:

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

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

Используйте sandbox.filesystem.allowWrite для предоставления доступа на запись подпроцесса к путям вне рабочего каталога
Используйте sandbox.filesystem.denyWrite и sandbox.filesystem.denyRead для блокирования доступа подпроцесса к определенным путям
Используйте sandbox.filesystem.allowRead для повторного разрешения чтения определенных путей в запрещенной области
Используйте правила отказа Read и Edit для блокирования доступа к определенным файлам или каталогам
Используйте правила разрешения/отказа WebFetch для контроля доступа к доменам
Используйте allowedDomains sandbox для контроля, к каким доменам могут получить доступ команды Bash

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

Продвинутое использование

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

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

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

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

Интеграция с существующими инструментами безопасности

Изолированный инструмент bash работает вместе с:

Правилами разрешений: Объедините с параметрами разрешений для защиты в глубину
Контейнерами разработки: Используйте с devcontainers для дополнительной изоляции
Корпоративными политиками: Применяйте конфигурации sandbox через управляемые параметры

Лучшие практики

Начните с ограничений: Начните с минимальных разрешений и расширяйте по мере необходимости
Мониторьте логи: Просмотрите попытки нарушения sandbox, чтобы понять потребности Claude Code
Используйте конфигурации, специфичные для окружения: Различные правила sandbox для разработки и производства
Объедините с разрешениями: Используйте sandboxing вместе с политиками IAM для комплексной безопасности
Протестируйте конфигурации: Проверьте, что ваши параметры sandbox не блокируют законные рабочие процессы

Открытый исходный код

Среда выполнения sandbox доступна как пакет npm с открытым исходным кодом для использования в ваших собственных проектах агентов. Это позволяет более широкому сообществу AI-агентов создавать более безопасные и защищенные автономные системы. Это также можно использовать для изоляции других программ, которые вы можете захотеть запустить. Например, для изоляции MCP сервера вы можете запустить:

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

Для деталей реализации и исходного кода посетите репозиторий GitHub.

Ограничения

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

Что sandboxing не охватывает

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

Встроенные инструменты файлов: Read, Edit и Write используют систему разрешений напрямую, а не работают через sandbox. См. разрешения.
Использование компьютера на Desktop: Когда Claude открывает приложения и управляет вашим экраном на macOS, он работает на вашем фактическом рабочем столе, а не в изолированной среде. Запросы разрешения для каждого приложения контролируют каждое приложение. См. использование компьютера.

См. также

Security - Комплексные функции безопасности и лучшие практики
Permissions - Конфигурация разрешений и контроль доступа
Settings - Полная справка по конфигурации
CLI reference - Параметры командной строки

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

​Обзор

​Почему sandboxing важен

​Как это работает

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

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

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

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

​Предварительные требования

​Включение sandboxing

​Режимы Sandbox

​Настройка sandboxing

​Предоставление доступа на запись подпроцесса к определенным путям

​Преимущества безопасности

​Защита от инъекции подсказок

​Сокращенная поверхность атаки

​Прозрачная работа

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

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

​Продвинутое использование

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

​Интеграция с существующими инструментами безопасности

​Лучшие практики

​Открытый исходный код

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

​Что sandboxing не охватывает

​См. также

Обзор

Почему sandboxing важен

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

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

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

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

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

Предварительные требования

Включение sandboxing

Режимы Sandbox

Настройка sandboxing

Предоставление доступа на запись подпроцесса к определенным путям

Преимущества безопасности

Защита от инъекции подсказок

Сокращенная поверхность атаки

Прозрачная работа

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

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

Продвинутое использование

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

Интеграция с существующими инструментами безопасности

Лучшие практики

Открытый исходный код

Ограничения

Что sandboxing не охватывает

См. также