Guia público de integração

API do +CORE DNS

Configure coleta autorizada em Prometheus, Grafana e Zabbix, consulte amostras JSON e mantenha cada credencial limitada à sua finalidade.

Este site é a documentação, não é o endereço da API.

As requisições devem usar a URL HTTPS de gerência do próprio appliance, com certificado válido e acesso permitido somente pela rede de gerência autorizada.

Endpoints

Mapa de acesso e responsabilidade

Cada recurso tem uma chave própria, gerada no painel indicado. As credenciais não são intercambiáveis e o recurso precisa existir na versão instalada.

Método e endpointSeção no painelChave necessáriaFinalidadeResposta
GET/api/v1/monitoring/metrics Sistema > Monitoramento > Gerar chave Monitoramento agregado Coleta de métricas pelo Prometheus. Texto Prometheus
GET/api/v1/monitoring/snapshot Sistema > Monitoramento > Gerar chave Monitoramento agregado Amostra agregada para Zabbix e integrações JSON. JSON
GET/api/v1/monitoring/ip-details Sistema > Monitoramento > Consulta de IPs Consulta de IPs Candidatos recentes e medidas registradas como vigentes. JSON restrito
GET/api/v1/monitoring/dns-protect/events Sistema > Monitoramento > Eventos do DNS Protect Eventos do DNS Protect Eventos exportáveis da amostra mais recente. JSON restrito
GET/api/v1/dns-mitigation/status Protect > Mitigação DNS > API de Mitigação DNS Mitigação DNS Consulta do estado da API de mitigação. JSON de estado
A chave de mitigação exige cuidado adicional.

Ela pode autorizar mudanças de configuração. Este guia documenta somente a consulta GET de estado. Para coleta, prefira a chave de monitoramento agregado e não habilite a chave de mitigação quando os indicadores agregados forem suficientes.

Acesso

Geração e ciclo de vida das chaves

A integração parte do appliance. O administrador do cliente gera a chave no painel e configura o coletor dentro da rede autorizada.

  1. 01
    Confirme a versão e a seção no painel.

    Se a seção não existir, o endpoint ainda não está disponível nessa instalação.

  2. 02
    Use a URL HTTPS de gerência.

    O certificado e o nome do host devem ser válidos. Não desative a validação TLS.

  3. 03
    Gere a chave correta.

    A chave aparece uma única vez. Guarde-a imediatamente em um cofre de segredos.

  4. 04
    Envie pelo cabeçalho.

    Use Authorization: Bearer SUA_CHAVE. Nunca coloque a chave na URL, em query string, dashboard ou chamado.

  5. 05
    Rotacione de forma coordenada.

    Gerar outra chave invalida a anterior. Atualize o cofre e o coletor antes da próxima coleta.

  6. 06
    Revogue quando não houver mais uso.

    A revogação encerra o acesso da integração sem interromper o serviço DNS.

Validação inicial

Um teste de leitura por endpoint

Troque apenas o host e a chave fictícios. Os exemplos mantêm a validação do certificado e não enviam credenciais na URL.

Métricas Prometheus

curl -fsS \
  -H 'Authorization: Bearer CHAVE_MONITORAMENTO' \
  'https://dns01.exemplo.net/api/v1/monitoring/metrics'

Snapshot agregado

curl -fsS \
  -H 'Authorization: Bearer CHAVE_MONITORAMENTO' \
  'https://dns01.exemplo.net/api/v1/monitoring/snapshot'

Consulta de IPs

curl -fsS \
  -H 'Authorization: Bearer CHAVE_CONSULTA_IPS' \
  'https://dns01.exemplo.net/api/v1/monitoring/ip-details'

Eventos do DNS Protect

curl -fsS \
  -H 'Authorization: Bearer CHAVE_EVENTOS' \
  'https://dns01.exemplo.net/api/v1/monitoring/dns-protect/events'

Estado da mitigação DNS

curl -fsS \
  -H 'Authorization: Bearer CHAVE_MITIGACAO' \
  'https://dns01.exemplo.net/api/v1/dns-mitigation/status'

Prometheus e Grafana

Coleta agregada sem expor a credencial

Crie um job por appliance, com arquivo de credencial protegido. O Grafana consulta o Prometheus; ele não deve apontar diretamente para o appliance.

Job completo

scrape_configs:
  - job_name: core-dns-01
    scheme: https
    metrics_path: /api/v1/monitoring/metrics
    scrape_interval: 60s
    scrape_timeout: 12s
    follow_redirects: false
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/secrets/core-dns-01.token
    static_configs:
      - targets: ["dns01.exemplo.net:443"]
    # Para CA privada, instale a confiança e use:
    # tls_config:
    #   ca_file: /etc/prometheus/ca-gerencia.pem

Validação

  1. O arquivo indicado em credentials_file contém somente a chave, sem a palavra Bearer.
  2. Execute promtool check config /etc/prometheus/prometheus.yml.
  3. Recarregue o Prometheus e confirme o alvo UP.
  4. No Grafana, adicione a URL do servidor Prometheus como datasource.
UP indica acesso ao coletor.A saúde da resolução deve ser avaliada pelas métricas específicas, não apenas pelo estado do alvo.
IndicadorPromQL
Coletor consegue lerup{job="core-dns-01"}
CPUcore_dns_cpu_usage_percent
Memóriacore_dns_memory_usage_percent
Tráfego recebido8 * rate(core_dns_network_rx_bytes_total[5m])
Tráfego enviado8 * rate(core_dns_network_tx_bytes_total[5m])
Erros e descartesrate(core_dns_network_rx_errors_total[5m]) e rate(core_dns_network_rx_dropped_total[5m]); use também as séries tx.
DNS Protectcore_dns_protect_events, core_dns_protect_category_events, core_dns_protect_max_score
Botnet / suspeitoscore_dns_suspicious_clients, core_dns_suspicious_max_score
Mitigaçãocore_dns_mitigation_active, core_dns_mitigation_min_score, core_dns_mitigation_min_qps, rate(core_dns_mitigation_packets_total[5m])
Resolução IPv6/UDP com DNSSECcore_dns_resolution_success{family="ipv6",transport="udp",test="valid"}
Latência da resolução1000 * core_dns_resolution_duration_seconds{test="valid"}
Fonte ausente ou atrasadacore_dns_collection_available == 0 e core_dns_collection_stale == 1

Zabbix

Um item mestre, vários itens dependentes

O item mestre realiza uma única requisição por minuto. Os itens dependentes extraem os valores do mesmo JSON e não geram novas chamadas ao appliance.

Macros do host

{$COREDNS.URL}
URL HTTPS de gerência, sem barra final.
{$COREDNS.TOKEN}
Macro secreta com a chave de monitoramento.

Item mestre HTTP agent

Chave
coredns.snapshot
URL
{$COREDNS.URL}/api/v1/monitoring/snapshot
Método / tipo
GET / Text
Intervalo / timeout
1m / 12s
Resposta
Body, código esperado 200, sem redirecionamento.
Cabeçalho
Authorization: Bearer {$COREDNS.TOKEN}
TLS
Verificar certificado e nome do host.

Teste o item mestre e confirme schema_version: 1 e observed_at. Depois crie os itens dependentes:

IndicadorJSONPathTipo final
CPU$.cpu.usage_percentDecimal, %
Memória disponível$.memory.available_bytesSem sinal, B
Uso de memória$.memory.usage_percentDecimal, %
Interface de exemplo$.interfaces.items[?(@.name == 'eth0')].rx_bytes_total.first()Sem sinal, B
DNS Protect, eventos$.dns_protect.event_countSem sinal
DNS Protect, ANY$.dns_protect.categories.anySem sinal
Botnet / suspeitos$.suspicious.client_countSem sinal
Mitigações ativas$.mitigation.active_countSem sinal
Score mínimo$.mitigation.min_scoreSem sinal
Mitigação automática$.mitigation.auto_enabledBoolean to decimal
Resolução IPv4/UDP$.resolution.checks[?(@.family == 'ipv4' && @.transport == 'udp' && @.test == 'valid')].success.first()Boolean to decimal
Latência IPv4/UDP$.resolution.checks[?(@.family == 'ipv4' && @.transport == 'udp' && @.test == 'valid')].latency_ms.first()Decimal, ms
DNS Protect atrasado$.dns_protect.staleBoolean to decimal
Suspeitos disponível$.suspicious.availableBoolean to decimal
Ausência não é zero.

Para números opcionais, valide com ^[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?$ e use Custom on fail > Discard value. Crie alertas separados para nodata, fonte atrasada e falha de resolução.

Coletores JSON restritos

Eventos do DNS Protect e consulta de IPs

Use coletores e chaves separados. Esses dados permanecem restritos ao NOC autorizado e nunca devem virar rótulos de métricas ou painéis públicos.

Versões compatíveis

Eventos do DNS Protect

/api/v1/monitoring/dns-protect/events
  • Até 100 linhas da amostra mais recente.
  • Sem histórico e sem paginação.
  • Não exporta nomes consultados nem ações de mitigação.
  • available: true com total: 0 significa amostra válida sem eventos exportáveis.
  • Amostra ausente ou antiga retorna available: false, total: null e items: [].
{
  "schema_version": 1,
  "generated_at": "2026-01-15T12:00:00+00:00",
  "age_seconds": 8,
  "available": true,
  "stale": false,
  "total": 1,
  "truncated": false,
  "items": [{
    "source_ip": "192.0.2.80",
    "destination_ip": "198.51.100.53",
    "categories": ["any", "random_subdomain"],
    "severity": "critical",
    "score": 95,
    "qps": 142.5,
    "queries": 285,
    "unique_names": 220,
    "unique_percent": 77.2,
    "qtypes": {"ANY": 270, "TXT": 15},
    "transports": {"UDP": 285}
  }]
}
Uso restrito

Consulta de IPs

/api/v1/monitoring/ip-details
  • Até 50 candidatos e 50 medidas vigentes.
  • Sem histórico; suspeita não significa bloqueio.
  • total: null indica fonte indisponível ou amostra antiga, não zero.
  • Endereços protegidos e domínios consultados não são exportados.
{
  "schema_version": 1,
  "collected_at": "2026-01-15T12:00:08+00:00",
  "candidates": {
    "available": true,
    "total": 1,
    "truncated": false,
    "items": [{
      "ip": "2001:db8::42",
      "score": 70,
      "qps": 2.5,
      "reasons": ["volume_consultas"]
    }],
    "generated_at": "2026-01-15T12:00:00+00:00",
    "stale": false
  },
  "mitigations": {
    "available": true,
    "total": 1,
    "truncated": false,
    "items": [{
      "ip": "192.0.2.42",
      "mode": "limit",
      "added_at": "2026-01-15T11:55:00+00:00",
      "expires_at": "2026-01-15T12:15:00+00:00"
    }]
  }
}

Zabbix restrito

Itens mestres e macros separados

Reutilize intervalo de 1 minuto, timeout de 12 segundos, resposta esperada 200, validação de certificado e nome do host e a opção de não seguir redirecionamentos.

Eventos do DNS Protect

Macro secreta
{$COREDNS.EVENTS_TOKEN}
Chave do item mestre
coredns.dns_protect.events
URL
{$COREDNS.URL}/api/v1/monitoring/dns-protect/events
Cabeçalho
Authorization: Bearer {$COREDNS.EVENTS_TOKEN}

Itens dependentes sugeridos

  • $.total — total exportável; descarte se for nulo.
  • $.available — use Boolean to decimal.
  • $.stale — use Boolean to decimal.

Consulta de IPs

Macro secreta
{$COREDNS.IP_TOKEN}
Chave do item mestre
coredns.ip_details
URL
{$COREDNS.URL}/api/v1/monitoring/ip-details
Cabeçalho
Authorization: Bearer {$COREDNS.IP_TOKEN}

Itens dependentes sugeridos

  • $.candidates.total — total recente; descarte se for nulo.
  • $.mitigations.total — medidas registradas como vigentes.

Histórico controlado

Se precisar de histórico, armazene cada amostra uma única vez por appliance e horário de geração, com retenção e acesso definidos pela sua política interna.

Zabbix separado

Crie um item mestre HTTP agent para cada endpoint, usando a macro secreta da chave correspondente. Não reutilize a chave agregada.

Disponibilidade

Eventos do DNS Protect são liberados somente em versões compatíveis. O cliente ainda precisa gerar a chave e configurar o próprio coletor.

Respostas HTTP

Como interpretar falhas de integração

Leia o código antes de repetir a chamada. Tentativas rápidas em sequência não corrigem chave, rede ou versão e podem dificultar o diagnóstico.

200

Leitura aceita. Ainda verifique available, stale e valores nulos. No estado da mitigação, confirme também ok: true.

400

Requisição inválida, inclusive parâmetros não aceitos. Não envie a chave em query string.

401

Chave ausente, incorreta, rotacionada ou revogada.

403

Use HTTPS e confirme se a origem está na rede de gerência autorizada.

404

Endpoint não disponível na versão instalada ou caminho incorreto.

405

Método não permitido. Os endpoints deste guia usam somente GET.

503

A amostra ainda não está pronta. Aguarde o próximo ciclo de coleta.

Checklist de segurança

Antes de ativar a coleta

O monitoramento deve ampliar a visibilidade sem transformar credenciais ou dados restritos em nova superfície de exposição.

01

URL HTTPS de gerência com certificado e nome do host validados.

02

Acesso limitado à rede autorizada e aos coletores necessários.

03

Uma chave por finalidade, armazenada em cofre ou macro secreta.

04

Coleta a cada 60 segundos, timeout de 12 segundos e sem redirecionamentos.

05

Rotação e revogação registradas, sem colocar a chave em URL, log ou chamado.

06

IPs restritos fora de rótulos de métricas, dashboards públicos e compartilhamentos entre clientes.

Suporte técnico

Precisa validar a integração?

Informe a versão instalada, o endpoint consultado e o código HTTP, sem enviar a credencial.

Falar com o NOC