Guías operativas

Inventario

Antes de cargar equipos

Los sitios, los tipos de sitio y los roles se definen antes, en Provisioning. Los tipos de sitio y los roles son globales de la instalación (sembrados: oficina, data_center, laboratorio, punto_de_venta; wan_router, core_switch, lan_switch, firewall…); los sitios pertenecen al tenant. Un rol que no exista en el catálogo no se acepta en un equipo.

Cargar por CSV

1. Prepara un CSV con las columnas de Inventario base. name es obligatorio; hostname debe ser la IP de gestión para que el equipo sea auditable.
2. En Inventario → Importar CSV sube el archivo. Por omisión la importación fusiona sin borrar; la opción «reemplazar todo» elimina los equipos que no vienen en el archivo.
3. Revisa la respuesta: la lista devices_without_management_ip son equipos que quedaron sin IP y no se auditarán.
4. Pulsa Sincronizar inventario o lanza una auditoría: el Engine lee el inventario de la organización desde la fuente de verdad.

Alias aceptados: site se guarda como location; junos_version se acepta como os_version. En Junos la fuente de verdad agrega automáticamente el acceso NETCONF por el puerto 830.

Alta manual

Inventario → Agregar equipo. Al elegir la plataforma se rellenan fabricante y método de acceso desde el catálogo (ios, iosxe, nxos y fortiswitch por SSH; junos por NETCONF; fortigate por API). Los equipos Meraki y SD-WAN no se dan de alta a mano: se sincronizan desde Integraciones.

En el Engine, sin UI

El inventario también puede cargarse directamente en el Engine desde el CSV de equipos con su herramienta de línea de comandos, para instalaciones sin UI o para pruebas. En una instalación con UI, el inventario de la organización tiene prioridad sobre cualquier archivo del Engine.

Exportar y revisar

• Exportar CSV desde la UI: equipo, rol, sitio, tipo de sitio, plataforma, fabricante, IP, modelo, serie, versión, ASN y etiquetas.
• La vista de cada equipo muestra lo observado (modelo, serie, versión, interfaces) y la frescura: last_audited_at sólo lo estampa una auditoría real, no una importación.
• Port Intelligence y Capacidad trabajan sobre las interfaces observadas: puertos en err-disabled, sin uso en 30 días, descripción que no coincide con el vecino LLDP, saturación, PoE y pronóstico de agotamiento.

Para pasar de un inventario en archivos al de la UI, ver Cómo migrar desde CSV y YAML hacia la fuente de verdad.

Discovery

Cómo decide el método

Cada equipo tiene un método de acceso (ssh, api, netconf) explícito o inferido de su plataforma. Los equipos se agrupan por método y se recolectan en paralelo, hasta max_workers a la vez.

Qué deja

• La salida cruda de cada comando o llamada, por equipo.
• El snapshot normalizado, con la misma forma para todos los fabricantes: device_info, facts, interfaces, vecinos CDP y LLDP, bgp, ospf, eigrp, routes, arp, mac_table, cpu, memory, config.running, config_model, capabilities, status, errors.
• El estado por equipo en el detalle del job y el snapshot vigente de cada equipo, consultables desde la UI y desde la API.

Un discovery puede terminar bien, parcial (hubo equipos que fallaron y el job queda completed_with_errors) o fatal. El caché normalizado no se pisa con un snapshot fallido: si un equipo no respondió, se conserva el último bueno.

Antes del primer discovery

El paso ping_ssh_check comprueba ICMP y TCP/22 de todo el inventario y deja una tabla CSV. Es la forma rápida de separar «el equipo no responde» de «la credencial está mal». Si un equipo cambió de llave SSH (reemplazo con la misma IP), hay que aceptar la nueva llave desde la UI.

Auditorías

Una auditoría es un job del Engine. La completa (run_all) encadena discovery, respaldo, sincronización del caché, inventario canónico, topología, generación, compliance y vulnerabilidades. Cada paso corre sólo en los equipos cuyas capabilities lo permiten.

Lanzar la primera auditoría

1. Confirma que hay inventario con IP de gestión, credenciales en la bóveda y al menos una regla guardada (para que exista la intención de la organización).
2. En el tablero pulsa Run Audit. La UI pide {"scope":"all","max_workers":6,"output_format":"both"} por omisión. Si la organización tiene Meraki o SD-WAN, parte el alcance por plataforma y lanza los jobs acompañantes.
3. Sigue el job en Operaciones: estado, paso en curso, equipos con error. Por API, con la consulta de detalle del job.
4. Al terminar, el Engine notifica a la UI y ésta ingiere inventario, resultados y topología. Si no, Sincronizar resultados.
5. Lee el tablero: puntaje global, equipos alcanzables, fallas activas y, en Cumplimiento, el detalle por sitio, categoría y equipo.

El mismo lanzamiento por API, desde cualquier cliente autenticado, es una petición de auditoría con este cuerpo:

{"scope": "site", "site": "CDMX-01", "max_workers": 4, "output_format": "both", "organization_slug": "mi-org"}

Variantes

El alcance se acota con scope (all, site, site_type, device, devices) y con los filtros por sitio, rol, plataforma y ciclo de vida. Los campos están en API / Jobs; los criterios para elegir, en Qué auditoría ejecutar.

Artefactos y descarga

Cada job lista sus artefactos con ruta relativa, tamaño y formato, y cada uno se descarga desde el detalle del job en la UI o por API. Job Reports conserva el historial, con las fallas por equipo y los cambios del Gemelo asociados.

Compliance

El cumplimiento compara lo observado con lo declarado. Las reglas viven en intended.json del tenant, que la UI escribe desde su base de datos; no se edita a mano.

Dos familias de reglas

Cada regla lleva identificador, categoría, severidad, puntaje, objetivos (fabricantes, plataformas, roles, tipos de sitio, sitios, equipos), tipo de remediación y ticket. Un targets vacío no significa «todos»: hay que marcar apply_to_all. El detalle de campos está en Compliance / Intended.

Cómo leer un resultado

• Puntaje: score_awarded sobre score_total, por sitio y global, con desglose por categoría (security, lan, wan, hardware, ops, system, software) y por tipo de prueba.
• Tres clases de no cumplimiento: compliance_failure (el equipo no cumple), data_missing (el dato no existe, por ejemplo la interfaz no está) y pipeline_inconsistency (algo falló al recolectar). Sólo la primera es un hallazgo de red.
• Un tipo de check que el Engine no implementa se omite con skip_reason, nunca cuenta como fallo. Para equipos SD-WAN sólo aplica un subconjunto de tipos.
• Cada prueba trae severidad, tipo de remediación, ticket y fecha de ejecución.

Compliance de configuración con diff

En Cumplimiento → Configuración, cada equipo muestra la configuración deseada frente a la observada con el diff resaltado y, si hay un proveedor de IA configurado, el botón «Explicar con IA». La norma de versión de software vive aparte, en Cumplimiento → Software.

Importar y exportar reglas

Las reglas de estado se importan y exportan en CSV (listas separadas por |), con vista previa antes de aplicar y registro de importaciones. Las reglas de configuración no entran a la base de datos: se derivan del Configurador. Columnas en CSV, YAML y JSON soportados.

Para armar la evidencia de una auditoría externa, ver Cómo preparar evidencia para compliance.

Config Generator

El Configurador es donde se declara la intención. Edita service_vars.json por alcances, genera la configuración deseada de cada equipo y activa automáticamente los checks de compliance de cada servicio.

Las piezas

• Catálogo de servicios: 99 servicios en ocho categorías (sistema, enrutamiento, alta disponibilidad, seguridad, ACL, capa 2, servicios L3, inalámbrico). Cada tenant habilita o deshabilita servicios; deshabilitar uno en cascada apaga sus checks.
• Alcances: defaults, by_site, by_site_type, by_role, by_platform, by_model, by_tag, by_filter, by_device. Se fusionan en ese orden y el último gana; las listas se reemplazan completas.
• Plantillas v2 en el Engine: un snippet por servicio y plataforma más un esqueleto por plataforma, compuestos en el orden del manifest. Cisco IOS e IOS-XE tienen 43 servicios con render; FortiGate 16, Junos 16, FortiSwitch 12. Meraki y SD-WAN son de intención solamente.
• Capacidades de plataforma (device_caps) derivadas del modelo y la versión: si el equipo no soporta ntp vrf o storm-control, el snippet lo omite.

Flujo de trabajo

1. En Configurador elige el alcance (empieza por defaults) y el servicio. El formulario viene del catálogo: campos, tipos, ayuda y valor por omisión.
2. Guarda. La UI actualiza service_vars.json del tenant, genera o actualiza los checks del servicio en intended.json y, para los servicios con estado, las reglas canónicas (state_bgp_neighbors, state_vlans_present, state_ospf_neighbors…).
3. Genera la configuración deseada por sitio, equipo, rol, plataforma o tipo de sitio. El resultado se descarga por equipo o por sitio como ZIP.
4. Compara con lo observado en Desired Configs o en Cumplimiento → Configuración. Si hay diferencia, el Gemelo la convierte en un cambio.

Herramientas de apoyo

• Desde el respaldo a la intención: la plataforma propone un bloque services a partir del running. Es una propuesta para revisar, no intención.
• Estandarización: factoriza servicios idénticos de varios equipos al alcance más amplio que los contiene, sólo si todos coinciden. Con proveedor de IA, «optimizar alcances» sugiere la factorización.
• Blindaje por rol (port_hardening) y día 0: se puede registrar un equipo nuevo sin discovery para generar su configuración inicial.
• CSV: la intención se exporta e importa en tres variantes (csv, csv_detailed, csv_review cruzada con inventario).

Cómo decidir en qué alcance va cada variable: Cuándo usar defaults, by_site, by_role, by_platform o by_device. Estructura del archivo: Service Vars.

Digital Twin

El Gemelo Digital es la capa de operación de cambios. No edita la intención (eso es del Configurador): toma la diferencia entre lo deseado y lo observado y la lleva, con control, hasta el equipo.

Snapshots y drift

Un snapshot congela el estado de un job con una nota. El diff de un equipo compara su running actual contra ese snapshot. Cada equipo se marca drift, ok o unknown.

Una solicitud de cambio

1. Crear: destino (equipo o sitio), carril (cli, fortigate, juniper, fortiswitch, meraki, sdwan), diff propuesto, impacto, responsable y comentario. La UI asigna un ticket CHG-0001 y el estado draft.
2. Vista previa (preview, modo live o snapshot): en Cisco calcula la remediación CLI línea a línea; en los carriles de API genera un plan de operaciones determinista (qué objetos se crean o actualizan).
3. Revisar y aprobar (review → approved) con nombre de quien aprueba y ticket. Rechazar deja rejected.
4. Ejecutar (execute) en modo dry_run o apply. Sólo cambios aprobados con alcance de un equipo. El carril debe tener su bandera de remediación encendida.
5. Confirmar o revertir: en Junos el apply es un commit confirmed; el cambio queda en pending_confirm hasta que una persona lo confirma. Si nadie lo hace, el vigilante del scheduler lo revierte y queda expired. rollback está disponible antes del plazo.
6. Verificar: una nueva auditoría o un service_check confirma que el hallazgo cerró.

Guardas por carril

• FortiGate: dry-run obligatorio, respaldo lógico reciente, sólo upserts. Dos servicios (fgt_admins, fgt_security_zones) sólo en dry-run.
• Junos: load merge, commit check, commit confirmed de 10 minutos por omisión; respaldo no mayor a 24 horas.
• Meraki: nunca DELETE; apply sólo con bandera y credencial con escritura.
• SD-WAN: cambios por Config Groups (variables de equipo, segmentos LAN, OSPF LAN, bloqueo de servicios de transporte).
• Cisco CLI: diff mostrado antes de aplicar; aplicación por SSH.

La UI muestra qué carriles tienen el apply habilitado en esa instalación; Job Reports → Cambios del Gemelo es el historial.

Parches de seguridad

Los cambios que corrigen un CVE van en la categoría Parches de seguridad, con su propio tablero: propuesto → aprobado → aplicado → verificado (las líneas del cambio ya aparecen en el respaldo) → corregido (el CVE desaparece del cruce por versión). Se originan de tres formas:

• Cambio urgente desde el CVE, después de «Cómo remediar», que lee el aviso del fabricante con la IA local. Queda como borrador.
• Declarar en el Configurador: si la línea de mitigación es un campo del estándar (servidor HTTP apagado, SSH v2, VTY sólo SSH, vistas SNMP, cifrado de contraseñas, modo de spanning-tree, logging trap), se escribe en la intención del equipo y el cumplimiento la audita como cualquier otra regla. Las líneas con un secreto quedan pendientes para la bóveda.
• Flujo de parches de seguridad (botón, o Argos con «prepara los parches de seguridad»): toma los CVE explotados o críticos cuya función está encendida en la running, prepara los borradores y las propuestas al estándar y notifica. Nunca aplica; la aprobación sigue siendo humana.

Telemetría

Oktavia separa dos planos. El plano de datos (CPU, memoria, almacenamiento, interfaces, temperatura, fuentes, ventiladores) lo recolecta Telegraf por SNMP cada 30 segundos y lo guarda InfluxDB con 7 días de retención. El plano de control (BGP, OSPF, EIGRP, rutas, drift) sale de las auditorías y se deriva como mediciones.

Poner a recolectar un equipo

1. Declara services.snmp en la intención (comunidad, ACL, contacto, ubicación) y aplícalo; o verifica que el equipo ya responda SNMP.
2. Da de alta la credencial snmp en la bóveda.
3. Ejecuta Sincronizar Telegraf en Métricas (o el paso telegraf_sync de una auditoría). Con probe activo, primero valida que cada equipo responda a un get o walk.
4. Revisa el reporte: targets incluidos, skipped con su razón y restart_required. Telegraf recarga sólo el proceso del tenant afectado.

Criterios de inclusión: el equipo existe en el inventario canónico, tiene services.snmp habilitado, su lifecycle es active (o production), su IP resuelve y su fabricante tiene perfil (cisco_ios_router, cisco_ios_switch, fortinet_fortigate, fortinet_fortiswitch, juniper_junos). Meraki y SD-WAN se excluyen: su telemetría llega por API.

Lo que se ve en la UI

• Métricas: CPU, memoria, interfaces, enlaces, BGP, OSPF, EIGRP, rutas, latencia, túneles y eventos SD-WAN, salud. Gráficas de tendencia con umbrales.
• Syslog: Telegraf recibe syslog y guarda la medición syslog con origen, severidad, facility y aplicación.
• Anomalías: cambios de estado en BGP y OSPF, y desviaciones (z-score) en CPU y conteo de rutas, consultables desde Métricas.
• Latencia: latency_collect mide ICMP hacia los destinos declarados en la intención y escribe en InfluxDB.
• Reportes: Telemetry Health (anomalías de CPU, memoria, interfaces y latencia), Config Risk, Config Drift y Topology Health, con exportación JSON y CSV.

Automatización de eventos

En Automatización se definen reglas métrica → acción: vecino BGP caído, vecino OSPF caído, interfaz caída, CPU alta (80 %), memoria alta (85 %), temperatura alta (75 °C), errores de interfaz. Acciones: correr compliance, recolectar diagnóstico, notificar por webhook, correo o dentro de la UI. Un evaluador independiente las revisa periódicamente.

Detalle de InfluxDB, Telegraf y perfiles SNMP en InfluxDB / Telegraf.

Scheduler

El programador del Engine ejecuta trabajos a horas fijas, espera a que terminen y, si se le indica, entrega el resultado a la UI para que lo ingiera. Se configura desde Operaciones → Programación en la UI o editando su archivo de configuración YAML a través de la API.

Estructura de un job programado

version: 2
poll_interval: 5
jobs:
  - name: auditoria-diaria
    enabled: true
    organization_slug: mi-org
    schedule:
      type: frequency
      frequency: daily
      time: "02:00"
    steps:
      - label: Auditoría completa
        operation: auditoria_completa
        payload: {"scope": "all", "max_workers": 4, "output_format": "both"}
        wait: true
        ingest: true
      - label: Alcance
        operation: ping_ssh_check
        payload: {"scope": "all"}
        wait: true

Cada paso indica la operación del Engine, su cuerpo, si se espera a que termine y si el resultado se entrega a la UI. La guía entregada con el software documenta la sintaxis exacta de la operación.

Tipos de programación

Un job puede ejecutarse al arrancar el programador o recuperarse si el programador arrancó poco después de su hora. El programador mantiene además tareas internas propias: el vigilante del commit confirmed de Junos y el sondeo de telemetría SD-WAN.

La UI muestra el estado del programador junto con el del Engine. Aparte, la UI tiene dos tareas de mantenimiento de eventos Meraki que conviene programar con el planificador del sistema.

Argos y MCP

Argos es el asistente de operación de la UI. Recibe una petición en lenguaje natural, la enruta a un flujo y devuelve una respuesta con intención detectada, razón, confianza, si usó un modelo de IA, el resultado de la acción y sugerencias.

Tres marcas, tres modos

• IAOps: flujos deterministas que no consumen modelo. Diagnóstico de un equipo, reemplazo o baja, onboarding, túnel GRE, publicar una red, DHCP por VLAN, segmento SD-WAN, switch de sucursal, pegado de CLI, triage de ticket, telemetría. Son los que lanzan operaciones en vivo del Engine: limpiar contadores, verificar un servicio, comprobar acceso.
• IA: lo que sí usa un modelo de lenguaje. Explicar un diff, revisar un cambio, resumir cumplimiento, redactar una remediación, analizar enrutamiento o un camino, proponer variables de servicio desde un respaldo, correlacionar eventos. Proveedor configurable por organización: API de Anthropic o un modelo local con Ollama. El uso de tokens se mide por organización. En la UI se marca ✦ IA.
• IA local (◆ IA local): respuestas desde la documentación indexada en el servidor de Oktavia, sin tokens ni salida de datos: preguntas «según la documentación…», «Qué dice la documentación» por incidente en el diagnóstico y «Cómo remediar · IA local» en cada CVE. Detalle en IA local (RAG).

Ciclos

Un flujo largo se convierte en un ciclo persistente que avanza el worker de Argos: pending → running → waiting_apply (espera la aprobación humana) → verifying → closed, con los estados attention, failed y canceled. Se consultan y reanudan desde la UI.

«Cerrar el ciclo» acepta también un cambio que ya existe en el Gemelo, por ejemplo un parche de seguridad preparado por el flujo. El veredicto compara las pruebas de cada equipo antes y después del cambio y las separa en corregidas, regresiones, fallas nuevas y siguen fallando. Una regresión impide pasar a closed; las fallas de estado que ya existían antes del cambio se listan aparte y no bloquean. Un parche verificado se marca «verificado» en su tablero, y cada veredicto se indexa en la IA local como reporte de cambio.

El servidor MCP

El Engine expone un servidor Model Context Protocol de solo lectura sobre los artefactos de la organización, pensado para Argos y para asistentes de escritorio como Claude Desktop. Herramientas: query_inventory, get_device_state, diff_snapshots, get_compliance_results, get_routing_table, list_snapshots, get_topology_neighbors, get_topology_impact, get_recent_jobs, triage_device. Recursos por organización y tres prompts: drift-triage, audit-narrative, pre-change-check.

• Toda llamada exige una organización permitida; no hay herramientas de escritura, acceso a equipos ni a la bóveda; se redactan secretos por clave y por línea; cada llamada queda en un registro de evidencia por organización.
• Argos, del lado de la UI, también puede actuar como cliente MCP de otros servidores, con una lista de herramientas permitidas.

Cómo conectarlo, en MCP / Argos.