CreaRack Local Agent - Guía Completa

CreaRack Local Agent - Guía Completa

Versión: 2.0.13 Última actualización: 12-03-2026 Autor: Claude (Anthropic)

1. Introducción

El CreaRack Local Agent es un componente standalone que permite a CreaRack Pro conectarse a dispositivos de red con IPs privadas que no son accesibles desde el servidor Docker.

Por qué es necesario

┌─────────────────────────────────────────────────────────────────┐
│  PROBLEMA: Docker no puede alcanzar IPs privadas               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Docker Container]              [Red Privada]                  │
│   Django Server    ──────X─────►  192.168.1.x                  │
│   localhost:8000                  10.0.0.x                      │
│                                   172.16.x.x                    │
│                                                                 │
│  SOLUCIÓN: Local Agent como puente                             │
│                                                                 │
│  [Navegador] ◄───► [Local Agent] ◄───► [Dispositivos]         │
│              WS     localhost:5050  SSH   192.168.x.x          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

El agente se ejecuta en la máquina del usuario (Windows) y actúa como puente entre el navegador y los dispositivos de red locales.

2. Arquitectura

2.1 Stack Tecnológico

2.2 Estructura Modular (v1.0.0)

Arquitectura modular para mejor mantenibilidad:

terminal/agent/
├── local_agent.py         # Main: FastAPI app, endpoints, WebSocket
├── models.py              # Pydantic request/response models
├── windows_integration.py # Install/uninstall/registry Windows
├── logging_handler.py     # MemoryLogHandler + WebSocket broadcast
├── ssh_bridge.py          # SSHBridge: conexiones persistentes
├── scrapli_manager.py     # LocalScrapliManager: multi-vendor
├── cluster_engine.py      # ClusterEngine: ejecución paralela
├── network_utils.py       # Ping, scan, discovery, ARP
├── version.py             # AGENT_VERSION (single source of truth)
├── installer.py           # Always-reinstall strategy (silent)
├── auth_manager.py        # DPAPI + JWT authentication
├── offline_cache.py       # SQLite cache offline
├── monitoring_service.py  # Workers de monitoreo (ping/SNMP/HTTP)
├── saas_connector.py      # WebSocket persistent connection
├── timeseries_store.py    # SQLite WAL store for Sentinel metrics
├── sentinel_scheduler.py  # Async ping/SNMP/HTTP monitoring loops
├── sync_manager.py        # REST push metrics to SaaS + pull targets
└── assets/
    ├── terminal.html      # UI del terminal (xterm.js + Asteroids)
    ├── debug.html         # Agent Home: Tools Hub + Sentinel status
    └── oui_vendors.json   # Base de datos MAC vendors (~230 entries)

2.3 Installer Strategy (v6.0.7)

El installer sigue una estrategia de always-reinstall:

Datos preservados en reinstall: credentials.enc, offline_cache.db, metrics.db, agent.log

Beneficios de la modularización:

• Archivos < 1000 líneas (mantenibilidad)
• Separación de responsabilidades
• Assets editables sin tocar Python
• Build más limpio con PyInstaller

2.3 Flujo de Datos

┌──────────────┐    HTTP/WS    ┌──────────────┐     SSH     ┌──────────────┐
│   Browser    │◄─────────────►│ Local Agent  │◄───────────►│   Device     │
│  (CreaRack)  │  localhost    │  port 5050   │  port 22    │ 192.168.x.x  │
└──────────────┘               └──────────────┘             └──────────────┘
       │                              │
       │  1. Abre modal SSH           │
       │  2. Envía credenciales       │
       │  ─────────────────────►      │
       │                              │  3. Establece túnel SSH
       │                              │  ─────────────────────►
       │                              │
       │  4. Streaming bidireccional  │
       │  ◄────────────────────►      │
       │                              │

3. Instalación

3.1 Auto-Instalación (Recomendado)

El agente se auto-instala automáticamente al ejecutarse por primera vez:

1. Descargar CreaRackAgent.exe desde CreaRack Pro
2. Ejecutar el archivo desde cualquier ubicación
3. El agente:
   • Se copia a %APPDATA%\CreaRackAgent\
   • Registra el protocolo crearack://
   • Se añade al inicio de Windows
   • Genera uninstall.bat
   • Se relanza desde la nueva ubicación

Directorio de instalación:

%APPDATA%\CreaRackAgent\
├── CreaRackAgent.exe           # Ejecutable principal (nombre fijo)
├── version.txt                 # Versión instalada
├── credentials.enc             # Credenciales DPAPI activas (SaaS actual)
├── profiles.enc                # Multi-profile DPAPI (Local + Online)
├── offline_cache.db            # Cache offline SQLite
├── agent.log                   # Logs del agente
├── agent.lock                  # Lock de instancia única
└── uninstall.bat               # Desinstalador

3.2 Desinstalación

Ejecutar uninstall.bat desde el directorio de instalación, o:

1. Abrir %APPDATA%\CreaRackAgent\
2. Ejecutar uninstall.bat

El desinstalador:

• Detiene el proceso del agente
• Elimina entrada de inicio de Windows
• Elimina protocolo crearack://
• Elimina la carpeta de instalación

4. Agent Home: Tools Hub (v6.0.0)

Acceder a http://localhost:5050/ desde el navegador para abrir el Agent Home.

4.1 Estructura de Tabs

La interfaz usa 3 tabs:

┌─────────────────────────────────────────────┐
│  CreaRack Local Agent v6.0.0               │
│  Status: ● ONLINE                           │
├─────────────────────────────────────────────┤
│  [Status]  [Tools]  [Debug]    ← Tab bar    │
├─────────────────────────────────────────────┤
│  Contenido de la tab activa                 │
├─────────────────────────────────────────────┤
│  Footer: Port · Refresh · CreaRack Pro link │
└─────────────────────────────────────────────┘

4.2 Tab: Status

Muestra información del agente en cards:

4.3 Tab: Tools (7 herramientas de red)

Cada herramienta es una card colapsable (click en header expande/colapsa). Al expandir muestra inputs + botón Run. Resultado aparece inline.

Resultados:

• Port Check, Ping, DNS, Banner: texto inline (ej: ✓ Open (12ms))
• ARP Table, Discovery, Scan: tablas scrollable (max-height 300px, sticky headers, zebra striping)

4.4 Tab: Debug (Enhanced v2.0.4)

Consola de debug profesional con logs en tiempo real via WebSocket (/ws/debug):

• Altura dinámica: calc(100vh - 320px) — usa todo el viewport disponible (min 200px)
• Colores por nivel: ERROR (rojo), WARNING (amarillo), INFO (azul), DEBUG (gris)
• Buffer limitado: Max 2000 líneas en DOM, trim batch de 500 al exceder (previene memory bloat)
• Auto-desconecta al cerrar navegador/pestaña

Toolbar (4 botones + filtros + búsqueda):

Útil para:

• Diagnosticar problemas de conexión SSH y SaaS
• Ver eventos del agente en tiempo real
• Filtrar logs por severidad durante debugging
• Exportar logs para compartir con soporte

4.3 Vendors Soportados

4.4 Ejemplo de Respuesta JSON (para API)

{
  "status": "online",
  "agent": "CreaRack Local Agent",
  "version": "3.0.1",
  "uptime": "2h 15m 30s",
  "uptime_seconds": 8130,
  "sessions": {
    "count": 2,
    "active": [
      {"id": "switch_01", "connected": true, "has_sftp": false, "logging": false},
      {"id": "router_main", "connected": true, "has_sftp": true, "logging": true}
    ]
  },
  "environment": {
    "python": "3.14.2",
    "platform": "Windows",
    "machine": "AMD64",
    "frozen": true
  },
  "paths": {
    "install_dir": "C:\\Users\\user\\AppData\\Roaming\\CreaRackAgent",
    "running_from_install": true,
    "exe_path": "C:\\Users\\user\\AppData\\Roaming\\CreaRackAgent\\CreaRackAgent.exe"
  }
}

5. Endpoints API

5.1 Health & Status

5.2 Verificación de Conectividad

Ejemplo:

curl "http://localhost:5050/check?host=192.168.1.1&port=22"
# {"host": "192.168.1.1", "port": 22, "reachable": true}

Uso en CreaRack: El frontend usa este endpoint para verificar el estado de dispositivos con IP privada, ya que el backend Docker no puede alcanzarlos.

5.3 Terminal SSH

Protocolo WebSocket:

// Conectar a dispositivo
ws.send(JSON.stringify({
    action: "connect",
    host: "192.168.1.1",
    port: 22,
    username: "admin",
    password: "secret"
}));

// Enviar comando
ws.send(JSON.stringify({
    action: "data",
    data: "show version\r\n"
}));

// Mensajes recibidos
// { type: "output", data: "..." }      - Output del dispositivo
// { type: "status", message: "..." }   - Estado de conexión
// { type: "error", message: "..." }    - Errores

Atajos de Teclado del Terminal (v4.0.6):

Nota: La selección de texto se realiza con el ratón. Tras copiar con Ctrl+C, la selección se limpia automáticamente.

Nota: El iframe del terminal requiere allow="clipboard-read; clipboard-write" para que la Clipboard API funcione en iframes cross-origin (Chrome 2024+).

Persistencia de Sesiones SSH (v2.0.11):

Las sesiones SSH sobreviven a la navegación entre páginas del SaaS:

Flujo técnico de reattach:

1. El iframe carga terminal.html y abre WebSocket /ws/terminal/{sid}
2. El Agent detecta sid en ACTIVE_BRIDGES y verifica ssh_conn + ssh_process
3. Si SSH está vivo → envía output_buffer por WS → “Tunnel Established!”
4. Si SSH está muerto → limpia bridge stale → crea nueva sesión
5. El frontend consulta GET /terminal/sessions antes de enviar CONNECT_SSH para distinguir reattach de nueva conexión
6. En reattach, no se muestra el banner de versión ni se reenvía CONNECT_SSH

Selector de Tema (v4.1.0):

El terminal incluye un dropdown con temas profesionales:

El selector envía SET_THEME al iframe del terminal.

Persistencia de Ajustes (Superpersistencia):

Los ajustes (tema y tamaño) se guardan automáticamente en localStorage bajo la clave crearack_terminal_settings. Los ajustes:

• Se guardan al cambiar cualquier selector
• Se restauran al abrir nuevas pestañas
• Se aplican automáticamente cuando el iframe está listo (AGENT_READY)
• Persisten entre recargas de página y sesiones del navegador

Selector de Tamaño:

5.3.1 Sistema de Coloreado (Syntax Highlighting)

El terminal implementa colorización automática del output usando códigos de escape ANSI. El sistema tiene dos capas y puede activarse/desactivarse.

Toggle de Color (v4.2.0)

En la toolbar de cada terminal hay un botón “Color”:

• ON (verde): Syntax highlighting activo - colores para IPs, errores, MACs, banners
• OFF (gris): Sin colores añadidos - texto como viene del dispositivo

El estado se guarda en localStorage con superpersistencia.

Capa 1: Keywords Highlighting (Palabras Clave)

Nota (v4.0.9): Las keywords usan word boundaries (\b) para evitar falsos positivos. Por ejemplo, “support” no coloreará “up” porque no es una palabra completa.

Capa 2: Banner Highlighting (Malva/Magenta)

Códigos de Escape ANSI Completos

Formato: \x1b[<estilo>;<color>m  ...texto...  \x1b[0m (reset)

ESTILOS (primer número):
┌────────┬─────────────────────────────────────┐
│ Código │ Efecto                              │
├────────┼─────────────────────────────────────┤
│   0    │ Reset (normal)                      │
│   1    │ Bold (brillante/negrita)            │
│   2    │ Dim (tenue)                         │
│   3    │ Italic (cursiva)                    │
│   4    │ Underline (subrayado)               │
│   5    │ Blink (parpadeo lento)              │
│   6    │ Blink (parpadeo rápido)             │
│   7    │ Reverse (invertir fg/bg)            │
│   8    │ Hidden (oculto)                     │
│   9    │ Strikethrough (tachado)             │
└────────┴─────────────────────────────────────┘

COLORES FOREGROUND (texto):
┌────────┬─────────────┬────────┬─────────────────┐
│ Normal │ Color       │ Bright │ Color Brillante │
├────────┼─────────────┼────────┼─────────────────┤
│   30   │ Negro       │   90   │ Gris            │
│   31   │ Rojo        │   91   │ Rojo Claro      │
│   32   │ Verde       │   92   │ Verde Claro     │
│   33   │ Amarillo    │   93   │ Amarillo Claro  │
│   34   │ Azul        │   94   │ Azul Claro      │
│   35   │ Magenta     │   95   │ Magenta Claro   │
│   36   │ Cian        │   96   │ Cian Claro      │
│   37   │ Blanco      │   97   │ Blanco Brillante│
└────────┴─────────────┴────────┴─────────────────┘

COLORES BACKGROUND (fondo):
┌────────┬─────────────┬────────┬─────────────────┐
│ Normal │ Color       │ Bright │ Color Brillante │
├────────┼─────────────┼────────┼─────────────────┤
│   40   │ Negro       │  100   │ Gris            │
│   41   │ Rojo        │  101   │ Rojo Claro      │
│   42   │ Verde       │  102   │ Verde Claro     │
│   43   │ Amarillo    │  103   │ Amarillo Claro  │
│   44   │ Azul        │  104   │ Azul Claro      │
│   45   │ Magenta     │  105   │ Magenta Claro   │
│   46   │ Cian        │  106   │ Cian Claro      │
│   47   │ Blanco      │  107   │ Blanco Brillante│
└────────┴─────────────┴────────┴─────────────────┘

COLORES 256 (extendido):
  \x1b[38;5;<n>m  - Foreground color (0-255)
  \x1b[48;5;<n>m  - Background color (0-255)

COLORES RGB (true color):
  \x1b[38;2;<r>;<g>;<b>m  - Foreground RGB
  \x1b[48;2;<r>;<g>;<b>m  - Background RGB

Ejemplos de Uso

// Rojo brillante + negrita
'\x1b[1;31mERROR: Connection failed\x1b[0m'

// Verde con fondo negro
'\x1b[32;40mSUCCESS\x1b[0m'

// Magenta brillante (usado para banners)
'\x1b[1;35mCopyright (c) 2024 Company\x1b[0m'

// Combinaciones múltiples
'\x1b[1;4;33mWarning: Bold + Underline + Yellow\x1b[0m'

5.3.2 Anatomía de una Terminal (Elementos Técnicos)

┌─────────────────────────────────────────────────────────────────────────────┐
│ ┌─ Title Bar ─────────────────────────────────────────────────────────────┐ │
│ │  Terminal - user@host                                           [_][□][X]│ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─ Menu Bar (opcional) ───────────────────────────────────────────────────┐ │
│ │  File   Edit   View   Terminal   Help                                   │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─ Toolbar (opcional) ────────────────────────────────────────────────────┐ │
│ │  [New] [Copy] [Paste] [Settings]                                        │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─ Terminal Viewport / Screen Buffer ─────────────────────────────────────┐ │
│ │                                                                         │ │
│ │  user@hostname:~$ ls -la                    ◄── Command Line [VERDE]    │ │
│ │  total 48                                   ◄── Output / Stdout         │ │
│ │  drwxr-xr-x  5 user user 4096 Jan 28 10:00 .                            │ │
│ │  drwxr-xr-x 18 user user 4096 Jan 27 15:30 ..                           │ │
│ │  -rw-r--r--  1 user user  220 Jan 28 09:00 file.txt                     │ │
│ │                                                                         │ │
│ │  user@hostname:~$ _                         ◄── Cursor [CIAN]           │ │
│ │                    ▲                                                    │ │
│ │                    └── Prompt (PS1)                                     │ │
│ │                                                                       ▲ │ │
│ │                                                                       █ │◄─ Scrollbar
│ │                                                                       ▼ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ┌─ Status Bar (opcional) ─────────────────────────────────────────────────┐ │
│ │  Rows: 24  Cols: 80  |  UTF-8  |  Connected  |  00:15:32                 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Leyenda de Colores del Diagrama:

Glosario de Términos Técnicos

Secuencias de Control Comunes

5.4 SFTP

Nota: SFTP usa la sesión SSH existente. El terminal debe estar conectado primero.

5.5 Network Tools (v6.0.0)

ARP Table Response:

{
  "entries": [
    {
      "ip": "192.168.0.1",
      "mac": "00-11-22-33-44-55",
      "type": "dynamic",
      "vendor": "Cisco Systems"
    }
  ],
  "total": 15
}

Hostname Response:

{
  "ip": "192.168.0.1",
  "hostname": "router.local"
}

MAC OUI Vendors soportados: ~150+ fabricantes incluyendo Cisco, HP, Dell, Samsung, Amazon, Apple, Intel, Arista, Juniper, Xirrus, y más.

5.6 Administración

6. Integración con CreaRack Pro

6.1 Detección de IP Privada

El frontend detecta automáticamente si un dispositivo tiene IP privada:

function isPrivateIPAddress(ip) {
    if (!ip) return false;
    const parts = ip.split('.').map(Number);
    if (parts.length !== 4) return false;

    // 10.0.0.0/8
    if (parts[0] === 10) return true;
    // 172.16.0.0/12
    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
    // 192.168.0.0/16
    if (parts[0] === 192 && parts[1] === 168) return true;
    // localhost
    if (parts[0] === 127) return true;

    return false;
}

6.2 Verificación de Estado

Para dispositivos con IP privada, el frontend usa el Local Agent:

async function checkViaLocalAgent(ip, port = 22) {
    try {
        const response = await fetch(
            `http://localhost:5050/check?host=${ip}&port=${port}`
        );
        const data = await response.json();
        return data.reachable;
    } catch (e) {
        return false; // Agent no disponible
    }
}

6.3 Backup de Configuración

Para dispositivos con IP privada, el backup se ejecuta via WebSocket:

// 1. Conectar al dispositivo via WebSocket
const ws = new WebSocket(`ws://localhost:5050/ws/terminal/${sessionId}`);

// 2. Enviar credenciales
ws.send(JSON.stringify({
    action: 'connect',
    host: device.ip,
    port: 22,
    username: credentials.username,
    password: credentials.password
}));

// 3. Esperar conexión, enviar comando
ws.send(JSON.stringify({
    action: 'data',
    data: 'show running-config\r\n'
}));

// 4. Recopilar output con idle detection
// 5. Guardar via POST /api/network/device/{id}/backup/save

7. Compilación

7.1 Requisitos

• Python 3.14+
• PyInstaller
• Dependencias: fastapi, uvicorn, asyncssh, pydantic, scrapli[asyncssh]

7.2 Usando build_agent.bat (Recomendado)

cd C:\dev\CreaRack_Pro_app_Django
build_agent.bat

El script:

1. Verifica rutas de Python y PyInstaller
2. Verifica que existen assets requeridos
3. Limpia builds anteriores
4. Instala dependencias (incluyendo Scrapli)
5. Compila con:
   • Assets externos (--add-data para HTML/JSON)
   • Módulos Python (--add-data para agent_modules/)
   • Hidden imports para uvicorn, asyncssh, scrapli
6. Copia a static/downloads/
7. Limpia archivos temporales

7.3 Estructura del .exe Compilado

CreaRackAgent.exe (extrae en _MEIPASS/)
├── assets/
│   ├── terminal.html      # UI terminal con xterm.js + Asteroids
│   ├── debug.html         # Agent Home: Tools Hub (3 tabs, 7 herramientas)
│   └── oui_vendors.json   # MAC vendor database
└── agent_modules/
    ├── models.py
    ├── windows_integration.py
    ├── logging_handler.py
    ├── ssh_bridge.py
    ├── scrapli_manager.py
    ├── cluster_engine.py
    ├── network_utils.py
    ├── version.py
    ├── installer.py
    ├── auth_manager.py
    ├── offline_cache.py
    ├── monitoring_service.py
    └── saas_connector.py

7.4 Imports Condicionales (Frozen vs Dev)

Los módulos usan detección de modo frozen para imports:

import sys

if getattr(sys, "frozen", False):
    # Modo frozen (PyInstaller .exe)
    from models import DeviceTarget
    from logging_handler import logger
else:
    # Modo desarrollo (Python directo)
    from .models import DeviceTarget
    from .logging_handler import logger

7.5 Resultado

• Ubicación: static/downloads/CreaRackAgent.exe
• Tamaño: ~25MB (incluye Scrapli)
• Dependencias: Ninguna (standalone)

8. Arquitectura SaaS-Connected (v5.0.0+)

A partir de v5.0.0, el agente funciona como una plataforma de monitoreo distribuido conectada al SaaS.

8.1 Diagrama de componentes

┌─────────────────────────────────────────────────────────────────────┐
│                        LOCAL AGENT v6.0.0                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌───────────────┐  ┌───────────────┐  ┌─────────────────────────┐  │
│  │  Installer    │  │  Agent Core   │  │  Monitoring Service     │  │
│  │               │  │               │  │                         │  │
│  │  - Toast UI   │  │  - FastAPI    │  │  - Ping Worker          │  │
│  │  - Version    │  │  - WebSocket  │  │  - SNMP Worker          │  │
│  │  - Auto-update│  │  - SSH/SFTP   │  │  - HTTP Worker          │  │
│  └───────────────┘  └───────────────┘  └─────────────────────────┘  │
│                                                                      │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐           │
│  │  Auth Manager │  │ Offline Cache │  │ SaaS Connector│           │
│  │               │  │               │  │               │           │
│  │  - DPAPI      │  │  - SQLite     │  │  - WebSocket  │           │
│  │  - JWT        │  │  - Sync       │  │  - Heartbeat  │           │
│  │  - Refresh    │  │  - Cleanup    │  │  - Reconnect  │           │
│  └───────────────┘  └───────────────┘  └───────────────┘           │
│                                                                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ WebSocket + HTTPS
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         CREARACK SAAS                                │
│  Agent API Gateway · Monitoring Targets · VictoriaMetrics · WS Hub  │
└─────────────────────────────────────────────────────────────────────┘

8.2 Módulos v5.0.0+

8.3 SNMP Bandwidth Polling (Sentinel)

El módulo sentinel/snmp_bandwidth.py pollea contadores de interfaz cada 60s para calcular throughput en Mbps.

Pipeline completo:

AutoConfigService              Consumer                  Agent Sentinel
──────────────────             ────────                  ──────────────
_select_primary_interface() →  config.snmp_interface →   SentinelTarget.snmp_interface
  Elige ifIndex de gig1         Envía en update_targets    Construye OIDs con {ifIndex}
  (excluye wds/bridge/lo)       via WebSocket              Pollea 8 OIDs (HC+legacy+errors+discards)
                                + v3 credentials           Calcula Mbps = delta × 8 / dt / 1M
                                (si snmp_version == v3)    Envía métricas a SaaS → VictoriaMetrics

8 OIDs polleados por target (en un solo SNMP GET):

• ifHCInOctets / ifHCOutOctets (Counter64, preferidos)
• ifInOctets / ifOutOctets (Counter32, fallback)
• ifInErrors / ifOutErrors (Counter32, errors/min)
• ifInDiscards / ifOutDiscards (Counter32, discards/min)

HC→Legacy Fallback: Si HC delta = 0 pero legacy delta > 0, usa legacy. Necesario para Xirrus APs donde ifHCInOctets devuelve 0 permanentemente en interfaces ethernet.

Baseline reset: Cuando snmp_interface cambia en update_targets(), se borran los contadores previos (_snmp_prev_counters) para evitar spikes por cambio de interfaz.

Spike protection: Rates > 10 Gbps descartados y baseline reseteado. Error/discard rates > 100k/min descartados.

Métricas escritas en VictoriaMetrics:

8.4 Protocolo WebSocket (SaaS ↔ Agent)

Mensajes del SaaS al Agent:

Mensajes del Agent al SaaS:

8.5 Flujo de auto-instalación

Ejecutar .exe → ¿Desde %APPDATA%? → SÍ → Iniciar normalmente
                                   → NO → ¿Versión instalada?
                                           → No existe → Toast confirmación → Instalar
                                           → Misma → "Ya tienes la última versión"
                                           → Más antigua → Auto-update silencioso
                                           → Más nueva → "Tienes versión más reciente"

8.6 Multi-Profile SaaS Toggle (v1.0.0)

El agente puede almacenar credenciales para múltiples instancias SaaS (ej: localhost y producción) y cambiar entre ellas sin reinstalar.

Almacenamiento: profiles.enc (DPAPI cifrado, junto a credentials.enc)

Endpoints:

UI: Card “SaaS Connection” en la tab Status de http://localhost:5050/:

• Colapsable (click en header para mostrar/ocultar)
• Muestra SaaS URL activa
• Token Status (polling cada 10s via GET /saas/status):
  • Verde: "Valid (23.5h)" — token con >6h restantes
  • Amarillo: "Expiring (1.5h)" — token con <6h restantes
  • Rojo: "EXPIRED" — token expirado
• Proactive Refresh: "Active" (verde) / "Inactive" (gris) — indica si el background refresh está corriendo
• Botones Local / Online (verde = activo, gris = inactivo)
• Botón Reconnect (azul) — fuerza reconexión WebSocket via POST /saas/reconnect
• Links de setup inicial para registrar cada entorno por primera vez

Flujo de setup inicial (una sola vez por entorno):

1. Agent vinculado a localhost:8000 (auto-link desde Observatory local)
   → Perfil "http://localhost:8000" guardado automáticamente

2. Abrir link "Online" en Agent UI → abre crearack.com/monitoring/?setup_agent=1
   → Observatory llama POST /saas/register-profile (NO cambia el activo)
   → Perfil "https://crearack.com" guardado

3. Ambos perfiles cached → Toggle funciona libremente

Flujo de switch:

POST /saas/switch { "saas_url": "https://crearack.com" }
  1. AuthManager carga credenciales del perfil
  2. Guarda como credentials.enc (activo)
  3. SaaSConnector desconecta WebSocket actual
  4. setup_saas_connection() reconecta al nuevo SaaS
  5. Si Sentinel activo → SyncManager se reinicia

9. Seguridad

9.1 Scope de Acceso

El agente solo escucha en 127.0.0.1:5050, no es accesible desde la red.

9.2 CORS

Configurado con allow_origins=["*"] para permitir requests desde cualquier origin (localhost, crearack.com, etc.).

9.3 CSP (Content Security Policy)

frame-ancestors 'self'
  http://localhost:8000 http://127.0.0.1:8000
  http://localhost:5000 http://127.0.0.1:5000
  http://localhost:5002 http://127.0.0.1:5002
  https://crearack.com https://*.crearack.com;

9.4 Credenciales

• SSH: Se transmiten en memoria, nunca se almacenan en el agente
• SaaS: Encriptadas con Windows DPAPI (vinculado al usuario del sistema)
• JWT: Access token (1h) + refresh token (30d), refresh automático

10. Troubleshooting

El agente no inicia

1. Verificar que puerto 5050 no está en uso
2. Revisar logs en %APPDATA%\CreaRackAgent\agent.log
3. Verificar que no hay otra instancia corriendo

Conexión SSH falla

1. Verificar credenciales
2. Verificar que el dispositivo es alcanzable (/check endpoint)
3. Verificar que SSH está habilitado en el dispositivo

El panel de debug no carga

1. Abrir http://localhost:5050/ (no https)
2. Verificar que el agente está corriendo
3. Revisar consola del navegador para errores

Backup tarda mucho

El sistema usa idle detection (1.5s de inactividad = completado). Si el dispositivo tarda en responder, el backup puede parecer lento. Esto es normal para dispositivos con mucha configuración.

11. Cluster Mode API

10.1 Endpoints de Cluster

10.2 Ejemplo: Cluster Execute

curl -X POST http://localhost:5050/cluster/execute \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [
      {"ip": "192.168.1.1", "username": "admin", "password": "xxx", "vendor": "cisco_ios"},
      {"ip": "192.168.1.2", "username": "admin", "password": "xxx", "vendor": "arista_eos"}
    ],
    "command": "show version"
  }'

Respuesta:

{
  "status": "completed",
  "command": "show version",
  "total_devices": 2,
  "success_count": 2,
  "failed_count": 0,
  "total_time_seconds": 1.45,
  "results": [
    {"device": "192.168.1.1", "ip": "192.168.1.1", "vendor": "cisco_ios", "success": true, "output": "...", "elapsed_seconds": 0.8},
    {"device": "192.168.1.2", "ip": "192.168.1.2", "vendor": "arista_eos", "success": true, "output": "...", "elapsed_seconds": 0.7}
  ]
}

10.3 Vendors Soportados (Scrapli)

12. Changelog

v2.0.6 (03-03-2026) — Zero-Intervention Token Recovery (Layer 3 Auto-Reauth)

Problema: Si ambos tokens (access + refresh) expiran — por ejemplo, equipo apagado >30 días o SaaS offline prolongado — el Agent quedaba atrapado sin poder auto-recuperarse. Requería intervención manual (“Reauth” en Fleet Manager).

Objetivo: Zero intervención del usuario en el manejo del Agent.

Layer 3 Auto-Reauth (core/auth.py):

• Nuevo método _auto_reauth(): cuando _do_refresh() recibe 401 (refresh expirado), re-autentica usando agent_id + tenant_id almacenados en DPAPI
• Llama POST /api/agent/reauth-self en el SaaS (no requiere Bearer token)
• Se integra en refresh_token_if_needed() como fallback automático
• El proactive refresh loop (_proactive_refresh_loop) también incluye fallback a Layer 3

SaaS: Nuevo endpoint (terminal/api.py):

• POST /api/agent/reauth-self: acepta {agent_id, tenant_id}, valida contra AgentInstance en DB, genera tokens frescos
• Rate limited: 5 requests/hora por agent_id (via Django cache)
• No requiere autenticación — identidad verificada por agent_id (UUID) + tenant_id match

SaaS: TTLs extendidos (terminal/api.py):

• Access token: 24h → 72h (sobrevive fines de semana sin refresh)
• Refresh token: 30d → 180d (sobrevive vacaciones largas)

Resumen de capas de protección:

Resultado: El Agent puede auto-recuperarse de CUALQUIER escenario de tokens expirados sin intervención humana.

v2.0.8 (04-03-2026) — Heartbeat Sentinel Status Reporting

Problema: Tras un fallo transitorio de DNS o reconexión WebSocket, el Observatory mostraba Sentinel como “desconectado” aunque el Agent estuviera activo y ejecutando loops Sentinel localmente. El estado sentinel_active solo se enviaba una vez al conectar el WS (_send_agent_status()), así que cualquier pérdida de ese mensaje dejaba el estado stale en la DB del SaaS.

Heartbeat mejorado (connector.py):

• El heartbeat (cada 30s) ahora incluye sentinel_active: true/false junto con el timestamp
• El Agent lee el estado real del scheduler (scheduler._running) en cada heartbeat
• Antes: { type: "ping", timestamp } → Ahora: { type: "ping", timestamp, sentinel_active }

SaaS Consumer (consumers.py):

• Al recibir un ping con sentinel_active, actualiza AgentInstance.sentinel_active en la DB
• Ventana máxima de estado stale: 30s (un ciclo de heartbeat) en vez de indefinido

Resultado: Si el WS se desconecta y reconecta (DNS hiccup, deploy, suspensión), el estado Sentinel se corrige automáticamente en el siguiente heartbeat (~30s).

v2.0.5 (03-03-2026) — Sleep/Wake Recovery for Windows Suspension

Problema: Tras suspender/hibernar Windows, el Agent se “congelaba” ~5 minutos antes de volver a enviar datos. Causas: circuit breaker acumulaba fallos pre-sleep, SNMP baselines corruptas (dt enorme), WebSocket heartbeat fallaba antes de que la NIC estuviera lista, sync manager asumia conectividad activa.

Sleep/Wake Detector (config.py + scheduler.py):

• Nueva constante SLEEP_DETECTION_THRESHOLD = 120 (2 minutos)
• SentinelScheduler.check_sleep_wake(): compara wall clock entre iteraciones
• Si gap > 120s: reset circuit breaker (evita 5 min OPEN penalty) + limpiar SNMP baselines (evita dt corrupto)

Sentinel Loops (5 archivos):

• ping.py, snmp_bandwidth.py, snmp_extras.py, snmp_fast.py, http_check.py
• Cada loop llama sched.check_sleep_wake() al inicio de cada iteracion

Connector Heartbeat (connector.py):

• Tras asyncio.sleep(30), detecta si wall clock salto >120s
• Si sleep detectado: espera 3s para que la NIC de Windows se estabilice

Sync Manager (sync.py):

• Detecta sleep y fuerza re-check de conectividad (antes asumia _connected = True)
• Primer fallo post-wake usa quick retry de 5s en vez del backoff normal de 60s

Resultado: De ~5 minutos de congelacion → <15 segundos tras wake.

v2.0.12 (06-03-2026) — metrics.db Triple Retention + Purge UI

• Triple retention en purge_old(): Tier 1: synced >48h (ya en VictoriaMetrics), Tier 2: snmp_fast_* >7d, Tier 3: standard unsynced >30d
• Root cause del bloat: Con 70+ metric types (per-radio SNMP), la DB acumulaba ~800K filas/día. El 99.97% ya estaban sincronizadas pero nunca se purgaban (solo se eliminaban datos >30d)
• Impacto: De ~500MB/4días a ~50MB steady-state. Reports de Observatory no afectados (consultan VictoriaMetrics, no metrics.db)
• Purge Synced + VACUUM: Nuevo botón en /metrics/ui — elimina todas las métricas synced y ejecuta VACUUM para reclamar espacio en disco
• Endpoint: POST /metrics/purge-synced — devuelve {deleted, size_before_mb, size_after_mb}
• Chunked delete fix: DELETE...LIMIT reemplazado por subquery rowid IN (SELECT) — compatible con todas las builds de SQLite (PyInstaller no incluye SQLITE_ENABLE_UPDATE_DELETE_LIMIT)

v2.0.11 (06-03-2026) — SSH Session Persistence + Clipboard Fix

• SSH session reattach: Al navegar fuera y volver, la sesión SSH se restaura automáticamente con replay del output_buffer (2000 chunks)
• Stale session cleanup: Bridges con SSH muerto (ssh_conn=None) se limpian automáticamente al reconectar en vez de intentar reattach
• /terminal/sessions filtrado: Solo devuelve sesiones con ssh_conn activo (no bridges sin SSH)
• Clipboard iframe fix: allow="clipboard-read; clipboard-write" en el iframe del terminal (SaaS-side)
• Banner condicional: Solo se muestra “CreaRack Local Agent vX” en sesiones nuevas; en reattach muestra “SESSION RESTORED”

v2.0.4 (02-03-2026) — Debug Console Pro + Token Status + Fleet Reauth

Agent debug.html:

• Debug Console mejorada: Altura dinámica (full viewport), toolbar con Pause/Resume, Copy All, Download (.txt), Clear
• Level filters: 4 checkboxes (ERROR/WARNING/INFO/DEBUG) para ocultar/mostrar líneas por nivel
• Search highlight: Input de búsqueda con highlight amarillo en matches
• Buffer limit: Max 2000 líneas en DOM, batch cleanup de 500 al exceder
• Token Status: Nueva fila en SaaS Connection card — muestra tiempo restante con colores (verde >6h, amarillo <6h, rojo expired)
• Proactive Refresh: Nueva fila mostrando si el background refresh task está activo
• Reconnect button: Botón azul que fuerza reconexión WebSocket via POST /saas/reconnect
• Polling 10s: Token Status se actualiza automáticamente cada 10 segundos

SaaS Fleet Manager (base.js):

• Reauth button: Botón “Reauth” en cada fila de la tabla Fleet Manager (online y offline)
• Flujo: Genera JWT frescos via POST /api/agent/fleet/{id}/reauth → envía al Agent via POST localhost:5050/saas/setup
• Fallback: Si Agent no accesible, muestra toast con instrucciones
• CSS: Nuevo estilo .btn-info en components.css

v1.0.0 (18-02-2026) — First Production Release

• Version reset: Reset from v6.6.0 pre-release to v1.0.0 for production
• Multi-Profile SaaS Toggle: Store credentials for multiple SaaS instances (Local/Online)
  • profiles.enc: DPAPI-encrypted multi-profile storage
  • 3 endpoints: /saas/profiles, /saas/switch, /saas/register-profile
  • UI card “SaaS Connection” in Agent Home Status tab
  • _forceLinkAgent() in Observatory for initial profile registration via ?setup_agent=1
• CSP frame-ancestors: Added https://crearack.com (wildcard *.crearack.com doesn’t match bare domain)

v6.5.1 (13-02-2026)

• Fix: WebSocket URL: auth_manager.py ahora incluye agent_id en el path (/ws/agent/{id}/). Antes era /ws/agent sin agent_id — el WebSocket nunca conectaba (bug latente desde v5.0.0)
• Fix: auto-resume: Rol persistido en SQLite (agent_role en tabla config). Antes usaba _agent_role default “secondary” que siempre saltaba auto-resume
• Fix: agent_status: _send_agent_status() envía AGENT_VERSION real y sentinel_active desde sys.modules['__main__']. Antes: version hardcodeada “5.0.0”, sin campo sentinel
• Fix: frozen imports: Todos los imports en _send_agent_status() usan check sys.frozen para evitar from .module relativo que falla en .exe
• Fix: Debug Console: MemoryLogHandler añadido al logger padre "agent" — los 8 módulos agent.* ahora aparecen en el debug console

v6.5.0 (13-02-2026)

• Primary/Secondary Fleet: Sistema de roles para multi-agente por tenant
  • Handler set_role: Recibe asignación de rol desde SaaS, inicia/detiene Sentinel automáticamente
  • Welcome con rol: El Agent lee el campo role del mensaje welcome al conectar al SaaS
  • Endpoint GET /agent/role: Consulta el rol actual y estado de Sentinel
  • _agent_role global: "primary" o "secondary", default "secondary"
• Hostname reporting: socket.gethostname() enviado en agent_status al conectar
• Auto-resume condicional: _auto_resume_sentinel() respeta el rol — Secondary no auto-resume Sentinel
• Role badge en debug.html: Muestra “Primary” (azul) o “Secondary” (gris) en la página del agente
• Campo role en /info: Respuesta JSON incluye el rol actual del agente
• Backwards compatible: Si el Agent no recibe set_role (SaaS antiguo), funciona como antes

v6.4.0 (12-02-2026)

• SNMP Interface Fix: _snmp_poll() usa snmp_interface del config SaaS (antes hardcoded "1")
• Dual-format targets: Acepta tanto formato REST (target_id/ip) como WebSocket (id/ip_address)
• SQLite migration: ALTER TABLE para columna snmp_interface en DBs existentes
• Baseline reset: Cuando snmp_interface cambia en un update_targets, se borran los contadores previos de ese target para evitar spikes por cambio de interfaz
• HC→Legacy fallback: Si ifHCInOctets (64-bit) delta = 0 pero ifInOctets (32-bit) delta > 0, usa contadores legacy (necesario para Xirrus APs donde HC devuelve 0 permanentemente)

v6.3.0 (10-02-2026)

• Metrics Maintenance UI: Página /metrics/ui con stats por tipo, purge selectivo
• Endpoints: /metrics/stats, /metrics/purge

v6.2.0 (10-02-2026)

• SNMP rate calc: Calcula Mbps desde deltas de contadores (fix bandwidth chart)
• Memory optimization: SnmpEngine singleton + aiohttp.ClientSession compartida (~-30MB)

v6.1.0 (09-02-2026)

• SNMP Support: pysnmp como dependencia del build (Sentinel SNMP bandwidth 24/7)

v6.0.9 (09-02-2026)

• Installer reliability: Retry loop (5 intentos) para PermissionError [WinError 32]

v6.0.8 (09-02-2026)

• Historical Re-sync: Backfill automático de últimas 24h al reconectar con SaaS

v6.0.7 (07-02-2026)

• Always-reinstall strategy: Simplificación del installer (sin version checks)

v6.0.0 (05-02-2026)

• Agent Home: Tools Hub — Transformación de debug.html de panel info-only a hub funcional
  • UI con 3 tabs: Status | Tools | Debug
  • 7 herramientas de red: Port Check, ICMP Ping, DNS Lookup, SSH Banner, ARP Table, Network Discovery, Port Scan
  • Cards colapsables con inputs, botón Run y resultado inline
  • Tablas scrollable para ARP, Discovery y Scan (max-height 300px, sticky headers)
• Version management: version.py es single source of truth, build_agent.bat lee de ahí
• Build scripts: Actualizados para v6.0.0 (verificación de módulos, mensajes)

v5.0.9 (05-02-2026)

• Fix auto-start: Nombre de exe fijo CreaRackAgent.exe (sin versión en nombre)
• Flag --minimized: Registro de startup incluye --minimized, parseado en run_agent()
• Silent installer flow: run_installer_flow(silent=True) suprime popups en arranque con Windows
• Uninstall mejorado: /admin/uninstall ahora elimina registro + directorio completo %APPDATA%\CreaRackAgent
• Dashboard uninstall: handleAgentUninstall() implementado en base.js
• Limpieza: Eliminados imports muertos (install_and_relaunch, setup_windows_integration) de local_agent.py
• Limpieza: setup_windows_integration() ya no se llama en cada ejecución (solo durante instalación)

v4.3.1 (29-01-2026)

• Arquitectura Modular: Refactorización completa del monolito
  • local_agent.py: 3576 → 824 líneas (-77%)
  • 7 módulos nuevos < 500 líneas cada uno
• Assets Externalizados:
  • terminal.html, debug.html → carpeta assets/
  • oui_vendors.json → base de datos MAC editable
• Build Mejorado:
  • --add-data para assets y módulos
  • Imports condicionales (frozen/dev mode)
• Documentación: AUTOPLAN_PERFORMANCE.md añadido

v4.3.0 (29-01-2026)

• Efecto Asteroids en terminales SSH
• Canvas de fondo animado con estrellas, asteroides y UFO
• Botón toggle (★) en esquina inferior derecha del terminal
• Fondo semi-transparente del xterm para ver el efecto
• Colisiones entre asteroides con física elástica
• Comunicación con ventana padre vía postMessage
• Soporte para mensajes SET_ASTEROIDS desde CreaRack

v4.0.6 (28-01-2026)

• Soporte de Clipboard en terminal SSH
• Ctrl+C: Copia texto seleccionado (si hay selección), envía SIGINT si no
• Ctrl+V: Pega desde el clipboard
• Ctrl+Shift+C/V: Atajos alternativos siempre disponibles

v4.0.5 (27-01-2026)

• Network Discovery endpoints para escaneo híbrido de red
• /network/arp-table: Leer tabla ARP de Windows con vendors MAC OUI
• /network/hostname: DNS reverse lookup para resolver hostnames
• Base de datos OUI: ~150+ fabricantes de dispositivos de red
• Optimización: Soporte para escaneo paralelo de múltiples IPs

v4.0.0 (27-01-2026)

• Scrapli integrado para soporte multi-vendor
• Cluster Mode con ejecución paralela real
• Endpoints de cluster: execute, script, health, backup
• LocalScrapliManager embebido en el agente
• ClusterEngine para orquestación paralela
• Panel de debug muestra info de Scrapli

v3.0.1 (28-01-2026)

• Panel de debug visual en endpoint raíz
• Endpoint /check para verificar conectividad de IPs privadas
• Auto-instalación a %APPDATA%\CreaRackAgent\
• Desinstalador automático generado en instalación
• Optimización de backups con idle detection

v3.0.0 (26-01-2026)

• Versión inicial para Django
• Terminal SSH con xterm.js
• SFTP integrado
• Persistencia de sesiones
• Protocolo crearack:// registrado

Documento relacionado: NETWORK_MANAGEMENT_IMPLEMENTATION.md

Véase también

• [[crearack-tech—admin—local-agent]] — operativa admin del Local Agent
• [[crearack-tech—guides—local-agent-guide]] — guía del Local Agent
• [[crearack-tech—agents—dev-terminal]] — agente técnico del Terminal
• [[concept—terminal—local-agent]] — concepto del Local Agent del Terminal
• [[entity—terminal—model—agentinstance]] — modelo AgentInstance (Local Agent)
• [[crearack—terminal—local-agent]] — Local Agent desde la perspectiva del usuario