SpyBara
Go Premium

sandboxing.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

329 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Sandboxing

Aprenda cómo la herramienta bash aislada de Claude Code proporciona aislamiento del sistema de archivos y la red para una ejecución de agentes más segura y autónoma.

Descripción general

Claude Code incluye sandboxing nativo para proporcionar un entorno más seguro para la ejecución de agentes mientras reduce la necesidad de solicitudes de permiso constantes. En lugar de pedir permiso para cada comando bash, el sandboxing crea límites definidos de antemano donde Claude Code puede trabajar más libremente con riesgo reducido.

La herramienta bash aislada utiliza primitivas a nivel del sistema operativo para aplicar tanto aislamiento del sistema de archivos como de la red.

Por qué el sandboxing es importante

La seguridad tradicional basada en permisos requiere aprobación constante del usuario para comandos bash. Si bien esto proporciona control, puede llevar a:

  • Fatiga de aprobación: Hacer clic repetidamente en "aprobar" puede hacer que los usuarios presten menos atención a lo que están aprobando
  • Productividad reducida: Las interrupciones constantes ralentizan los flujos de trabajo de desarrollo
  • Autonomía limitada: Claude Code no puede trabajar de manera eficiente cuando espera aprobaciones

El sandboxing aborda estos desafíos mediante:

  1. Definir límites claros: Especifique exactamente qué directorios y hosts de red puede acceder Claude Code
  2. Reducir solicitudes de permiso: Los comandos seguros dentro del sandbox no requieren aprobación
  3. Mantener la seguridad: Los intentos de acceder a recursos fuera del sandbox desencadenan notificaciones inmediatas
  4. Habilitar autonomía: Claude Code puede ejecutarse de manera más independiente dentro de límites definidos

Cómo funciona

Aislamiento del sistema de archivos

La herramienta bash aislada restringe el acceso al sistema de archivos a directorios específicos:

  • Comportamiento de escritura predeterminado: Acceso de lectura y escritura al directorio de trabajo actual y sus subdirectorios
  • Comportamiento de lectura predeterminado: Acceso de lectura a toda la computadora, excepto ciertos directorios denegados
  • Acceso bloqueado: No puede modificar archivos fuera del directorio de trabajo actual sin permiso explícito
  • Configurable: Defina rutas permitidas y denegadas personalizadas a través de la configuración

Puede otorgar acceso de escritura a rutas adicionales usando sandbox.filesystem.allowWrite en su configuración. Estas restricciones se aplican a nivel del sistema operativo (Seatbelt en macOS, bubblewrap en Linux), por lo que se aplican a todos los comandos de subproceso, incluidas herramientas como kubectl, terraform y npm, no solo a las herramientas de archivo de Claude.

Aislamiento de red

El acceso a la red se controla a través de un servidor proxy que se ejecuta fuera del sandbox:

  • Restricciones de dominio: Solo se pueden acceder a dominios aprobados
  • Confirmación del usuario: Las nuevas solicitudes de dominio desencadenan solicitudes de permiso (a menos que allowManagedDomainsOnly esté habilitado, que bloquea automáticamente dominios no permitidos)
  • Soporte de proxy personalizado: Los usuarios avanzados pueden implementar reglas personalizadas en el tráfico saliente
  • Cobertura integral: Las restricciones se aplican a todos los scripts, programas y subprocesos generados por comandos

Aplicación a nivel del sistema operativo

La herramienta bash aislada aprovecha las primitivas de seguridad del sistema operativo:

  • macOS: Utiliza Seatbelt para la aplicación del sandbox
  • Linux: Utiliza bubblewrap para el aislamiento
  • WSL2: Utiliza bubblewrap, igual que Linux

WSL1 no es compatible porque bubblewrap requiere características del kernel solo disponibles en WSL2.

Estas restricciones a nivel del sistema operativo garantizan que todos los procesos secundarios generados por los comandos de Claude Code hereden los mismos límites de seguridad.

Primeros pasos

Requisitos previos

En macOS, el sandboxing funciona de inmediato usando el marco Seatbelt integrado.

En Linux y WSL2, instale primero los paquetes requeridos:

sudo apt-get install bubblewrap socat

WSL1 no admite sandboxing porque carece de las primitivas de espacio de nombres de Linux requeridas. Si ve Sandboxing requires WSL2, actualice su distribución a WSL2 o ejecute Claude Code sin sandboxing.

En WSL2, los comandos aislados no pueden lanzar binarios de Windows como cmd.exe, powershell.exe, o cualquier cosa bajo /mnt/c/. WSL entrega estos al host de Windows a través de un socket Unix, que el sandbox bloquea. Si un comando necesita invocar un binario de Windows, agréguelo a excludedCommands para que se ejecute fuera del sandbox.

Habilitar sandboxing

Puede habilitar el sandboxing ejecutando el comando /sandbox:

/sandbox

Esto abre un menú donde puede elegir entre modos de sandbox. Si faltan dependencias requeridas (como bubblewrap o socat en Linux), el menú muestra instrucciones de instalación para su plataforma.

De forma predeterminada, si el sandbox no puede iniciarse (dependencias faltantes o plataforma no compatible), Claude Code muestra una advertencia y ejecuta comandos sin sandboxing. Para hacer que esto sea un error grave en su lugar, configure sandbox.failIfUnavailable a true. Esto está destinado a implementaciones administradas que requieren sandboxing como una puerta de seguridad.

Modos de sandbox

Claude Code ofrece dos modos de sandbox:

Modo de auto-permitir: Los comandos Bash intentarán ejecutarse dentro del sandbox y se permitirán automáticamente sin requerir permiso. Los comandos que no se pueden aislar (como aquellos que necesitan acceso a la red a hosts no permitidos) vuelven al flujo de permiso regular. Las reglas de denegación explícitas siempre se respetan, y los comandos rm o rmdir que apunten a /, su directorio de inicio u otras rutas críticas del sistema aún desencadenan un aviso de permiso. Las reglas de solicitud se aplican solo a comandos que vuelven al flujo de permiso regular.

Modo de permisos regulares: Todos los comandos bash pasan por el flujo de permiso estándar, incluso cuando están aislados. Esto proporciona más control pero requiere más aprobaciones.

En ambos modos, el sandbox aplica las mismas restricciones de sistema de archivos y red. La diferencia es solo si los comandos aislados se aprueban automáticamente o requieren permiso explícito.

Configurar sandboxing

Personalice el comportamiento del sandbox a través de su archivo settings.json. Consulte Configuración para obtener la referencia de configuración completa.

Otorgar acceso de escritura de subproceso a rutas específicas

De forma predeterminada, los comandos aislados solo pueden escribir en el directorio de trabajo actual. Si comandos de subproceso como kubectl, terraform o npm necesitan escribir fuera del directorio del proyecto, use sandbox.filesystem.allowWrite para otorgar acceso a rutas específicas:

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

Estas rutas se aplican a nivel del sistema operativo, por lo que todos los comandos que se ejecutan dentro del sandbox, incluidos sus procesos secundarios, las respetan. Este es el enfoque recomendado cuando una herramienta necesita acceso de escritura a una ubicación específica, en lugar de excluir la herramienta del sandbox por completo con excludedCommands.

Cuando allowWrite (o denyWrite/denyRead/allowRead) se define en múltiples ámbitos de configuración, los arrays se fusionan, lo que significa que las rutas de cada ámbito se combinan, no se reemplazan. Por ejemplo, si la configuración administrada permite escrituras en /opt/company-tools y un usuario agrega ~/.kube en su configuración personal, ambas rutas se incluyen en la configuración final del sandbox. Esto significa que los usuarios y proyectos pueden extender la lista sin duplicar ni anular las rutas establecidas por ámbitos de mayor prioridad.

Los prefijos de ruta controlan cómo se resuelven las rutas:

Prefijo Significado Ejemplo
/ Ruta absoluta desde la raíz del sistema de archivos /tmp/build se mantiene como /tmp/build
~/ Relativo al directorio de inicio ~/.kube se convierte en $HOME/.kube
./ o sin prefijo Relativo a la raíz del proyecto para configuración de proyecto, o a ~/.claude para configuración de usuario ./output en .claude/settings.json se resuelve a <project-root>/output

El prefijo anterior //path para rutas absolutas sigue funcionando. Si anteriormente usó /path esperando resolución relativa al proyecto, cambie a ./path. Esta sintaxis difiere de las reglas de permiso Read y Edit, que usan //path para absoluto y /path para relativo al proyecto. Las rutas del sistema de archivos del sandbox usan convenciones estándar: /tmp/build es una ruta absoluta.

También puede denegar acceso de escritura o lectura usando sandbox.filesystem.denyWrite y sandbox.filesystem.denyRead. Estos se fusionan con cualquier ruta de las reglas de permiso Edit(...) y Read(...). Para permitir nuevamente la lectura de rutas específicas dentro de una región denegada, use sandbox.filesystem.allowRead, que tiene prioridad sobre denyRead. Cuando allowManagedReadPathsOnly está habilitado en la configuración administrada, solo se respetan las entradas allowRead administradas; las entradas allowRead de usuario, proyecto y local se ignoran. denyRead sigue fusionándose desde todas las fuentes.

Por ejemplo, para bloquear la lectura de todo el directorio de inicio mientras aún se permite la lectura del proyecto actual, agregue esto al .claude/settings.json de su proyecto:

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

El . en allowRead se resuelve a la raíz del proyecto porque esta configuración se encuentra en la configuración del proyecto. Si colocara la misma configuración en ~/.claude/settings.json, . se resolvería a ~/.claude en su lugar, y los archivos del proyecto permanecerían bloqueados por la regla denyRead.

Beneficios de seguridad

Protección contra inyección de solicitud

Incluso si un atacante manipula con éxito el comportamiento de Claude Code a través de inyección de solicitud, el sandbox garantiza que su sistema permanezca seguro:

Protección del sistema de archivos:

  • No puede modificar archivos de configuración críticos como ~/.bashrc
  • No puede modificar archivos a nivel del sistema en /bin/
  • No puede leer archivos que se deniegan en su configuración de permisos de Claude

Protección de red:

  • No puede exfiltrar datos a servidores controlados por atacantes
  • No puede descargar scripts maliciosos de dominios no autorizados
  • No puede realizar llamadas API inesperadas a servicios no aprobados
  • No puede contactar a ningún dominio que no esté explícitamente permitido

Monitoreo y control:

  • Todos los intentos de acceso fuera del sandbox se bloquean a nivel del sistema operativo
  • Recibe notificaciones inmediatas cuando se prueban los límites
  • Puede elegir denegar, permitir una vez o actualizar permanentemente su configuración

Superficie de ataque reducida

El sandboxing limita el daño potencial de:

  • Dependencias maliciosas: Paquetes NPM u otras dependencias con código dañino
  • Scripts comprometidos: Scripts de compilación o herramientas con vulnerabilidades de seguridad
  • Ingeniería social: Ataques que engañan a los usuarios para que ejecuten comandos peligrosos
  • Inyección de solicitud: Ataques que engañan a Claude para que ejecute comandos peligrosos

Operación transparente

Cuando Claude Code intenta acceder a recursos de red fuera del sandbox:

  1. La operación se bloquea a nivel del sistema operativo
  2. Recibe una notificación inmediata
  3. Puede elegir:
    • Denegar la solicitud
    • Permitirla una vez
    • Actualizar su configuración de sandbox para permitirla permanentemente

Limitaciones de seguridad

  • Limitaciones de sandboxing de red: El sistema de filtrado de red funciona restringiendo los dominios a los que se permite que se conecten los procesos. De lo contrario, no inspecciona el tráfico que pasa a través del proxy y los usuarios son responsables de asegurarse de que solo permitan dominios confiables en su política.
  • Escalada de privilegios a través de sockets Unix: La configuración allowUnixSockets puede otorgar inadvertidamente acceso a servicios del sistema poderosos que podrían llevar a omisiones del sandbox. Por ejemplo, si se usa para permitir acceso a /var/run/docker.sock, esto efectivamente otorgaría acceso al sistema host explotando el socket de docker. Se anima a los usuarios a considerar cuidadosamente cualquier socket unix que permitan a través del sandbox.
  • Escalada de permisos del sistema de archivos: Los permisos de escritura del sistema de archivos demasiado amplios pueden permitir ataques de escalada de privilegios. Permitir escrituras en directorios que contienen ejecutables en $PATH, directorios de configuración del sistema o archivos de configuración de shell del usuario (.bashrc, .zshrc) puede llevar a la ejecución de código en diferentes contextos de seguridad cuando otros usuarios o procesos del sistema acceden a estos archivos.
  • Fortaleza del sandbox de Linux: La implementación de Linux proporciona un fuerte aislamiento del sistema de archivos y la red pero incluye un modo enableWeakerNestedSandbox que le permite funcionar dentro de entornos Docker sin espacios de nombres privilegiados. Esta opción debilita considerablemente la seguridad y solo debe usarse en casos donde se aplica aislamiento adicional de otra manera.

Cómo se relaciona el sandboxing con los permisos

El sandboxing y los permisos son capas de seguridad complementarias que funcionan juntas:

  • Permisos controlan qué herramientas puede usar Claude Code y se evalúan antes de que se ejecute cualquier herramienta. Se aplican a todas las herramientas: Bash, Read, Edit, WebFetch, MCP y otras.
  • Sandboxing proporciona aplicación a nivel del sistema operativo que restringe lo que los comandos Bash pueden acceder a nivel del sistema de archivos y la red. Se aplica solo a comandos Bash y sus procesos secundarios.

Las restricciones del sistema de archivos y la red se configuran tanto a través de la configuración del sandbox como de las reglas de permiso:

  • Use sandbox.filesystem.allowWrite para otorgar acceso de escritura de subproceso a rutas fuera del directorio de trabajo
  • Use sandbox.filesystem.denyWrite y sandbox.filesystem.denyRead para bloquear el acceso de subproceso a rutas específicas
  • Use sandbox.filesystem.allowRead para permitir nuevamente la lectura de rutas específicas dentro de una región denyRead
  • Use reglas de denegación Read y Edit para bloquear el acceso a archivos o directorios específicos
  • Use reglas de permitir/denegar WebFetch para controlar el acceso al dominio
  • Use allowedDomains del sandbox para controlar qué dominios pueden alcanzar los comandos Bash
  • Use deniedDomains del sandbox para bloquear dominios específicos incluso cuando un comodín allowedDomains más amplio de otra manera los permitiría

Las rutas de ambas configuraciones sandbox.filesystem y reglas de permiso se fusionan en la configuración final del sandbox.

Este repositorio incluye configuraciones de configuración de inicio para escenarios de implementación comunes, incluidos ejemplos específicos del sandbox. Úselos como puntos de partida y ajústelos según sus necesidades.

Uso avanzado

Configuración de proxy personalizado

Para organizaciones que requieren seguridad de red avanzada, puede implementar un proxy personalizado para:

  • Descifrar e inspeccionar tráfico HTTPS
  • Aplicar reglas de filtrado personalizadas
  • Registrar todas las solicitudes de red
  • Integrar con infraestructura de seguridad existente
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Integración con herramientas de seguridad existentes

La herramienta bash aislada funciona junto con:

Mejores prácticas

  1. Comience restrictivo: Comience con permisos mínimos y expanda según sea necesario
  2. Monitoree registros: Revise los intentos de violación del sandbox para entender las necesidades de Claude Code
  3. Use configuraciones específicas del entorno: Diferentes reglas de sandbox para contextos de desarrollo versus producción
  4. Combine con permisos: Use sandboxing junto con políticas IAM para seguridad integral
  5. Pruebe configuraciones: Verifique que su configuración de sandbox no bloquee flujos de trabajo legítimos

Código abierto

El tiempo de ejecución del sandbox está disponible como un paquete npm de código abierto para usar en sus propios proyectos de agentes. Esto permite que la comunidad más amplia de agentes de IA construya sistemas autónomos más seguros y protegidos. Esto también se puede usar para aislar otros programas que desee ejecutar. Por ejemplo, para aislar un servidor MCP podría ejecutar:

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

Para detalles de implementación y código fuente, visite el repositorio de GitHub.

Limitaciones

  • Sobrecarga de rendimiento: Mínima, pero algunas operaciones del sistema de archivos pueden ser ligeramente más lentas
  • Compatibilidad: Algunas herramientas que requieren patrones de acceso específicos del sistema pueden necesitar ajustes de configuración, o incluso pueden necesitar ejecutarse fuera del sandbox
  • Soporte de plataforma: Admite macOS, Linux y WSL2. WSL1 no es compatible. Se planea soporte nativo de Windows.

Lo que el sandboxing no cubre

El sandbox aísla subprocesos Bash. Otras herramientas operan bajo límites diferentes:

  • Herramientas de archivo integradas: Read, Edit y Write usan el sistema de permisos directamente en lugar de ejecutarse a través del sandbox. Consulte permisos.
  • Uso de computadora: Cuando Claude abre aplicaciones y controla su pantalla, se ejecuta en su escritorio real en lugar de en un entorno aislado. Los mensajes de permiso por aplicación controlan cada aplicación. Consulte uso de computadora en CLI o uso de computadora en Desktop.

Ver también