egutierrez
690cbf4a64
Cambios en documentacion para completar fase 7 del issue 0019: - CLAUDE.md: nueva seccion Seguridad con resumen de protecciones - create_agent.md: requisito obligatorio de seccion anti-injection en system prompts + item en checklist de verificacion - create_tool.md: nueva seccion Seguridad con requisitos para tools que hacen I/O (deny-by-default, path traversal, SSRF, command injection, rate limiting) - docs/security.md: documentacion completa de las 5 capas de defensa (sanitizacion, prompt hardening, tool validation, rate limiting, filesystem isolation) con ejemplos de configuracion Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
136 lines
4.3 KiB
Markdown
136 lines
4.3 KiB
Markdown
# 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:**
|
|
|
|
```yaml
|
|
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:**
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
## Activacion
|
|
|
|
Para activar todas las protecciones, añadir al `config.yaml` del agente:
|
|
|
|
```yaml
|
|
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
|