Guía CNS — CreaRack Network Sentinel

Guía CNS — CreaRack Network Sentinel

Edge Intelligence: IA para diagnóstico automático de anomalías de red con Human-in-the-Loop. Versión: v1.0.43 (17-03-2026) Ubicación: Observatory, Wireless, UPS (pestaña CNS centralizada + sidebar indicators + Rack Editor)

Índice

1. Visión General
2. Arquitectura
3. Flujo Completo
4. AI Providers
5. Detección de Anomalías (Agent)
6. Modelo AIInsight
7. Frontend — Pestaña CNS
8. InsightDetailModal
9. Explain (Preguntas al AI)
10. Revise Diagnosis
11. Ejecución de Comandos
12. Auto-Resolve
13. Network Tutor
14. Rate Limiting
15. WebSocket Real-Time
16. Integraciones Cross-Module
17. API Endpoints
18. Administración
19. Probando el Sistema

1. Visión General

CreaRack Network Sentinel (CNS) es el sistema de inteligencia artificial integrado en CreaRack Pro que:

1. Detecta anomalías en la red automáticamente (Agent local en modo Sentinel)
2. Diagnostica la causa raíz usando Gemini 3 Flash o Claude Haiku
3. Recomienda acciones correctivas con comandos SSH específicos
4. Espera aprobación del operador antes de ejecutar (Human-in-the-Loop)
5. Ejecuta los comandos via el Agent y reporta resultados
6. Aprende del feedback del operador (Explain + Revise Diagnosis)

Componentes

2. Arquitectura

┌──────────────────────┐     POST /sentinel/insights/receive
│   LOCAL AGENT         │ ──────────────────────────────────────→ ┌─────────────────────┐
│   (Sentinel Mode)     │                                          │   SAAS BACKEND       │
│                       │     WebSocket (bi-directional)            │                     │
│   AnomalyDetector     │ ←────────────────────────────────────── │   AI Providers       │
│   InsightReporter     │     ai_remediate commands                │   (Gemini/Claude)    │
│   Scrapli SSH exec    │                                          │                     │
└──────────────────────┘                                          │   ITSM Hooks         │
                                                                   │   (SLA, Notif, etc)  │
        ┌──────────────────────────────────────────────────────── │                     │
        │  WebSocket broadcast (insight_update)                    └─────────────────────┘
        ▼
┌──────────────────────┐
│   BROWSER             │
│   Observatory CNS     │
│   InsightDetailModal  │
│   Sidebar indicators  │
│   Rack Editor badges  │
└──────────────────────┘

3. Flujo Completo

Detect → Diagnose → Act → Learn

1. AGENT DETECTA ANOMALÍA
   Sentinel loop detecta: packet loss >10%, latency >200ms,
   CRC errors >100/min, client drop >30%, interface down

2. AGENT REPORTA AL SAAS
   POST /sentinel/insights/receive
   Body: { target_id, snmp_data, ssh_logs, anomaly_description }

3. SAAS PROCESA
   a) Verifica maintenance window → suprime si activa
   b) Verifica rate limit (5/device/h, 100/tenant/h)
   c) Llama a Gemini 3 Flash (o Claude, o static rules como fallback)
   d) Crea AIInsight en DB + audit log
   e) Calcula SLA deadlines
   f) Busca known issues + runbooks
   g) Correlaciona con incidents existentes
   h) Envía notificaciones
   i) Broadcast via WebSocket a Observatory

4. OPERADOR VE EL INSIGHT
   - Toast notification en Observatory
   - Insight aparece en tabla CNS
   - Sidebar muestra dot pulsante en el device
   - Rack Editor muestra badge en Properties Panel

5. OPERADOR INTERACTÚA
   a) Ver detalle → InsightDetailModal
   b) Preguntar al AI → Explain (persistido en DB)
   c) Revisar diagnóstico → Revise Diagnosis
   d) Aplicar fix → Apply (envía comandos al Agent)
   e) Acknowledge → cierra el caso con notas

6. AGENT EJECUTA COMANDOS (si Apply)
   - Recibe comandos via WebSocket
   - Ejecuta via Scrapli SSH
   - Reporta resultado: POST /sentinel/insights/{id}/result

7. AUTO-RESOLVE (si el device se recupera)
   Agent detecta recovery → POST /sentinel/insights/recover/{target_id}
   Insights de connectivity se auto-acknowledgen

4. AI Providers

Proveedores disponibles

Selección del provider

Variable EDGE_AI_PROVIDER en settings (default: gemini). Se puede cambiar a claude.

Fallback automático

Si Gemini falla (error 429, timeout, etc.), el sistema hace fallback a Static Rules automáticamente. Static Rules tiene 6 reglas para patrones comunes:

• CRC errors, packet loss, interface down, bandwidth saturation, latency spike, client drop

Gemini backoff exponencial

Para errores 429 (RESOURCE_EXHAUSTED):

• 3 reintentos: 2s → 4s → 8s (max 30s)
• Si los 3 fallan → fallback a static

Configuración AI

5. Detección de Anomalías (Agent)

El Agent local en modo Sentinel ejecuta loops de monitoreo continuos:

Umbrales de detección

Rate limiting del Agent

• Cooldown 5 min por tipo de anomalía por target
• Max 10 insights/hora global
• Se complementa con rate limiting del SaaS

Requisitos

• Agent conectado al SaaS via WebSocket
• Agent en rol Primary (solo Primary ejecuta Sentinel)
• Modo Sentinel activo

6. Modelo AIInsight

Ciclo de vida (status)

        ┌──────────┐
        │ PENDING  │ ← Insight creado por AI
        └────┬─────┘
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
┌────────┐ ┌────────┐ ┌─────────┐
│EXECUTING│ │ACKNOWL.│ │ EXPIRED │
└────┬───┘ └────────┘ └─────────┘
     │                  (auto, 4h)
┌────┼────┐
▼         ▼
┌────────┐ ┌────────┐
│ APPLIED│ │ FAILED │
└────────┘ └────────┘

Risk levels

Campos principales

Campos de revisión

Audit Log

Cada acción sobre un insight se registra en AIInsightAuditLog:

• created, executing, execution_result, acknowledged, auto_resolved, rollback, revise
• Incluye: usuario, timestamp, detalles JSON

7. Frontend — Pestaña CNS

Acceso

Observatory → pestaña CNS (CreaRack Network Sentinel)

Componentes

Stats bar (tarjetas clickables):

• Total, Pending, Executing, Applied, Acknowledged
• Success Rate (%)
• Click en una tarjeta → filtra la tabla por ese status

Filtros:

• Status (dropdown, sincronizado con stat cards)
• Risk Level (HIGH / MEDIUM / LOW)
• Search (busca en summary, root_cause, target, IP, case number)
• Date range (from / to)

Tabla paginada (25 por página):

• Case ID (monospace)
• Risk (badge con color)
• Target + IP
• Summary (con badges REV si revisado, (N) si tiene conversaciones)
• Status (badge)
• Confidence (%)
• Date
• Actions: Details, Acknowledge

Export CSV: Descarga hasta 500 insights con todos los campos.

Auto-refresh: Cada 60 segundos cuando la pestaña está activa.

8. InsightDetailModal

Modal compartido entre Observatory CNS, Rack Editor y Acknowledge History.

Contenido del modal

1. Header: “AI Insight Detail [CNS-000042]”
2. Info Grid (2 columnas): Target, Risk, Confidence, Status, Provider, OSI Layer, Created, Expires
3. ITSM Badges (si configurado): SLA deadlines, escalation level, known issue, runbook, incident group
4. Summary (con badge REVISED + original en cursiva si revisado)
5. Root Cause (con original en cursiva si revisado)
6. Telemetry Insight
7. Recommended Action
8. Impact Description
9. Commands (bloques de código monospace)
10. Rollback Commands
11. Acknowledge (input notas + botón)
12. Acknowledge Info (si ya acknowledged: quién, cuándo, notas)
13. Action Buttons: Apply Fix (si actionable), Dry Run
14. Explain (input pregunta + respuesta AI)
15. Conversation History (lazy-loaded, scrollable)
16. Revise Diagnosis (si hay conversaciones previas)

Acciones disponibles

9. Explain (Preguntas al AI)

Cómo funciona

1. En el InsightDetailModal, escribir una pregunta en el campo Explain
2. Pulsar Enter o click en el botón
3. El AI responde usando el contexto completo del insight (target, summary, root cause, comandos, etc.)
4. La pregunta y respuesta se persisten en DB (InsightConversation)
5. Aparecen en el historial de conversaciones del modal

Persistencia

Cada Q&A se guarda como InsightConversation:

• question: La pregunta del operador
• answer: La respuesta del AI
• ai_provider: Gemini o Claude
• asked_by: El usuario que preguntó
• created_at: Timestamp

El historial completo se carga via GET /sentinel/insights/{id}/conversations.

Ejemplo

Pregunta: "¿Por qué hay CRC errors en esta interfaz?"
Respuesta: "Los errores CRC en GigabitEthernet0/1 sugieren problemas en la capa
física (Layer 1). Las causas más comunes son: cable dañado o mal crimpado, SFP
defectuoso, incompatibilidad de dúplex..."

10. Revise Diagnosis

Qué es

Después de hacer preguntas (Explain), el operador puede pedirle al AI que re-evalúe su diagnóstico original considerando la información adicional de la conversación.

Requisitos

• Al menos 1 conversación (Explain) registrada
• Botón “Revise Diagnosis” aparece debajo del historial de conversaciones

Proceso

1. Click en “Revise Diagnosis”
2. El AI recibe: contexto original + todas las conversaciones
3. Evalúa si el diagnóstico debe cambiar
4. Si revised: true:
   • Guarda original_summary y original_root_cause
   • Actualiza summary, root_cause, confidence_score
   • Marca is_revised = true, revised_at, revised_by
   • Badge “REVISED” púrpura en el modal y tabla CNS
5. Si revised: false:
   • Solo muestra “Diagnosis confirmed — no changes needed”
6. Audit log con action="revise"

11. Ejecución de Comandos

Flujo Apply

1. Operador click “Apply Fix” en InsightDetailModal
2. Backend valida comandos contra vendor whitelist
3. Status: PENDING → EXECUTING
4. Comandos se envían al Agent via WebSocket (ai_remediate)
5. Agent ejecuta via Scrapli SSH en el dispositivo
6. Agent reporta resultado: POST /sentinel/insights/{id}/result
7. Status: EXECUTING → APPLIED (éxito) o FAILED (error)

Command Whitelist

Comandos seguros (permitidos):

show, display, get, ping, traceroute, dir, more

Comandos bloqueados (prohibidos):

reload, reboot, erase, format, delete, write erase,
copy running-config startup-config, configure replace

Comandos vendor-específicos (extras permitidos):

• Cisco IOS: clear counters, clear arp-cache, interface, no shutdown
• NX-OS: clear counters, interface, system mode maintenance
• Arista EOS: clear counters, interface, ip route
• Juniper JunOS: clear interfaces statistics, set interfaces, commit

Dry Run

Valida los comandos sin ejecutar. Retorna:

• valid: true/false
• error: mensaje si inválido
• commands: lista de comandos que se ejecutarían
• vendor: vendor detectado del dispositivo

Rollback

Si se aplicó un fix y hay problemas, el operador puede ejecutar rollback:

• Usa rollback_commands del insight
• Valida contra la misma whitelist
• Se ejecuta por el mismo flujo (WebSocket → Agent → SSH)

12. Auto-Resolve

Qué es

Cuando un dispositivo que estaba caído se recupera, el Agent lo detecta y reporta al SaaS. Los insights de pérdida de conectividad pendientes se auto-acknowledgen.

Keywords de conectividad

Solo se auto-resuelven insights cuyo summary o anomaly_trigger contenga:

• "total loss"
• "unreachable"
• "100%"
• "device down"

Insights de CRC, latencia, bandwidth, etc. no se auto-resuelven (requieren acknowledge manual).

Flujo

1. Agent detecta que el target responde a ping (estaba down)
2. Agent envía: POST /sentinel/insights/recover/{target_id}
3. SaaS busca insights PENDING del target con keywords de connectivity
4. Marca como ACKNOWLEDGED con nota “Auto-resolved: device connectivity recovered”
5. Broadcast via WebSocket

13. Network Tutor

Qué es

Asistente AI de networking integrado en el sidebar del Observatory. Responde preguntas de networking desde nivel CCNA hasta CCIE.

Acceso

Observatory → botón “Network Tutor” en el sidebar (slide-in panel)

Guardrails de tópico

Filtro de 2 capas:

1. Pre-filtro de keywords (~130 términos de networking): si la pregunta no contiene ningún término relevante, se rechaza antes de llamar al API
2. System prompt: instrucción al AI de solo responder sobre networking

Contexto de dispositivo

Si hay un dispositivo seleccionado en Observatory, el tutor recibe su contexto (nombre, IP, vendor, tipo) para respuestas más específicas.

Historial

• 50 mensajes por usuario
• TTL 4 horas
• Almacenado en Valkey (cache)

Endpoints

14. Rate Limiting

SaaS-side

Si se excede → HTTP 429 con mensaje de error.

Agent-side

15. WebSocket Real-Time

Eventos broadcast

Cuando se crea un insight, el SaaS envía via WebSocket a todos los browsers de la organización:

{
    "type": "insight_update",
    "data": {
        "insight_id": 42,
        "summary": "Packet loss detected on GigabitEthernet0/1",
        "risk_level": "HIGH",
        "target_name": "switch-core-01",
        "status": "pending",
        "timestamp": "2026-03-10T14:30:00Z"
    }
}

Efectos en el frontend

• Toast notification en Observatory
• Auto-refresh de la tabla CNS
• Sidebar indicator: dot pulsante (rojo/naranja/azul según riesgo) en el device afectado
• Rack Editor: badge clickable en Properties Panel si el device tiene insights activos

16. Integraciones Cross-Module

Arquitectura Centralizada (v1.0.43+)

A partir de v1.0.43, CNS utiliza servicios centralizados reutilizables en lugar de implementaciones por página:

ScopedInsightTab

Servicio centralizado (static/js/services/ScopedInsightTab.js) que renderiza una pestaña CNS completa (stats, filtros, tabla paginada, export CSV, auto-refresh) scoped a un conjunto de targetIds.

import { ScopedInsightTab } from '../services/ScopedInsightTab.js';

const cns = new ScopedInsightTab({
    containerId: 'my-cns-container',
    targetIds: [1, 2, 3],
    actionNamespace: 'wireless',
});
cns.render();

InsightIndicatorService

Servicio centralizado (static/js/services/InsightIndicatorService.js) que gestiona puntos pulsantes (.insight-indicator) junto a los nombres de dispositivos en sidebars. Soporta actualizaciones en tiempo real via WebSocket (insight_update).

• Rojo = HIGH
• Naranja = MEDIUM
• Azul = LOW

DeviceProfile.assigned_page (antes MonitoringTarget.scope)

El campo scope de MonitoringTarget fue eliminado (Ficha Central F4, migración monitoring/0025): el target es 1:1 por (organization, ip_address). La pertenencia a página la decide ahora DeviceProfile.assigned_page (network/models/profile.py, valores: wireless, ups, signage; null = sin asignar). Cada página obtiene sus target IDs filtrando fichas por página y siguiendo linked_monitoring_target:

# Backend: obtener los target IDs de una página (Ficha Central)
profiles = DeviceProfile.objects.filter(organization=org, assigned_page='wireless').select_related(
    'linked_monitoring_target'
)
target_ids = [p.linked_monitoring_target_id for p in profiles if p.linked_monitoring_target_id]

Filtrado por target_ids en endpoints

Los endpoints insight_stats y list_insights aceptan un parámetro opcional target_ids (comma-separated):

GET /api/sentinel/insights/stats/?target_ids=1,2,3
GET /api/sentinel/insights/?target_ids=1,2,3&status=pending

Cuando no se proporcionan target_ids, se retornan todos los insights de la organización (comportamiento original).

Patrón de integración para nuevas páginas

Para añadir CNS a un nuevo tipo de dispositivo (ej: Switches):

1. Backend: Añadir el choice a DeviceProfile.assigned_page y asignar assigned_page='switches' a las fichas del nuevo tipo (el MonitoringTarget es universal, no se toca)
2. View: Pasar target_ids (lista de IDs) al template context
3. Template: Añadir tab header “CNS” y un container div vacío
4. JS coordinator: Instanciar ScopedInsightTab con containerId, targetIds del template, y actionNamespace único
5. JS coordinator: Instanciar InsightIndicatorService para los dots del sidebar
6. WS handler: En el handler de insight_update, llamar a cnsTab.refresh() y indicators.update()
7. ITSM: Añadir botón “ITSM Settings” que navega a /monitoring/observatory/?tab=itsm

Páginas con CNS integrado

Observatory — Widget Overview

Widget “AI Insights” en el GridStack de Overview con cards de insights activos (risk color, summary, target, actions).

Observatory — Pestaña CNS

Dashboard completo con stats, filtros, tabla paginada, export CSV. Refactorizado como thin wrapper de ScopedInsightTab.

Observatory — Sidebar

Dot pulsante via InsightIndicatorService en cada device que tiene insights activos.

Rack Editor — Properties Panel

Indicador clickable en el panel de propiedades del dispositivo. Click → abre InsightDetailModal con todas las acciones (Apply, Acknowledge, Explain, Revise).

Acknowledge History Modal

Modal master-detail en Observatory (botón “History”):

• Panel izquierdo: lista compacta de insights acknowledged con risk dots, target, summary
• Panel derecho: detalle completo del insight seleccionado
• Búsqueda + filtro por risk level
• AI Explain inline

17. API Endpoints

Insights CRUD

Acciones sobre insights

Recovery + Admin

Network Tutor

Total: 18 endpoints CNS

18. Administración

Purgar insights (Superuser only)

DELETE /api/sentinel/insights/purge

Elimina todos los insights de la organización actual. Solo accesible para superusuarios.

Purgar via CLI (producción)

docker exec -it crearack-pro-zcmvsl-web-1 python manage.py shell -c "from django.db import connection; cursor = connection.cursor(); [cursor.execute(f'DELETE FROM {t}') or print(f'{t}: {cursor.rowcount} deleted') for t in ['monitoring_notificationlog','monitoring_insightconversation','monitoring_aiinsightauditlog','monitoring_insightlink','monitoring_aiinsight']]"

Django Admin

Los modelos AIInsight, AIInsightAuditLog e InsightConversation están registrados en Django Admin con filtros y búsqueda.

Reset del Sentinel (Agent)

Si el Agent acumula errores, cooldowns o rate limits que bloquean la generación de insights:

Desde la UI: Modal Agent Fleet Manager → columna Actions → botón Reset

Via API local:

curl -X POST http://localhost:5050/sentinel/reset

Limpia: rate limits (10/hora), cooldowns (5 min por target), circuit breakers, contadores de error del InsightReporter. No reinicia el proceso.

Configuración del provider

En config/settings/base.py:

EDGE_AI_PROVIDER = env("EDGE_AI_PROVIDER", default="gemini")
GEMINI_API_KEY = env("GEMINI_API_KEY", default="")
ANTHROPIC_API_KEY = env("ANTHROPIC_API_KEY", default="")

19. Probando el Sistema

Prerequisitos

1. Agent conectado y en modo Sentinel (Primary)
2. Targets configurados en Observatory con dispositivos monitoreados
3. API keys configuradas (Gemini o Anthropic)

Generar un insight manualmente (via API)

Si no quieres esperar a que el Agent detecte una anomalía:

curl -X POST https://crearack.com/api/sentinel/insights/receive \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=YOUR_SESSION_ID" \
  -d '{
    "target_id": 1,
    "snmp_data": {"ifInErrors": 150, "ifOutErrors": 50},
    "ssh_logs": "",
    "anomaly_description": "CRC errors detected: 200 errors/min on GigabitEthernet0/1"
  }'

Verificar el flujo

1. Insight creado → aparece en pestaña CNS
2. Explain → pregunta “¿Qué causa los CRC errors?” → respuesta AI
3. Revise → después de 1+ explains → “Revise Diagnosis”
4. Acknowledge → escribir nota “Investigated, replacing cable” → Acknowledge
5. Export CSV → verificar que el insight aparece
6. Stats → verificar contadores actualizados

Verificar WebSocket

Abrir Observatory → crear un insight via API → debería aparecer un toast notification y el insight en la tabla sin recargar la página.

Verificar ITSM integration

1. Configurar SLA policies (ITSM tab → Initialize Default Policies)
2. Crear un insight → verificar que tiene sla_ack_deadline en el detail modal
3. Esperar > ack_minutes → verificar sla_ack_breached = true

Archivos del Sistema

Backend

Frontend

Última actualización: 17-03-2026 Mantenido por: Claude (Anthropic) + Equipo CreaRack

Véase también

• [[concept—monitoring—cns]]
• [[crearack—monitoring—cns-sentinel]]
• [[crearack-tech—agents—dev-cns]]
• [[crearack-tech—guides—cns-itsm-user-guide]]
• [[crearack-tech—guides—itsm-guide]]
• [[crearack-tech—architecture—sentinel-mode]]
• [[crearack-tech—guides—sentinel-24-7-test]]