Integração de APIs e Enriquecimento Automatizado

Nota 09 do capítulo 09 (Ferramentas e Plataformas), que fecha o capítulo tratando a integração programática com provedores externos de enriquecimento.
Cobre as APIs de referência, os padrões de integração, o controle de caching e rate limits e os riscos de OPSEC do enriquecimento automatizado.
Dialoga com a nota 08 deste capítulo (pipeline), com a nota 12 do capítulo 02 (automação de coleta via APIs) e com a nota 05 do capítulo 03 (contextualização e validação de indicadores).

1. Contexto e Posicionamento na Biblioteca

Um indicador bruto, um IP, um domínio, um hash, quase nunca vale nada sozinho; é o contexto em volta dele que transforma dado em inteligência. Esta nota trata da etapa em que esse contexto é obtido de forma programática: consultas automatizadas a provedores externos que respondem o que aquele IP já fez, quem registra aquele domínio, com que outros hosts aquele certificado já foi emitido. A nota 05 do capítulo 03 descreve a lógica analítica desse enriquecimento; aqui o foco é a engenharia da integração, de modo que ela seja rápida, barata, resiliente e discreta.

O capítulo 09 fecha com este tema porque a integração de APIs é o ponto onde pipeline, ferramentas e método se encontram. O lake da nota 08 persiste os resultados com proveniência; o Velociraptor da nota 07 produz os alvos a enriquecer; os analistas do capítulo 05 consomem o contexto nas análises de links e de infraestrutura. Enriquecimento mal feito cobra caro em três moedas: latência das consultas, fatura de API e exposição desnecessária de informação operacional para terceiros, e os três são tratados nas seções seguintes.

2. APIs de Enriquecimento e o que Cada Uma Acrescenta

A tabela concentra os provedores de referência usados nesta biblioteca, com o que cada um responde e a restrição prática dominante. Os limites de taxa citados são ordens de magnitude públicas e mudam; o desenho da integração nunca deve assumir um número fixo, mas sim ler os cabeçalhos de resposta e reagir.

A regra de seleção é a pergunta analítica primeiro, o provedor depois. Para análise de infraestrutura do capítulo 05, passive DNS, WHOIS e CT logs carregam o trabalho de agrupamento; para triagem de alerta, reputação de IP e multi-engine de arquivo resolvem 80 por cento dos casos; para superexposição e IOE, o Shodan responde o que o adversário enxerga da sua superfície. Enriquecer tudo com todos é desperdício, e o orçamento de API é recurso de análise, não taxinha de conveniência.

3. Padrões de Integração: Enriquecer na Ingestão ou na Consulta

A decisão de desenho mais importante é quando enriquecer. O enriquecimento na ingestão decora cada indicador no momento em que entra no pipeline, e o resultado passa a estar sempre disponível para consulta; o enriquecimento na consulta chama a API só quando alguém precisa do atributo, e o custo segue o uso real. Os dois padrões podem coexistir, com enriquecimento barato e estável na ingestão e enriquecimento caro e volátil na consulta.

A regra prática desta biblioteca é enriquecer na consulta por padrão e mover para a ingestão apenas atributos baratos, estáveis e de demanda transversal, como geolocalização e ASN. E existe uma exceção de método que vira regra: hashes de amostra obtidos em resposta a incidente nunca devem ser consultados em sandboxes públicas antes da triagem interna, porque a submissão ou a busca pode alertar o operador da amostra; nesse caso, o enriquecimento só acontece com o alvo já decidido como público para consulta.

4. Caching, Rate Limits e Resiliência

O cache é a peça que sustenta as duas metades do problema: economiza quota e reduz latência. O desenho canônico usa chave composta por provedor, alvo e janela temporal, de modo que o TTL reflita a estabilidade do atributo: reputação de IP vale horas, WHOIS de domínio vale semanas, passive DNS vale meses. Armazenar a resposta inteira, e não só o campo de interesse, preserva a possibilidade de extrair atributos novos sem reconsultar. O rate limit é respeitado com três camadas simples: agendador que serializa consultas por provedor, backoff exponencial diante de resposta 429 e circuit breaker que abre quando o provedor passa a falhar.

A tabela abaixo resume as políticas de retenção de cache recomendadas por classe de atributo, valores que o time ajusta por observação empírica do próprio ambiente:

5. Exemplo Python de Enriquecimento em Lote com Cache

O script abaixo enriquece uma lista de IPs com dois provedores, respeita rate limit com intervalo entre chamadas e usa SQLite como cache persistente com chave por janela de tempo. Ele é intencionalmente minimalista, mas contém as quatro peças de produção: cache, TTL por janela, backoff mínimo e salvaguarda de IPs privados:

import hashlib
import json
import os
import sqlite3
import time

import requests

PROVEDORES = {
    "abuseipdb": {"url": "https://api.abuseipdb.com/api/v2/check",
                  "chave_env": "ABUSEIPDB_KEY", "ttl": 86400},
    "shodan": {"url": "https://api.shodan.io/shodan/host/",
               "chave_env": "SHODAN_KEY", "ttl": 604800},
}

def abrir_cache(caminho):
    conn = sqlite3.connect(caminho)
    conn.execute("""CREATE TABLE IF NOT EXISTS cache (
        chave TEXT PRIMARY KEY,
        resposta TEXT NOT NULL,
        gravado_em INTEGER NOT NULL)""")
    return conn

def chave_cache(provedor, alvo, ttl):
    janela = int(time.time() // ttl)
    material = f"{provedor}|{alvo}|{janela}"
    return hashlib.sha256(material.encode()).hexdigest()

def consultar(provedor, alvo, conn):
    cfg = PROVEDORES[provedor]
    chave = chave_cache(provedor, alvo, cfg["ttl"])
    linha = conn.execute(
        "SELECT resposta FROM cache WHERE chave = ?", (chave,)).fetchone()
    if linha:
        return json.loads(linha[0]), True
    if provedor == "abuseipdb":
        resp = requests.get(cfg["url"],
                            headers={"Key": os.environ[cfg["chave_env"]],
                                     "Accept": "application/json"},
                            params={"ipAddress": alvo, "maxAgeInDays": 90},
                            timeout=15)
    else:
        resp = requests.get(cfg["url"] + alvo,
                            params={"key": os.environ[cfg["chave_env"]]},
                            timeout=15)
    if resp.status_code == 429:
        time.sleep(30)
        raise RuntimeError(f"rate limit em {provedor}, tentar de novo")
    resp.raise_for_status()
    conn.execute("INSERT OR REPLACE INTO cache VALUES (?, ?, ?)",
                 (chave, resp.text, int(time.time())))
    conn.commit()
    return resp.json(), False

def e_privado(ip):
    return (ip.startswith("10.") or ip.startswith("192.168.")
            or ip.startswith("172.16.") or ip.startswith("172.17.")
            or ip.startswith("172.18.") or ip.startswith("172.19.")
            or ip.startswith("172.2") or ip.startswith("172.3")
            or ip.startswith("127."))

def enriquecer_em_lote(ips, intervalo_segundos=1.2):
    conn = abrir_cache("cache_enriquecimento.db")
    for ip in ips:
        if e_privado(ip):
            print(f"[skip] {ip} e privado e nao sai da rede")
            continue
        for provedor in PROVEDORES:
            dado, de_cache = consultar(provedor, ip, conn)
            print(provedor, ip, "cache" if de_cache else "API")
            time.sleep(intervalo_segundos)

if __name__ == "__main__":
    enriquecer_em_lote(["8.8.8.8", "185.220.101.34", "10.2.3.4"])

Três detalhes do script merecem atenção porque resumem boas práticas. A chave da API nunca está no código, apenas no ambiente, e o cache guarda resposta completa para permitir reanálise sem nova consulta. A função e_privado é uma salvaguarda defensiva em camada dupla com a checagem de rede no pipeline, e o intervalo entre chamadas é parâmetro, porque cada provedor tem sua régua.

6. Riscos de OPSEC e Exposição de Dados

Toda consulta a API externa é um sinal emitido. Consultar em massa os domínios que só aparecem numa campanha específica pode revelar ao provedor, e por extensão a quem o monitora, que a sua organização está investigando aquilo; em casos com infraestrutura monitorada pelo adversário, a própria consulta pode ser vista. As contramedidas operacionais são diretas: concentrar chamadas em um ponto de saída corporativo conhecido, em vez de analistas consultando de IPs residenciais; preferir planos empresariais com contrato, que documentam o tratamento dos dados de consulta; e separar consultas rotineiras de triagem das consultas sensíveis de investigação, aplicando a exceção de hash descrita na seção 3.

O segundo risco é vazamento de dados internos. Endereços privados, nomes internos de host, e-mails de analistas e hashes de amostras proprietárias não devem viajar para APIs externas sem decisão consciente, e o filtro deve viver no código, como a função e_privado, e não na memória do analista. O terceiro risco é contratual e legal: termos de uso de APIs restringem redistribuição de dados, e resultados de enriquecimento incorporados a relatórios compartilhados via TLP precisam respeitar essas restrições, além das obrigações de proteção de dados pessoais eventualmente presentes em WHOIS de titulares pessoa física.

7. Erros Comuns e Pontos de Atenção

O erro operacional mais comum é ignorar os cabeçalhos de rate limit e tratar 429 como falha de rede, gerando tempestade de reconsultas que agrava o bloqueio; o script da seção 5 mostra o caminho mínimo, e a produção exige backoff exponencial com teto. O segundo é cache sem TTL, que transforma enriquecimento em base de dados congelada: reputação de dois anos atrás usada como atual é distorção, não contexto. O terceiro é enriquecer tudo na ingestão por conveniência, esgotando quota com atributos que ninguém lê; a métrica de correção é simples, proporção de campos enriquecidos efetivamente consultados.

Na frente analítica, cuidado com o efeito de ancoragem: pontuação de reputação alta ou baixa não é veredito, e a nota 05 do capítulo 03 define como contexto entra na validação de indicadores com peso de fonte e idade. Cuidado também com dependência única: provedores caem, planos mudam de limite, e toda integração séria tem um segundo provedor configurado para o mesmo atributo crítico, testado em exercício, não apenas citado no runbook.

8. Integração com o Restante da Biblioteca

Esta nota fecha o capítulo 09 conectando as ferramentas ao ciclo de inteligência. Os resultados de enriquecimento persistem no lake da nota 08 com proveniência completa, alimentam a análise de infraestrutura do diretório 06 do capítulo 03 e a contextualização de indicadores da nota 05 do capítulo 03, e sustentam os PIRs do capítulo 01 com contexto fresco na hora da análise. A automação de coleta via APIs da nota 12 do capítulo 02 é o complemento de coleta, e o controle AUT.1 do capítulo 15 governa a orquestração dessas chamadas dentro do SOAR.

A disciplina que o leitor deve levar desta nota é tripla: todo enriquecimento tem cache com TTL consciente, todo provedor tem quota tratada como orçamento, e todo alvo sensível tem política explícita de consulta. Com as ferramentas do capítulo cobertas, da forense da nota 06 ao enriquecimento desta nota, o próximo movimento da biblioteca é voltar ao método: o capítulo 14 sobre BAS mostra como provar, com simulação controlada, que todo esse aparato de detecção funciona contra os TTPs que a inteligência aponta.