Agente · dev-auto-provision

Propósito

Desarrollo y mantenimiento del módulo Auto-Provision de CreaRack-Pro. Cubre la app network/, el pipeline de descubrimiento de dispositivos, la base de datos de vendors y las integraciones con Observatory, Rack Editor y Wireless Monitor.

Estructura de archivos

Backend

network/
├── models.py                         # DeviceProfile, VendorProfile, CustomMib
├── api/
│   ├── discovery.py                  # Endpoints de discovery
│   ├── profiles.py                   # CRUD perfiles + configuración
│   ├── vendor.py                     # CRUD vendors + custom MIBs
│   └── common.py                     # Schemas Pydantic (DeviceProfileOut, etc.)
└── services/
    ├── device_discovery.py           # DeviceDiscoveryService — pipeline 6 etapas
    ├── auto_config.py                # AutoConfigService — configure-observatory + stencil
    ├── vendor_registry.py            # VendorProfileRegistry — L1/L2 cache + lookups
    ├── port_config_reader.py         # PortConfigReader — SNMP Q-BRIDGE + SSH
    ├── mib_manager.py                # MibManager — pysmi download/compilation
    └── oui_lookup.py                 # MAC OUI vendor lookup (38,893 entries)

Frontend

static/js/network/
├── auto_provision.js                 # AutoProvisionWizard class (orquestador)
└── auto_provision/
    ├── discovery.js                  # Lógica discovery (~650 LOC)
    ├── results.js                    # Tabla de resultados (~400 LOC)
    ├── actions.js                    # Acciones batch (~350 LOC)
    ├── deep_discovery.js             # MIB upload + OID probe (~500 LOC)
    └── sessions.js                   # Persistencia localStorage (~200 LOC)

Modelos

DeviceProfile

~40 campos. Almacena todo lo descubierto sobre un dispositivo.

Campos clave:

• ip_address, mac_address, hostname, vendor, model, serial_number
• os_type, os_version, device_type (router/switch/firewall/access_point/other)
• supports_snmp, supports_ssh
• confidence_score (0-100)
• snmp_community, snmp_version, snmp_v3_* (credenciales v3)
• interfaces (dict ifIndex→data), lldp_neighbors, cdp_neighbors
• deep_snmp_data (JSONField — datos extendidos por categoría)
• discovery_method (ping/snmp/ssh/http)

VendorProfile

Base de datos de vendors. 17 curated (priority 10-90) + ~1,600 IANA (priority 100+).

Campos clave:

• slug, display_name, aliases
• snmp_communities — comunidades vendor-specific
• sys_descr_patterns — regex para sysDescr
• sys_object_id_prefix — prefijo OID enterprise
• scrapli_platform — plataforma SSH
• deep_discovery_oids — OIDs extendidos por categoría
• monitoring_oids, fast_poll_oids — para Observatory

Pipeline de descubrimiento (6 etapas)

DeviceDiscoveryService en network/services/device_discovery.py:

Stage 1: ICMP Ping      → Verificar alcanzabilidad + RTT
Stage 2: SNMP Probing   → sysDescr, sysObjectID, ifTable, hardware OIDs
Stage 3: SSH Fallback   → show version/inventory/interfaces (si SNMP falla)
Stage 4: LLDP/CDP       → Descubrimiento de vecinos
Stage 5: Stencil Match  → Fuzzy matching con stencils del Rack Editor
Stage 6: Confidence     → Calcular score 0-100%

Stage 2 — SNMP Probing

SNMPv2c (default):

1. Community rotation: prueba community proporcionada → vendor-specific → fallbacks genéricos
2. sysObjectID → lookup O(1) en VendorProfileRegistry por prefijo enterprise
3. sysDescr → regex matching contra VendorProfile.sys_descr_patterns
4. ifTable walk → nombres, tipos, velocidades, MTUs
5. Hardware OIDs → CPU, memoria (HOST-RESOURCES-MIB)

SNMPv3 (cuando snmp_version == 'v3'):

• Credenciales directas via UsmUserData — NO rota communities
• build_snmp_auth() en network/services/device_discovery/snmp_auth.py
• Si falla → error snmpv3_auth_failed (no fallback a v2c)

Confidence Scoring

Vendor autodetect pipeline (prioridad)

1. sysObjectID → enterprise OID prefix lookup (más fiable)
2. sysDescr → regex patterns (fallback SNMP)
3. Device stencil_name del Rack Editor vinculado (cuando no hay SNMP)
4. HTTP fingerprint → headers + body patterns (14 vendors)
5. MAC OUI → IEEE database (último recurso)

⚠ El vendor siempre se resuelve automáticamente. NO hay selector manual de vendor en el wizard.

Deep Discovery (Stage 7, on-demand)

Activado via POST /profiles/{id}/deep-discover:

• Descarga MIBs vendor-specific via pysmi
• SNMP walks/gets extendidos por categoría: hardware, vlans, wireless, clients, ssids, cpu, memory, environment
• Almacena en DeviceProfile.deep_snmp_data (JSONField)
• Límite: máximo 200 OIDs por vendor (MAX_DEEP_DISCOVERY_OIDS)
• Dispatch: via WebSocket al Agent Primary (mode: "ws") o REST directo (mode: "rest")

API Endpoints — Discovery y Profiles (21 endpoints)

Discovery

Profile Management

Configuration

Vendor Profiles

MAC OUI

Integración con Observatory

POST /configure-observatory → AutoConfigService:

1. Crea/actualiza MonitoringTarget con ping_enabled=True + snmp_enabled=True
2. Auto-selecciona interfaz física primaria via _select_primary_interface()
3. Copia monitoring_oids y fast_poll_oids del VendorProfile al config del target
4. Notifica Agent via WebSocket (update_targets)

Pipeline selección de interfaz SNMP (_select_primary_interface)

DeviceProfile.interfaces (dict ifIndex→data)
    ↓
1. Excluir virtuales: wds, bridge, br-, lo, loopback, null, vlan, tunnel,
   tun, tap, bond, lag, port-channel, management, mgmt, iap, bvi,
   nve, stack, cpu, internal, unrouted
    ↓
2. Preferir físicas: gig, eth, ge-, xe-, te-, fa, gigabitethernet,
   fastethernet, tengigabitethernet
    ↓
3. Ordenar: physical first → UP status (ifOperStatus=1) → mayor ifSpeed
    ↓
4. Retorna primer candidato como config.snmp_interface (ifIndex)

Quirks por vendor (ifIndex conocidos)

Más quirks en backend/MULTI_VENDOR_SNMP_GUIDE.md §4

Integración con Rack Editor

DeviceProfile → "Add to Rack" → floating panel
    ├── auto-fill name + management_config (IP)
    ├── auto-select stencil sugerido (fuzzy match)
    └── propagate interfaces → enriched port format
        {label, live: {vlan, description, speed, mode}, desired: {...}}

Integración con Local Agent (producción)

En producción el SaaS no puede alcanzar IPs privadas. El Agent actúa como proxy de red.

5 fases via Agent (localhost:5050):

⚠ Confidence 10-20% en todos los dispositivos = Agent no conectado o no accesible. Verificar Fleet Manager en Observatory.

Dos modos de descubrimiento

Bulk-enrich concurrencia: max 5 paralelos (semáforo), usa quick_mode=True (~2s/device).

Persistencia de sesiones (frontend)

• Scans guardados en localStorage["auto_provision_scans"] (máx 20 sesiones)
• Session keepalive cada 60s durante scans activos
• “Load Previous Results” para restaurar scans anteriores

Vendors curated (17)

Xirrus, Cambium, Cisco, Juniper, Arista, Huawei, HP, Ubiquiti, MikroTik, Fortinet, Palo Alto, Ruckus, Meraki, Dell, Netgear, TP-Link, ZyXEL.

Troubleshooting frecuente

API Endpoints adicionales (38 endpoints)

Endpoints de network/ no cubiertos en la seccion principal (discovery/profiles/vendors).

Devices (/api/network/device/)

Port Connections (/api/network/port-connections/)

Schemas: PortConnectionIn (device_id, port_key, profile_id, notes), DeviceConnectionIn (+ cable_type, cable_color, cable_length)

Cable Report (/api/network/cable-report/)

Query params: scope (device/rack/all), id (device_id o rack_id)

Device Groups (/api/network/device-groups/)

Backups (/api/network/backup/)

Patron Cloud/Agent: trigger devuelve 422 + USE_LOCAL_AGENT para IPs privadas.

Scripts (/api/scripts/)

Router montado en /api/scripts/ (separado de /api/network/). Misma logica 422 USE_LOCAL_AGENT para IPs privadas.

Convenciones y restricciones

• El vendor siempre se resuelve automáticamente — no añadir selector manual
• SNMPv3: no hacer fallback a v2c si falla — retornar snmpv3_auth_failed
• MAX_DEEP_DISCOVERY_OIDS = 200 — no superar este límite por vendor
• _select_primary_interface() es la única fuente de verdad para snmp_interface — no hardcodear ifIndex
• Cambio de snmp_interface en update_targets → resetear baseline de contadores SNMP en Agent (evita spikes)
• Formato enriched ports para Rack Editor: {label, live: {vlan, description, speed, mode}, desired: {...}}

Véase también

• [[concept—network—auto-provision]] — concepto de auto-descubrimiento de red
• [[crearack-tech—backend—auto-provision-guide]] — guía técnica de Auto-Provision
• [[crearack—network—auto-provision-wizard]] — wizard de Auto-Provision
• [[crearack-tech—backend—multi-vendor-snmp-guide]] — SNMP multi-vendor
• [[entity—network—model—deviceprofile]] — perfil de dispositivo descubierto
• [[entity—network—model—vendorprofile]] — vendor y sus MIBs asociadas
• [[entity—network—model—custommib]] — MIB personalizada compilada
• [[crearack-tech—guides—port-assignment-guide]] — asignación de puertos físicos