Sandboxing

El modo sandbox de Theus ejecuta los comandos de Bash y las herramientas dentro de un entorno aislado del sistema operativo, con restricciones de archivos y de red aplicadas por el kernel.

Qué es

Cuando el sandbox está activo, Theus no lanza los comandos directamente contra tu máquina: los ejecuta dentro de una capa de aislamiento del sistema operativo. Esa capa limita a qué archivos puede leer y escribir un comando, y a qué hosts de red puede conectarse. Si un comando intenta salirse de esos límites, la ejecución se marca como una violación del sandbox en lugar de tocar tu sistema.

El sandbox se aplica a la herramienta de Bash de Theus. El aislamiento lo gestiona SandboxManager (utils/sandbox/sandbox-adapter.ts), y la decisión de aislar cada comando concreto la toma shouldUseSandbox() (tools/BashTool/shouldUseSandbox.ts).

Plataformas soportadas

El sandbox solo funciona en plataformas compatibles. En cualquier otra plataforma queda desactivado de forma silenciosa y los comandos se ejecutan sin aislar.

Además del sistema operativo, deben estar presentes las dependencias del sandbox. En Linux/WSL, si faltan, Theus sugiere instalarlas (por ejemplo apt install bubblewrap socat). Si las dependencias faltan, isSandboxingEnabled() devuelve falso y no se aplica aislamiento.

Los modos

El panel de configuración del sandbox ofrece tres modos:

Sandbox estricto vs. alternativa sin sandbox

Cuando el sandbox está activo, existe una opción de fallback a ejecución sin aislar, controlada por allowUnsandboxedCommands:

• Fallback permitido (por defecto): un comando que no puede ejecutarse dentro del sandbox —o que se marca explícitamente con dangerouslyDisableSandbox— puede correr sin aislamiento, pasando por el flujo de permisos habitual.
• Sandbox estricto (allowUnsandboxedCommands: false): no se permite salirse del sandbox. Un comando que no pueda aislarse no se ejecuta. Es la postura más segura.

En modo estricto, aunque el modelo pida dangerouslyDisableSandbox, shouldUseSandbox() sigue aislando el comando: solo se salta el sandbox cuando ambas condiciones se cumplen (override explícito y fallback permitido por política).

Configurar el sandboxing

La forma recomendada es el comando slash dentro de Theus:

/sandbox

Muestra el estado actual (activado, auto-permitir, fallback, o "gestionado" si lo fija una política) y abre el panel para elegir el modo. Para excluir un patrón de comando del sandbox:

/sandbox exclude "npm run test:*"

Los comandos excluidos se ejecutan sin aislar. Es una comodidad para herramientas que el sandbox rompe (por ejemplo constructores que necesitan red o rutas amplias), no un control de seguridad: quien pueda editar la configuración puede añadir exclusiones.

Ajustes de configuración

Los ajustes viven bajo la clave sandbox de tu configuración de Theus:

Restricciones de archivos y de red

Dentro del sandbox se aplican restricciones que Theus resume al modelo en cada petición:

• Lectura de archivos: lista de rutas denegadas, con posibles excepciones permitidas dentro de lo denegado.
• Escritura de archivos: lista de rutas permitidas, con posibles denegaciones dentro de lo permitido.
• Red: hosts permitidos (allowedHosts) y hosts denegados (deniedHosts). Una configuración gestionada puede limitar la red solo a dominios aprobados.
• Sockets Unix: lista de sockets permitidos (network.allowUnixSockets / allowAllUnixSockets).

Implicaciones de seguridad

• El sandbox reduce el radio de daño de un comando: sin él, cualquier comando de Bash tiene el acceso completo de tu usuario a archivos y red.
• Auto-permitir intercambia prompts por aislamiento. Con auto-permitir, dejas de confirmar cada comando; la protección pasa a depender de que el aislamiento aguante. Úsalo con las restricciones de archivos y red bien definidas.
• El sandbox estricto (allowUnsandboxedCommands: false) es la postura más defensiva: nada se ejecuta fuera del aislamiento.
• Las exclusiones y excludedCommands no son un límite de seguridad. Son comodidad; cualquiera que edite la configuración puede ampliarlas.
• No confíes en el aislamiento donde no existe. En plataformas no soportadas o sin dependencias, el sandbox queda inactivo. Usa failIfUnavailable: true si necesitas garantizar que nunca se ejecute sin protección.