docs: documentacion de seguridad y requisitos en reglas operativas
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>
This commit is contained in:
@@ -88,6 +88,22 @@ Guias detalladas en `.claude/rules/index.md`:
|
||||
- CGO_ENABLED=0 (pure-Go SQLite via modernc, shim en `cmd/launcher/sqlite.go`)
|
||||
- Secrets via env vars (`.env.example`), nunca commitear `.env`
|
||||
|
||||
## Seguridad
|
||||
|
||||
Protecciones contra prompt injection y abuso de tools (issue 0019):
|
||||
|
||||
- **`pkg/sanitize/`** — deteccion pura de patrones de injection en mensajes entrantes
|
||||
- **Tools deny-by-default** — allowlist vacia = todo denegado (file, ssh, http, matrix)
|
||||
- **Path traversal** — EvalSymlinks + prefix validation en `tools/file/`
|
||||
- **SSRF** — bloqueo de IPs privadas en `tools/http/`
|
||||
- **SSH** — AllowedCommands allowlist + validacion de sintaxis shell en `tools/ssh/`
|
||||
- **Rate limiting** — por room en `tools/registry.go` via `security.tool_rate_limit`
|
||||
- **System prompts** — seccion anti-injection obligatoria (template en `.claude/templates/security-prompt.md`)
|
||||
- **`storage.base_path`** — permite aislar datos de runtime fuera del arbol del proyecto
|
||||
|
||||
Config YAML relevante: `security.sanitize.*`, `security.tool_rate_limit.*`, `storage.base_path`
|
||||
Documentacion completa: `docs/security.md`
|
||||
|
||||
## Preferencias
|
||||
|
||||
- Espanol en configs/comentarios de dominio, ingles en codigo Go
|
||||
|
||||
@@ -110,6 +110,7 @@ Escribir el system prompt completo. Debe incluir:
|
||||
- **Capacidades**: qué puede hacer (incluir tools si `tool_use.enabled: true`)
|
||||
- **Estilo**: idioma, tono, formato de respuestas
|
||||
- **Restricciones**: qué NO debe hacer
|
||||
- **Seguridad** (obligatorio): copiar la seccion de `.claude/templates/security-prompt.md` al final del prompt. Esta seccion protege contra prompt injection.
|
||||
|
||||
Ejemplo de referencia: `agents/asistente-2/prompts/system.md`
|
||||
|
||||
@@ -152,6 +153,7 @@ Checklist a verificar antes de considerar el agente listo:
|
||||
- [ ] `cmd/launcher/main.go` tiene import + entry en rulesRegistry con el mismo ID
|
||||
- [ ] `.env` contiene: `MATRIX_TOKEN_<NORM>`, `MATRIX_PASSWORD_<NORM>`, `PICKLE_KEY_<NORM>`, `SSSS_RECOVERY_KEY_<NORM>`
|
||||
- [ ] `prompts/system.md` tiene contenido real (no el stub)
|
||||
- [ ] `prompts/system.md` incluye la seccion de seguridad anti-injection (de `.claude/templates/security-prompt.md`)
|
||||
- [ ] Si `tool_use.enabled: true`, el prompt menciona las tools disponibles
|
||||
|
||||
## Arranque y verificación
|
||||
|
||||
@@ -64,3 +64,15 @@ Asegurarse de que `llm.tool_use.enabled: true` y la sección relevante de `tools
|
||||
- **Usar `getString()`**: helper del package para extraer strings de args de forma segura.
|
||||
- **Param types válidos**: "string", "number", "integer", "boolean", "object", "array" (JSON Schema types).
|
||||
- **Descripción clara**: el LLM decide cuándo usar la tool basándose en el Description del Def.
|
||||
|
||||
## Seguridad — requisitos obligatorios
|
||||
|
||||
Toda tool que haga I/O externo debe implementar protecciones:
|
||||
|
||||
- **Deny-by-default**: si la tool tiene una allowlist (AllowedPaths, AllowedDomains, AllowedCommands, etc.), un allowlist vacio debe denegar todo, no permitir todo.
|
||||
- **Path traversal**: para tools que aceptan rutas de archivo, resolver symlinks con `filepath.EvalSymlinks` y validar que el path resuelto este dentro de los paths permitidos. Proteger contra `../` y prefix confusion.
|
||||
- **SSRF protection**: para tools que hacen HTTP, resolver la IP del dominio antes de conectar y bloquear IPs privadas (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16).
|
||||
- **Command injection**: para tools que ejecutan comandos, validar sintaxis shell (no permitir pipes `|`, subshells `$()`, redirects `>`, chains `&&`/`||`/`;`) a menos que esten explicitamente permitidos.
|
||||
- **Rate limiting**: las tools estan sujetas a rate limiting por room via `security.tool_rate_limit` en el config. No se necesita implementar nada en la tool — el registry lo maneja automaticamente.
|
||||
|
||||
Referencia de implementaciones: `tools/file/`, `tools/ssh/`, `tools/http/`.
|
||||
|
||||
@@ -0,0 +1,135 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user