Skip to content

Catálogo de Funcionalidades de API — o que o TLSStress.Art destrava via APIs REST

Leia no seu idioma: English · Português · Español

Status do escopo (pós-congelamento de escopo 2026-05-10) — Ver ARCHITECTURE.md para os 37 MÓDULOs canônicos + 7 Test Kinds + arquitetura de safety DOM/CPOS/PIE-PA. ADRs 0014, 0019-0025 cobrem adições pós-Freeze. Este documento cataloga toda funcionalidade concreta destravada ao falar com as APIs REST dos elementos de laboratório (Cisco FTD, Cisco Nexus 9000 NX-API DME, Cisco UCS CIMC Redfish, futuros Palo Alto + Fortinet). É o roadmap da integração de API: o que está entregue, o que está conectado, o que está planejado.

Para detalhes de implementação, veja DUT_API_INTEGRATION.pt-BR.md.

Legenda de status

Símbolo Significado
✅ Entregue — método do adapter existe e o dashboard / relatório consome
🟡 Método do adapter existe, mas a conexão com UI / dashboard está pendente
🔵 Desenhado — método do adapter agendado
⚪ Ideia capturada, ainda não planejada

Três pilares de telemetria

Pilar Origem O que entrega
Métricas SNMP, node-exporter, kubelet Estado numérico em séries temporais
Eventos Syslog, eventos do K8s Fluxo reativo de eventos
API (este catálogo) APIs REST dos fornecedores Configuração viva, políticas aplicadas, saúde de hardware, topologia, ações de escrita

Os três combinados produzem o nível de completude forense que o Test Run Report exige.

A. Verificações de pré-voo (recusar execução se o estado estiver errado)

Antes de permitir que um Test Plan inicie, o engine consulta os endpoints de API relevantes para confirmar que o laboratório está em estado executável. Se qualquer verificação falhar, a execução é recusada com um erro específico e acionável.

# Funcionalidade Origem Status
A-1 Confirmar que o status de deploy do NGFW é DEPLOYED (não pendente) FTD /operational/deploy 🟡
A-2 Confirmar que a política de decrypt está habilitada e se aplica às interfaces de teste FTD /policy/sslpolicies 🟡
A-3 Confirmar que a fonte NTP do NGFW corresponde à expectativa do laboratório FTD /devicesettings/default/ntp 🟡
A-4 Confirmar que o Nexus tem LLDP e CDP habilitados Nexus sys/lldp/inst + sys/cdp/inst 🟡
A-5 Confirmar que o UCS CIMC não reporta falhas críticas de hardware UCS LogServices/Faults/Entries 🟡
A-6 Confirmar que sensores térmicos do UCS estão abaixo do limiar UCS Chassis/<id>/Thermal 🟡
A-7 Confirmar que os papéis active+standby do par HA estão corretos no FTD FTD /devices/default/ha 🟡
A-8 Confirmar que a smart license do FTD tem capacidade suficiente FTD /license (planejado v6.x) 🔵
A-9 Confirmar que o perfil de QoS do Nexus corresponde ao baseline esperado Nexus sys/qos 🔵
A-10 Confirmar a revisão de firmware do UCS contra a lista aprovada UCS Systems/<id> Bios + Firmware 🔵

O pré-voo roda em paralelo contra cada dispositivo registrado. Orçamento total de tempo: ≤30 s. O resumo de falhas é mostrado ao operador com um único botão "Sobrepor e executar mesmo assim (registra como não-forense)" — opt-in explícito do operador para casos incomuns.

B. Métricas em tempo real durante execuções

Assim que uma execução está ativa, o worker de polling aumenta sua cadência nos dispositivos ativos e transmite snapshots de métricas para o Prometheus via um exporter customizado — exibido como painéis Grafana ao lado das métricas de agente já coletadas.

# Funcionalidade Origem Status
B-1 Utilização de CPU do NGFW durante o teste FTD /operational/systemmonitoring/cpu 🔵
B-2 Utilização de memória do NGFW FTD /operational/systemmonitoring/memory 🔵
B-3 Conexões ativas do NGFW + novas conexões/s FTD /operational/systemmonitoring/connections 🔵
B-4 Contagens atuais de hits da regra de decrypt do NGFW FTD /operational/policy/sslpolicy/<id>/hitcount 🔵
B-5 Contadores de interface do Nexus (bytes, erros, drops) a 1 Hz Nexus sys/intf/<id>/counters 🔵
B-6 RPM dos fans do UCS durante a execução UCS Chassis/<id>/Thermal 🔵
B-7 Temperatura de CPU do UCS durante a execução UCS Chassis/<id>/Thermal 🔵
B-8 Consumo de energia do UCS (watts) UCS Chassis/<id>/Power 🔵
B-9 Contagens de hits do IPS do NGFW FTD /operational/policy/intrusionpolicy/<id>/hitcount 🔵
B-10 Profundidade de fila + drops de QoS do Nexus Nexus sys/qos/<class>/queue ⚪

Essas métricas dão ao operador uma visão em tempo real de "o que o dispositivo vê" — sem nunca precisar logar no console de gerência do NGFW ou no CLI do Nexus.

C. Topologia e inventário

# Funcionalidade Origem Status
C-1 Construção automática de diagrama de topologia do laboratório a partir de LLDP/CDP Nexus sys/lldp/inst + sys/cdp/inst ✅ adapter / 🟡 dashboard
C-2 Anexo de inventário de hardware (S/N + firmware + PSU + DIMM) Nexus sys/ch?rsp-subtree=full + UCS Systems/<id> ✅ adapter / 🟡 dashboard / 🔵 relatório
C-3 Verificação de vínculo de service profile (apenas UCS gerenciado por UCSM) UCSM serviceProfile/<id> ⚪
C-4 Estado de interface do NGFW + status do cabo FTD /operational/interfaces ✅ adapter / 🟡 dashboard
C-5 Estado de link da NIC do UCS + negociação de velocidade UCS Systems/<id>/EthernetInterfaces ✅ adapter / 🟡 dashboard

O Anexo A do Test Run Report — topologia auto-gerada — é produzido a partir de C-1.

D. Forense e conformidade

# Funcionalidade Origem Status
D-1 Snapshot de configuração pré-execução de cada dispositivo + SHA-256 Todos os adapters ✅ adapter / 🔵 conectado ao engine de Test Plan
D-2 Diff de config pós-execução contra snapshot pré-execução Query interna dut_api_snapshots 🔵
D-3 Atestado de conformidade contra baseline de política FTD /policy/* + Nexus running-config 🔵
D-4 SHA-256 por snapshot citado nos Anexos B + C + D do Relatório Interno ✅ campo existe / 🔵 conexão ao relatório
D-5 Cadeia tamper-evident — SHA-256 do Snapshot ancorado no PDF Assinatura Cosign futura 🔵

E. Correlação entre origens

O valor único: combinar os três pilares para detectar coisas que nenhum pilar isolado consegue.

# Funcionalidade Combinação de origens Status
E-1 Syslog do NGFW "decrypt error" + verificação simultânea via API do estado da política de decrypt. Diff = drift de config no meio da execução Syslog (decrypt error) + API (estado da política de decrypt) 🔵
E-2 Falha do CIMC do UCS + falhas de agente correlacionadas. Mesma janela de tempo = atribuição de causa raiz API (falhas do UCS) + Postgres (falhas da tabela runs) 🔵
E-3 Pico de contador de erros de interface do Nexus + pico de latência p99 correlacionado API (contadores Nexus) + Prometheus (p99 do agente) 🔵
E-4 TLS Decrypt Probe diz "off" + API confirma política de decrypt habilitada. Discrepância → NGFW quebrado Métrica do probe + API (política de decrypt) 🔵
E-5 Estado de deploy do NGFW muda no meio da execução = execução invalidada Delta de polling de API 🔵

F. Operações de escrita (confirmadas pelo operador)

Somente leitura está entregue; escritas exigem confirmação do operador, trilha de auditoria e rollback automático em caso de falha.

# Funcionalidade Origem Status
F-1 Definir servidor NTP do NGFW via API FTD PUT /devicesettings/default/ntp/<id> + POST /operational/deploy 🔵
F-2 Alternar estado da política de decrypt para teste A/B FTD PUT /policy/sslpolicies/<id> 🔵
F-3 Aplicar política de QoS específica do test-bed no Nexus pré-execução, reverter pós-execução Nexus DME PUT 🔵
F-4 Resetar contadores de interface antes da execução Ação Nexus DME ⚪
F-5 Preparar configuração de rollback antes de qualquer escrita Interno: snapshot antes, restore depois 🔵
F-6 Mudança de perfil de energia BIOS do UCS para execuções "max-perf" UCS Redfish Systems/<id>/Bios PATCH ⚪

Cada escrita exige: 1. Re-autenticação de admin no momento da requisição 2. Confirmação explícita do operador na UI ("prestes a alterar a fonte NTP do NGFW — prosseguir?") 3. Entrada em audit log com snapshots before/after 4. Rollback automático se a leitura pós-escrita confirmar divergência da intenção

G. Energia, sustentabilidade, performance-per-watt

# Funcionalidade Origem Status
G-1 Série temporal de consumo de energia do UCS durante execuções UCS Chassis/<id>/Power 🔵
G-2 Métrica "throughput-per-watt" por execução de plano UCS Power + throughput do Prometheus ⚪
G-3 Detecção de throttle térmico (avisar se temp de CPU exceder limiar) UCS Thermal + alerting 🔵
G-4 Estimativa de equivalente de carbono por execução (fator de grid fornecido pelo operador) Computado a partir de G-1 ⚪

H. Saúde de hardware para execuções SOAK

Planos de 24 horas ou mais demandam vigilância em nível de hardware. A integração de API fornece o que o node-exporter não consegue.

# Funcionalidade Origem Status
H-1 Contagens de erros de DIMM do UCS (correctable + uncorrectable) UCS Memory?$expand=. ✅ adapter / 🔵 alerting
H-2 Status de redundância de PSU durante execuções 24 h+ UCS Chassis/<id>/Power ✅ adapter / 🔵 alerting
H-3 Baseline de taxa de erro de NIC + comparação durante execução Contadores de interface UCS + Nexus 🔵
H-4 Dados SMART de disco no armazenamento local UCS UCS SimpleStorage/<id> ⚪
H-5 Relatório de fim de SOAK: pico de RPM de fan, pico de temp, energia total, pico de watts Agregação sobre snapshots coletados 🔵

I. Auto-rollback

# Funcionalidade Origem Status
I-1 Captura pré-execução da configuração completa dos 3 tipos de dispositivo Adapters + nova tabela pre_run_config 🔵
I-2 Restore automático pós-execução (operador opt-in via parâmetro do plano) Métodos de escrita dos adapters 🔵 (depende de F-*)
I-3 Detecção de drift no meio da execução → auto-pause + alerta Diff de polling contra pré-execução 🔵
I-4 Verificação de rollback: snapshot pós-restore corresponde ao pré-execução Comparação de SHA-256 🔵

J. Integração com test plan

O YAML do Test Plan pode expressar "o laboratório PRECISA estar neste estado para este plano ser válido":

# Funcionalidade Campo YAML Status
J-1 Plano declara ngfw_state_required: decrypt-on e adapter verifica já existe ✅
J-2 Plano declara ntp_source_must_match: lab-relay novo campo 🔵
J-3 Plano declara expected_ngfw_models: [FPR1010, FPR1140] e recusa em mismatch novo campo 🔵
J-4 Plano declara pre_run_capture_config: true para execuções de conformidade novo campo 🔵
J-5 Conclusão de plano dispara snapshot final de config automaticamente hook do engine 🔵
J-6 Falha de plano dispara snapshot post-mortem automático hook do engine 🔵

K. Abstração multi-vendor

Mesmas queries de endpoint_label retornam dados independentemente do fornecedor — código de Dashboard e Report fica vendor-agnostic.

# Funcionalidade Origem Status
K-1 Mesma query "show NGFW NTP config" funciona em FTD / Palo Alto / Fortinet Abstração de adapter ✅ FTD / 🔵 Palo Alto / 🔵 Fortinet
K-2 Dashboard do operador mostra "todos os NGFWs" de forma agnóstica View Postgres + Grafana 🟡
K-3 Futuros adapters Palo Alto + Fortinet encaixam transparentemente Arquitetura suporta ✅
K-4 Matriz de funcionalidades do adapter exposta na UI admin ("FTD tem decrypt_policy, Palo Alto também, Fortinet não") Introspecção de adapter 🔵

L. Relatório

O Test Run Report (Fase 3 → 5) consome snapshots de API intensamente.

# Funcionalidade Origem Status
L-1 Anexo A — topologia auto-gerada a partir de LLDP/CDP Adapter Nexus ✅ adapter / 🔵 render SVG
L-2 Anexo B — inventário Nexus + running-config sanitizada Adapter Nexus ✅ adapter / 🔵 conexão ao relatório
L-3 Anexo C — inventário NGFW + política de decrypt + estado IPS Adapter FTD ✅ adapter / 🔵 conexão ao relatório
L-4 Anexo D — inventário de hardware UCS + leituras de sensor Adapter UCS ✅ adapter / 🔵 conexão ao relatório
L-5 Cadeia de custódia SHA-256 por anexo (já no formato) Todos os adapters ✅
L-6 Apêndice "o que mudou durante a execução" — diff pré vs pós Computação interna 🔵

M. Exposição na UI — o operador nunca abre o console do NGFW

A meta "single pane of glass" do operador — tudo visível em Grafana / Dashboard / Report.

# Funcionalidade Superfície Status
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 / testar dispositivos Nova /admin/dut-api/ 🔵
M-4 Dashboard — navegador de snapshots por dispositivo ("me mostre o que o FTD-1 disse sobre sua config NTP 30 min atrás") Nova página 🔵
M-5 Dashboard — botão de disparo manual de snapshot por dispositivo Novo endpoint de API 🔵
M-6 Dashboard — modal de confirmação de operação de escrita Novo componente 🔵 (depende de F-*)
M-7 Test Run Report — contexto DUT completo auto-incorporado Builder de relatório da Fase 3 🔵

N. Long-tail e ideias futuras

# Funcionalidade Status
N-1 Integração com Cisco Intersight (UCS gerenciado em nuvem) ⚪
N-2 UCS Manager (UCSM) XML API para chassi B-series ⚪
N-3 Integração com Cisco DNA Center para fabric de switch ⚪
N-4 Suporte a NetConf/YANG como alternativa ao NX-API DME ⚪
N-5 Telemetria de streaming gNMI a partir do Nexus (métricas sub-second) ⚪
N-6 Modelos OpenConfig YANG — interface vendor-neutral ⚪
N-7 Export de playbook Ansible — "TLSStress.Art configurou meu NGFW assim; aqui está o playbook para reproduzir" ⚪
N-8 Provider Terraform — TLSStress.Art como tipo de recurso ⚪
N-9 Webhook para ServiceNow / Jira / PagerDuty quando escrita de API falhar ⚪
N-10 Replay de chamada de API — gravar + reproduzir uma sequência de chamadas de API de um engagement para outro ⚪

Prioridade de implementação — próximos 3 PRs recomendados

Baseado em valor para o operador vs custo de implementação:

  1. PR-B (maior ROI) — Worker de polling + UI admin para registro de dispositivo. Sem isso, os adapters não rodam em agenda. ~1 semana de trabalho.
  2. PR-C — Verificações de pré-voo (A-1 a A-7) integradas ao engine de Test Plan. Recusa execuções em estados inválidos. ~3 dias de trabalho.
  3. PR-D — Conexão dos Anexos B / C / D do Test Run Report (L-2, L-3, L-4). Fecha o loop de "dados derivados de API para PDF". ~1 semana de trabalho.

As categorias restantes (B real-time, F escritas, I auto-rollback) seguem assim que a fundação estiver sólida.

Comparação de capacidades vs alternativas comerciais

Grupo de funcionalidades Spirent CyberFlood Ixia BreakingPoint TLSStress.Art (este catálogo)
Verificações de pré-voo via API parcial (DUTs vendor-locked) parcial completa (arquitetura aberta multi-vendor)
Visibilidade em tempo real da config do NGFW nenhuma nenhuma completa
Descoberta automática de topologia manual manual LLDP/CDP automático
Saúde de hardware durante SOAK nenhuma nenhuma UCS Redfish completo
Cadeia de custódia forense em config nenhuma nenhuma SHA-256 por snapshot
Abstração multi-vendor vendor-locked vendor-locked open adapter pattern
Integração com relatório formato proprietário fechado formato proprietário fechado JSON versionado + PDF assinado

Relacionados

Referências