Documentación de Oktavia · Referencia
Referencia técnica
APIs del Engine y de la UI, capas del inventario, variables de entorno, artefactos que deja cada job y todos los formatos CSV, YAML y JSON que la plataforma importa o exporta.
API del Engine
El motor expone una API REST autenticada con credenciales de integración: la credencial maestra de la instalación o claves por organización con acceso de lectura o escritura y un conjunto acotado de operaciones. La especificación OpenAPI completa, con interfaz interactiva, se consulta dentro de la instalación y es la referencia exacta de la versión instalada. Las operaciones de auditoría son asíncronas: devuelven el identificador y el estado de un job, y el resultado se consulta después.
Errores comunes
- No autorizado: credencial ausente o inválida.
- Petición inválida: cuerpo incompleto, por ejemplo
scope=sitesinsite. - Servicio no disponible: la organización no tiene reglas de intención sincronizadas.
Áreas de la API
| Área | Qué permite | Notas |
|---|---|---|
| Salud y metadatos | Verificación de salud; catálogo de tipos de check con el esquema de su expected; carriles de remediación y si el apply está habilitado; estado del programador | — |
| Auditorías | Auditoría completa; compliance en seco; cada paso por separado; verificación de acceso; sincronización de Telegraf; medición de latencia; exportables CSV; discovery y compliance de Meraki y SD-WAN | Todas reciben la petición de auditoría y devuelven un job |
| Jobs | Listar jobs por estado y organización; detalle de un job con pasos, tiempos y errores; estado por equipo; lista y descarga de artefactos | Estados: queued, running, completed, completed_with_errors, failed, timeout |
| Inventario y discovery | Inventario canónico vigente; reconstruirlo desde el caché; alta y baja de un equipo; importar y exportar CSV; resolver nombres; snapshot vigente de un equipo; resumen de incorporación | El alta acepta los campos de Inventario base |
| Operaciones en vivo | Limpiar contadores, verificar un servicio y comprobar acceso (las usa Argos); gestión de llaves SSH conocidas por organización | Devuelven un job consultable |
| Compliance e intención | Resultados y resumen por sitio; leer y escribir el archivo de reglas completo, con validación; reglas en CSV; mapa servicio → plantilla y checks; análisis de vulnerabilidades | El archivo de reglas se describe en Compliance / Intended |
| Config Generator | Leer y escribir los archivos de variables (service_vars.json, device_inventory.json, etiquetas); CSV del generador; generar configuración por sitio, equipo, rol, plataforma o tipo de sitio; registrar un equipo de día 0; descargar la configuración deseada por equipo o por sitio en ZIP | — |
| Respaldos | Running config por equipo o por sitio en ZIP; respaldo estructurado; respaldo lógico de FortiGate; propuesta de variables de servicio a partir del respaldo | La propuesta no aplica a SD-WAN |
| Topología | Snapshot de topología y reconstrucción; vecinos e impacto de un equipo; puntos únicos de falla; inconsistencias (por ejemplo áreas OSPF) | — |
| Métricas y telemetría | CPU, memoria, interfaces, salud, latencia y ambiente del plano de datos; vecinos BGP, OSPF y EIGRP y tabla de rutas del plano de control; anomalías y consulta genérica; túneles y eventos SD-WAN; vista previa y sincronización de Telegraf | Aceptan equipo, sitio, ventana de tiempo, agregación y organización |
| Digital Twin | Crear y listar snapshots; diff de un equipo contra un snapshot; crear, consultar y actualizar cambios; vista previa, aprobación, ejecución, confirmación y reversión; vigilante de cambios sin confirmar | Flujo en Digital Twin |
| Programador | Leer y escribir la configuración de tareas programadas | Formato en Scheduler |
| Integraciones | FortiGate (snapshot, prueba de conexión, rotación de token); Meraki (estado, validación, sincronización, sondeo de cámaras, registro y bitácora de webhooks); SD-WAN (validación, sincronización, aprovisionamiento, telemetría); red de pruebas en CML (estado, laboratorio, operaciones, sincronización, respaldos) | — |
| Insights | Resumen compacto por categoría para asistentes | Prueba de concepto |
API de la UI
La UI expone sus propias rutas, con sesión de usuario, para todo lo que sus vistas hacen, y un conjunto aparte para el motor, autenticado con la credencial de integración compartida. Su especificación OpenAPI se genera de las rutas y se consulta dentro de la instalación, junto con la del motor.
Lo que consume el motor
- La fuente de verdad de cada organización: inventario, topología, IPAM, resultados de compliance, variables de servicio y estado de los servicios del catálogo.
- La ingesta: el motor o el programador entregan el identificador de un job terminado y la UI lo importa.
- La verificación de salud, que resume el estado de la UI, del motor y del programador.
Lo que usan las vistas (con sesión)
| Área | Operaciones |
|---|---|
| Jobs | Lanzar, consultar estado, listar y descargar artefactos; verificación de acceso; limpiar contadores; configuración del programador |
| Inventario | Exportar e importar CSV (con opción de reemplazo), alta manual, sincronización con el motor, datos y autocompletado para las vistas, vista previa de equipos |
| Intención | Leer, exportar (JSON y tres variantes CSV) e importar variables de servicio; registro de alcances; catálogo del Configurador; estado de los servicios; generar configuración |
| Reglas | Reglas de cumplimiento con exportación e importación CSV (vista previa y aplicación), derivación desde el Configurador, catálogo de reglas de estado y plantillas |
| Gemelo | Cambios con aprobación, ejecución, reintento, confirmación, reversión y vista previa por equipo |
| Reportes | Puertos, capacidad, topología, riesgo, salud y drift en JSON y CSV; recolección bajo demanda; sincronización de la línea base |
| Automatización | Reglas, eventos, notificaciones y carga de reglas por omisión |
| Argos e IA | Chat del asistente, conversaciones, ciclos y las operaciones de análisis asistido (explicar diff, revisar cambio, resumir cumplimiento, redactar remediación, analizar enrutamiento o camino, proponer variables, correlacionar eventos) |
| Integraciones | Configuración y pruebas de SMTP, proveedor de IA y SSO; credenciales; Meraki; SD-WAN; CML |
| Provisioning y organización | Organizaciones, tipos de sitio, roles, sitios y equipos; paquetes y versiones de organización |
| Red de pruebas | Estado, laboratorio, agregar, reemplazar y quitar equipos, auditoría, sincronización, configuración de nodos y respaldos |
| Eventos push de Meraki | Rutas de ingreso para webhooks, ubicación y MV Sense, con token propio por organización y límites de tamaño y tasa; se obtienen al registrar la integración |
Campos de inventario
El inventario tiene tres capas y cada una tiene su tabla de campos en la Referencia de datos.
| Capa | Dónde vive | Quién la escribe | Tabla |
|---|---|---|---|
| Base (declarada) | CSV de equipos e inventario interno del Engine; inventario de la organización en la UI | Una persona, por CSV o en la UI | Inventario base |
| Canónica (construida) | device_inventory.json más device_tags.json e interface_tags.json | El Engine, tras el discovery; editable por API | Device Inventory |
| Observada (espejo) | Modelo, serie, versión, interfaces, vecinos LLDP y telemetría por interfaz en la UI | La ingesta de cada job | Resumen en Device Inventory |
Los catálogos globales que validan esos campos: tipos de sitio (slug, label, default_services), roles (slug, category en router, switch, firewall u otro, compliance_groups) y plataformas con su fabricante y método de acceso (ios, iosxe, nxos, meraki, sdwan, fortigate, fortiswitch, junos).
Variables de entorno
La referencia completa de variables, con nombres y valores por omisión, está en la configuración de ejemplo de cada componente y se entrega con el software. Por política de publicación, este sitio no documenta los nombres de las variables que contienen secretos ni los valores por omisión relacionados con autenticación. Lo que sigue es el mapa de qué se configura dónde.
Motor (Engine)
| Grupo | Qué configura | Notas |
|---|---|---|
| Autenticación | Clave de API maestra; archivo de claves con alcance; token hacia la fuente de verdad | Secretos. Sin la clave maestra el Engine no arranca fuera de un entorno de desarrollo |
| Fuente de verdad | URL de la UI; tenant por omisión | — |
| Bóveda | Clave de cifrado; ubicación de la bóveda; modo «sólo bóveda» | La clave es secreta e idéntica a la de la UI |
| Intención y artefactos | Ubicación del archivo de reglas compartido; directorio de exportación; temporales | En el almacenamiento compartido |
| Render | Activación de las plantillas por servicio (v2) | Apagada por omisión |
| Discovery y jobs | Timeout por equipo; paralelismo de la API y del ejecutor de jobs; umbral de job estancado | — |
| Programador | URL del motor; URL de ingesta de la UI | — |
| Inventario legado | Ubicación del inventario interno; credenciales legadas | Las credenciales legadas son secretos y sólo existen como ruta de migración |
| Telemetría | Credencial SNMP (v2c o v3); conexión, retención y token de InfluxDB; recarga de Telegraf | El token de InfluxDB se fija antes del primer arranque; retención configurable |
| Carriles por fabricante | Bandera de remediación de FortiGate, FortiSwitch, Junos, Meraki y SD-WAN; verificación TLS y timeouts de FortiGate; minutos del commit confirmed, antigüedad máxima del respaldo e intervalo del vigilante en Junos; registro de webhooks en Meraki; intervalo de telemetría en SD-WAN | Todas las remediaciones apagadas por omisión |
| Vulnerabilidades | Clave de la API de NVD (opcional); directorio de caché de catálogos | Con clave, NVD admite más consultas por minuto |
| Servidor MCP | Organizaciones permitidas; transporte; registro de evidencia; etiqueta del cliente | — |
| Varios | Lista blanca de acceso; zona horaria | — |
Interfaz (UI)
| Grupo | Qué configura | Notas |
|---|---|---|
| Motor | URL del motor; credenciales de integración en ambos sentidos; timeouts de salud, lectura, job, artefacto y operación larga | Las credenciales son secretas |
| Bóveda | Clave de cifrado | Secreta; obligatoria en producción |
| Aplicación web | Secreto de la aplicación; modo de depuración; hosts permitidos; orígenes CSRF; política de sesión y cabeceras de seguridad | El secreto no se versiona; en producción los hosts se declaran explícitamente |
| Base de datos y caché | Conexión a PostgreSQL (modo TLS, pooling); conexión, prefijo y tiempo de la caché | Sin caché externa, se usa memoria local |
| Arranque | Tenant por omisión; importaciones automáticas de inventario y compliance; siembra del laboratorio de demostración | Siembra apagada en producción |
| Artefactos | Ubicación de inventario, resultados y resumen; línea base de reportes; archivo de reglas | En el almacenamiento compartido |
| Auditoría por omisión | Cuerpo del botón «Run Audit» | {"scope":"all","max_workers":6,"output_format":"both"} |
| Identidad | Emisor, cliente, secreto, redirección, scopes y claims de OIDC; exigencias de MFA; login local de emergencia | El secreto del cliente no se documenta |
| Acceso | Redes siempre permitidas; desactivación de la lista blanca; proxies de confianza | — |
| Servidor | Workers, hilos y timeout del servidor de aplicación | — |
| Workers | Intervalo del evaluador de reglas; intervalo del worker de Argos; límite de tokens del modelo; frescura de la ingesta | — |
| IA | Proveedor (Anthropic u Ollama); clave de API; modelo; conexión y timeout de Ollama; servidor, herramientas permitidas y timeout del cliente MCP | La configuración por organización en la UI gana sobre el entorno; la clave es secreta |
| Correo | Backend, host, puerto, TLS, usuario, contraseña y remitente SMTP | Respaldo; lo normal es configurar SMTP por organización en la UI |
| Eventos push de Meraki | URL pública; tasa de ingreso; retención de eventos, ubicación y cámaras; reintentos de recolección; clave de hash de clientes | Retención configurable |
| Varios | Passphrase de paquetes de organización; clave de administración de tokens; URL pública; laboratorio CML; zona horaria | Las dos primeras son secretas |
Artefactos generados
Todo job deja archivos en su propio espacio de trabajo, listados en su detalle con ruta relativa, tamaño, fecha y formato (json, csv, cfg). Al terminar, se fusionan con la copia vigente de la organización, por equipo y por sitio. El motor no genera XLSX, HTML ni Markdown.
| Paso | Artefacto | Formato | Contenido |
|---|---|---|---|
| discovery | Salida cruda y snapshot normalizado por equipo | JSON | Lo recolectado, en bruto y con forma común |
| backup_config | Respaldo por equipo | CFG, JSON | Running config; respaldo estructurado; respaldo lógico de FortiGate |
| build_inventory | device_inventory.json | JSON | Inventario canónico |
| build_topology | Snapshot de topología | JSON | Nodos, enlaces CDP y LLDP, vecinos BGP, OSPF y EIGRP, HSRP y VRRP, rutas, túneles, circuitos WAN, BFD de SD-WAN |
| render_configs | Configuración deseada por equipo | CFG | El resultado de aplicar las plantillas a la intención |
| compliance | compliance_results.json, summary_by_site.json, resultado por equipo | JSON | Resultados por sitio y equipo, resúmenes por categoría y tipo de prueba, puntajes |
| vulnerabilities | Reporte de vulnerabilidades | JSON | Cruce de versiones con NVD, KEV y EPSS |
| export_*_csv | device_inventory.csv, compliance_tests.csv, device_summary.csv, site_summary.csv | CSV | Exportables para evidencia |
| ping_ssh_check | Tabla de alcance | CSV | ICMP y TCP/22 por equipo |
| intended_from_csv · csv_to_vars | Reglas y variables convertidas | JSON, CSV | — |
| meraki_* · sdwan_* | Snapshots normalizados y resumen de discovery | JSON | Discovery por API |
| telegraf_sync | Configuración SNMP por organización | TOML | Entradas SNMP más un reporte de objetivos incluidos y omitidos |
| Gemelo | Snapshots congelados y solicitudes de cambio | JSON | — |
| MCP · red de pruebas | Registro de evidencia; bitácora y respaldos del laboratorio | JSONL, YAML | Cada llamada MCP; actividad del laboratorio y sus respaldos con historial |
| Exportación | Copia por job | JSON, CFG | Inventario, resumen, resultados y configuraciones cuando se pide output_path o existe un directorio de exportación configurado |
Los respaldos y las configuraciones deseadas se descargan también por sitio, en ZIP. Cada job conserva además su registro de ejecución.
CSV, YAML y JSON soportados
Todo lo que la plataforma importa o exporta, con sus columnas o claves. Las listas dentro de un CSV se separan con |; los booleanos aceptan true, 1, yes, y.
| Archivo | Formato | Columnas o claves | Dónde |
|---|---|---|---|
| Inventario base | CSV | name, hostname, platform, group, os, type, site, site_type, role, vendor y opcionales ssh_options, ping_source; el motor lo convierte en su inventario interno | Motor (herramienta de línea de comandos); UI: Inventario → Importar (acepta además model, serial_number, os_version) |
| Inventario exportado | CSV | device, role, location, site_type, platform, vendor, ip_address, model, serial_number, os_version, bgp_asn, tags | UI: Inventario → Exportar; API del motor |
| Inventario canónico | JSON | {devices: {nombre: {...}}}, ver Device Inventory | device_inventory.json |
| Etiquetas | JSON | {device_tags: {equipo: [tag]}}; {rules: [{tag, match, mode, interfaces}]} con mode en prefix, contains o custom | device_tags.json, interface_tags.json |
| Intención | JSON, CSV | JSON por alcances (Service Vars); CSV scope, key, payload_json en tres variantes: csv, csv_detailed, csv_review | service_vars.json; UI: Configurador → exportar e importar |
| Reglas (archivo) | JSON, YAML | version, metadata, checks[], ver Compliance / Intended | intended.json, intended.yaml |
| Reglas (motor) | CSV | config_checks.csv: id, service_id, category, vendors, platforms, roles, devices, score, remediation_type, remediation_ticket, severity; network_checks.csv sin service_id; hardware_checks.csv añade max_percent, max_errors, include_discards | API del motor (reglas en CSV) |
| Reglas de estado (UI) | CSV | rule_id, test_type, check_type, category, service_id, label, severity, enabled, score, apply_to_all, description, remediation_type, roles, target_devices, target_site_types, target_vendors, target_platforms, required_lines, forbidden_lines, thresholds | Cumplimiento → Reglas → importar y exportar |
| Catálogo de servicios | CSV, JSON | CSV: service_id, label, category, severity, platforms, device_models, roles, apply_to_all, required_lines, forbidden_lines, description, enabled; JSON del catálogo con categories[] y services{} | Configurador → Catálogo |
| Programador | YAML | version, poll_interval, jobs[] {name, enabled, organization_slug, schedule{}, steps[]}, más la conexión al motor y a la ingesta de la UI | Operaciones → Programación; API del motor |
| Resultados | JSON | compliance_results.json: sites[] {site, site_type, summary, summary_by_category, summary_by_test_type, devices[]}; summary_by_site.json: checks_total, checks_passed, checks_failed, score_awarded, score_total, status, severity | Artefactos de compliance |
| Reportes de la UI | CSV, JSON | ports.csv (equipo, sitio, interfaz, estados, VLAN, modo, descripción, vecino LLDP, utilización, PoE, severidad, recomendación), health_findings.csv, risk_findings.csv, drift.csv, capacity_hotspots.csv, capacity_forecast.csv, topology.csv | Reportes |
| FinOps | CSV | Por equipo: device, site, role, model, vendor, capex_mxn, license_mxn_year, support_mxn_year, lifecycle_years, avg_power_watts; por sitio: site, internet_mxn_month, noc_mxn_month, provider_support_mxn_month, notes | FinOps → importar (descarga una plantilla) |
| Paquete de organización | ZIP | Manifiesto con counts, secrets, state; passphrase opcional; con límite de tamaño | Exportar e importar organización |
| Bóveda | JSON cifrado | Por organización y tipo: alcance, valor de alcance, usuario, secreto cifrado y metadatos | Entrega UI → motor |
| Laboratorio CML | YAML | Topología del laboratorio; respaldos con fecha e historial | Red de pruebas |