Seguridad
Una capa útil, con bordes conocidos
ai-jail mantiene a un agente de programación con IA lejos de tus claves, de tu directorio home y del resto de tu máquina. Es un sandbox de procesos, así que comparte tu kernel. No reemplaza a una máquina virtual desechable cuando el código es hostil.
Lo que está hecho para detener
Una página web, un paquete o un archivo del repositorio pueden convencer a un agente de portarse mal. Esto es lo que entonces intenta alcanzar, y no encuentra.
Fuera de alcance
- Tu directorio home y las credenciales que contiene. El agente recibe un home nuevo y vacío, así que
~/.sshy~/.awsno existen ahí dentro. - Los secretos de tu shell. Las variables de entorno se reducen a una lista de permitidos pequeña, así que los tokens exportados se quedan fuera.
- La red. Está apagada, así que nada de lo que el agente lee se puede enviar a ningún lado.
- La memoria compartida del host, tu servidor gráfico y tu portapapeles. La salida del agente pasa por un filtro que descarta las secuencias de terminal de portapapeles y de consulta.
- Escribir en tu terminal. Linux bloquea la llamada
TIOCSTI, que falsifica pulsaciones de teclas, y macOS limita el control de terminal a la única terminal que ai-jail creó para esa ejecución. - Sus propias reglas. Un archivo
.ai-jaildentro de un repositorio no es de confianza: puede endurecer el sandbox y nunca abrirlo.
Dónde termina el muro
La jaula y tu sistema se apoyan en el mismo kernel. Un bug en ese kernel, en un driver o en el backend del sandbox es una forma de rodear el muro, y ai-jail no puede hacer nada al respecto. Una máquina virtual trae su propio kernel, y por eso es la frontera más fuerte.
Lo que sigue en riesgo
- Vulnerabilidades del kernel y de los drivers. Cada proceso aislado habla con el mismo kernel que el resto de tu máquina.
- Bugs en tu emulador de terminal, sobre todo con
--terminal-passthrough, que apaga el filtro de salida. - Defectos en el propio backend del sandbox: bubblewrap, Landlock y seccomp en Linux,
sandbox-execen macOS. - Secretos dentro del proyecto. Un archivo
.enven el repositorio se puede leer salvo que lo enmascares. Mira cómo enmascarar archivos. - Las máscaras cubren solo las rutas que existen cuando arranca el sandbox. Un archivo con secretos creado después, durante la sesión, no queda oculto.
- Canales laterales y algunas clases de comunicación entre procesos.
- En macOS,
sandbox-execestá marcado como obsoleto por Apple y no equivale al aislamiento de Linux. Mira las diferencias en macOS.
Interruptores que abren el muro
Todo lo de abajo está apagado hasta que lo activas, y cada uno le da al agente un acceso real. Cómo configurarlos está en la página Configurar.
| Interruptor | Lo que puede hacer entonces cualquier cosa dentro del sandbox |
|---|---|
--network | Enviar a cualquier parte todo lo que puede leer. El tráfico no tiene restricciones y no hay filtro por dominio. |
--docker | Actuar como root en tu máquina a través del daemon de Docker. |
--x11 | Registrar pulsaciones de teclas y tomar capturas de otras ventanas de X11. |
--systemd-user | Pedirle a tu gestor de usuario de systemd que ejecute servicios en el host. |
--inherit-env | Leer todo el entorno de tu shell, secretos incluidos. |
--agent-state | Usar el login guardado del agente, por ejemplo el ~/.claude de Claude. |
--audio | Grabar y reproducir audio mientras esté activado. |
--no-private-home | Ver tu directorio home real. Es una excepción amplia; mejor mapea la única ruta que necesitas. |
Ante la duda, se niega a arrancar
Un sandbox que arranca en silencio más débil de lo que pediste es peor que uno que se detiene con un error. En estos casos ai-jail se detiene.
- Un archivo de configuración que existe y es inválido o ilegible.
- Un
.ai-jailde proyecto que es un symlink. Un~/.ai-jailglobal que es un symlink se sigue solo hasta un archivo regular del que eres dueño, que nadie más puede escribir y que está fuera del proyecto. --lockdowncuando Landlock, las reglas de sistema de archivos del propio kernel, falta, es parcial o no se puede aplicar.--lockdown --no-landlocktambién se rechaza.--allow-tcp-port. Esa interfaz no puede restringir UDP, así que el flag se acepta por compatibilidad y el arranque falla.- Un
BWRAP_BINque apunta a un binario de bubblewrap que alguien distinto de root pudo haber reemplazado. Se ignora con una advertencia, y sin un bubblewrap de confianza el arranque falla.
Cómo se revisa el proyecto
Un solo mantenedor lleva el proyecto de forma abierta. Abajo está lo que se revisa y lo que no.
- 19
- tests de integración de escape del sandbox que intentan escribir en
/usr, leer~/.ssh, llamar aptraceybpf, y esperan fallar - 720
- tests unitarios en el código fuente en la versión 1.22.0
- 0
- peticiones de red al arrancar. La comprobación de actualizaciones es opt-in con
--update-check
Cómo se hace una versión
- Los tags de versión están firmados, y CI verifica cada uno contra una huella de clave fijada en el repositorio.
- Cada GitHub Action está fijada a un SHA de commit, y las actions están restringidas a una lista de permitidos.
- Las compilaciones usan una toolchain de Rust fijada y dependencias con
--locked. - Los binarios de macOS están firmados y notarizados por Apple.
- Cada archivo comprimido viene con un checksum SHA-256, y el job de publicación los vuelve a comprobar.
Lo que el documento de versiones dice que todavía falta
- Los secretos de firma y publicación todavía se guardan a nivel de repositorio y deberían pasar a los entornos de publicación.
- Todavía ningún ruleset obliga a que cada tag
v*esté firmado. - Las versiones inmutables (immutable releases) no están activadas.
- La publicación en crates.io todavía usa un token. El trusted publishing está planeado.
- Con un solo mantenedor no hay un segundo revisor para los cambios ni para las versiones.
Reportar una vulnerabilidad
No abras un issue público. Usa el reporte privado de vulnerabilidades de GitHub, incluye los pasos para reproducirla y las versiones afectadas, y da tiempo para coordinar una corrección.
Preguntas frecuentes
¿El agente puede escaparse?
Los valores por defecto están hechos y probados para bloquear las rutas habituales: archivos, entorno, red e IPC del host. Un bug del kernel, de un driver, de la terminal o del backend del sandbox todavía podría dejarlo salir. Todo sandbox de procesos tiene ese límite, y por eso el código hostil va en una VM desechable.
¿Es seguro ejecutarlo con la red activada?
Es más seguro que ejecutar el agente sin jaula, porque tus claves y tu directorio home siguen sin estar ahí para enviarlos. Todo lo que el agente puede leer, lo puede enviar, y ai-jail no tiene filtrado por dominio. Enmascara primero los secretos dentro del proyecto. Mira cómo enmascararlos.
¿Ha sido auditado?
Internamente, antes de la 1.0, con los informes publicados en el repositorio. No ha tenido ninguna auditoría de terceros. El código es abierto bajo GPL 3.0, y los reportes privados de vulnerabilidades son bienvenidos.
Pon a tu agente tras las rejas
ai-jail es un único binario que no necesita daemon ni root. Añades una palabra delante del comando que ya usas.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude