Безопасное развертывание AI-агентов

Руководство по защите развертываний Claude Code и Agent SDK с использованием изоляции, управления учетными данными и сетевых элементов управления

Claude Code и Agent SDK могут выполнять код, получать доступ к файлам и взаимодействовать с внешними сервисами от вашего имени.

В отличие от традиционного программного обеспечения, которое следует предопределенным путям кода, эти инструменты динамически генерируют свои действия на основе контекста и целей. Эта гибкость делает их полезными, но это также означает, что их поведение может быть подвержено влиянию содержимого, которое они обрабатывают: файлов, веб-страниц или пользовательского ввода. Это иногда называют prompt injection. Например, если README репозитория содержит необычные инструкции, Claude Code может включить их в свои действия способами, которые оператор не предусмотрел. Это руководство охватывает практические способы снижения этого риска.

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

Модель угроз

Агенты могут предпринимать непредусмотренные действия из-за prompt injection (инструкции, встроенные в содержимое, которое они обрабатывают) или ошибки модели. Модели Claude разработаны для сопротивления этому; см. обзор модели и карту системы для модели, которую вы развертываете, для получения деталей оценки.

Защита в глубину все еще является хорошей практикой. Например, если агент обрабатывает вредоносный файл, который инструктирует его отправить данные клиентов на внешний сервер, сетевые элементы управления могут полностью заблокировать этот запрос.

Встроенные функции безопасности

Claude Code включает несколько функций безопасности, которые решают распространенные проблемы. Полные детали см. в документации по безопасности.

• Система разрешений: Правила разрешений определяют, выполняется ли вызов инструмента, блокируется или сначала запрашивает подтверждение. О формах, которые не охватывает правило Bash, и о том, как правила сочетаются с режимами разрешений, см. Что не охватывает правило Bash и Настройка разрешений. Администраторы также могут задавать правила в управляемых настройках.
• Удаление критических путей: Когда режим разрешений установлен в default, команда rm или rmdir, распознанная как удаляющая ваш рабочий каталог или другой критический путь, требует подтверждения. Совпадающее разрешающее правило не позволяет пропустить это подтверждение. Это шлюз разрешений, а не песочница. Чтобы управлять тем, что агент может записывать, используйте средства управления файловой системой.
• Суммирование результатов веб-поиска: Результаты поиска суммируются, а не передаются в контекст в виде необработанного содержимого, что снижает риск prompt injection из вредоносного веб-контента.
• Режим sandbox: Команды Bash могут выполняться в изолированной среде, которая ограничивает доступ к файловой системе и сети. Подробности см. в документации по sandboxing.

Принципы безопасности

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

Границы безопасности

Граница безопасности разделяет компоненты с разными уровнями доверия. Для развертываний с высокой безопасностью вы можете разместить чувствительные ресурсы (такие как учетные данные) вне границы, содержащей агента. Если что-то пойдет не так в среде агента, ресурсы вне этой границы остаются защищенными.

Например, вместо того чтобы давать агенту прямой доступ к ключу API, вы можете запустить прокси вне среды агента, который внедряет ключ в запросы. Агент может делать вызовы API, но он никогда не видит саму учетную данные. Этот паттерн полезен для многопользовательских развертываний или при обработке ненадежного содержимого.

Принцип наименьших привилегий

При необходимости вы можете ограничить агента только возможностями, необходимыми для его конкретной задачи:

Защита в глубину

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

• Изоляция контейнеров
• Ограничения сети
• Элементы управления файловой системой
• Валидация запросов на прокси

Правильная комбинация зависит от вашей модели угроз и операционных требований.

Технологии изоляции

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

[!NOTE]

Во всех этих конфигурациях Claude Code (или ваше приложение Agent SDK) работает внутри границы изоляции (sandbox, контейнер или VM). Элементы управления безопасностью, описанные ниже, ограничивают то, к чему агент может получить доступ из этой границы.

Sandbox runtime

Для лёгкой изоляции без контейнеров sandbox-runtime обеспечивает ограничения файловой системы и сети на уровне ОС.

Основное преимущество — простота: не требуется конфигурация Docker, образы контейнеров или настройка сети. Прокси и ограничения файловой системы встроены.

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

• Файловая система: Использует примитивы ОС (bubblewrap на Linux, sandbox-exec на macOS) для ограничения доступа на чтение/запись к настроенным путям
• Сеть: Запускает команды в собственном сетевом пространстве имён (Linux) или под профилем Seatbelt (macOS) и направляет их трафик через встроенный прокси, который разрешает настроенные домены. Подключение к внешнему хосту в обход прокси завершается ошибкой.
• Конфигурация: Списки разрешений на основе JSON для доменов и путей файловой системы

Настройка:

Шаги установки, настройки и запуска см. в разделе Настройка и запуск среды выполнения.

Соображения безопасности:

1. Ядро на одном хосте: В отличие от VMs, изолированные процессы используют ядро хоста. Уязвимость ядра теоретически может позволить выход. Для некоторых моделей угроз это приемлемо, но если вам нужна изоляция на уровне ядра, используйте gVisor или отдельную VM.

2. Без проверки TLS: По умолчанию прокси формирует список разрешённых доменов на основе имени хоста, предоставленного клиентом, и не завершает и не проверяет зашифрованный трафик. Код, работающий внутри песочницы, потенциально может использовать domain fronting или аналогичные методы для доступа к хостам вне списка разрешённых. Если ваша модель угроз требует более сильных гарантий, используйте прокси с завершением TLS, который проверяет трафик, как описано в разделе Перенаправление трафика. Подробнее см. в ограничениях безопасности изоляции в песочнице.

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

Для многих случаев использования одного разработчика и CI/CD sandbox-runtime значительно повышает планку с минимальной настройкой. Разделы ниже охватывают контейнеры и VMs для развертываний, требующих более сильной изоляции.

Контейнеры

Контейнеры обеспечивают изоляцию через пространства имен Linux. Каждый контейнер имеет свой собственный вид файловой системы, дерева процессов и стека сети, при этом используя ядро хоста.

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

docker run \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --security-opt seccomp=/path/to/seccomp-profile.json \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /home/agent:rw,noexec,nosuid,size=500m \
  --network none \
  --memory 2g \
  --cpus 2 \
  --pids-limit 100 \
  --user 1000:1000 \
  -v /path/to/code:/workspace:ro \
  -v /var/run/proxy.sock:/var/run/proxy.sock:ro \
  agent-image

Вот что делает каждый параметр:

Архитектура Unix-сокета:

С --network none DNS-запрос или прямое подключение к другому хосту внутри контейнера завершается ошибкой. Чтобы код в контейнере мог обращаться к другим хостам, запустите прокси на хосте и смонтируйте его Unix-сокет в контейнер. Если вы направляете ANTHROPIC_BASE_URL или HTTP_PROXY на порт localhost, как показано в разделе Настройка Claude Code для использования прокси, перенаправьте этот порт внутри контейнера на сокет.

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

[!WARNING]

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

Дополнительные варианты усиления:

gVisor

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

Если агент запускает вредоносный код (возможно, из-за prompt injection), этот код работает в контейнере и может попытаться использовать уязвимости ядра. С gVisor поверхность атаки намного меньше: вредоносный код должен сначала использовать реализацию gVisor в пользовательском пространстве и будет иметь ограниченный доступ к реальному ядру.

Чтобы использовать gVisor с Docker, установите runtime runsc и настройте демон:

{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc"
    }
  }
}

Затем запустите контейнеры с:

docker run --runtime=runsc agent-image

Соображения производительности:

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

Виртуальные машины

VMs обеспечивают изоляцию на уровне оборудования через расширения виртуализации CPU. Каждая VM запускает свое собственное ядро, создавая сильную границу. Уязвимость в ядре гостя не напрямую компрометирует хост. Однако VMs не автоматически "более безопасны" чем альтернативы, такие как gVisor. Безопасность VM сильно зависит от гипервизора и кода эмуляции устройств.

Firecracker разработан для легкой изоляции microVM. Он может загружать VMs менее чем за 125 мс с накладными расходами памяти менее 5 МиБ, убирая ненужную эмуляцию устройств, чтобы уменьшить поверхность атаки.

При таком подходе VM агента не имеет внешнего сетевого интерфейса. Вместо этого она взаимодействует через vsock (виртуальные сокеты). Весь трафик маршрутизируется через vsock к прокси на хосте, который обеспечивает списки разрешений и внедряет учетные данные перед пересылкой запросов.

Облачные развертывания

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

1. Запустите контейнеры агента в приватной подсети без интернет-шлюза
2. Настройте правила облачного брандмауэра (AWS Security Groups, GCP VPC firewall) для блокировки всего исходящего трафика, кроме как к вашему прокси
3. Запустите прокси (такой как Envoy с его фильтром credential_injector), который проверяет запросы, обеспечивает списки разрешений доменов, внедряет учетные данные и пересылает на внешние API
4. Назначьте минимальные разрешения IAM учетной записи сервиса агента, маршрутизируя чувствительный доступ через прокси, где это возможно
5. Регистрируйте весь трафик на прокси в целях аудита

Управление учетными данными

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

Паттерн прокси

Рекомендуемый подход — запустить прокси вне границы безопасности агента, который внедряет учетные данные в исходящие запросы. Агент отправляет запросы без учетных данных, прокси добавляет их и пересылает запрос к его месту назначения.

Этот паттерн имеет несколько преимуществ:

1. Агент никогда не видит фактические учетные данные
2. Прокси может обеспечивать список разрешений разрешенных конечных точек
3. Прокси может регистрировать все запросы для аудита
4. Учетные данные хранятся в одном безопасном месте, а не распределяются каждому агенту

Настройка Claude Code для использования прокси

Claude Code поддерживает два метода маршрутизации запросов выборки через прокси:

Вариант 1: ANTHROPIC_BASE_URL (простой, но только для запросов API выборки)

export ANTHROPIC_BASE_URL="http://localhost:8080"

Это говорит Claude Code и Agent SDK отправлять запросы выборки на ваш прокси вместо прямого обращения к Claude API. Ваш прокси получает открытые HTTP-запросы, может проверять и изменять их (включая внедрение учетных данных), затем пересылает на реальный API.

Вариант 2: HTTP_PROXY / HTTPS_PROXY (системный уровень)

export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"

Claude Code и Agent SDK соблюдают эти стандартные переменные окружения, маршрутизируя весь HTTP-трафик через прокси. Для HTTPS прокси создает зашифрованный туннель CONNECT: он не может видеть или изменять содержимое запроса без перехвата TLS.

Реализация прокси

Вы можете построить свой собственный прокси или использовать существующий:

• Envoy Proxy: прокси производственного уровня с фильтром credential_injector для добавления заголовков аутентификации
• mitmproxy: прокси, завершающий TLS, для проверки и изменения HTTPS-трафика
• Squid: кэширующий прокси со списками контроля доступа
• LiteLLM: шлюз LLM с внедрением учетных данных и ограничением скорости

Учетные данные для других сервисов

Помимо выборки из Claude API, агентам часто нужен аутентифицированный доступ к другим сервисам, таким как git-репозитории, базы данных и внутренние API. Есть два основных подхода:

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

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

Например, MCP-сервер git может принимать команды от агента, но пересылать их на git-прокси, работающий на хосте, который добавляет аутентификацию перед контактом с удаленным репозиторием. Агент никогда не видит учетные данные.

Преимущества:

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

Пересылка трафика

Для вызовов Claude API ANTHROPIC_BASE_URL позволяет маршрутизировать запросы к прокси, который может проверять и изменять их в открытом виде. Но для других HTTPS-сервисов (GitHub, npm-реестры, внутренние API) трафик часто зашифрован от конца до конца. Даже если вы маршрутизируете его через прокси через HTTP_PROXY, прокси видит только непрозрачный TLS-туннель и не может внедрять учетные данные.

Чтобы изменить HTTPS-трафик к произвольным сервисам без использования пользовательского инструмента, вам нужен прокси, завершающий TLS, который расшифровывает трафик, проверяет или изменяет его, затем повторно шифрует перед пересылкой. Это требует:

1. Запуска прокси вне контейнера агента
2. Установки сертификата CA прокси в хранилище доверия агента (чтобы агент доверял сертификатам прокси)
3. Настройки HTTP_PROXY/HTTPS_PROXY для маршрутизации трафика через прокси

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

Обратите внимание, что не все программы соблюдают HTTP_PROXY/HTTPS_PROXY. Большинство инструментов (curl, pip, npm, git) соблюдают, но некоторые могут обойти эти переменные и подключиться напрямую. Например, Node.js fetch() по умолчанию игнорирует эти переменные; в Node 24+ вы можете установить NODE_USE_ENV_PROXY=1 для включения поддержки. Чтобы охватить инструменты, которые игнорируют эти переменные, вы можете использовать proxychains для перехвата сетевых вызовов или настроить iptables для перенаправления исходящего трафика на прозрачный прокси.

[!NOTE]

Прозрачный прокси перехватывает трафик на сетевом уровне, поэтому клиент не нужно настраивать для его использования. Обычные прокси требуют, чтобы клиенты явно подключались и говорили HTTP CONNECT или SOCKS. Прозрачные прокси (такие как Squid или mitmproxy в прозрачном режиме) могут обрабатывать необработанные перенаправленные TCP-соединения.

Оба подхода все еще требуют прокси, завершающего TLS, и доверенного сертификата CA. Они просто гарантируют, что трафик действительно достигает прокси.

Конфигурация файловой системы

Элементы управления файловой системой определяют, какие файлы агент может читать и писать.

Монтирование кода только для чтения

Когда агенту нужно анализировать код, но не изменять его, смонтируйте каталог только для чтения:

docker run -v /path/to/code:/workspace:ro agent-image

[!WARNING]

Даже доступ только для чтения к каталогу кода может раскрыть учетные данные. Распространенные файлы для исключения или санитизации перед монтированием:

Файл	Риск
.env, .env.local	Ключи API, пароли базы данных, секреты
~/.git-credentials	Пароли/токены Git в открытом виде
~/.aws/credentials	Ключи доступа AWS
~/.config/gcloud/application_default_credentials.json	Токены Google Cloud ADC
~/.azure/	Учетные данные Azure CLI
~/.docker/config.json	Токены аутентификации реестра Docker
~/.kube/config	Учетные данные кластера Kubernetes
.npmrc, .pypirc	Токены реестра пакетов
*-service-account.json	Ключи учетной записи сервиса GCP
*.pem, *.key	Приватные ключи

Рассмотрите возможность копирования только необходимых исходных файлов или использования фильтрации в стиле .dockerignore.

Записываемые местоположения

Если агенту нужно писать файлы, у вас есть несколько вариантов в зависимости от того, хотите ли вы, чтобы изменения сохранялись:

Для эфемерных рабочих пространств в контейнерах используйте монтирования tmpfs, которые существуют только в памяти и очищаются при остановке контейнера:

docker run \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /workspace:rw,noexec,size=500m \
  agent-image

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

Дополнительное чтение

• Документация по безопасности Claude Code
• Размещение Agent SDK
• Обработка разрешений
• Sandbox runtime
• The Lethal Trifecta for AI Agents
• OWASP Top 10 for LLM Applications
• Docker Security Best Practices
• gVisor Documentation
• Firecracker Documentation