Network Management Implementation Guide

Fecha: 29-01-2026 Estado: Implementado y Probado Versión: v6.1.2

1. Resumen Ejecutivo

Este documento detalla la implementación completa del sistema Network Management para CreaRack Pro Django, incluyendo:

• CredentialManager: Encriptación/desencriptación de credenciales con Fernet
• ScrapliManager: Automatización de red para dispositivos con IPs públicas
• Local Agent v3.0.0: Terminal SSH para dispositivos con IPs privadas

2. Arquitectura del Sistema

┌─────────────────────────────────────────────────────────────────────────┐
│                         CreaRack Pro Django                              │
│                         (localhost:8000)                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
│  │ CredentialManager│    │  ScrapliManager  │    │   Network API    │  │
│  │ (Fernet AES-128) │    │ (Async SSH)      │    │ (Django Ninja)   │  │
│  └────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘  │
│           │                       │                       │             │
│           └───────────────────────┼───────────────────────┘             │
│                                   │                                      │
└───────────────────────────────────┼──────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    │                               │
                    ▼                               ▼
        ┌───────────────────┐           ┌───────────────────┐
        │   IP PÚBLICA      │           │   IP PRIVADA      │
        │                   │           │                   │
        │  ScrapliManager   │           │   Local Agent     │
        │  (desde servidor) │           │  (localhost:5050) │
        │                   │           │                   │
        └─────────┬─────────┘           └─────────┬─────────┘
                  │                               │
                  ▼                               ▼
        ┌───────────────────┐           ┌───────────────────┐
        │  Dispositivo de   │           │  Dispositivo de   │
        │  Red (Público)    │           │  Red (Privado)    │
        │  203.0.113.x      │           │  192.168.x.x      │
        └───────────────────┘           └───────────────────┘

3. Componentes Implementados

3.1 CredentialManager

Ubicación: core/security/credential_manager.py

Funcionalidades:

from core.security import CredentialManager

# Encriptar credencial
encrypted = CredentialManager.encrypt_credential("mi_password")

# Desencriptar credencial
decrypted = CredentialManager.decrypt_credential(encrypted)

# Desencriptación segura (no lanza excepción)
value = CredentialManager.safe_decrypt(encrypted, "password")

# Verificar si está encriptado (tokens Fernet empiezan con gAAAAA)
is_enc = CredentialManager.is_encrypted(value)

# Encriptar/desencriptar diccionarios
encrypted_dict = CredentialManager.encrypt_dict({"username": "admin", "password": "secret"})
decrypted_dict = CredentialManager.decrypt_dict(encrypted_dict, ["username", "password"])

# Enmascarar para UI
masked = CredentialManager.mask_credential("admin123", visible_chars=2)  # "ad******"

Seguridad:

• Usa Fernet (AES-128 en modo CBC)
• Clave derivada de Django’s SECRET_KEY via SHA256
• Fallback con DEV_KEY para migraciones

3.2 ScrapliManager

Ubicación: network/services/scrapli_manager.py

Vendors soportados:

Uso básico:

from network.services import ScrapliManager
import asyncio

# Método conveniente para ejecutar scripts
async def run():
    output, error = await ScrapliManager.execute_script(
        host="203.0.113.10",
        username="admin",
        password="secret",
        commands=["show version", "show interfaces"],
        platform="cisco_ios",
        port=22,
    )
    return output, error

output, error = asyncio.run(run())

Gestión de sesiones:

# Conectar
success, error = await ScrapliManager.connect(
    session_id="session_001",
    host="203.0.113.10",
    username="admin",
    password="secret",
    platform="cisco_ios"
)

# Enviar comandos
output = await ScrapliManager.send_command(session_id, "show version")
output, error = await ScrapliManager.send_commands(session_id, ["cmd1", "cmd2"])

# Desconectar
await ScrapliManager.disconnect(session_id)

3.3 DeviceConfigService (v6.1.0)

Ubicación: network/services/device_config.py

Propósito: Centralizar helpers de parsing de configuración de dispositivos, eliminando código duplicado en network/api.py.

Funciones disponibles:

from network.services.device_config import (
    parse_device_config,
    get_device_ip,
    get_decrypted_credentials,
    is_private_ip,
    get_device_vendor,
    get_device_port,
)

# Parsear management_config JSON de un dispositivo
config = parse_device_config(device)  # Returns {} si inválido

# Obtener IP (soporta múltiples formatos de config)
ip = get_device_ip(config, decrypt=True, device_id=device.id)

# Obtener todas las credenciales desencriptadas
creds = get_decrypted_credentials(config, device_id=device.id)
# Returns: {hostname, username, password, enable_password, vendor, port}

# Verificar si IP es privada (RFC 1918)
is_priv, error = is_private_ip("192.168.1.1")  # (True, None)

# Helpers simples
vendor = get_device_vendor(config)  # "cisco_ios" o "generic"
port = get_device_port(config)      # 22 por defecto

Formatos de config soportados:

• config.ip_address, config.ip, config.host
• config.connection.ip_address, config.connection.ip, config.connection.host

3.4 Local Agent v4.3.1

Ubicación: terminal/agent/

Características:

• Puerto: 5050 (localhost)
• Framework: FastAPI + uvicorn
• SSH: asyncssh
• Terminal: xterm.js (CDN)
• Persistencia de sesiones
• SFTP integrado
• Auto-instalación a %APPDATA%\CreaRackAgent\
• Panel de debug visual en http://localhost:5050/
• Desinstalador automático (uninstall.bat)
• Verificación de estado para IPs privadas (/check)
• Arquitectura Modular (v4.3.1)

Estructura de archivos (v4.3.1 - Modular):

terminal/agent/
├── local_agent.py       (824 líneas)  # Main FastAPI, endpoints, WebSocket
├── models.py            (86 líneas)   # Pydantic schemas
├── windows_integration.py (205 líneas) # Install/uninstall Windows
├── logging_handler.py   (92 líneas)   # MemoryLogHandler + WebSocket
├── ssh_bridge.py        (173 líneas)  # Conexiones SSH persistentes
├── scrapli_manager.py   (198 líneas)  # Multi-vendor automation
├── cluster_engine.py    (237 líneas)  # Ejecución paralela
├── network_utils.py     (485 líneas)  # Ping, scan, ARP, discovery
└── assets/
    ├── terminal.html    # UI terminal con xterm.js + Asteroids
    ├── debug.html       # Panel de debug
    └── oui_vendors.json # MAC vendor database (~230 entries)
├── requirements.txt    # Dependencias del agente
├── build.bat          # Script de compilación Windows
└── README.md          # Documentación del agente

Endpoints del Agente:

Protocolo WebSocket:

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

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

// Recibir mensajes
// { type: "output", data: "..." }
// { type: "status", message: "Tunnel Established!" }
// { type: "error", message: "Connectivity failed" }

4. API Endpoints de Network Management

4.1 Device Management

4.2 Backup Management

4.3 Script Management

4.4 Lógica Híbrida de Ejecución

El endpoint /api/scripts/{id}/execute implementa lógica híbrida:

# Payload
{
    "device_id": 123,
    "username": "admin",
    "password": "secret"
}

# Respuesta IP PRIVADA (422)
{
    "error": "USE_LOCAL_AGENT",
    "message": "Private IP detected. Use Local Agent for execution.",
    "use_local_agent": true,
    "script_content": "[\"show version\"]",
    "ip_address": "192.168.1.1",
    "vendor": "cisco_ios"
}

# Respuesta IP PÚBLICA (200)
{
    "output": "Cisco IOS Software...",
    "status": "success"
}

5. Dependencias

5.1 Backend Django (requirements.txt)

# Security
cryptography>=43.0.0  # Para CredentialManager (Fernet)

# Async & Networking
scrapli==2024.7.30    # Automatización de red
asyncssh==2.18.0      # SSH asíncrono

5.2 Local Agent (terminal/agent/requirements.txt)

fastapi>=0.115.0
uvicorn[standard]>=0.34.0
asyncssh>=2.18.0
pydantic>=2.10.0

6. Configuración

6.1 Django Settings

El CredentialManager usa settings.SECRET_KEY para derivar la clave de encriptación:

# config/settings/base.py
SECRET_KEY = os.getenv("DJANGO_SECRET_KEY", "your-secret-key")

6.2 CSP del Local Agent

El agente permite iframe desde:

• http://localhost:8000 (Django)
• http://localhost:5000 (Flask dev)
• https://eduesedu.pythonanywhere.com (Producción)

7. Estado de Pruebas (26-01-2026)

7.1 CredentialManager ✅ COMPLETADO

• Encriptar/desencriptar credenciales
• Fallback con DEV_KEY
• Detección de valores encriptados (is_encrypted())
• Enmascaramiento para UI (mask_credential())
• Encriptar/desencriptar diccionarios

7.2 ScrapliManager ✅ COMPLETADO

• Conexión a dispositivo (probado con Xirrus XD2-240)
• Ejecución de comandos show
• Fix: execute_script ahora usa send_show_commands para drivers genéricos
• Ejecución de comandos config (requiere vendor específico)
• Manejo de errores de conexión

7.3 Local Agent v3.0.1 ✅ COMPLETADO

• Compilar ejecutable Windows (CreaRackAgent.exe ~20MB)
• Conexión SSH a dispositivo
• Terminal UI con XTerm.js
• Persistencia de sesiones
• SFTP endpoints implementados
• Auto-instalación a %APPDATA%\CreaRackAgent\
• Panel de debug visual en http://localhost:5050/
• Endpoint /check para verificar estado de dispositivos con IP privada
• Desinstalador automático generado en directorio de instalación
• Optimización de backups con idle detection (1.5s vs 5s fijo)

7.4 Integración ✅ COMPLETADO

• Flujo completo IP privada (Local Agent) - Terminal SSH funcional
• Flujo completo IP privada (ScrapliManager desde Docker) - Probado con Xirrus
• Terminal SSH desde UI (Panel Properties → SSH Terminal)
• Guardar configuración con credenciales encriptadas
• Configuration Snapshots - Modal funcional con create/list/compare/restore

7.5 Configuration Snapshots ✅ COMPLETADO (26-01-2026)

• Modal “Configuration Snapshots” accesible desde SSH Backups y Terminal SSH
• Crear snapshots manuales con nombre descriptivo
• Listar snapshots guardados con tipo (Manual/Auto)
• Comparar 2 snapshots (diff view)
• Restore confirmation modal
• Backend endpoint POST /api/network/device/{id}/backup/trigger crea ConfigBackup real
• UI sin X de cierre (usa botones Close/Cancel)

8. Compilación del Local Agent

Windows (Recomendado)

# Usar el script de build automatizado
build_agent.bat

El script build_agent.bat automatiza:

1. Limpieza de builds anteriores
2. Instalación de dependencias
3. Compilación con PyInstaller (hidden imports configurados)
4. Copia a static/downloads/
5. Limpieza post-build

Manual (Si el script falla)

cd terminal/agent
pip install -r requirements.txt
pip install pyinstaller
pyinstaller --noconsole --onefile --name "CreaRackAgent" ^
    --hidden-import=uvicorn --hidden-import=asyncssh ^
    local_agent.py
copy dist\CreaRackAgent.exe ..\..\static\downloads\

Linux/macOS

cd terminal/agent
pip install -r requirements.txt
pip install pyinstaller
pyinstaller --onefile --name CreaRackAgent local_agent.py

9. Troubleshooting

Error: “SECRET_KEY is not configured”

• Verificar que DJANGO_SECRET_KEY está en .env

Error: “Connection failed” en Scrapli

• Verificar conectividad de red al dispositivo
• Verificar credenciales SSH
• Verificar que el puerto SSH está abierto

Local Agent no responde

• Verificar que puerto 5050 está disponible
• Revisar logs en %APPDATA%\CreaRackAgent\agent.log

Credenciales no se desencriptan

• Puede ser que se encriptaron con otra SECRET_KEY
• El sistema intenta fallback con DEV_KEY automáticamente

10. Archivos Creados en Esta Sesión

CreaRack_Pro_app_Django/
├── core/
│   └── security/
│       ├── __init__.py              # Export CredentialManager
│       └── credential_manager.py    # Implementación Fernet
├── network/
│   ├── api.py                       # ACTUALIZADO - Usa CredentialManager y ScrapliManager
│   └── services/
│       ├── __init__.py              # Export ScrapliManager
│       └── scrapli_manager.py       # Implementación Scrapli
├── terminal/
│   └── agent/
│       ├── __init__.py
│       ├── local_agent.py           # Agente FastAPI v3.0.0
│       ├── requirements.txt         # Dependencias del agente
│       ├── build.bat                # Script compilación Windows
│       └── README.md                # Documentación del agente
├── requirements.txt                  # ACTUALIZADO - cryptography añadido
└── Documentation/
    └── NETWORK_MANAGEMENT_IMPLEMENTATION.md  # Este documento

11. Próximos Pasos

1. Rebuild Docker para instalar cryptography:

   docker compose down && docker compose build --no-cache web && docker compose up -d

2. Probar CredentialManager en Django shell:

   docker compose exec web python manage.py shell
   >>> from core.security import CredentialManager
   >>> enc = CredentialManager.encrypt_credential("test123")
   >>> CredentialManager.decrypt_credential(enc)

3. Compilar Local Agent (opcional):

   cd terminal/agent
   build.bat

4. Probar flujo completo en la UI de CreaRack Pro

Autor: Claude (Anthropic) Última actualización: 27-01-2026 (Infrastructure Health Monitor + Local Agent v4.0.0)

12. Actualización 28-01-2026

Endpoints Añadidos (Frontend Compatibility)

Se añadieron 4 endpoints faltantes para completar la integración con el frontend backups.js:

1. GET /api/network/backup/compare?id1=X&id2=Y

   • Versión GET del endpoint de comparación para compatibilidad con frontend
   • Devuelve array de líneas diff en lugar de string

2. POST /api/network/backup/{id}/restore

   • Restaurar configuración de backup a dispositivo
   • Requiere rol Admin
   • Placeholder: logging implementado, push de config pendiente de integración Scrapli

3. DELETE /api/network/backup/{id}/delete

   • Eliminar snapshot de configuración
   • Requiere rol Admin
   • Incluye logging en SystemLog

4. GET /api/network/backup/{id}/download

   • Descargar configuración como archivo .txt
   • Nombre de archivo: {device}_config_{timestamp}.txt

5. POST /api/network/device/{id}/backup/save

   • Guardar configuración obtenida via Local Agent
   • Recibe config_text directamente del frontend
   • Usado para dispositivos con IPs privadas

Flujo de Backup Completo (Implementación Híbrida)

┌─────────────────────────────────────────────────────────────────┐
│ Modal: Configuration Snapshots                                  │
├─────────────────────────────────────────────────────────────────┤
│ Name:    [Pre-event backup                                    ] │
│ Command: [show running-config                       ] [cisco_ios]│
│                                         [Close] [Save Snapshot] │
└─────────────────────────────────────────────────────────────────┘

Flujo:
1. Usuario abre modal → Se carga vendor del dispositivo
2. Comando se precarga según vendor (editable)
3. Click "Save Snapshot":
   a) Backend verifica si IP es pública o privada
   b) IP Pública → ScrapliManager ejecuta comando directo
   c) IP Privada → Frontend usa Local Agent vía WebSocket
4. Configuración guardada en ConfigBackup

Comandos por Vendor

13. Actualización 27-01-2026

13.1 Infrastructure Health Monitor

Sistema de monitoreo continuo de dispositivos de red implementado en static/js/dashboard_widgets.js.

Características:

• Polling automático cada 30 segundos
• Verificación via Agent usando endpoint /cluster/health
• Actualización de DB con status real de cada dispositivo
• Actualización de UI en tiempo real

Estados del botón Dashboard:

Control manual (consola JS):

HealthMonitor.start()   // Iniciar monitoreo
HealthMonitor.stop()    // Detener monitoreo
HealthMonitor.check()   // Check inmediato

13.2 Local Agent v4.0.0

Actualización mayor con Scrapli integrado y Cluster Mode.

Nuevas características:

• Scrapli embebido para soporte multi-vendor nativo
• Cluster Mode con ejecución paralela real (asyncio.gather)
• ClusterEngine para orquestación de comandos en múltiples dispositivos

Nuevos endpoints del Agent:

13.3 Terminal Page - Filtrado NM

La página /terminal/ ahora solo muestra dispositivos con Network Management habilitado.

Propiedades añadidas al modelo Device:

# racks/models.py
@property
def has_network_management(self):
    """Check if device has NM enabled (valid config with IP)."""

@property
def management_ip(self):
    """Extract management IP from config JSON (auto-decrypt)."""

@property
def management_vendor(self):
    """Extract vendor from config JSON."""

Características:

• Auto-desencriptado de IPs Fernet
• Filtrado por organización (SaaS isolation)
• Excluye racks en papelera

13.4 Nuevos Endpoints API

13.5 Fixes Aplicados

1. NM Disable: El checkbox “Network Mgmt” ahora persiste enabled: false a DB
2. Status Update: El indicador de status se actualiza tras conexión SSH exitosa
3. URLs Legacy: Corregidas URLs Flask /network/api/ → /api/network/
4. Auto Health Check: Al guardar SSH Config, se verifica conectividad inmediatamente

14. Network Tools (27-01-2026)

14.1 Network Tools Module v2.6

Módulo frontend completo para herramientas de red, ubicado en static/js/modules/network_tools.js.

Características:

• Network Discovery: Escaneo híbrido de red (ICMP + ARP + TCP)
• Port Scanner: Escaneo de puertos en dispositivo específico
• Health Check: Verificación de conectividad masiva
• Persistencia: Resultados de Discovery sobreviven recarga de página

14.2 Network Discovery (Hybrid Approach)

El Discovery usa un enfoque híbrido similar a Angry IP Scanner:

┌─────────────────────────────────────────────────────────────┐
│                    Discovery Phases                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Phase 1: ICMP Ping Scan (fuerza entradas ARP)              │
│      └─► 192.168.0.1-254                                    │
│                                                              │
│  Phase 2: ARP Table Check (lee cache ARP de Windows)        │
│      └─► Obtiene MAC + Vendor de dispositivos silenciosos   │
│                                                              │
│  Phase 3: TCP Port Scan (22, 80, 443, 23)                   │
│      └─► Detecta hosts que no responden a ping/ARP          │
│                                                              │
│  Phase 4: Detailed Port Scan (todos los hosts)              │
│      └─► Identifica servicios (SSH, HTTP, Telnet)           │
│                                                              │
│  Phase 5: DNS Reverse Lookup (hostnames)                    │
│      └─► Resuelve nombres de host                           │
│                                                              │
│  Final: Sort by IP address                                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

14.3 Columnas de Resultados

Características de la tabla:

• Columnas de ancho fijo (no dinámico)
• Redimensionable manualmente via drag en bordes
• Ordenamiento por IP al finalizar Discovery
• Fondo sólido (no transparente)

14.4 Persistencia de Resultados

Los resultados de Discovery se guardan en localStorage:

// Estructura de datos persistidos
{
    timestamp: 1706380800000,
    range: "192.168.0.1-254",
    results: [
        {
            ip: "192.168.0.1",
            mac: "00-11-22-33-44-55",
            hostname: "router.local",
            vendor: "Cisco Systems",
            ports: [22, 80],
            method: "ICMP"
        }
    ]
}

Al recargar la página, se restauran automáticamente con indicador:

"Restored: 11 devices (5m ago)"

14.5 Tab Coordination

NetworkTools y TerminalApp comparten el mismo espacio. Coordinación implementada:

1. NetworkTools.activateTab(): Oculta contenedores de TerminalApp
2. TerminalApp.activateTab(): Oculta contenedores de NetworkTools
3. quickConnect(): Oculta Discovery antes de abrir modal SSH

14.6 Endpoints del Agent Usados

14.7 Documentación Relacionada

Ver documentación completa en:

• Documentation/NETWORK_TOOLS.md - Guía detallada de Network Tools
• Documentation/LOCAL_AGENT_GUIDE.md - Endpoints del Local Agent

Véase también

• [[crearack-tech—backend—auto-provision-guide]] — guía técnica de Auto-Provision
• [[crearack-tech—backend—multi-vendor-snmp-guide]] — SNMP multi-vendor en backend
• [[crearack-tech—backend—network-tools]] — herramientas de red backend
• [[crearack—network—gestion-red]] — gestión de red para usuarios
• [[crearack—network—scripts-red]] — scripts de red automatizados
• [[entity—network—model—deviceprofile]] — modelo DeviceProfile