API do Flow Novo na 7.2

Referência completa da API do ambiente Flow (anti-DDoS): acompanhe tráfego em tempo real, eventos de ataque, saúde do coletor e roteamento BGP, e gerencie mitigações, prefixos, listas e janelas de manutenção por integração externa. São 36 operações: 21 de leitura e 15 de escrita.

Visão geral

A API do Flow expõe todo o ambiente Flow para sistemas externos. Ela cobre dois grandes usos:

Acompanhar: tráfego ao vivo por exportador e interface, top talkers, saúde do coletor, eventos de ataque, anomalias de baseline, alertas de roteamento BGP, mitigações ativas e configurações.
Gerenciar: disparar e remover mitigações (FlowSpec cirúrgico ou blackhole RTBH), resolver eventos e anomalias, marcar falso-positivo, cadastrar prefixos monitorados, manter whitelist de mitigação e allowlist de detecção, ligar e desligar regras de detecção e exportadores, e abrir ou encerrar janelas de manutenção.

Casos típicos: alimentar um painel NOC próprio (Grafana ou similar) com métricas do Flow, integrar alertas de DDoS a sistemas de ticket, automatizar mitigação a partir de ferramentas externas e silenciar a detecção durante janelas de mudança programadas via script.

Pré-requisitos

Requisito	Detalhe
Plano com Flow Premium Flow+	O ambiente Flow existe nos planos Premium Flow (1 exportador), Gold Flow (até 4) e ENTERPRISE (ilimitado). Sem ambiente Flow configurado, as respostas vêm vazias e `collector_online` fica `false`.
Chave de API com permissão Flow	Ao criar ou editar a chave em Configurações, aba Integrações, card Gerenciamento de API, marque a permissão Acesso a Flow na seção Permissões de Acesso. Veja Criar uma chave de API.
Ambiente Flow ativo	Coletor rodando, exportadores cadastrados e, para mitigar, peers BGP de mitigação configurados e ativos.
Rede	Acesso HTTPS ao servidor Ravi do cliente.

Uma chave com Acesso a Flow tem leitura e escrita em tudo do módulo: consegue disparar blackhole de qualquer IP e desligar regras de detecção. Trate-a como credencial de alto privilégio: crie uma chave dedicada por integração, preencha o campo Descrição (opcional) e não marque outras permissões desnecessárias.

A API do Flow não cadastra exportadores, regras de detecção nem peers BGP. Esses cadastros são feitos apenas pela interface, no ambiente Flow. Pela API é possível listá-los e ligá-los ou desligá-los (exporter_toggle e detection_toggle).

Formato das chamadas

Todas as operações usam o endpoint único da API pública, com action=flow. GET e POST são aceitos em todas as operações; prefira POST nas operações de escrita e sempre que quiser evitar o token em logs de acesso.

URL base

https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=NOME_DA_OPERACAO

Parâmetro	Tipo	Obrigatório	Descrição
`token`	string	sim	Chave de API de 32 caracteres com a permissão Acesso a Flow.
`action`	string	sim	Sempre `flow` para este módulo.
`operation`	string	sim	A operação desejada (referência nas seções abaixo).

O módulo Flow usa o envelope padrão em 100% das operações:

Sucesso: {"status":"success","data":{...}} com HTTP 200.
Erro: {"status":"error","message":"..."} com código HTTP 400, 401, 403, 404 ou 500. As mensagens de erro são em inglês.

Erros comuns a todas as operações

HTTP	`message`	Causa
400	`Token not provided` / `Action not provided`	Faltou `token` ou `action`.
401	`Invalid token`	Chave inexistente, errada ou revogada.
403	`Access denied for flow`	Chave sem a permissão Acesso a Flow.
400	`Please provide a valid operation`	Faltou `operation`.
400	`Invalid Flow operation`	`operation` desconhecida.
500	`Database connection error`	Banco de dados indisponível logo na abertura da conexão.
500	`Database error`	Falha ao gravar no banco. Devolvido pelas operações de escrita (`event_resolve`, `anomaly_resolve`, `prefix_add`, `prefix_del`, `detection_toggle`, `whitelist_add`, `whitelist_del`, `allowlist_add`, `allowlist_del`, `exporter_toggle`, `maintenance_add`, `maintenance_end`). Não confunda com `Database connection error`.

Conceitos usados na referência

Coletor: daemon que recebe NetFlow/IPFIX/sFlow, detecta ataques e fala BGP para mitigar. A API não fala BGP diretamente: comandos de mitigação são enfileirados e o coletor os processa em até 1 segundo. O coletor é considerado online quando o snapshot de tempo real tem menos de 30 segundos de idade.
Evento: ataque detectado. Status: ativo, mitigando, resolvido. Severidade: info, warning, critical. Cada evento carrega um vetor (classificação precisa: ampl_dns, syn_flood, carpet_bombing...) que orienta a mitigação FlowSpec cirúrgica.
Anomalia: desvio do baseline sazonal, não necessariamente ataque. Status: ativa ou resolvida.
FlowSpec vs. RTBH: FlowSpec descarta só o tráfego do vetor (ex.: UDP com porta de origem 53); RTBH (blackhole) descarta todo o tráfego para o IP, medida mais drástica.
Whitelist de mitigação: prefixos protegidos da mitigação automática. Não bloqueia mitigação manual nem via API.
Allowlist de detecção: exceções anti falso-positivo, origens e destinos que a detecção deve ignorar.

Operações de monitoramento

As 21 operações de leitura. Os exemplos abaixo mostram GET por brevidade; POST também funciona. Datas e horas seguem o fuso do servidor Ravi, no formato YYYY-MM-DD HH:MM:SS.

GET/api/api.php?action=flow&operation=overview

Resumo geral do ambiente: junta o snapshot ao vivo com contadores do banco. Ideal para um semáforo do Flow em painel externo. Sem parâmetros. Campos de data: collector_online, collector_version, snapshot_age_sec, flows_per_sec, total_in_bps/total_out_bps (soma de todos os exportadores, em bits/s), exporters_total/exporters_active, prefixes_monitored, events_active (status ativo + mitigando), events_mitigating, anomalies_active, mitigations_active, bgp_alerts_open e bgp_rib ({ativa, v4, v6, built_at} ou null).

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=overview"

{"status":"success","data":{"collector_online":true,"collector_version":"1.9.0",
 "snapshot_age_sec":3,"flows_per_sec":4210,"total_in_bps":3812345678,
 "total_out_bps":1523456789,"exporters_total":2,"exporters_active":2,
 "prefixes_monitored":14,"events_active":1,"events_mitigating":0,
 "anomalies_active":0,"mitigations_active":0,"bgp_alerts_open":0,
 "bgp_rib":{"ativa":true,"v4":1080342,"v6":210577,"built_at":1751540000}}}

GET/api/api.php?action=flow&operation=live

Tempo real por exportador e interface, mais top talkers. Sem parâmetros. Resposta: ts, collector_online, flows_per_sec, total_in_bps, total_out_bps, top (top talkers globais, mesmo formato da operação top) e exporters[]. Cada exportador traz id, nome, total_in_bps, total_out_bps, top (só daquele exportador) e interfaces[] com if_index, nome, in_bps, out_bps, in_pps, out_pps e cap_bps (capacidade; 0 = desconhecida).

Exportadores cadastrados e ativos que não aparecem no snapshot entram na lista com sem_fluxo: true e taxas zeradas: sinal de que o roteador parou de exportar fluxos.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=live"

{"status":"success","data":{"ts":1751540123,"collector_online":true,
 "flows_per_sec":4210,"total_in_bps":3812345678,"total_out_bps":1523456789,
 "top":{...},"exporters":[{"id":1,"nome":"NE8000 Borda","total_in_bps":3600000000,
  "total_out_bps":1400000000,"top":{...},"interfaces":[
   {"if_index":5,"nome":"100GE0/1/0 Transito","in_bps":3100000000,
    "out_bps":1200000000,"in_pps":410000,"out_pps":220000,"cap_bps":100000000000}]}]}}

GET/api/api.php?action=flow&operation=top

Top talkers do snapshot ao vivo, top 10 por dimensão, agregado global.

Parâmetro	Tipo	Obrigatório	Descrição
`dimension`	string	não	Filtra uma dimensão: `src_ip`, `dst_ip`, `src_port`, `dst_port`, `proto`, `src_asn`, `dst_asn`, `nexthop`, `peer`, `src_upstream`, `dst_upstream`, `src_pais`, `dst_pais`. Sem ele, devolve todas.

bytes e packets são acumulados dentro do bucket corrente de 60 segundos do coletor, não taxa instantânea. Para taxas por interface, use a operação live.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=top&dimension=dst_ip"

{"status":"success","data":{"dimension":"dst_ip","top":[
 {"valor":"203.0.113.10","bytes":812345678,"packets":654321}]}}

GET/api/api.php?action=flow&operation=health

Saúde do coletor, do banco e do host. Sem parâmetros. Resposta: collector_online, snapshot_age_sec, fps, pps (soma de pacotes/s das interfaces), bloco health com contadores cumulativos desde o start do coletor (uptime_seg, pkts_recebidos, registros, drops_canal, drops_kernel, rss_mb, heap_mb, goroutines, rib_rotas, rib_mem_mb), rollup_lag_sec (atraso da gravação histórica) e tables[]/tables_mb_total (tamanho das tabelas do Flow no banco, útil para vigiar retenção e disco).

Sintomas: drops_canal ou drops_kernel crescendo indicam coletor saturado (CPU ou volume de fluxos); rollup_lag_sec alto indica banco lento.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=health"

{"status":"success","data":{"collector_online":true,"snapshot_age_sec":2,
 "fps":4210,"pps":830000,"health":{"uptime_seg":864000,"pkts_recebidos":901234567,
 "registros":812345678,"drops_canal":0,"drops_kernel":0,"rss_mb":812,"heap_mb":540,
 "goroutines":64,"rib_rotas":1290919,"rib_mem_mb":310},"rollup_lag_sec":4,
 "tables":[{"name":"flow_amostras","rows":7100000,"mb":2210}],"tables_mb_total":3480}}

GET/api/api.php?action=flow&operation=exporters

Lista os exportadores cadastrados. Sem parâmetros. Itens de data.exporters[]: id, nome, ip, modelo, versao (protocolo de export), sampling_rate, asn, descricao, ativo (0/1), status, motivo (texto do último problema) e datasinc.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=exporters"

{"status":"success","data":{"exporters":[{"id":1,"nome":"NE8000 Borda",
 "ip":"192.0.2.1","modelo":"Huawei NE8000","versao":"ipfix","sampling_rate":1000,
 "asn":64511,"descricao":"Transito","ativo":1,"status":"ok","motivo":null,
 "datasinc":"2026-07-03 10:00:00"}]}}

GET/api/api.php?action=flow&operation=interfaces

Interfaces conhecidas dos exportadores.

Parâmetro	Tipo	Obrigatório	Descrição
`exporter_id`	inteiro	não	Filtra por exportador; sem ele, lista todas.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=interfaces&exporter_id=1"

{"status":"success","data":{"interfaces":[{"id":10,"exportador_id":1,"if_index":5,
 "if_name":"100GE0/1/0","if_alias":"Transito","if_speed":100000000000,"monitorar":1}]}}

GET/api/api.php?action=flow&operation=prefixes

Prefixos monitorados: os blocos do provedor (ou de clientes) que a detecção vigia. Sem parâmetros. Itens: id, cidr, nome, cliente, ativo, created_at.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=prefixes"

{"status":"success","data":{"prefixes":[{"id":3,"cidr":"203.0.113.0/24",
 "nome":"Bloco clientes","cliente":"","ativo":1,"created_at":"2026-06-01 09:00:00"}]}}

GET/api/api.php?action=flow&operation=events

Eventos de ataque, ordenados por id decrescente.

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	não	`ativo`, `mitigando`, `resolvido` ou o atalho `ativos` (= `ativo` + `mitigando`).
`severity`	string	não	`info`, `warning` ou `critical`.
`exporter_id`	inteiro	não	Filtra por exportador.
`since_id`	inteiro	não	Só eventos com `id` maior que o valor: use para polling incremental, guardando o último id visto.
`limit`	inteiro	não	Padrão 100, máximo 1000.

Campos de cada evento: id, exportador_id, deteccao_id (regra que disparou), tipo (assinatura: udp_flood, syn_flood, icmp_flood, amplification, dns_query_flood, generic_pps, generic_bps, volumetrico...), vetor (classificação precisa: ampl_dns, ampl_ntp, ampl_ssdp, ampl_memcached, ampl_chargen, ampl_cldap, ampl_snmp, ampl_netbios, udp_flood, tcp_flood, syn_flood, ack_flood, rst_flood, icmp_flood, dns_query_flood, frag, carpet_bombing, multi_vetor...), direcao (entrada/saida), dst_count, carpet (1 = carpet bombing), src_ip, dst_ip (IP, ou CIDR no carpet), dst_porta, proto, peak_pps, peak_bps, total_bytes, total_packets, severidade, status, mitigado (0/1), inicio, fim.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=events&status=ativos&severity=critical"

{"status":"success","data":{"events":[{"id":812,"exportador_id":1,"deteccao_id":4,
 "tipo":"amplification","vetor":"ampl_dns","direcao":"entrada","dst_count":1,"carpet":0,
 "src_ip":"198.51.100.53","dst_ip":"203.0.113.10","dst_porta":0,"proto":17,
 "peak_pps":920000,"peak_bps":7800000000,"severidade":"critical","status":"ativo",
 "mitigado":0,"inicio":"2026-07-03 10:12:04","fim":null}]}}

GET/api/api.php?action=flow&operation=event

Detalhe de um evento com a anatomia do ataque.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id do evento.

Resposta: event (todos os campos do evento) mais sources[] com as principais origens do ataque (até 200, ordenadas por pacotes): src_ip, src_asn, packets, pais, cidade. Em eventos de saída, sources traz os destinos externos atingidos. Erros: 400 Please provide a valid event id; 404 Event not found.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=event&id=812"

{"status":"success","data":{"event":{"id":812,"vetor":"ampl_dns", ...},
 "sources":[{"src_ip":"198.51.100.53","src_asn":64500,"packets":812345,
  "pais":"US","cidade":"Ashburn"}]}}

GET/api/api.php?action=flow&operation=anomalies

Anomalias de baseline sazonal (desvios de tráfego, não necessariamente ataques).

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	não	`ativa` ou `resolvida`; sem ele, lista tudo (até 500).

Itens: id, tipo, ref1, ref2, direcao, label, baseline_bps (esperado), atual_bps (medido), sigma (desvios-padrão), severidade, status, inicio, fim.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=anomalies&status=ativa"

{"status":"success","data":{"anomalies":[{"id":45,"tipo":"interface","label":"Transito in",
 "direcao":"entrada","baseline_bps":2100000000,"atual_bps":3900000000,"sigma":4.2,
 "severidade":"warning","status":"ativa","inicio":"2026-07-03 09:40:00","fim":null}]}}

GET/api/api.php?action=flow&operation=detections

Regras de detecção configuradas. Sem parâmetros. Itens: id, nome, escopo (IP, prefixo ou interface), escopo_id, direcao, assinatura, limiar_pps, limiar_bps, janela_seg, severidade, auto_mitigar (0/1, regra que pode mitigar sozinha), acao_mitig, rate_value, ativo.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=detections"

{"status":"success","data":{"detections":[{"id":3,"nome":"Flood UDP prefixos",
 "escopo":"prefixo","escopo_id":0,"direcao":"entrada","assinatura":"udp_flood",
 "limiar_pps":200000,"limiar_bps":0,"janela_seg":30,"severidade":"critical",
 "auto_mitigar":0,"acao_mitig":"discard","rate_value":0,"ativo":1}]}}

GET/api/api.php?action=flow&operation=mitigations

Regras de mitigação FlowSpec/RTBH.

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	não	`active` (padrão), `withdrawn` ou `expired`; qualquer outro valor lista tudo (até 500).

Itens: id, evento_id (null nas manuais), peer_id, tipo (flowspec/rtbh), match_json (match FlowSpec anunciado), dst_ip, acao (discard/ratelimit), rate_value, origem (auto/manual), status, announced_at, expires_at (null = sem expiração automática).

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=mitigations"

{"status":"success","data":{"mitigations":[{"id":21,"evento_id":null,"peer_id":1,
 "tipo":"flowspec","match_json":"{\"dst\":\"203.0.113.10/32\",\"proto\":17,\"sport\":53}",
 "dst_ip":"203.0.113.10","acao":"discard","rate_value":0,"origem":"manual",
 "status":"active","announced_at":"2026-07-03 10:13:00","expires_at":null}]}}

GET/api/api.php?action=flow&operation=whitelist

Prefixos protegidos da mitigação automática. Sem parâmetros. Itens: id, cidr, nome, ativo, created_at.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=whitelist"

{"status":"success","data":{"whitelist":[{"id":2,"cidr":"198.51.100.0/24",
 "nome":"Infra DNS","ativo":1,"created_at":"2026-06-10 08:00:00"}]}}

GET/api/api.php?action=flow&operation=allowlist

Exceções de detecção (anti falso-positivo). Sem parâmetros. Itens: id, escopo (src_asn, src_prefixo, dst_ip, dst_prefixo), valor, motivo, origem (manual/auto), expira_em, ativo, created_at.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=allowlist"

{"status":"success","data":{"allowlist":[{"id":7,"escopo":"src_asn","valor":"15169",
 "motivo":"CDN conhecida","origem":"manual","expira_em":null,"ativo":1,
 "created_at":"2026-06-15 14:00:00"}]}}

GET/api/api.php?action=flow&operation=peers

Peers BGP. Sem parâmetros. Duas listas na resposta:

mitigation_peers[] (anúncio FlowSpec/RTBH): id, nome, neighbor_ip, our_asn, peer_asn, flowspec_capable (0/1; sem essa capacidade, a mitigação vira RTBH naquele peer), rtbh_community, rtbh_next_hop, ativo, status.
route_peers[] (coleta de rotas para enriquecimento): id, nome, neighbor_ip, our_asn, peer_asn, descricao, relacao, multihop, ativo, status, prefixos_v4, prefixos_v6, datasinc.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=peers"

{"status":"success","data":{"mitigation_peers":[{"id":1,"nome":"Borda 1",
 "neighbor_ip":"192.0.2.1","our_asn":65001,"peer_asn":64511,"flowspec_capable":1,
 "rtbh_community":"64511:666","rtbh_next_hop":"192.0.2.254","ativo":1,
 "status":"established"}],"route_peers":[...]}}

GET/api/api.php?action=flow&operation=bgp

Enriquecimento BGP/RIB e alertas de roteamento (possível sequestro de rota). Sem parâmetros. Resposta: collection_active, rib ({ativa, v4, v6, built_at}), route_peers[] (resumo) e alerts[] com até 200 itens: id, tipo (origin_change, subprefix...), prefixo, origem_ant, origem_nova, detalhe, status (aberto...), detectado_em, visto_em.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=bgp"

{"status":"success","data":{"collection_active":true,
 "rib":{"ativa":true,"v4":1080342,"v6":210577,"built_at":1751540000},
 "route_peers":[...],"alerts":[{"id":9,"tipo":"origin_change","prefixo":"203.0.113.0/24",
 "origem_ant":"64511","origem_nova":"64500","detalhe":"...","status":"aberto",
 "detectado_em":"2026-07-03 08:00:00","visto_em":"2026-07-03 10:10:00"}]}}

GET/api/api.php?action=flow&operation=templates

Templates FlowSpec catalogados. Sem parâmetros. Itens: id, nome, protocol, sport, dport, tcpflags, fragment, plen_op, plen, acao, rate_value. A aplicação de template é feita pela interface; via API a mitigação é feita por vetor (operação mitigate).

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=templates"

{"status":"success","data":{"templates":[{"id":1,"nome":"Amplificacao DNS",
 "protocol":"17","sport":"53","dport":"","tcpflags":"","fragment":"",
 "plen_op":"","plen":"","acao":"discard","rate_value":0}]}}

GET/api/api.php?action=flow&operation=communities

Comunidades BGP catalogadas para leitura no enriquecimento. Sem parâmetros. Itens: id, community, nome, classificacao, descricao, ativo.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=communities"

{"status":"success","data":{"communities":[{"id":1,"community":"64511:100",
 "nome":"Clientes","classificacao":"customer","descricao":"","ativo":1}]}}

GET/api/api.php?action=flow&operation=holidays

Feriados do baseline sazonal. Em feriado, o baseline usa um perfil próprio de dia de feriado para evitar falsa anomalia. Sem parâmetros. Itens: id, data, nome, nacional, ativo.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=holidays"

{"status":"success","data":{"holidays":[{"id":12,"data":"2026-09-07",
 "nome":"Independencia do Brasil","nacional":1,"ativo":1}]}}

GET/api/api.php?action=flow&operation=maintenance

Janelas de manutenção (períodos com detecção e alertas silenciados). Sem parâmetros. Até 200 itens, mais recentes primeiro: id, inicio, fim (null se indefinida), indefinida (0/1), escopo (global/exportador), exportador_id, motivo, criado_por (API quando criada por aqui), ativa, criado_em.

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=maintenance"

{"status":"success","data":{"maintenance":[{"id":7,"inicio":"2026-07-03 22:00:00",
 "fim":"2026-07-04 02:00:00","indefinida":0,"escopo":"exportador","exportador_id":1,
 "motivo":"Troca de uplink","criado_por":"API","ativa":1,
 "criado_em":"2026-07-03 10:00:00"}]}}

GET/api/api.php?action=flow&operation=settings

Configurações do Flow, somente leitura (não há operação de escrita de configurações na API). Sem parâmetros. Resposta: settings (mapa chave e valor) e raw[] (com updated_at). Chaves típicas, que variam por instalação: alerta_severidade_min, bgp_coleta_ativa, collector_addr, explorer_sampling, dados_historicos, retencao_rollup_dias, anomalia_alerta_sigma, postmortem_auto, threat_ativo, auto_minhas_redes, forecast_cache, mitig_ttl_seg (TTL das mitigações automáticas, em segundos).

exemplo

curl "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=settings"

{"status":"success","data":{"settings":{"alerta_severidade_min":"warning",
 "mitig_ttl_seg":"1800","bgp_coleta_ativa":"1"},"raw":[...]}}

Operações de gerenciamento

As 15 operações de escrita. Prefira POST em todas. As operações de mitigação são enfileiradas para o coletor, que as processa em até 1 segundo; a resposta queued:true significa "comando aceito", não "anúncio BGP feito".

POST/api/api.php?action=flow&operation=mitigate

Dispara uma mitigação para um destino: FlowSpec cirúrgico montado a partir do vetor do ataque, ou blackhole RTBH.

Parâmetro	Tipo	Obrigatório	Descrição
`dst`	string	sim	IP (`203.0.113.10`) ou CIDR (`203.0.113.0/24`, para carpet bombing).
`modo`	string	não	`vetor` (padrão, FlowSpec cirúrgico) ou `rtbh` (blackhole total do destino).
`vetor`	string	não	Vetor do ataque para montar o FlowSpec (lista na operação `events`). Ex.: `ampl_dns` descarta UDP com porta de origem 53; `syn_flood` filtra TCP com flag S; `frag` filtra fragmentos. Vazio ou desconhecido: match amplo por `proto`/`port`.
`proto`	inteiro	não	Número do protocolo IP (17=UDP, 6=TCP...), usado nos vetores genéricos e no carpet.
`port`	inteiro	não	Porta de destino, usada em `udp_flood`, `tcp_flood` e genérico.
`acao`	string	não	`discard` (padrão) ou `ratelimit`.
`rate`	inteiro	não	Limite em bps quando `acao=ratelimit`.
`event_id`	inteiro	não	Vincula ao evento: ele passa para o status `mitigando` e `mitigado=1`. A regra de mitigação em si é gravada sem vínculo com o evento; para retirá-la depois, use `mitigate_clear` com `dst`.
`grupo_id`	inteiro	não	Grupo de anúncio (subconjunto de peers); 0 ou ausente anuncia em todos os peers.

Com modo=rtbh todo o tráfego para o destino é descartado, inclusive o legítimo: o IP fica fora do ar até um mitigate_clear. Peers sem capacidade FlowSpec aplicam RTBH mesmo em modo=vetor (fallback por peer). A whitelist de mitigação não bloqueia o mitigate: ela protege apenas da mitigação automática.

Mitigações via API (origem=manual) não expiram por TTL: expires_at fica null e a regra permanece até um mitigate_clear explícito. E se nenhum peer BGP estiver ativo, a mitigação falha silenciosamente: a API não devolve erro. Sempre confirme com operation=mitigations (deve surgir uma regra origem:"manual", status:"active") cerca de 2 segundos depois.

Erros: 400 Invalid dst (use IP or CIDR); 500 Failed to enqueue mitigation command.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=mitigate" -d "dst=203.0.113.10" -d "modo=vetor" \
  -d "vetor=ampl_dns" -d "event_id=812"

{"status":"success","data":{"queued":true,"modo":"vetor","dst":"203.0.113.10"}}

POST/api/api.php?action=flow&operation=mitigate_clear

Remove mitigações ativas (retira o anúncio BGP). Também é enfileirada para o coletor.

Parâmetro	Tipo	Obrigatório	Descrição
`event_id`	inteiro	um dos dois	Retira as regras vinculadas ao evento (criadas pela mitigação automática) e zera o `mitigado` dele. Regras disparadas pelo `mitigate` da API não ficam vinculadas ao evento: para retirá-las, use `dst`.
`dst`	string	um dos dois	Retira todas as regras ativas para o destino (IP ou CIDR).

Se enviar os dois parâmetros, o coletor usa apenas o event_id e ignora o dst. Para limpar um destino avulso, envie somente dst.

Erros: 400 Provide event_id and/or dst; 500 Failed to enqueue clear command.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=mitigate_clear" -d "dst=203.0.113.10"

{"status":"success","data":{"queued":true}}

POST/api/api.php?action=flow&operation=event_resolve

Marca um evento como resolvido (status=resolvido e fim = agora). Não remove mitigações: se houver, use mitigate_clear antes ou depois.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id do evento.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=event_resolve" -d "id=812"

{"status":"success","data":{"id":812,"status":"resolvido"}}

POST/api/api.php?action=flow&operation=event_false_positive

Marca um evento como falso-positivo: resolve o evento (com mitigado=0) e, se o alvo for um IP puro (não CIDR), adiciona esse IP automaticamente à allowlist com escopo dst_ip. A detecção passa a ignorar aquele destino. A exceção criada é gravada com origem auto, o que permite distingui-la das entradas manuais ao consultar operation=allowlist.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id do evento.

Quando o alvo do evento era um CIDR (carpet bombing), a resposta traz allowlist_added:null; nesse caso, avalie usar allowlist_add com escopo dst_prefixo. Erros: 400 Please provide a valid event id; 404 Event not found.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=event_false_positive" -d "id=812"

{"status":"success","data":{"id":812,"status":"resolvido","allowlist_added":"203.0.113.10"}}

POST/api/api.php?action=flow&operation=anomaly_resolve

Marca uma anomalia de baseline como resolvida.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id da anomalia.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=anomaly_resolve" -d "id=45"

{"status":"success","data":{"id":45,"status":"resolvida"}}

POST/api/api.php?action=flow&operation=prefix_add

Adiciona um prefixo monitorado. É um upsert: se o CIDR já existe, atualiza nome e cliente e reativa o registro.

Parâmetro	Tipo	Obrigatório	Descrição
`cidr`	string	sim	CIDR ou IP puro (IPv4 ou IPv6).
`nome`	string	não	Rótulo do bloco.
`cliente`	string	não	Nome do cliente dono do bloco.

Erro: 400 Invalid CIDR/IP.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=prefix_add" -d "cidr=203.0.113.0/24" -d "nome=Bloco clientes"

{"status":"success","data":{"cidr":"203.0.113.0/24"}}

POST/api/api.php?action=flow&operation=prefix_del

Remove um prefixo monitorado. Idempotente: responde deleted:true mesmo se nada correspondeu.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	um dos dois	Id do prefixo.
`cidr`	string	um dos dois	CIDR exato.

Erro: 400 Provide id or cidr.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=prefix_del" -d "cidr=203.0.113.0/24"

{"status":"success","data":{"deleted":true}}

POST/api/api.php?action=flow&operation=detection_toggle

Liga ou desliga uma regra de detecção. Use operation=detections para descobrir os ids.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id da regra.
`ativo`	inteiro	sim	`0` ou `1`.

Erros: 400 Please provide a valid detection id / Provide ativo=0|1.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=detection_toggle" -d "id=3" -d "ativo=0"

{"status":"success","data":{"id":3,"ativo":0}}

POST/api/api.php?action=flow&operation=whitelist_add

Protege um prefixo da mitigação automática (upsert; reativa se já existir). Uso típico: blocos de infraestrutura crítica, como DNS e gateways, que jamais podem tomar blackhole automático. Não impede mitigação manual ou via API.

Parâmetro	Tipo	Obrigatório	Descrição
`cidr`	string	sim	CIDR ou IP.
`nome`	string	não	Rótulo.

Erro: 400 Invalid CIDR/IP quando cidr não é um IP nem um CIDR válido (IPv4 ou IPv6).

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=whitelist_add" -d "cidr=198.51.100.0/24" -d "nome=Infra DNS"

{"status":"success","data":{"cidr":"198.51.100.0/24"}}

POST/api/api.php?action=flow&operation=whitelist_del

Remove um prefixo da whitelist de mitigação. Idempotente (deleted:true mesmo sem correspondência).

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	um dos dois	Id do registro.
`cidr`	string	um dos dois	CIDR exato.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=whitelist_del" -d "cidr=198.51.100.0/24"

{"status":"success","data":{"deleted":true}}

POST/api/api.php?action=flow&operation=allowlist_add

Adiciona uma exceção de detecção (anti falso-positivo). Upsert com origem=manual.

Parâmetro	Tipo	Obrigatório	Descrição
`escopo`	string	sim	`src_asn`, `src_prefixo`, `dst_ip` ou `dst_prefixo`.
`valor`	string	sim	ASN, prefixo ou IP conforme o escopo.
`motivo`	string	não	Texto livre, para auditoria.

Erros: 400 Invalid escopo (src_asn|src_prefixo|dst_ip|dst_prefixo) / Provide valor.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=allowlist_add" -d "escopo=src_asn" -d "valor=15169" -d "motivo=CDN conhecida"

{"status":"success","data":{"escopo":"src_asn","valor":"15169"}}

POST/api/api.php?action=flow&operation=allowlist_del

Remove uma exceção de detecção. Aceita apenas o id (não remove por valor). Idempotente.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id da exceção (ver `allowlist`).

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=allowlist_del" -d "id=7"

{"status":"success","data":{"deleted":true}}

POST/api/api.php?action=flow&operation=exporter_toggle

Ativa ou desativa um exportador. Desativar faz o coletor ignorar os fluxos daquele roteador; não altera a configuração do equipamento.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id do exportador.
`ativo`	inteiro	sim	`0` ou `1`.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=exporter_toggle" -d "id=1" -d "ativo=0"

{"status":"success","data":{"id":1,"ativo":0}}

POST/api/api.php?action=flow&operation=maintenance_add

Cria uma janela de manutenção. Durante a janela, detecção e alertas do escopo ficam silenciados. A janela é gravada com criado_por=API e ativa=1.

Parâmetro	Tipo	Obrigatório	Descrição
`inicio`	datetime	não	`YYYY-MM-DD HH:MM:SS`; vazio = agora.
`fim`	datetime	condicional	Obrigatório se `indefinida` não for 1.
`indefinida`	inteiro	não	`1` = sem fim (até encerrar manualmente); ignora `fim`.
`escopo`	string	não	`global` (padrão) ou `exportador`.
`exportador_id`	inteiro	condicional	Necessário quando `escopo=exportador`.
`motivo`	string	não	Texto exibido na interface.

Janela com indefinida=1 silencia a detecção até alguém encerrá-la com maintenance_end. Não esqueça janelas abertas: o ambiente fica cego a ataques no escopo silenciado.

Erro: 400 Provide fim or set indefinida=1.

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=maintenance_add" -d "fim=2026-07-04 02:00:00" \
  -d "escopo=exportador" -d "exportador_id=1" -d "motivo=Troca de uplink"

{"status":"success","data":{"created":true}}

POST/api/api.php?action=flow&operation=maintenance_end

Encerra uma janela de manutenção. A detecção e os alertas voltam ao normal no escopo.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	inteiro	sim	Id da janela (ver `maintenance`).

exemplo

curl -X POST "https://SEU-RAVI/api/api.php" -d "token=CHAVE" -d "action=flow" \
  -d "operation=maintenance_end" -d "id=7"

{"status":"success","data":{"id":7,"ativa":0}}

Exemplos práticos

Monitorar eventos de ataque (polling incremental)

Consulte events com since_id guardando o maior id já processado. Assim nenhum evento é duplicado nem perdido, mesmo com intervalos irregulares.

# novos eventos desde o id 812, só ativos/mitigando
curl -s -X POST "https://SEU-RAVI/api/api.php" \
  -d "token=CHAVE" -d "action=flow" -d "operation=events" \
  -d "status=ativos" -d "since_id=812"

<?php
$base = 'https://SEU-RAVI/api/api.php';
$ultimoId = 812; // persistir entre execuções
$resp = file_get_contents($base . '?' . http_build_query([
    'token' => 'CHAVE', 'action' => 'flow', 'operation' => 'events',
    'status' => 'ativos', 'since_id' => $ultimoId,
]));
$json = json_decode($resp, true);
if (($json['status'] ?? '') === 'success') {
    foreach ($json['data']['events'] as $ev) {
        printf("Evento %d %s em %s (%s)\n",
            $ev['id'], $ev['vetor'], $ev['dst_ip'], $ev['severidade']);
        $ultimoId = max($ultimoId, $ev['id']);
    }
}

import requests

BASE = "https://SEU-RAVI/api/api.php"
ultimo_id = 812  # persistir entre execuções
r = requests.post(BASE, data={
    "token": "CHAVE", "action": "flow", "operation": "events",
    "status": "ativos", "since_id": ultimo_id,
}, timeout=15)
j = r.json()
if j.get("status") == "success":
    for ev in j["data"]["events"]:
        print(f"Evento {ev['id']} {ev['vetor']} em {ev['dst_ip']} ({ev['severidade']})")
        ultimo_id = max(ultimo_id, ev["id"])

Mitigar um ataque e confirmar a regra

O fluxo recomendado: disparar a mitigação por vetor vinculada ao evento, aguardar cerca de 2 segundos e confirmar em mitigations que a regra ficou active.

# 1) dispara FlowSpec cirurgico para amplificacao DNS
curl -s -X POST "https://SEU-RAVI/api/api.php" \
  -d "token=CHAVE" -d "action=flow" -d "operation=mitigate" \
  -d "dst=203.0.113.10" -d "modo=vetor" -d "vetor=ampl_dns" -d "event_id=812"

# 2) ~2 s depois, confirma a regra ativa
curl -s "https://SEU-RAVI/api/api.php?token=CHAVE&action=flow&operation=mitigations"

# 3) ao fim do ataque, retira o anuncio (via API nao expira sozinho)
curl -s -X POST "https://SEU-RAVI/api/api.php" \
  -d "token=CHAVE" -d "action=flow" -d "operation=mitigate_clear" -d "dst=203.0.113.10"

<?php
function flow(array $params): array {
    $params += ['token' => 'CHAVE', 'action' => 'flow'];
    $ctx = stream_context_create(['http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/x-www-form-urlencoded',
        'content' => http_build_query($params),
    ]]);
    return json_decode(file_get_contents('https://SEU-RAVI/api/api.php', false, $ctx), true);
}

$r = flow(['operation' => 'mitigate', 'dst' => '203.0.113.10',
           'modo' => 'vetor', 'vetor' => 'ampl_dns', 'event_id' => 812]);
if (($r['data']['queued'] ?? false) !== true) { exit("falhou\n"); }

sleep(2); // aguarda o coletor processar a fila
$m = flow(['operation' => 'mitigations']);
foreach ($m['data']['mitigations'] as $regra) {
    if ($regra['dst_ip'] === '203.0.113.10' && $regra['status'] === 'active') {
        echo "Mitigacao ativa (id {$regra['id']})\n";
    }
}

import time, requests

BASE = "https://SEU-RAVI/api/api.php"

def flow(**params):
    params.update(token="CHAVE", action="flow")
    return requests.post(BASE, data=params, timeout=15).json()

r = flow(operation="mitigate", dst="203.0.113.10",
         modo="vetor", vetor="ampl_dns", event_id=812)
assert r["data"]["queued"] is True

time.sleep(2)  # aguarda o coletor processar a fila
m = flow(operation="mitigations")
ativa = [x for x in m["data"]["mitigations"]
         if x["dst_ip"] == "203.0.113.10" and x["status"] == "active"]
print("Mitigacao ativa" if ativa else "Regra nao apareceu: verificar peers BGP")

# ao fim do ataque:
flow(operation="mitigate_clear", dst="203.0.113.10")

Silenciar a detecção durante uma janela de mudança

terminal

# abre janela de 2h para o exportador 1
curl -s -X POST "https://SEU-RAVI/api/api.php" \
  -d "token=CHAVE" -d "action=flow" -d "operation=maintenance_add" \
  -d "fim=2026-07-04 02:00:00" -d "escopo=exportador" -d "exportador_id=1" \
  -d "motivo=Janela de mudanca programada"

# se terminar antes, encerra pela lista (operation=maintenance para achar o id)
curl -s -X POST "https://SEU-RAVI/api/api.php" \
  -d "token=CHAVE" -d "action=flow" -d "operation=maintenance_end" -d "id=7"

Boas práticas de polling: overview, live e top leem um snapshot leve do coletor e são baratos; intervalos de 5 a 10 segundos já acompanham o ritmo do coletor. Para eventos, use sempre since_id. Limites de listagem: events até 1000 por chamada; anomalies e mitigations até 500; alertas BGP e maintenance até 200; sources do evento até 200.

Solução de problemas

Sintoma	Causa provável e o que fazer
403 `Access denied for flow`	Chave sem a permissão Acesso a Flow. Edite a chave (dentro da janela de 2 horas) ou crie outra com a permissão marcada.
`collector_online:false` em tudo	Coletor parado ou ambiente Flow não configurado naquele servidor. Verifique a tela do Flow; a API não substitui a configuração inicial pela interface.
Exportador listado com `sem_fluxo:true`	O roteador parou de exportar: configuração perdida, firewall bloqueando as portas UDP de export (2055, 4739, 9995, 9996, 6343) ou equipamento reiniciado.
`mitigate` retorna `queued:true` mas nada acontece	Nenhum peer BGP de mitigação ativo ou sessão BGP caída. Confira o campo `status` em `peers` e depois `mitigations`. A falha é silenciosa: a API não devolve erro nesse caso.
Mitigação nunca "sai" sozinha	Comportamento esperado: mitigações via API não têm TTL. Remova com `mitigate_clear`. O TTL automático (`mitig_ttl_seg`, padrão 1800 s) vale só para as mitigações automáticas.
`mitigate_clear` com `dst` não limpou	Foi enviado junto um `event_id`: o coletor prioriza o evento e ignora o `dst`. Reenvie somente com `dst`.
Whitelist "não funcionou" contra mitigação da API	Comportamento esperado: a whitelist bloqueia apenas a mitigação automática, não a manual nem a via API.
`event_false_positive` não adicionou à allowlist	O alvo do evento era um CIDR (carpet bombing): `allowlist_added` vem `null`. Adicione manualmente com `allowlist_add` e escopo `dst_prefixo`.
Eventos duplicados no polling	Use `since_id` com o maior `id` já processado, em vez de filtrar por data.
Números gigantes no `top`	São bytes acumulados no bucket de 60 segundos, não bits por segundo. Para taxas, use `live`.
`drops_canal`/`drops_kernel` crescendo no `health`	Coletor saturado por CPU ou volume de fluxos. `rollup_lag_sec` alto indica banco lento.

Autenticação da APIToken, endpoint único e ordem de validação do gateway. Criar uma chave de APIPasso a passo na interface e janela de cópia de 2 horas. Mitigação de ataques na interfaceFlowSpec, RTBH e aprovação em 1 clique.

← Anterior API de Dispositivos Próximo → API de DNS