Claude Code в devcontainer

Песочница для разработки запуска Claude Code с безопасно включённым bypassPermissions. Создана в Trail of Bits для рабочих процессов аудита безопасности.

Зачем это нужно?

Запуск Claude с bypassPermissions на вашей хост-машине рискован — он может выполнить любую команду без подтверждения. Этот devcontainer обеспечивает изоляцию файловой системы, так что вы получаете преимущества продуктивности неограниченного Claude без риска для вашей хост-системы.

Предназначен для:

• Аудит безопасности: Просмотр клиентского кода без риска для вашего хоста
• Недоверенные репозитории: Безопасное исследование незнакомых кодовых баз
• Экспериментальная работа: Позволить Claude свободно изменять код в изоляции
• Работа с несколькими репозиториями: Работа с несколькими связанными репозиториями

Необходимые условия

• Среда выполнения Docker (одна из):

  • Docker Desktop — убедитесь, что она запущена
  • OrbStack
  • Colima: brew install colima docker && colima start

• Для терминальной работы (однократная установка):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

Быстрый старт

Выберите шаблон, соответствующий вашему рабочему процессу:

Шаблон A: Контейнер на проект (изолированный)

Каждый проект получает свой собственный контейнер с независимыми томами. Лучше всего подходит для разовых проверок, недоверенных репозиториев или когда необходима изоляция между проектами.

Терминал:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor:

1. Установите расширение Dev Containers:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. Настройте devcontainer (выберите один):

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Откройте папку вашего проекта в VS Code, затем:

   • Нажмите Cmd+Shift+P (Mac) или Ctrl+Shift+P (Windows/Linux)
   • Введите "Reopen in Container" и выберите Dev Containers: Reopen in Container

Шаблон B: Общий рабочий контейнер (сгруппированный)

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

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

Аутентификация на основе токена (безголовый режим)

Для безголовых серверов или чтобы пропустить интерактивного мастера входа:

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

Токен передаётся в контейнер. При каждом создании контейнера post_install.py выполняет однократное подтверждение аутентификации, так что claude запускается без мастера входа.

Это обходит проблему постоянного отображения интерактивного мастера настройки Claude Code в контейнерах, даже с действительными учётными данными (#8938).

Если вы не задаёте токен, интерактивный вход работает как прежде.

Вспомогательные команды CLI

devc .              Установить шаблон + запустить контейнер в текущем каталоге
devc up             Запустить devcontainer
devc rebuild        Пересобрать контейнер (сохраняет постоянные тома)
devc destroy [-f]   Удалить контейнер, тома и образ для текущего проекта
devc down           Остановить контейнер
devc shell          Открыть zsh-оболочку в контейнере
devc exec CMD       Выполнить команду внутри контейнера
devc upgrade        Обновить Claude Code в контейнере
devc mount SRC DST  Добавить связывание монтирования (хост → контейнер)
devc sync [NAME]    Синхронизировать сеансы Claude Code из devcontainers на хост
devc template DIR   Скопировать файлы devcontainer в каталог
devc self-install   Установить devc в ~/.local/bin

Примечание: Используйте devc destroy для очистки Docker-ресурсов проекта. Ручное удаление контейнеров (например, docker rm) оставит сиротские тома и образы, которые devc destroy не сможет найти.

Синхронизация сеансов для /insights

Команда /insights анализирует историю ваших сеансов, но она читает только из ~/.claude/projects/ на хосте. Сеансы внутри томов devcontainer для неё невидимы.

devc sync копирует журналы сеансов из всех devcontainers (работающих и остановленных) на хост, чтобы /insights могла их включить:

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

Devcontainers автоматически обнаруживаются через метки Docker — не нужно знать имена или идентификаторы контейнеров. Синхронизация инкрементальная, поэтому её можно запускать многократно.

Общий доступ к файлам

VS Code / Cursor

Перетаскивайте файлы с хост-машины на панель обозревателя VS Code — они автоматически копируются в /workspace/. Никакой настройки не требуется.

Терминал: devc mount

Чтобы сделать каталог хоста доступным внутри контейнера:

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

Это добавляет связывание монтирования в devcontainer.json и пересоздаёт контейнер. Существующие монтирования сохраняются при обновлениях devc template.

Совет: общая "папка для передачи" полезна для передачи файлов без монтирования всей домашней директории.

Замечание по безопасности: Избегайте монтирования больших каталогов хоста (например, $HOME). Каждый смонтированный путь доступен для записи изнутри контейнера, если не указан --readonly, что подрывает изоляцию файловой системы, которую обеспечивает этот проект.

Изоляция сети

По умолчанию контейнеры имеют полный исходящий сетевой доступ. Для более строгой безопасности используйте iptables для ограничения доступа к сети.

Когда включать изоляцию сети

• Просмотр кода, который может содержать вредоносные зависимости
• Аудит программного обеспечения с телеметрией или поведением "звонка домой"
• Максимальная изоляция для высокочувствительных проверок

Пример: Claude + GitHub + Пакетные реестры

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

Компромиссы

• Блокирует менеджеры пакетов, если вы не добавите реестры в белый список
• Может нарушить работу инструментов, требующих сетевого доступа
• DNS-резолюция всё ещё работает (рассмотрите возможность блокировки, если вы параноик)

Модель угроз

Основная угроза, которую решает этот проект, — Claude Code, выполняющий произвольные команды на вашей хост-машине. Когда bypassPermissions включён, Claude исполняет shell-команды, устанавливает пакеты и изменяет файлы без подтверждения. На хост-машине это означает, что он может изменить вашу конфигурацию оболочки, выполнить rm -rf за пределами каталога проекта или злоупотребить локально сохранёнными учётными данными. Devcontainer ограничивает всё это одноразовым контейнером, где радиус поражения ограничен /workspace.

Контейнер включает распространённые инструменты разработки, так что вы можете выполнять всю работу по разработке внутри него — не только запускать Claude. Предполагаемый рабочий процесс: клонируйте репозиторий, запустите devcontainer и работайте полностью внутри него. Если вашему проекту требуются дополнительные среды выполнения или инструменты сверх включённых, либо добавьте их в Dockerfile для повторного использования, либо установите их в ad-hoc режиме с помощью devc exec.

Что касается конкретных границ изоляции — см. Модель безопасности ниже. Один нюанс, который стоит отметить: среда выполнения devcontainer автоматически перенаправляет сокет SSH-агента хоста (SSH_AUTH_SOCK) в контейнер. Это позволяет коду внутри контейнера аутентифицироваться от вашего имени по SSH (например, git push), но сам закрытый ключ остаётся на хосте и никогда не раскрывается контейнеру.

Модель безопасности

Этот devcontainer обеспечивает изоляцию файловой системы, но не полную песочницу.

Изолировано: Файловая система (файлы хоста недоступны), процессы (изолированы от хоста), установки пакетов (остаются в контейнере)

Не изолировано: Сеть (полный исходящий доступ по умолчанию — см. Изоляция сети), git-идентичность (~/.gitconfig смонтирован только для чтения), SSH-агент (сокет перенаправлен, ключи остаются на хосте), Docker-сокет (не смонтирован по умолчанию)

Контейнер автоматически настраивает режим bypassPermissions — Claude запускает команды без подтверждения. Это было бы рискованно на хост-машине, но сам контейнер является песочницей.

Детали контейнера

Тома хранятся вне контейнера, поэтому ваша история shell, настройки Claude и логин gh сохраняются даже после devc rebuild. Хост ~/.gitconfig смонтирован только для чтения для git-идентичности.

Устранение неполадок

"devcontainer CLI not found"

npm install -g @devcontainers/cli

Контейнер не запускается

1. Проверьте, запущен ли Docker
2. Попробуйте пересобрать: devc rebuild
3. Проверьте логи: docker logs $(docker ps -lq)

Аутентификация GitHub CLI не сохраняется

Тому gh может потребоваться исправление прав доступа:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv не работает

Python управляется через uv:

uv run script.py              # Run a script
uv add package                # Add project dependency
uv run --with requests py.py  # Ad-hoc dependency

Разработка

Соберите образ вручную:

devcontainer build --workspace-folder .

Протестируйте контейнер:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh