Configurar la herramienta Bash aislada

​

Primeros pasos

/sandbox

​

Configurar Linux y WSL2

• bubblewrap: la herramienta de sandboxing sin privilegios que aplica aislamiento del sistema de archivos
• socat: el relé utilizado para enrutar el tráfico de red a través del proxy del sandbox

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

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

sudo systemctl reload apparmor

​

Modos de sandbox

• Las reglas de denegación explícitas siempre se respetan
• Los comandos rm o rmdir que apunten a /, su directorio de inicio u otras rutas críticas del sistema aún desencadenan una solicitud de permiso
• Las reglas de solicitud con alcance de contenido como Bash(git push *) aún fuerzan una solicitud incluso para comandos aislados
• Una regla de solicitud Bash simple, o la forma equivalente Bash(*), se omite para comandos que se ejecutan aislados; aún se aplica a comandos que vuelven al flujo de permiso regular

​

Configurar sandboxing

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

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

​

Proteger credenciales

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

​

Cómo funciona el sandboxing

​

Aislamiento del sistema de archivos

• Comportamiento de escritura predeterminado: acceso de lectura y escritura al directorio de trabajo actual y sus subdirectorios, más el directorio temporal de sesión al que apunta $TMPDIR
• Comportamiento de lectura predeterminado: acceso de lectura a toda la computadora, excepto ciertos directorios denegados. Tenga en cuenta que este comportamiento predeterminado aún permite leer archivos de credenciales como ~/.aws/credentials y ~/.ssh/. Utilice sandbox.credentials para bloquear lecturas de estos archivos y desconfigurar variables de entorno secretas, o agregue las rutas a denyRead.
• Acceso bloqueado: no puede modificar archivos fuera del directorio de trabajo actual y el directorio temporal de sesión sin permiso explícito, incluidos archivos de configuración de shell como ~/.bashrc y binarios del sistema en /bin/
• Git worktrees: cuando el directorio de trabajo es un git worktree vinculado, el sandbox también permite escrituras en el directorio compartido .git del repositorio principal para que comandos como git commit puedan actualizar referencias e índices. Las escrituras a hooks/ y config dentro de ese directorio permanecen denegadas.
• Configurable: defina rutas permitidas y denegadas personalizadas a través de la configuración

​

Aislamiento de red

• Restricciones de dominio: no hay dominios pre-permitidos. La primera vez que un comando necesita un nuevo dominio, Claude Code solicita aprobación. A partir de v2.1.191, elegir Sí permite el host para el resto de la sesión actual, por lo que las conexiones posteriores al mismo host no solicitan nuevamente. Pre-permita dominios con allowedDomains para evitar la solicitud por completo.
• Bloqueo administrado: si allowManagedDomainsOnly se establece en la configuración administrada, los dominios no permitidos se bloquean automáticamente en lugar de solicitar, y solo se honran allowedDomains de la configuración administrada.
• 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

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

​

Cómo se relaciona el sandboxing con los permisos y modos de permiso

​

Reglas de permiso

• Reglas de permiso 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.

​

Modos de permiso

​

Configurar el sandbox para su organización

​

Aplicar sandboxing con configuración administrada

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

• failIfUnavailable: una dependencia faltante como bubblewrap en Linux bloquea que Claude Code se inicie en lugar de mostrar una advertencia y volver a la ejecución sin aislar
• allowUnsandboxedCommands: false: la salida de emergencia dangerouslyDisableSandbox se ignora, por lo que los comandos que fallan bajo el sandbox no pueden reintentarse fuera de él

​

Evitar que los desarrolladores amplíen la política

​

Configuración de proxy personalizado

• 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
    }
  }
}

​

Solución de problemas

• Los comandos fallan con un error de host no permitido: muchas herramientas CLI necesitan alcanzar hosts específicos. Otorgar permiso cuando se solicita agrega el host a su lista de permitidos para que la herramienta se ejecute dentro del sandbox en el futuro.
• jest se cuelga o falla: watchman es incompatible con el sandbox. Ejecute jest --no-watchman en su lugar.
• Las CLI basadas en Go fallan en la verificación de TLS en macOS: herramientas como gh, gcloud y terraform pueden fallar en la verificación de TLS bajo Seatbelt. Liste estas herramientas en excludedCommands para ejecutarlas fuera del sandbox. Si está usando httpProxyPort con un proxy MITM y CA personalizado, establezca enableWeakerNetworkIsolation en true en su lugar.
• Los comandos open, osascript o los flujos de autenticación basados en navegador fallan con el error -600 en macOS: el sandbox bloquea Apple Events de forma predeterminada. Establezca allowAppleEvents en true en su configuración de usuario, administrada o CLI para permitirlos. La configuración del proyecto se ignora para esta clave. Habilitarlo elimina el aislamiento de ejecución de código, ya que los comandos aislados pueden entonces lanzar otras aplicaciones sin aislar sin solicitud del usuario y enviar comandos AppleScript a aplicaciones en ejecución, sujeto a la solicitud de consentimiento de automatización de macOS (TCC). Alternativamente, agregue el comando a excludedCommands para ejecutarlo fuera del sandbox.
• Los comandos docker fallan: docker es incompatible con el sandbox. Agregue docker * a excludedCommands para ejecutarlo fuera del sandbox.
• Bubblewrap falla al iniciarse dentro de un contenedor: en un contenedor sin privilegios, bubblewrap no puede montar un sistema de archivos /proc nuevo. Establezca enableWeakerNestedSandbox en true para que el sandbox interno monte el /proc existente del contenedor en su lugar. Solo use esta configuración cuando el contenedor externo ya proporcione el límite de aislamiento que necesita, ya que expone información de proceso a comandos aislados que un montaje /proc nuevo ocultaría.
• Filtro seccomp en Linux: el filtro seccomp es necesario para bloquear sockets de dominio Unix. La pestaña Dependencies en /sandbox muestra si está disponible. Si falta, ejecute npm install -g @anthropic-ai/sandbox-runtime para instalar el asistente.
• --dangerously-skip-permissions falla como root: esta bandera se bloquea cuando se ejecuta como root o a través de sudo en Linux y macOS, porque el acceso root combinado sin solicitudes de permiso puede modificar cualquier archivo o servicio en el sistema. La verificación se omite automáticamente dentro de un sandbox reconocido. Para ejecutar de manera autónoma en un contenedor, use la configuración contenedor de desarrollo, que ejecuta Claude Code como un usuario no root.

​

Limitaciones

​

Limitaciones de seguridad

• Filtrado de red: el sistema de filtrado de red funciona restringiendo los dominios a los que se permite que se conecten los procesos. El proxy integrado no termina ni realiza inspección de TLS en el tráfico saliente, por lo que el contenido de las conexiones cifradas no se examina. Usted es responsable de asegurarse de que solo se 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, permitir acceso a /var/run/docker.sock efectivamente otorga acceso al sistema host a través del socket de Docker. Considere cuidadosamente cualquier socket Unix que permita 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 como .bashrc o .zshrc puede llevar a 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, o en hosts Linux donde los espacios de nombres de usuario sin privilegios están deshabilitados por sysctl. Esta opción debilita considerablemente la seguridad y solo debe usarse cuando se aplica aislamiento adicional de otra manera.
• Apple Events en macOS: el sandbox de macOS bloquea Apple Events de forma predeterminada. La configuración allowAppleEvents levanta esta restricción para que herramientas como open y osascript funcionen, pero elimina el aislamiento de ejecución de código: los comandos aislados pueden lanzar otras aplicaciones sin aislar sin solicitud del usuario, y pueden enviar comandos AppleScript a aplicaciones en ejecución, sujeto al aviso de consentimiento de automatización por aplicación de macOS (TCC). Solo se honra desde configuración de usuario, administrada o CLI. La configuración del proyecto no puede habilitarla.
• Archivos de configuración protegidos: el sandbox automáticamente deniega acceso de escritura a los archivos settings.json de Claude Code en cada ámbito y al directorio de configuración administrada, por lo que un comando aislado no puede modificar su propia política.

​

Compatibilidad de plataforma y herramienta

• Soporte de plataforma: admite macOS, Linux y WSL2. WSL1 y Windows nativo no son compatibles.
• Sobrecarga de rendimiento: mínima, pero algunas operaciones del sistema de archivos pueden ser ligeramente más lentas.
• Compatibilidad de herramienta: algunas herramientas que requieren patrones de acceso específicos del sistema pueden necesitar ajustes de configuración, o pueden necesitar ejecutarse fuera del sandbox.

​

Alcance

• 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. Las solicitudes de permiso por aplicación controlan cada aplicación. Consulte uso de computadora en CLI o uso de computadora en Desktop.
• Variables de entorno: los comandos Bash aislados heredan el entorno del proceso padre de forma predeterminada, incluidas las credenciales establecidas allí. Use sandbox.credentials para eliminar variables específicas para comandos aislados, o establezca CLAUDE_CODE_SUBPROCESS_ENV_SCRUB para eliminar credenciales de Anthropic y proveedores de nube de todos los subprocesos.
• Subagentes: los subagentes se ejecutan en el mismo proceso que la sesión padre y usan la misma configuración de sandbox. Los comandos Bash dentro de un subagente están aislados cuando el sandboxing está habilitado en la sesión padre.

​

Ver también

• Entornos sandbox: compare el sandbox integrado con contenedores de desarrollo, contenedores y máquinas virtuales
• Seguridad: características de seguridad integral y mejores prácticas
• Permisos: configuración de permisos y control de acceso
• Configuración: referencia de configuración completa
• Referencia de CLI: opciones de línea de comandos