API Flow - Monitoramento e Mitigação de DDoS

Visão Geral

A API Flow expõe o ambiente Flow do Ravi Monitor (coleta NetFlow/IPFIX/sFlow, detecção e mitigação de DDoS). Permite acompanhar tudo (tráfego em tempo real, eventos/ataques, anomalias, saúde do coletor, enriquecimento BGP, mitigações ativas e configuração) e gerenciar tudo (disparar/remover mitigação, resolver eventos, prefixos monitorados, whitelist/allowlist, regras de detecção, janelas de manutenção e mais) — sem abrir a interface.

Configuração Prévia

⚠️ IMPORTANTE:

O token precisa da permissão Acesso a Flow (Configurações → Integrações → Gerenciamento de Chave API).
O ambiente Flow deve estar configurado (ao menos um exportador cadastrado e o coletor ravi-flow em execução). Use operation=overview para confirmar collector_online.

Parâmetros Base

Todas as operações Flow requerem:

action=flow
operation: Operação específica
token: Token com permissão flow

Os parâmetros são aceitos via GET ou POST.

Formato de Resposta

Atenção: diferente das APIs OLT/DNS/WhatsApp (que devolvem {"msg": ...}), a API Flow usa um envelope padronizado:

Sucesso

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

Erro

{
  "status": "error",
  "message": "Invalid Flow operation"
}

Sempre verifique status antes de ler data. Erros comuns: Token not provided (400), Invalid token (401), Access denied for flow (403 — o token não tem a permissão Flow), Please provide a valid operation (400).

Operações de Monitoramento (leitura)

1. overview - Resumo do ambiente

Indicadores gerais: estado do coletor, tráfego agregado e contadores (exportadores, prefixos, eventos, anomalias, mitigações, alertas BGP).

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=flow" \
  -d "operation=overview"

Resposta

{
  "status": "success",
  "data": {
    "collector_online": true,
    "collector_version": "1.0.0",
    "snapshot_age_sec": 2,
    "flows_per_sec": 1488,
    "total_in_bps": 24393479106,
    "total_out_bps": 24393479007,
    "exporters_total": 5,
    "exporters_active": 5,
    "prefixes_monitored": 8,
    "events_active": 0,
    "events_mitigating": 0,
    "anomalies_active": 1,
    "mitigations_active": 0,
    "bgp_alerts_open": 0,
    "bgp_rib": { "ativa": true, "v4": 0, "v6": 0, "built_at": 1782167047 }
  }
}

2. live - Tráfego em tempo real

Snapshot ao vivo do coletor: tráfego por exportador e por interface (bps/pps + capacidade), além do top-N (ASN/proto/país) e top por exportador. Exportadores cadastrados sem fluxo aparecem com sem_fluxo: true.

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=flow" \
  -d "operation=live"

Resposta (resumida)

{
  "status": "success",
  "data": {
    "collector_online": true,
    "flows_per_sec": 1488,
    "total_in_bps": 24393479106,
    "total_out_bps": 24393479007,
    "exporters": [
      {
        "id": 30, "nome": "NE-8000-JONNY",
        "total_in_bps": 12000000000, "total_out_bps": 11000000000,
        "interfaces": [
          { "if_index": 12, "nome": "Uplink-Transito", "in_bps": 8000000000, "out_bps": 1000000, "in_pps": 900000, "out_pps": 1200, "cap_bps": 100000000000 }
        ],
        "top": { }
      }
    ],
    "top": { "dst_as": [], "proto": [], "dst_pais": [] }
  }
}

3. health - Saúde do coletor

Self-health: idade do snapshot, fps/pps, bloco health do coletor (drops de canal/kernel, RSS/heap/goroutines, RIB), lag do rollup e tamanho das tabelas flow_*.

Exemplo

curl ... -d "action=flow" -d "operation=health"

4. exporters - Exportadores cadastrados

Lista as fontes de fluxo (NetFlow/IPFIX/sFlow) com modelo, versão, sampling, ASN e estado.

curl ... -d "action=flow" -d "operation=exporters"

5. interfaces - Interfaces

Interfaces conhecidas (via SNMP). Opcional: filtrar por exportador.

Parâmetros Opcionais

exporter_id: ID do exportador

curl ... -d "action=flow" -d "operation=interfaces" -d "exporter_id=30"

6. prefixes - Prefixos monitorados

Lista os CIDRs monitorados (flow_prefixos).

curl ... -d "action=flow" -d "operation=prefixes"

7. events - Eventos / ataques

Lista os eventos de detecção. Por padrão, os mais recentes (até 100).

Parâmetros Opcionais

status: ativo, mitigando, resolvido ou ativos (atalho para ativo+mitigando)
severity: info, warning, critical
exporter_id: filtra por exportador
since_id: retorna apenas eventos com id maior (polling incremental)
limit: máximo de registros (1–1000, padrão 100)

curl ... -d "action=flow" -d "operation=events" -d "status=ativos" -d "severity=critical" -d "limit=50"

8. event - Detalhe de um evento

Detalhe completo de um evento + as origens do ataque (src_ip, ASN, packets, país, cidade).

Parâmetros Obrigatórios

id: ID do evento

curl ... -d "action=flow" -d "operation=event" -d "id=484"

9. anomalies - Anomalias de baseline

Lista anomalias (desvio sazonal). Opcional status = ativa | resolvida.

curl ... -d "action=flow" -d "operation=anomalies" -d "status=ativa"

10. detections - Regras de detecção

Lista as regras de detecção (flow_deteccao): escopo, assinatura, limiares, severidade e auto-mitigação.

curl ... -d "action=flow" -d "operation=detections"

11. mitigations - Mitigações

Lista as regras de mitigação (FlowSpec/RTBH). Opcional status = active | withdrawn | expired (padrão active).

curl ... -d "action=flow" -d "operation=mitigations" -d "status=active"

12. whitelist - Prefixos protegidos

Prefixos protegidos da auto-mitigação (flow_mitig_whitelist).

curl ... -d "action=flow" -d "operation=whitelist"

13. allowlist - Exceções de detecção

Exceções anti-falso-positivo (flow_allowlist).

curl ... -d "action=flow" -d "operation=allowlist"

14. peers - Peers BGP

Peers de mitigação (anúncio FlowSpec/RTBH) e peers de coleta de rota (enriquecimento da RIB).

curl ... -d "action=flow" -d "operation=peers"

15. bgp - Estado do BGP/RIB

Estado da coleta de rota: flag collection_active, RIB do snapshot, peers de rota e alertas de roteamento (origin change / sub-prefix hijack).

curl ... -d "action=flow" -d "operation=bgp"

16. templates - Templates de FlowSpec

Lista os templates de FlowSpec (flow_flowspec_templates).

curl ... -d "action=flow" -d "operation=templates"

17. communities - Comunidades BGP

Catálogo de comunidades BGP (flow_communities).

curl ... -d "action=flow" -d "operation=communities"

18. holidays - Feriados

Feriados usados no baseline sazonal (flow_feriados).

curl ... -d "action=flow" -d "operation=holidays"

19. maintenance - Janelas de manutenção

Lista as janelas de manutenção/silêncio (flow_manutencao).

curl ... -d "action=flow" -d "operation=maintenance"

20. top - Top talkers

Top-N do snapshot ao vivo. Opcional dimension (ex.: dst_as, src_ip, proto, dst_pais) para retornar apenas uma dimensão.

curl ... -d "action=flow" -d "operation=top" -d "dimension=dst_as"

21. settings - Configurações

Configurações do Flow (flow_settings) em formato chave/valor.

curl ... -d "action=flow" -d "operation=settings"

Operações de Gerenciamento (escrita)

⚠️ As operações de mitigação atuam no plano de roteamento (anúncio BGP FlowSpec/RTBH). Use com critério — o coletor ravi-flow aplica o comando enfileirado.

22. mitigate - Disparar mitigação

Mitiga um destino sob ataque. O PHP não fala BGP diretamente: enfileira o comando para o daemon ravi-flow.

Parâmetros Obrigatórios

dst: IP (/32) ou CIDR (carpet bombing). Ex.: 192.0.2.10 ou 192.0.2.0/24

Parâmetros Opcionais

modo: vetor (FlowSpec cirúrgico, padrão) ou rtbh (blackhole do IP inteiro)
vetor: vetor do ataque para o FlowSpec (ex.: udp_flood, ampl_dns)
proto: número do protocolo IP (ex.: 17 = UDP)
port: porta
acao: discard (padrão) ou ratelimit
rate: bps quando acao=ratelimit
grupo_id: grupo de anúncio para direcionamento (0 = todos)
event_id: vincula a mitigação a um evento (marca o evento como mitigando)

Exemplo (FlowSpec por vetor)

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=flow" \
  -d "operation=mitigate" \
  -d "event_id=484" \
  -d "dst=192.0.2.10" \
  -d "modo=vetor" \
  -d "vetor=udp_flood" \
  -d "proto=17" \
  -d "acao=discard"

Exemplo (RTBH / blackhole)

curl ... -d "operation=mitigate" -d "dst=192.0.2.10" -d "modo=rtbh"

Resposta

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

23. mitigate_clear - Remover mitigação

Remove a mitigação por evento e/ou destino.

Parâmetros (ao menos um)

event_id: ID do evento
dst: IP ou CIDR

curl ... -d "action=flow" -d "operation=mitigate_clear" -d "event_id=484"

24. event_resolve - Resolver evento

Marca um evento como resolvido.

Parâmetros Obrigatórios

id: ID do evento

curl ... -d "action=flow" -d "operation=event_resolve" -d "id=484"

25. event_false_positive - Marcar falso-positivo

Resolve o evento e, quando o destino é um IP, adiciona-o à allowlist (origem auto) para reduzir reincidência.

Parâmetros Obrigatórios

id: ID do evento

curl ... -d "action=flow" -d "operation=event_false_positive" -d "id=484"

26. anomaly_resolve - Resolver anomalia

Marca uma anomalia como resolvida.

Parâmetros Obrigatórios

id: ID da anomalia

curl ... -d "action=flow" -d "operation=anomaly_resolve" -d "id=15"

27. prefix_add - Adicionar prefixo monitorado

Parâmetros Obrigatórios

cidr: CIDR ou IP (ex.: 203.0.113.0/24)

Parâmetros Opcionais

nome: rótulo
cliente: cliente associado

curl ... -d "action=flow" -d "operation=prefix_add" -d "cidr=203.0.113.0/24" -d "nome=Cliente-X"

28. prefix_del - Remover prefixo

Parâmetros (um deles)

id ou cidr

curl ... -d "action=flow" -d "operation=prefix_del" -d "cidr=203.0.113.0/24"

29. detection_toggle - Ativar/desativar regra de detecção

Parâmetros Obrigatórios

id: ID da regra
ativo: 1 (ativa) ou 0 (desativa)

curl ... -d "action=flow" -d "operation=detection_toggle" -d "id=22" -d "ativo=0"

30. whitelist_add - Proteger prefixo da auto-mitigação

Parâmetros Obrigatórios

cidr: CIDR ou IP

Parâmetros Opcionais

nome: rótulo

curl ... -d "action=flow" -d "operation=whitelist_add" -d "cidr=198.51.100.0/24" -d "nome=Core"

31. whitelist_del - Remover da whitelist

Parâmetros (um deles)

id ou cidr

curl ... -d "action=flow" -d "operation=whitelist_del" -d "cidr=198.51.100.0/24"

32. allowlist_add - Adicionar exceção de detecção

Parâmetros Obrigatórios

escopo: src_asn, src_prefixo, dst_ip ou dst_prefixo
valor: o valor conforme o escopo (ASN, CIDR ou IP)

Parâmetros Opcionais

motivo: justificativa

curl ... -d "action=flow" -d "operation=allowlist_add" -d "escopo=src_asn" -d "valor=15169" -d "motivo=Google"

33. allowlist_del - Remover exceção

Parâmetros Obrigatórios

id: ID da entrada

curl ... -d "action=flow" -d "operation=allowlist_del" -d "id=7"

34. exporter_toggle - Ativar/desativar exportador

Parâmetros Obrigatórios

id: ID do exportador
ativo: 1 ou 0

curl ... -d "action=flow" -d "operation=exporter_toggle" -d "id=30" -d "ativo=1"

35. maintenance_add - Criar janela de manutenção

Silencia alertas durante uma janela. Por padrão começa "agora".

Parâmetros Opcionais

inicio: YYYY-MM-DD HH:MM:SS (vazio = agora)
fim: YYYY-MM-DD HH:MM:SS (obrigatório se indefinida=0)
indefinida: 1 para janela sem fim (ignora fim)
escopo: global (padrão) ou exportador
exportador_id: necessário quando escopo=exportador
motivo: descrição

curl ... -d "action=flow" -d "operation=maintenance_add" \
  -d "fim=2026-06-23 04:00:00" -d "motivo=Janela de upgrade"

36. maintenance_end - Encerrar janela

Parâmetros Obrigatórios

id: ID da janela

curl ... -d "action=flow" -d "operation=maintenance_end" -d "id=3"

Exemplos Práticos

Script Shell

#!/bin/bash

TOKEN="seu_token_aqui"
API_URL="https://seu-servidor-ravi/api.php"

flow() {
    # $1 = operation, demais = pares chave=valor
    local op="$1"; shift
    local args=()
    for kv in "$@"; do args+=( -d "$kv" ); done
    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" -d "action=flow" -d "operation=$op" "${args[@]}"
}

# Estado geral
flow overview

# Ataques ativos
flow events "status=ativos" "limit=20"

# Mitigar um destino com FlowSpec por vetor
flow mitigate "event_id=484" "dst=192.0.2.10" "vetor=udp_flood" "acao=discard"

# Remover a mitigação
flow mitigate_clear "event_id=484"

Script PHP

<?php

/**
 * Chama a API Flow do Ravi Monitor.
 *
 * @param string $operation  Operação (overview, events, mitigate, ...)
 * @param array  $params     Parâmetros adicionais (chave => valor)
 * @return array             Resposta decodificada ({status, data|message})
 */
function raviFlow(string $operation, array $params = []): array {
    $token  = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = array_merge([
        'token'     => $token,
        'action'    => 'flow',
        'operation' => $operation,
    ], $params);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true) ?: ['status' => 'error', 'message' => 'sem resposta'];
}

// Uso
$r = raviFlow('overview');
if (($r['status'] ?? '') === 'success') {
    echo "Coletor online: " . var_export($r['data']['collector_online'], true) . "\n";
}

// Mitigar (RTBH)
$r = raviFlow('mitigate', ['dst' => '192.0.2.10', 'modo' => 'rtbh']);

?>

Códigos de Status / Erros

Mensagem	HTTP	Descrição
`status: success`	200	Operação concluída (ler `data`)
`Token not provided`	400	Falta `token`
`Action not provided`	400	Falta `action`
`Please provide a valid operation`	400	Falta `operation`
`Invalid Flow operation`	400	`operation` desconhecida
`Invalid token`	401	Token não encontrado
`Access denied for flow`	403	Token sem a permissão Flow
`Invalid dst (use IP or CIDR)`	400	`dst` inválido em `mitigate`
`Invalid CIDR/IP`	400	`cidr` inválido (prefixo/whitelist)
`Event not found`	404	`id` de evento inexistente
`Database error`	500	Falha ao gravar/ler

Limitações

O token precisa da permissão flow.
Mitigação depende do coletor ravi-flow em execução e dos peers BGP de mitigação configurados; o disparo é assíncrono (enfileirado).
events retorna no máximo 1000 registros por chamada; para histórico extenso, pagine com since_id.
Operações de leitura provider-wide (live, health, top) refletem o snapshot mais recente do coletor (/opt/Ravi/flow/live/live.json).

Nota: As operações de gerenciamento alteram o comportamento de detecção/mitigação em produção. Em automações, prefira validar antes com as operações de leitura (ex.: confirmar o event e o dst antes de mitigate).