diff --git a/dev/issues/0043-father-bot-security-guardrails.md b/dev/issues/0043-father-bot-security-guardrails.md new file mode 100644 index 0000000..460223b --- /dev/null +++ b/dev/issues/0043-father-bot-security-guardrails.md @@ -0,0 +1,131 @@ +# 0043 — Guardrails de seguridad para Father Bot + +**Estado:** pendiente + +## Objetivo + +Implementar capas adicionales de seguridad para Father Bot (el agente que crea otros agentes). Dado que tiene acceso de escritura al repositorio y puede ejecutar scripts, necesita restricciones mas alla del ACL admin-only basico que se configura en el issue 0037. + +## Contexto + +- Father Bot usa `provider: claude-code` con `bypassPermissions` y `working_dir` apuntando a la raiz del proyecto. Esto le da acceso completo de lectura/escritura. +- Actualmente la unica barrera es el ACL admin-only de `security/permissions.yaml`. +- El sistema de seguridad centralizado (issue 0024) ya soporta grupos de usuarios y agentes, pero no tiene restricciones dinamicas basadas en env vars ni path-scoping fino. +- Solo el propietario del servidor accede actualmente, pero el sistema debe estar preparado para multiples desarrolladores. + +## Arquitectura + +### 1. Visibilidad basada en .env (developer allowlist) + +Nuevo env var `FATHER_BOT_ALLOWED_USERS` que lista los Matrix user IDs autorizados para interactuar con Father Bot. Esto complementa (no reemplaza) el ACL centralizado. + +``` +# .env +FATHER_BOT_ALLOWED_USERS="@admin:matrix-af2f3d.organic-machine.com,@dev2:matrix-af2f3d.organic-machine.com" +``` + +**Implementacion:** +- `agents/_specials/father-bot/config.yaml` referencia el env var +- El runtime valida `FATHER_BOT_ALLOWED_USERS` antes de procesar cualquier mensaje +- Si el env var esta vacio o no existe, DENEGAR todo (deny-by-default) +- Log de nivel WARN por cada intento denegado + +### 2. Path scoping para el subprocess claude-code + +Restringir las operaciones de escritura del subprocess `claude -p` a paths seguros: + +**Paths permitidos (escritura):** +- `agents/` — crear nuevos agentes +- `agents/_specials/` — si se crean specials +- `cmd/launcher/main.go` — blank imports + +**Paths permitidos (lectura):** +- Todo el repositorio (necesita leer templates, config, rules) + +**Paths prohibidos (lectura y escritura):** +- `.env` — contiene secrets +- `security/` — no debe auto-modificar permisos +- `.git/` — no debe tocar el historial + +**Implementacion:** +- Instrucciones en el system prompt (primera linea de defensa) +- Validacion en un wrapper/hook que el subprocess claude-code respete +- Audit log de cada archivo tocado + +### 3. Rate limiting de operaciones de creacion + +- Maximo 3 agentes por hora (configurable via env var `FATHER_BOT_MAX_CREATES_PER_HOUR`) +- Contador persistido en memoria del agente o en SQLite +- Si se excede, rechazar con mensaje explicativo + +### 4. Audit trail extendido + +- Log estructurado de cada operacion de creacion: + - Timestamp, usuario solicitante, tipo (agent/robot), ID creado, resultado (exito/fallo) + - Scripts ejecutados y exit codes + - Archivos creados/modificados +- Opcionalmente enviar resumen a un room de auditoria (`security.audit.log_to_room`) + +### 5. Validacion de agentes creados + +Antes de reiniciar el launcher, verificar que el agente creado: +- No tiene `security.sanitize.enabled: false` (debe heredar defaults seguros) +- No tiene `tools.ssh.allowed_commands: ["*"]` (no wildcard en SSH) +- No tiene `tools.file_ops.allowed_paths: ["/"]` (no root access) +- Tiene seccion de seguridad en el system prompt +- Compila sin errores + +## Tareas + +### Fase 1 — Developer allowlist + +- [ ] **1.1** Implementar validacion de `FATHER_BOT_ALLOWED_USERS` en el runtime de father-bot +- [ ] **1.2** Deny-by-default si env var vacio +- [ ] **1.3** Tests unitarios para la validacion + +### Fase 2 — Path scoping + +- [ ] **2.1** Definir allowlist/denylist de paths en config.yaml +- [ ] **2.2** Implementar validacion post-ejecucion (verificar que solo se tocaron paths permitidos) +- [ ] **2.3** Tests para path validation + +### Fase 3 — Rate limiting + +- [ ] **3.1** Implementar contador de creaciones por hora +- [ ] **3.2** Rechazar con mensaje si se excede el limite +- [ ] **3.3** Tests para rate limiting + +### Fase 4 — Audit trail + +- [ ] **4.1** Extender audit log con eventos de creacion de agentes +- [ ] **4.2** Opcion de enviar a room de auditoria +- [ ] **4.3** Tests para audit events + +### Fase 5 — Validacion de agentes creados + +- [ ] **5.1** Implementar validador de config de agente creado +- [ ] **5.2** Rechazar creacion si la config viola politicas de seguridad +- [ ] **5.3** Tests para validador + +## Decisiones de diseno + +1. **Deny-by-default en env var vacio**: si nadie configura `FATHER_BOT_ALLOWED_USERS`, father-bot no responde a nadie. Esto previene que un deploy sin configurar exponga el agente. + +2. **Path scoping via system prompt + validacion**: la primera linea de defensa es el system prompt (instrucciones explicitas). La segunda es validacion post-ejecucion que verifica que archivos fueron tocados. + +3. **Rate limiting simple**: no necesitamos un sistema sofisticado. Un contador en memoria con reset por hora es suficiente para la frecuencia esperada de creacion de agentes. + +4. **Validacion de config creada**: previene escalacion de privilegios indirecta (crear un agente con mas permisos de los debidos). + +## Prerequisitos + +- Issue 0037 completado (father-bot funcional) +- Sistema de permisos centralizado (issue 0024) — ya completado + +## Riesgos + +| Riesgo | Mitigacion | +|--------|------------| +| Env var no configurado en deploy | Deny-by-default: father-bot inactivo sin config | +| Path scoping evadido via symlinks | Resolver symlinks antes de validar (como en tools/file/) | +| Rate limit reseteado al reiniciar | Aceptable: es defensa en profundidad, no la unica barrera | diff --git a/dev/issues/README.md b/dev/issues/README.md index b9c7ddc..03db569 100644 --- a/dev/issues/README.md +++ b/dev/issues/README.md @@ -53,3 +53,4 @@ afectados y notas de implementacion. | 40 | Soporte para mensajes de voz (STT) | [0040-voice-messages-stt.md](0040-voice-messages-stt.md) | pendiente | | 41 | Videollamadas con agentes via LiveKit | [0041-livekit-videocall.md](0041-livekit-videocall.md) | pendiente | | 42 | Auto-avatar con proveedores gratuitos | [0042-auto-avatar-providers.md](completed/0042-auto-avatar-providers.md) | completado | +| 43 | Guardrails de seguridad para Father Bot | [0043-father-bot-security-guardrails.md](0043-father-bot-security-guardrails.md) | pendiente |