Auto-Provision — Technical Guide

Auto-Provision — Technical Guide

Sistema completo de descubrimiento y aprovisionamiento automático de dispositivos de red. Versión: Fase 1-10 completadas | Fase 8 (SNMPv3) completada en v1.0.37

1. Overview

Qué hace Auto-Provision

Auto-Provision descubre dispositivos de red en una subred, identifica vendor/modelo/capacidades via SNMP/SSH/HTTP, y los provisiona automáticamente en Rack Editor, Observatory y Wireless Monitor.

Requisito: Local Agent

En producción (SaaS en Hetzner), el servidor no puede alcanzar IPs privadas (192.168.x.x). Todo el descubrimiento SNMP/HTTP se enruta a través del Local Agent (localhost:5050) instalado en la red del cliente.

┌──────────┐    ┌────────────────┐    ┌──────────────┐    ┌──────────┐
│  Browser │───▶│   SaaS API     │───▶│  Local Agent │───▶│  Device  │
│          │    │  (Hetzner)     │    │  (localhost) │    │ (SNMP)   │
└──────────┘    └────────────────┘    └──────────────┘    └──────────┘
                        │                     │
                   Enrichment            ICMP / SNMP
                   Business Logic        SSH / HTTP

Dos modos de descubrimiento

Conceptos clave

2. API Reference

Base URL: /api/network/

2.1 Discovery Endpoints

POST /auto-provision/discover

Descubrimiento completo de un dispositivo (6 etapas).

Request (DiscoverRequest):

{
  "ip": "192.168.1.10",
  "snmp_community": "public",
  "snmp_version": "v2c",
  "snmp_v3_username": null,
  "snmp_v3_auth_protocol": null,
  "snmp_v3_auth_key": null,
  "snmp_v3_priv_protocol": null,
  "snmp_v3_priv_key": null,
  "ssh_username": "admin",
  "ssh_password": "password",
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "vendor_hint": "Cisco",
  "rtt_ms": 25.5,
  "quick_mode": false,
  "snmp_data": {},
  "http_data": {}
}

Solo ip es requerido. Todos los demás campos son opcionales.

Vendor autodetect: El vendor/platform se resuelve automáticamente desde SNMP sysDescr/sysObjectID durante el discovery. Si no hay datos SNMP, se usa como fallback el stencil_name del Device vinculado en el Rack Editor. El campo device_type se ha eliminado del request — ya no se selecciona manualmente.

SNMPv3 example (authPriv):

{
  "ip": "10.0.0.1",
  "snmp_version": "v3",
  "snmp_v3_username": "snmpuser",
  "snmp_v3_auth_protocol": "SHA256",
  "snmp_v3_auth_key": "authPassphrase",
  "snmp_v3_priv_protocol": "AES128",
  "snmp_v3_priv_key": "privPassphrase"
}

Con snmp_version: "v3", el pipeline no rota communities — usa directamente las credenciales USM proporcionadas.

Response (200): DeviceProfileOut — ver Schema completo.

Errores: 400 si el host no es alcanzable.

POST /auto-provision/bulk-enrich

Enriquecimiento rápido de múltiples hosts (post-ping sweep).

Request (BulkEnrichRequest):

{
  "hosts": [
    { "ip": "192.168.1.100", "mac": "AA:BB:CC:00:00:01", "vendor_hint": "Xirrus", "rtt_ms": 15.2, "snmp_data": null, "http_data": null },
    { "ip": "192.168.1.101", "mac": "AA:BB:CC:00:00:02", "vendor_hint": "Cambium", "rtt_ms": 18.5 }
  ],
  "snmp_community": "public",
  "snmp_version": "v2c",
  "snmp_v3_username": null,
  "snmp_v3_auth_protocol": null,
  "snmp_v3_auth_key": null,
  "snmp_v3_priv_protocol": null,
  "snmp_v3_priv_key": null
}

Response (200): Lista de DeviceProfileOut.

Concurrencia: Max 5 paralelos (semáforo). Usa quick_mode=True para velocidad (~2s/device vs ~7s).

POST /auto-provision/bulk-discover

Descubrimiento de subred completa (backend-only, sin Agent).

Request (BulkDiscoverRequest):

{
  "subnet": "192.168.1.0/24",
  "snmp_community": "public",
  "snmp_version": "v2c",
  "max_concurrent": 20
}

Los 3 endpoints de discovery aceptan los mismos 6 campos SNMPv3 opcionales (snmp_version, snmp_v3_username, snmp_v3_auth_protocol, snmp_v3_auth_key, snmp_v3_priv_protocol, snmp_v3_priv_key).

Response (200): Lista de DeviceProfileOut para hosts alcanzables.

Soporta CIDR /20 a /30.

POST /auto-provision/profiles/{id}/deep-discover

Descubrimiento extendido con MIBs vendor-specific (hardware, wireless, environment).

Response (200):

{
  "status": "dispatched",
  "profile_id": 42,
  "mode": "ws"
}

• mode: "ws" → Dispatched via WebSocket al Agent primario
• mode: "rest" → Devuelve tasks para que el browser los envíe directamente al Agent

Límite: Máximo 200 OIDs por vendor (prioridad: hardware > wireless > ssids > clients).

GET /auto-provision/profiles/{id}/deep-discover-status

Estado del job de deep discovery.

Response (200):

{ "status": "running", "done": 1, "failed": 0 }

Valores de status: idle, running, complete, failed.

2.2 Profile Management

GET /auto-provision/profiles

Lista todos los DeviceProfiles con filtros opcionales.

Query params:

• vendor (string): Filtro por vendor (substring, case-insensitive)
• device_type (string): router, switch, firewall, access_point, other
• min_confidence (int): Score mínimo 0-100
• snmp_only (bool): Solo devices con SNMP

Response (200): Lista paginada de DeviceProfileOut.

GET /auto-provision/profiles/{id}

Detalle completo de un DeviceProfile.

PUT /auto-provision/profiles/{id}

Actualizar campos básicos (correcciones manuales).

Request (ProfileUpdateRequest):

{
  "hostname": "core-router-1",
  "vendor": "Cisco",
  "model": "ISR 4451",
  "serial_number": "FDO211900XYZ"
}

DELETE /auto-provision/profiles/{id}

Eliminar DeviceProfile. No elimina Device ni MonitoringTarget vinculados.

GET /device-profile/by-device/{device_id}

Buscar DeviceProfile vinculado a un Device del Rack Editor.

• 200 con DeviceProfileOut si existe
• 204 si no hay perfil vinculado

2.3 Configuration Endpoints

POST /auto-provision/profiles/{id}/configure-observatory

Auto-crear MonitoringTarget en Observatory.

Response (200):

{
  "success": true,
  "target_id": 123,
  "target_name": "192.168.1.10",
  "snmp_enabled": true,
  "selected_interfaces_count": 2,
  "message": "MonitoringTarget configured successfully"
}

Acciones automáticas:

1. Crea MonitoringTarget (o actualiza existente)
2. Habilita ping (siempre) + SNMP (si soportado)
3. Auto-selecciona interfaz física primaria para bandwidth polling (ver §6.1)
4. Copia monitoring_oids y fast_poll_oids del VendorProfile al config del target
5. Notifica Agent via WebSocket (update_targets)

POST /auto-provision/profiles/{id}/suggest-stencil

Sugiere stencil del Rack Editor por fuzzy matching vendor/modelo.

Response (200):

{
  "stencil_id": 42,
  "stencil_name": "Cisco ISR 4451-X",
  "manufacturer": "Cisco",
  "confidence": 85,
  "u_height": 2,
  "suggested": true
}

GET /auto-provision/profiles/{id}/validation

Validar calidad y completitud del perfil.

Response (200):

{
  "valid": false,
  "score": 65,
  "issues": ["Low confidence score (65%)", "No interfaces detected"],
  "recommendations": ["Re-run with SNMP/SSH credentials", "Run configure-observatory"]
}

POST /auto-provision/profiles/{id}/propagate-ports

Propagar interfaces SNMP al Rack Editor Device (formato enriched ports).

Response (200):

{
  "profile_id": 42,
  "linked_device_id": 123,
  "interfaces_count": 8,
  "propagated": true,
  "ports_created": 8
}

POST /device-profile/{id}/read-port-config

Leer configuración de puertos via SNMP Q-BRIDGE-MIB o SSH.

Request (ReadPortConfigRequest):

{
  "protocol": "auto",
  "ssh_username": "admin",
  "ssh_password": "password"
}

Response (200):

{
  "portCount": 48,
  "sfpCount": 4,
  "readMethod": "snmp",
  "ports": {
    "Ethernet1": {
      "name": "Ethernet1",
      "adminStatus": "up",
      "operStatus": "up",
      "vlan": 100,
      "description": "Uplink to Core",
      "speed": "10G",
      "mode": "trunk"
    }
  }
}

POST /device-profile/{id}/refresh-interfaces

Re-escanear ifTable SNMP sin redescubrimiento completo.

2.4 Vendor Profile Endpoints

GET /vendor-profiles/

Lista todos los VendorProfiles. Query param: active_only (bool, default true).

GET /vendor-profiles/{slug}/

Detalle de un VendorProfile.

POST /vendor-profiles/

Crear VendorProfile (admin only).

Request (VendorProfileInput):

{
  "slug": "arista",
  "display_name": "Arista Networks",
  "aliases": ["arista"],
  "snmp_communities": ["arista"],
  "sys_descr_patterns": ["Arista"],
  "sys_object_id_prefix": "1.3.6.1.4.1.30065",
  "scrapli_platform": "arista_eos",
  "default_device_type": "switch",
  "os_types": ["eos"],
  "priority": 10,
  "is_active": true
}

PUT /vendor-profiles/{slug}/

Actualizar VendorProfile (admin only).

GET /vendor-profiles/communities

Obtener todas las comunidades SNMP de todos los vendors (deduplicadas). Usado por el Agent para discovery.

2.5 Custom MIB Endpoints

POST /vendor-profiles/{slug}/upload-mib

Subir y compilar MIB custom. multipart/form-data, max 2MB.

Response (200):

{
  "id": 1,
  "module_name": "MY-CUSTOM-MIB",
  "compiled": true,
  "extracted_oids": [
    { "name": "myObj1", "oid": "1.3.6.1.4.1.9999.1.1.1.1", "type": "get" }
  ]
}

GET /vendor-profiles/{slug}/custom-mibs

Lista MIBs custom del vendor.

DELETE /vendor-profiles/{slug}/custom-mibs/{mib_id}

Eliminar MIB y limpiar OIDs asociados.

POST /vendor-profiles/{slug}/custom-mibs/{mib_id}/apply-oids

Aplicar OIDs seleccionados al deep discovery del vendor.

Request:

{
  "category": "custom",
  "oids": [
    { "name": "myObj1", "oid": "1.3.6.1.4.1.9999.1.1.1.1", "type": "get" }
  ]
}

Máximo 200 OIDs totales por vendor (MAX_DEEP_DISCOVERY_OIDS).

2.6 MAC OUI Lookup

POST /mac/oui-lookup

Lookup batch de MACs a vendor via IEEE OUI database (38,893 entries).

Request:

{ "macs": ["AA:BB:CC:DD:EE:FF", "00:1A:6B:00:00:01"] }

Response (200):

{
  "results": {
    "AA:BB:CC:DD:EE:FF": "Apple Inc.",
    "00:1A:6B:00:00:01": "Cisco Systems Inc."
  }
}

Máximo 500 MACs por request.

3. Data Schemas

3.1 DeviceProfileOut

Schema completo de respuesta para perfiles de dispositivos.

Source: network/api/common.py → DeviceProfileOut

3.2 VendorProfileOut

Source: network/api/vendor.py → VendorProfileOut

4. Discovery Pipeline

El servicio DeviceDiscoveryService ejecuta 6 etapas secuenciales:

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 (detalle)

SNMPv2c (default):

1. Community rotation → Prueba la community proporcionada, luego las del vendor detectado, luego 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 de todas las interfaces
5. Hardware OIDs → CPU, memoria total (HOST-RESOURCES-MIB)

SNMPv3 (cuando snmp_version == 'v3'):

1. Credenciales directas → Usa UsmUserData con las credenciales proporcionadas (NO rota communities)
2. Auth builder → build_snmp_auth() en network/services/device_discovery/snmp_auth.py construye el objeto de autenticación
3. Mismo pipeline → sysObjectID, sysDescr, ifTable, hardware — los datos son idénticos a v2c
4. Si falla → Retorna error snmpv3_auth_failed (no fallback a v2c automático)

Confidence Scoring

Deep Discovery (Stage 7, on-demand)

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

1. Descarga MIBs vendor-specific via pysmi (on-demand)
2. Ejecuta SNMP walks/gets extendidos por categoría
3. Categorías: hardware, vlans, wireless, clients, ssids, cpu, memory, environment
4. Almacena resultados en DeviceProfile.deep_snmp_data (JSONField)

Source: network/services/device_discovery.py → DeviceDiscoveryService

5. Frontend Wizard

Módulos

static/js/network/auto_provision/
├── discovery.js      (~650 LOC) — Lógica de discovery single/subnet
├── results.js        (~400 LOC) — Tabla de resultados + modal de detalle
├── actions.js        (~350 LOC) — Acciones batch (assign racks, wireless)
├── deep_discovery.js (~500 LOC) — MIB upload, OID probe
└── sessions.js       (~200 LOC) — Persistencia localStorage, keepalive

Orquestados por auto_provision.js (AutoProvisionWizard class).

Wizard de 3 pasos

Step 1: Discovery

• Toggle: Single IP / Subnet scan
• Campos: IP, SNMP community, SSH credentials (colapsable)
• Vendor/platform auto-detected from SNMP sysDescr/sysObjectID (no manual vendor selector)
• Progress bar durante el scan
• 5 fases via Local Agent: Ping → ARP → SNMP → HTTP → SaaS enrichment

Step 2: Results

• Tabla con 8 columnas: checkbox, IP, MAC, hostname, vendor, model, confidence, badges
• Badges: método (SNMP/SSH/HTTP/PING), MIB, IN RACK, MONITORED
• Botón “Details” abre modal con información completa
• Export CSV, select all, confidence color coding

Step 3: Actions

• “Assign Racks” → Modal multi-device con dropdown por rack
• “Send to Wireless” → Filtrar APs y navegar a /monitoring/wireless/
• “Configure Observatory” → Crear MonitoringTargets
• “Suggest Stencils” → Fuzzy matching con stencils

Persistencia

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

6. Integrations

Con Observatory

DeviceProfile → POST /configure-observatory → MonitoringTarget creado
                                              ├── ping_enabled: true
                                              ├── snmp_enabled: true (si soportado)
                                              ├── config.snmp_interface: <ifIndex>
                                              ├── config.selected_interfaces: [{ifIndex, ifDescr, ifSpeed, ifOperStatus}]
                                              ├── config.monitoring_oids: {...}  (de VendorProfile)
                                              └── config.fast_poll_oids: {...}   (de VendorProfile)

El Agent recibe notificación via WebSocket (update_targets) y añade el target a sus loops de monitoreo.

6.1 Pipeline de selección de interfaz SNMP (snmp_interface)

El campo snmp_interface determina qué ifIndex usa el Agent para polling de bandwidth (ifInOctets/ifOutOctets). La selección automática sigue este pipeline:

Discovery (Agent)          AutoConfigService (SaaS)           Agent Sentinel
─────────────────          ────────────────────────           ──────────────
1. SNMP ifTable walk  ──►  2. _select_primary_interface()  ──►  3. Polls ifIndex
   Guarda interfaces        Heurística vendor-agnostic          OIDs: ifHCInOctets.{ifIndex}
   en DeviceProfile         Elige interfaz física                     ifInOctets.{ifIndex}
   (dict: ifIndex→data)     Guarda en config.snmp_interface          ifInErrors.{ifIndex}
                                                                      ifInDiscards.{ifIndex}

Paso 2 — Heurística de _select_primary_interface() (network/services/auto_config.py):

1. Excluye interfaces 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. Prefiere interfaces físicas ethernet: gig, eth, ge-, xe-, te-, fa, gigabitethernet, fastethernet, tengigabitethernet
3. Ordena por: physical first → UP status (ifOperStatus=1) → mayor velocidad (ifSpeed)
4. Retorna el primer candidato como config.snmp_interface

Ejemplo — Xirrus XR4820 (XR11):

Interfaces descubiertas:
  ifIndex=1  wds1      (virtual, excluida)
  ifIndex=20 gig2      100 Mbps, UP
  ifIndex=28 gig1      1000 Mbps, UP  ← Seleccionada (physical, UP, highest speed)

config.snmp_interface = 28

Quirks por vendor (documentados en MULTI_VENDOR_SNMP_GUIDE.md §4):

Propagación al Agent:

• terminal/consumers.py → _send_targets() lee config.get('snmp_interface', 1) del MonitoringTarget
• Envía via WebSocket update_targets con campo snmp_interface por target
• terminal/agent/sentinel/scheduler.py → update_targets() crea SentinelTarget(snmp_interface=X)
• Si el ifIndex cambia, resetea baseline de contadores SNMP (evita spikes por cambio de interfaz)
• terminal/agent/sentinel/snmp_bandwidth.py → _snmp_bandwidth() construye OIDs con {ifIndex}

Con Rack Editor

DeviceProfile → "Add to Rack" → Floating panel en Rack Editor
                                 ├── auto-fill name + management_config (IP)
                                 ├── auto-select stencil sugerido
                                 └── propagate interfaces → enriched port format

Formato enriched: {label, live: {vlan, description, speed, mode}, desired: {...}}.

Con Wireless Monitor

DeviceProfile (device_type=access_point) → "Send to Wireless" → /monitoring/wireless/

Deep SNMP data (radios, SSIDs, clients) se renderiza en la vista de detalle del AP.

Con Local Agent

Flujo de 5 fases para discovery desde producción:

7. Vendor Support

Detección de vendor (prioridad)

1. sysObjectID → Enterprise OID prefix lookup (más fiable)
2. sysDescr → Regex patterns (fallback SNMP)
3. Device stencil_name → Fallback from linked Rack Editor Device (when SNMP unavailable)
4. HTTP fingerprint → Server headers + body patterns (14 vendors)
5. MAC OUI → IEEE OUI database (38,893 entries, último recurso)

Vendor autodetect pipeline: El vendor se resuelve siempre automáticamente. En discovery.py, se consulta primero el DeviceProfile (SNMP data). Si no tiene vendor, se busca el Device vinculado en el Rack Editor y se extrae el vendor del stencil_name. El resultado se persiste de vuelta al DeviceProfile.vendor. El selector manual de vendor se ha eliminado del SSH Config modal y del wizard de discovery.

Base de datos de vendors

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

Crear vendor custom

POST /api/network/vendor-profiles/
{
  "slug": "my-vendor",
  "display_name": "My Vendor",
  "sys_object_id_prefix": "1.3.6.1.4.1.99999",
  "snmp_communities": ["myvendor"],
  ...
}

Source: network/services/vendor_registry.py → VendorProfileRegistry

8. Troubleshooting

Confidence por vendor (tipico)

9. Source Files Reference

Backend

Frontend

Documentación relacionada

10. Dependencias

Última actualización: 18-03-2026 Mantenido por: Equipo CreaRack

Véase también

• [[crearack-tech—backend—multi-vendor-snmp-guide]] — SNMP multi-vendor en backend
• [[crearack-tech—backend—network-management-implementation]] — implementación de gestión de red
• [[crearack-tech—agents—dev-auto-provision]] — agente técnico del módulo Auto-Provision
• [[concept—network—auto-provision]] — concepto de Auto-Provision de dispositivos de red
• [[crearack—network—auto-provision-wizard]] — wizard de Auto-Provision para el usuario
• [[entity—network—model—vendorprofile]] — modelo VendorProfile