agents_and_robots/docs/security.md

Seguridad — Protecciones contra prompt injection y abuso de tools

Este documento describe las capas de defensa implementadas para proteger los agentes Matrix contra ataques de prompt injection y abuso de herramientas.

Capas de defensa

La estrategia es defensa en profundidad: multiples capas independientes, ninguna es la unica barrera.

Mensaje del usuario
  |
  v
1. Input sanitization (pkg/sanitize/) — detecta patrones de injection
  |
  v
2. System prompt hardening — instrucciones anti-manipulation al LLM
  |
  v
3. Tool validation (deny-by-default) — cada tool valida sus inputs
  |
  v
4. Rate limiting (tools/registry.go) — limite de tool calls por room
  |
  v
5. RBAC (pkg/acl/) — control de acceso por usuario/rol

1. Sanitizacion de input (pkg/sanitize/)

Funciones puras que detectan patrones de prompt injection en mensajes entrantes.

Configuracion:

security:
  sanitize:
    enabled: true
    mode: warn          # warn | strip | reject
    min_severity: medium  # low | medium | high
    disabled_patterns: []  # nombres de patrones a ignorar

Modos:

• warn: loguea warnings pero no modifica el mensaje (default)
• strip: elimina las secciones sospechosas del mensaje
• reject: rechaza el mensaje completamente con respuesta de error

Patrones detectados:

• Delimitadores de sistema: <|system|>, <|assistant|>, [INST]
• Frases de override: "ignore previous instructions", "you are now", etc.
• Intentos de exfiltracion: "repeat your instructions", "show me your prompt"

Los patrones estan en pkg/sanitize/patterns.go. Son extensibles.

2. Hardening de system prompts

Todos los system prompts deben incluir una seccion de seguridad obligatoria. Template en .claude/templates/security-prompt.md.

Las instrucciones cubren:

• Rechazo de acciones fuera del rol
• Proteccion del system prompt (no revelar)
• Rechazo de comandos destructivos
• Validacion de coherencia contextual
• Resistencia a redefinicion de identidad

3. Validacion en tools (deny-by-default)

Cada tool que hace I/O valida sus inputs de forma independiente.

tools/file/ — read_file

• Deny-by-default: si AllowedPaths esta vacio, todo denegado
• Path traversal: resuelve symlinks con filepath.EvalSymlinks, valida que el path este dentro de los permitidos
• Prefix confusion: usa separador de directorio para evitar que /allowed/path matchee /allowed/pathevil

tools/ssh/ — ssh_command

• AllowedCommands: allowlist de prefijos de comandos. Si esta definida, solo los comandos que matcheen se ejecutan
• ForbiddenCommands: blocklist como segunda capa
• Validacion de sintaxis: detecta pipes |, subshells $(), redirects >, chains &&/||/;
• AllowedTargets: solo los hosts configurados

tools/http/ — http_get, http_post

• AllowedDomains: solo los dominios configurados
• SSRF protection: resuelve DNS y bloquea IPs privadas (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local (169.254.0.0/16) y metadata (169.254.169.254)

tools/matrix/ — matrix_send

• AllowedRooms: si esta configurado, solo permite enviar a rooms especificos

4. Rate limiting

Limite de tool calls por room por minuto. Previene abuso repetitivo.

Configuracion:

security:
  tool_rate_limit:
    enabled: true
    max_calls_per_min: 10     # default 10
    cleanup_interval_s: 60    # limpieza de entries expiradas

Implementado en tools/ratelimit.go como sliding window per room. El registry verifica antes de ejecutar cada tool.

5. Aislamiento de filesystem

storage.base_path permite mover datos de runtime fuera del arbol del proyecto:

storage:
  base_path: /var/lib/agents/mi-bot  # o via $AGENTS_DATA_DIR

Prioridad: config base_path > $AGENTS_DATA_DIR/<id> > agents/<id>/data/ (default).

Esto previene que tools como read_file accedan accidentalmente a codigo fuente, .env, o configs del proyecto.

6. Aislamiento de claude -p (provider claude-code)

Cuando un agente usa el provider claude-code, el subproceso claude -p se ejecuta en un directorio de trabajo aislado, no en la raiz del repositorio.

Configuracion:

llm:
  primary:
    claude_code:
      working_dir: "/tmp/claude-agents/mi-bot"  # directorio aislado

Comportamiento:

• Si working_dir esta configurado: se crea el directorio automaticamente con MkdirAll y se usa como CWD del subproceso
• Si working_dir esta vacio: se crea un directorio temporal (os.MkdirTemp) y se loguea un WARN para que el operador lo note
• Nunca se hereda el CWD del launcher (raiz del repo)

Esto evita que el subproceso claude -p tenga acceso de lectura/escritura al codigo fuente del proyecto, incluso con permission_mode: bypassPermissions.

Implementado en shell/llm/claudecode.go → resolveWorkDir().

Activacion

Para activar todas las protecciones, añadir al config.yaml del agente:

security:
  sanitize:
    enabled: true
    mode: warn
  tool_rate_limit:
    enabled: true
    max_calls_per_min: 10

Y asegurarse de que:

• Las tools tienen allowlists configuradas (no vacias si se quieren usar)
• El system prompt incluye la seccion de seguridad
• storage.base_path apunta fuera del proyecto en produccion
• claude_code.working_dir apunta fuera del repo si se usa el provider claude-code