From 690cbf4a644957dcc2c2f76c44aad1738aacf402 Mon Sep 17 00:00:00 2001 From: Enmanuel Date: Sat, 7 Mar 2026 19:52:27 +0000 Subject: [PATCH] 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 --- .claude/CLAUDE.md | 16 ++++ .claude/rules/create_agent.md | 2 + .claude/rules/create_tool.md | 12 +++ docs/security.md | 135 ++++++++++++++++++++++++++++++++++ 4 files changed, 165 insertions(+) create mode 100644 docs/security.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b282059..271db94 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -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 diff --git a/.claude/rules/create_agent.md b/.claude/rules/create_agent.md index 5763c8a..4578467 100644 --- a/.claude/rules/create_agent.md +++ b/.claude/rules/create_agent.md @@ -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_`, `MATRIX_PASSWORD_`, `PICKLE_KEY_`, `SSSS_RECOVERY_KEY_` - [ ] `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 diff --git a/.claude/rules/create_tool.md b/.claude/rules/create_tool.md index d1754f5..0f32b4b 100644 --- a/.claude/rules/create_tool.md +++ b/.claude/rules/create_tool.md @@ -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/`. diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..13b2873 --- /dev/null +++ b/docs/security.md @@ -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/` > `agents//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