AgentGuard

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.

Cómo funciona

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.

Inicio rápido

Compilar

go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/

Ambos binarios deben estar en el mismo directorio.

Crear una política

agentguard init

Esto crea .agentguard/policy.yaml en el directorio actual. Edítalo para adaptarlo a tus necesidades.

Ejecutar un agente (TUI interactiva)

agentguard run -- python my_agent.py

La TUI toma el control de la terminal y muestra:

• Flujo de actividad en vivo (cada acción interceptada)
• Solicitudes de aprobación para comandos ambiguos (presiona Y/N/A/B)
• Eventos de permitir/denegar red del proxy
• Eventos de violación del sandbox
• stdout/stderr del agente (alternar con Tab)

Ejecutar un agente (sin interfaz)

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

Referencia de CLI

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

Archivo de política

Las políticas son archivos YAML que definen lo que el agente puede y no puede hacer. AgentGuard verifica tres ubicaciones (en orden):

1. ./.agentguard/policy.yaml (local del proyecto)
2. ~/.agentguard/policy.yaml (global del usuario)
3. Valores predeterminados integrados

Ejemplo de política

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"

Orden de evaluación de reglas

1. Reglas de denegación específicas — se verifican primero. Si coinciden, la acción se bloquea inmediatamente.
2. Reglas de permiso — se verifican en segundo lugar. Si coinciden, la acción se permite.
3. Reglas de denegación general (por ejemplo, deny network *) — se verifican en tercer lugar. Actúan como una denegación predeterminada.
4. Sin coincidencia — se solicita al humano (TUI) o se deniega automáticamente (headless).

Tipos de reglas

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.

Controles de la TUI

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

Lo que captura cada capa

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í

Arquitectura