agents_and_robots/dev/issues/0043-father-bot-security-guardrails.md

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