Servicio SaaS-Commands del Local Agent (terminal/agent/core/saas_commands.py)

Propósito

core/saas_commands.py es el módulo del Local Agent que abre la conexión WebSocket con el SaaS tras autenticarse y registra los 8 handlers de comandos que el SaaS puede enviarle al agente. Nace en la v2.25.1 (28-08-2026, PR #467) cuando app_main.py se trocea por la Regla 5 (tope de 500 líneas de lógica por módulo): antes esta lógica vivía mezclada dentro de app_main.py (677 líneas), ahora tiene módulo propio (262 líneas) sin ningún cambio de comportamiento.

Contrato

Función	Qué hace
`setup_saas_connection(state)`	Punto de entrada: refresca el token si hace falta y, si hay sesión válida, abre el WS, registra los 8 handlers y arranca el refresco proactivo de token.
`handle_update_targets`	Aplica (o deja pendiente si el scheduler no está listo) la lista de targets a monitorizar que llega del SaaS.
`handle_set_role`	Cambia el rol del agente (`primary`/`secondary`); si pasa a `primary` arranca el Modo Sentinel, si deja de serlo lo para (delega en [[entity—terminal—service—sentinel-runtime]]).
`handle_enable_sentinel` / `handle_disable_sentinel`	Arrancan/paran el Modo Sentinel a demanda explícita del SaaS.
`handle_update_sentinel_targets`	Actualiza los targets del scheduler ya corriendo.
`handle_deep_discover`	Lanza un job de descubrimiento profundo acotado en paralelo (`network/deep_discovery.py`).
`handle_get_status`	Devuelve la foto de `get_sentinel_info()`.
`handle_ai_remediate`	Ejecuta comandos de red recomendados por IA vía Scrapli SSH, con lista de bloqueo defensiva antes de tocar el dispositivo, y postea el resultado de vuelta al SaaS.
`_post_remediate_result`	POST del resultado de una remediación a `/api/monitoring/sentinel/insights/{id}/result`.

Dependencias

Usa: core/auth.py, core/connector.py (WS + registro de handlers), core/sentinel_runtime.py (start_sentinel_mode, stop_sentinel_mode, get_sentinel_info), core/updater.py (registra el handler de auto-update), network/deep_discovery.py, y bajo demanda network/ssh.py (LocalScrapliManager) para ai_remediate.
Le usan: app_main.py (invocado desde el lifespan de FastAPI al arrancar).

Ejemplo de uso

from core.saas_commands import setup_saas_connection

# Durante el lifespan de la app, tras cargar el AppState:
await setup_saas_connection(state)

Seguridad

handle_ai_remediate es el único camino por el que una recomendación de IA ejecuta comandos reales en un dispositivo de red. La lista BLOCKED (reload, reboot, write erase, factory-reset, zeroize…) es defensa en profundidad: bloquea comandos destructivos incluso si el SaaS ya los validó, antes de que lleguen a Scrapli.

Véase también

[[entity—terminal—service—app-main]]
[[entity—terminal—service—sentinel-runtime]]
[[entity—terminal—service—connector-ws-diagnostics]]
[[entity—terminal—service—sync-throttle]]
[[concept—terminal—local-agent]]