Skip to content

Catálogo de Funcionalidades de API — qué desbloquea TLSStress.Art vía APIs REST

Estado del alcance (post-congelación de alcance 2026-05-10) — Ver ARCHITECTURE.md para los 37 MÓDULOs canónicos + 7 Test Kinds + arquitectura de safety DOM/CPOS/PIE-PA. ADRs 0014, 0019-0025 cubren adiciones post-Freeze.

Lea en su idioma: English · Português · Español

Este documento cataloga toda funcionalidad concreta desbloqueada al hablar con las APIs REST de los elementos del laboratorio (Cisco FTD, Cisco Nexus 9000 NX-API DME, Cisco UCS CIMC Redfish, futuros Palo Alto + Fortinet). Es la hoja de ruta para la integración de API: lo que está entregado, lo que está conectado, lo que está planificado.

Para detalles de implementación véase DUT_API_INTEGRATION.es.md.

Leyenda de estado

Símbolo Significado
✅ Entregado — el método del adapter existe y el dashboard / informe lo consume
🟡 Método del adapter existe, pero la conexión con UI / dashboard está pendiente
🔵 Diseñado — método del adapter agendado
⚪ Idea capturada, aún no planificada

Tres pilares de telemetría

Pilar Origen Lo que entrega
Métricas SNMP, node-exporter, kubelet Estado numérico en series temporales
Eventos Syslog, eventos de K8s Flujo reactivo de eventos
API (este catálogo) APIs REST de los proveedores Configuración viva, políticas aplicadas, salud de hardware, topología, acciones de escritura

Los tres combinados producen el nivel de completitud forense que el Test Run Report exige.

A. Verificaciones de pre-vuelo (rechazar ejecución si el estado es incorrecto)

Antes de permitir que un Test Plan inicie, el motor consulta los endpoints de API relevantes para confirmar que el laboratorio está en estado ejecutable. Si cualquier verificación falla, la ejecución se rechaza con un error específico y accionable.

# Funcionalidad Origen Estado
A-1 Confirmar que el estado de deploy del NGFW es DEPLOYED (no pendiente) FTD /operational/deploy 🟡
A-2 Confirmar que la política de decrypt está habilitada y se aplica a las interfaces de prueba FTD /policy/sslpolicies 🟡
A-3 Confirmar que la fuente NTP del NGFW corresponde a la expectativa del laboratorio FTD /devicesettings/default/ntp 🟡
A-4 Confirmar que el Nexus tiene LLDP y CDP habilitados Nexus sys/lldp/inst + sys/cdp/inst 🟡
A-5 Confirmar que el UCS CIMC no reporta fallas críticas de hardware UCS LogServices/Faults/Entries 🟡
A-6 Confirmar que sensores térmicos del UCS están bajo el umbral UCS Chassis/<id>/Thermal 🟡
A-7 Confirmar que los roles active+standby del par HA son correctos en FTD FTD /devices/default/ha 🟡
A-8 Confirmar que la smart license del FTD tiene capacidad suficiente FTD /license (planeado v6.x) 🔵
A-9 Confirmar que el perfil de QoS del Nexus corresponde al baseline esperado Nexus sys/qos 🔵
A-10 Confirmar la revisión de firmware del UCS contra la lista aprobada UCS Systems/<id> Bios + Firmware 🔵

El pre-vuelo se ejecuta en paralelo contra cada dispositivo registrado. Presupuesto total de tiempo: ≤30 s. El resumen de fallas se muestra al operador con un solo botón "Sobrescribir y ejecutar de todas formas (registra como no-forense)" — opt-in explícito del operador para casos inusuales.

B. Métricas en tiempo real durante ejecuciones

Una vez que una ejecución está activa, el worker de polling aumenta su cadencia en los dispositivos activos y transmite snapshots de métricas a Prometheus vía un exporter personalizado — exhibido como paneles Grafana junto a las métricas del agente ya recolectadas.

# Funcionalidad Origen Estado
B-1 Utilización de CPU del NGFW durante la prueba FTD /operational/systemmonitoring/cpu 🔵
B-2 Utilización de memoria del NGFW FTD /operational/systemmonitoring/memory 🔵
B-3 Conexiones activas del NGFW + nuevas conexiones/s FTD /operational/systemmonitoring/connections 🔵
B-4 Conteos actuales de hits de la regla de decrypt del NGFW FTD /operational/policy/sslpolicy/<id>/hitcount 🔵
B-5 Contadores de interfaz del Nexus (bytes, errores, drops) a 1 Hz Nexus sys/intf/<id>/counters 🔵
B-6 RPM de los fans del UCS durante la ejecución UCS Chassis/<id>/Thermal 🔵
B-7 Temperatura de CPU del UCS durante la ejecución UCS Chassis/<id>/Thermal 🔵
B-8 Consumo de energía del UCS (watts) UCS Chassis/<id>/Power 🔵
B-9 Conteos de hits del IPS del NGFW FTD /operational/policy/intrusionpolicy/<id>/hitcount 🔵
B-10 Profundidad de cola + drops de QoS del Nexus Nexus sys/qos/<class>/queue ⚪

Estas métricas dan al operador una visión en tiempo real de "lo que el dispositivo ve" — sin nunca necesitar iniciar sesión en la consola de gestión del NGFW o en el CLI del Nexus.

C. Topología e inventario

# Funcionalidad Origen Estado
C-1 Construcción automática de diagrama de topología del laboratorio a partir de LLDP/CDP Nexus sys/lldp/inst + sys/cdp/inst ✅ adapter / 🟡 dashboard
C-2 Anexo de inventario de hardware (S/N + firmware + PSU + DIMM) Nexus sys/ch?rsp-subtree=full + UCS Systems/<id> ✅ adapter / 🟡 dashboard / 🔵 informe
C-3 Verificación de vínculo de service profile (solo UCS gestionado por UCSM) UCSM serviceProfile/<id> ⚪
C-4 Estado de interfaz del NGFW + estado del cable FTD /operational/interfaces ✅ adapter / 🟡 dashboard
C-5 Estado de link de NIC del UCS + negociación de velocidad UCS Systems/<id>/EthernetInterfaces ✅ adapter / 🟡 dashboard

El Anexo A del Test Run Report — topología auto-generada — se produce a partir de C-1.

D. Forense y conformidad

# Funcionalidad Origen Estado
D-1 Snapshot de configuración pre-ejecución de cada dispositivo + SHA-256 Todos los adapters ✅ adapter / 🔵 conectado al motor de Test Plan
D-2 Diff de config post-ejecución contra snapshot pre-ejecución Query interna dut_api_snapshots 🔵
D-3 Atestación de conformidad contra baseline de política FTD /policy/* + Nexus running-config 🔵
D-4 SHA-256 por snapshot citado en los Anexos B + C + D del Informe Interno ✅ campo existe / 🔵 conexión al informe
D-5 Cadena tamper-evident — SHA-256 del Snapshot anclado en PDF Firma Cosign futura 🔵

E. Correlación entre orígenes

El valor único: combinar los tres pilares para detectar cosas que ningún pilar aislado puede.

# Funcionalidad Combinación de orígenes Estado
E-1 Syslog del NGFW "decrypt error" + verificación simultánea vía API del estado de la política de decrypt. Diff = drift de config a mitad de ejecución Syslog (decrypt error) + API (estado de política de decrypt) 🔵
E-2 Falla del CIMC del UCS + fallas de agente correlacionadas. Misma ventana de tiempo = atribución de causa raíz API (fallas del UCS) + Postgres (fallas de tabla runs) 🔵
E-3 Pico de contador de errores de interfaz del Nexus + pico de latencia p99 correlacionado API (contadores Nexus) + Prometheus (p99 del agente) 🔵
E-4 TLS Decrypt Probe dice "off" + API confirma política de decrypt habilitada. Discrepancia → NGFW roto Métrica del probe + API (política de decrypt) 🔵
E-5 Estado de deploy del NGFW cambia a mitad de ejecución = ejecución invalidada Delta de polling de API 🔵

F. Operaciones de escritura (confirmadas por el operador)

Solo lectura está entregado; las escrituras requieren confirmación del operador, traza de auditoría y rollback automático en caso de falla.

# Funcionalidad Origen Estado
F-1 Establecer servidor NTP del NGFW vía API FTD PUT /devicesettings/default/ntp/<id> + POST /operational/deploy 🔵
F-2 Alternar estado de la política de decrypt para prueba A/B FTD PUT /policy/sslpolicies/<id> 🔵
F-3 Aplicar política de QoS específica del test-bed en Nexus pre-ejecución, revertir post-ejecución Nexus DME PUT 🔵
F-4 Resetear contadores de interfaz antes de la ejecución Acción Nexus DME ⚪
F-5 Preparar configuración de rollback antes de cualquier escritura Interno: snapshot antes, restore después 🔵
F-6 Cambio de perfil de energía BIOS del UCS para ejecuciones "max-perf" UCS Redfish Systems/<id>/Bios PATCH ⚪

Cada escritura requiere: 1. Re-autenticación de admin en el momento del request 2. Confirmación explícita del operador en la UI ("a punto de cambiar la fuente NTP del NGFW — ¿proceder?") 3. Entrada de audit log con snapshots before/after 4. Rollback automático si la lectura post-escritura confirma divergencia de la intención

G. Energía, sostenibilidad, performance-per-watt

# Funcionalidad Origen Estado
G-1 Serie temporal de consumo de energía del UCS durante ejecuciones UCS Chassis/<id>/Power 🔵
G-2 Métrica "throughput-per-watt" por ejecución de plan UCS Power + throughput de Prometheus ⚪
G-3 Detección de throttle térmico (advertir si temp de CPU excede umbral) UCS Thermal + alerting 🔵
G-4 Estimación de equivalente de carbono por ejecución (factor de grid suministrado por el operador) Computado a partir de G-1 ⚪

H. Salud de hardware para ejecuciones SOAK

Planes de 24 horas o más demandan vigilancia a nivel de hardware. La integración de API provee lo que el node-exporter no puede.

# Funcionalidad Origen Estado
H-1 Conteos de errores de DIMM del UCS (correctable + uncorrectable) UCS Memory?$expand=. ✅ adapter / 🔵 alerting
H-2 Estado de redundancia de PSU durante ejecuciones 24 h+ UCS Chassis/<id>/Power ✅ adapter / 🔵 alerting
H-3 Baseline de tasa de error de NIC + comparación durante ejecución Contadores de interfaz UCS + Nexus 🔵
H-4 Datos SMART de disco en almacenamiento local UCS UCS SimpleStorage/<id> ⚪
H-5 Informe de fin de SOAK: pico de RPM de fan, pico de temp, energía total, pico de watts Agregación sobre snapshots recolectados 🔵

I. Auto-rollback

# Funcionalidad Origen Estado
I-1 Captura pre-ejecución de la configuración completa de los 3 tipos de dispositivo Adapters + nueva tabla pre_run_config 🔵
I-2 Restore automático post-ejecución (operador opt-in vía parámetro del plan) Métodos de escritura de los adapters 🔵 (depende de F-*)
I-3 Detección de drift a mitad de ejecución → auto-pause + alerta Diff de polling contra pre-ejecución 🔵
I-4 Verificación de rollback: snapshot post-restore corresponde al pre-ejecución Comparación de SHA-256 🔵

J. Integración con test plan

El YAML del Test Plan puede expresar "el laboratorio DEBE estar en este estado para que este plan sea válido":

# Funcionalidad Campo YAML Estado
J-1 El plan declara ngfw_state_required: decrypt-on y el adapter verifica ya existe ✅
J-2 El plan declara ntp_source_must_match: lab-relay nuevo campo 🔵
J-3 El plan declara expected_ngfw_models: [FPR1010, FPR1140] y rechaza en mismatch nuevo campo 🔵
J-4 El plan declara pre_run_capture_config: true para ejecuciones de conformidad nuevo campo 🔵
J-5 La conclusión del plan dispara snapshot final de config automáticamente hook del motor 🔵
J-6 La falla del plan dispara snapshot post-mortem automático hook del motor 🔵

K. Abstracción multi-vendor

Las mismas queries de endpoint_label retornan datos independientemente del proveedor — el código de Dashboard y Report queda vendor-agnostic.

# Funcionalidad Origen Estado
K-1 La misma query "show NGFW NTP config" funciona en FTD / Palo Alto / Fortinet Abstracción de adapter ✅ FTD / 🔵 Palo Alto / 🔵 Fortinet
K-2 El dashboard del operador muestra "todos los NGFWs" de forma agnóstica Vista Postgres + Grafana 🟡
K-3 Futuros adapters Palo Alto + Fortinet encajan transparentemente La arquitectura soporta ✅
K-4 Matriz de funcionalidades del adapter expuesta en la UI admin ("FTD tiene decrypt_policy, Palo Alto también, Fortinet no") Introspección de adapter 🔵

L. Informe

El Test Run Report (Fase 3 → 5) consume snapshots de API intensamente.

# Funcionalidad Origen Estado
L-1 Anexo A — topología auto-generada a partir de LLDP/CDP Adapter Nexus ✅ adapter / 🔵 render SVG
L-2 Anexo B — inventario Nexus + running-config sanitizada Adapter Nexus ✅ adapter / 🔵 conexión al informe
L-3 Anexo C — inventario NGFW + política de decrypt + estado IPS Adapter FTD ✅ adapter / 🔵 conexión al informe
L-4 Anexo D — inventario de hardware UCS + lecturas de sensor Adapter UCS ✅ adapter / 🔵 conexión al informe
L-5 Cadena de custodia SHA-256 por anexo (ya en formato) Todos los adapters ✅
L-6 Apéndice "qué cambió durante la ejecución" — diff pre vs post Computación interna 🔵

M. Exposición en la UI — el operador nunca abre la consola del NGFW

La meta "single pane of glass" del operador — todo visible en Grafana / Dashboard / Report.

# Funcionalidad Superficie Estado
M-1 Grafana — dashboard DUT API Status dashboards/dut-api-status-cm.yaml ✅
M-2 Grafana — dashboard DUT Live State (NGFW + Switch + UCS) dashboards/dut-live-state-cm.yaml ✅
M-3 Dashboard — página admin para registrar / probar dispositivos Nueva /admin/dut-api/ 🔵
M-4 Dashboard — navegador de snapshots por dispositivo ("muéstrame lo que FTD-1 dijo sobre su config NTP hace 30 min") Nueva página 🔵
M-5 Dashboard — botón de disparo manual de snapshot por dispositivo Nuevo endpoint de API 🔵
M-6 Dashboard — modal de confirmación de operación de escritura Nuevo componente 🔵 (depende de F-*)
M-7 Test Run Report — contexto DUT completo auto-incrustado Builder de informe de la Fase 3 🔵

N. Long-tail e ideas futuras

# Funcionalidad Estado
N-1 Integración con Cisco Intersight (UCS gestionado en la nube) ⚪
N-2 UCS Manager (UCSM) XML API para chasis B-series ⚪
N-3 Integración con Cisco DNA Center para fabric de switch ⚪
N-4 Soporte a NetConf/YANG como alternativa a NX-API DME ⚪
N-5 Telemetría de streaming gNMI desde Nexus (métricas sub-second) ⚪
N-6 Modelos OpenConfig YANG — interfaz vendor-neutral ⚪
N-7 Export de playbook Ansible — "TLSStress.Art configuró mi NGFW así; aquí está el playbook para reproducir" ⚪
N-8 Provider Terraform — TLSStress.Art como tipo de recurso ⚪
N-9 Webhook a ServiceNow / Jira / PagerDuty cuando una escritura de API falle ⚪
N-10 Replay de llamada de API — grabar + reproducir una secuencia de llamadas de API de un engagement a otro ⚪

Prioridad de implementación — próximos 3 PRs recomendados

Basado en valor para el operador vs costo de implementación:

  1. PR-B (mayor ROI) — Worker de polling + UI admin para registro de dispositivo. Sin esto, los adapters no corren en agenda. ~1 semana de trabajo.
  2. PR-C — Verificaciones de pre-vuelo (A-1 a A-7) integradas al motor de Test Plan. Rechaza ejecuciones en estados inválidos. ~3 días de trabajo.
  3. PR-D — Conexión de los Anexos B / C / D del Test Run Report (L-2, L-3, L-4). Cierra el loop de "datos derivados de API hacia PDF". ~1 semana de trabajo.

Las categorías restantes (B real-time, F escrituras, I auto-rollback) siguen una vez que la fundación esté sólida.

Comparación de capacidades vs alternativas comerciales

Grupo de funcionalidades Spirent CyberFlood Ixia BreakingPoint TLSStress.Art (este catálogo)
Verificaciones de pre-vuelo vía API parcial (DUTs vendor-locked) parcial completa (arquitectura abierta multi-vendor)
Visibilidad en tiempo real de la config del NGFW ninguna ninguna completa
Descubrimiento automático de topología manual manual LLDP/CDP automático
Salud de hardware durante SOAK ninguna ninguna UCS Redfish completo
Cadena de custodia forense en config ninguna ninguna SHA-256 por snapshot
Abstracción multi-vendor vendor-locked vendor-locked open adapter pattern
Integración con informe formato propietario cerrado formato propietario cerrado JSON versionado + PDF firmado

Relacionados

Referencias