API Gateway Logs: investigue abuso sem transformar limiar em prova

ANÁLISE EDITORIAL

Um aumento de respostas 401 ou uma sequência de identificadores não prova, por si só, que uma API está sob ataque. A Analyzing API Gateway Access Logs organiza essa investigação: transforma logs de gateways em tabelas, agrupa padrões de requisição e aponta candidatos que um analista deve confirmar com contexto de autenticação, autorização e negócio.

A Skill vem do repositório comunitário mukul975/Anthropic-Cybersecurity-Skills, que tinha 33.200 estrelas na consulta de 22 de setembro de 2026. A conta mantenedora é mukul975; o nome do repositório não torna esta Skill oficial da Anthropic. A adoção ajuda na curadoria, mas não valida os limiares do exemplo nem transforma uma anomalia estatística em incidente confirmado.

O que esta Skill faz

A Skill orienta a leitura de logs de acesso de AWS API Gateway, Kong e NGINX para procurar cinco famílias de sinal: enumeração de identificadores associada a BOLA ou IDOR, tentativa de contornar limite de requisições, varredura de credenciais, entradas com aparência de injeção e métodos HTTP incomuns para determinada rota. O procedimento original usa pandas para ler JSON Lines, agrupar eventos e selecionar linhas que ultrapassam um limiar.

O resultado correto não é “ataque detectado”. É uma lista priorizada de combinações como usuário, rota, origem, código de resposta e período que merecem conferência. A distinção é importante porque tráfego em lote, integrações, testes de carga e mudanças de cliente podem produzir padrões parecidos.

Para quem serve

Ela é útil para analistas de SOC, AppSec, SRE e equipes responsáveis por APIs que já têm acesso autorizado aos logs e precisam começar uma triagem reproduzível. Também pode ajudar quem está desenhando regras de detecção, desde que a equipe trate o código da Skill como exemplo e o adapte ao esquema real do gateway.

Não substitui uma plataforma de observabilidade nem uma investigação completa. A Skill Datadog Logs cobre busca e filtragem dentro do produto. A Cloudflare Security Audit cobre auditoria ofensiva autorizada. Aqui, o recorte é menor: examinar eventos de acesso de uma API sem confundir correlação com prova.

Origem, adoção e versão

O arquivo auditado é skills/analyzing-api-gateway-access-logs/SKILL.md, fixado no commit cb8d79e068f2e2505788ec7ecfc3047c40628483. O frontmatter declara a versão 1.0, o autor mahipal e a licença Apache-2.0. O repositório pertence à conta mukul975 e não estava arquivado na consulta.

Esse commit fixa os bytes revisados. A contagem de estrelas, o estado do repositório e a documentação dos gateways podem mudar depois da curadoria. Antes de instalar uma versão mais nova, compare o novo SKILL.md, a licença e qualquer dependência adicional.

Compatibilidade

O documento pode ser carregado por agentes compatíveis com Skills em Markdown. A execução do exemplo exige Python 3.8 ou superior e pandas, conforme os pré-requisitos da própria Skill. O exemplo espera um arquivo JSON Lines e nomes de campo como user_id, endpoint, resource_id, status_code e source_ip.

Esses nomes não são um padrão universal. A documentação do AWS API Gateway permite escolher variáveis no formato do log de acesso. O módulo de log do NGINX também usa formatos configuráveis. Em Kong, o mecanismo e o destino dependem do plugin e da configuração adotada. Por isso, o primeiro trabalho é mapear o esquema, não rodar o trecho sem adaptação.

Pré-requisitos

• Autorização explícita para ler os logs e investigar a API.
• Período, ambiente, gateway, serviço e rotas delimitados.
• Uma cópia minimizada ou um ambiente de análise com controle de acesso.
• Dicionário dos campos exportados e entendimento básico do fluxo de autenticação.
• Python 3.8 ou superior e pandas instalados separadamente em ambiente isolado, somente se o exemplo for executado.

Não envie logs brutos para um agente antes de revisar tokens, cabeçalhos, parâmetros, endereços IP, identificadores de conta e dados pessoais. A investigação precisa respeitar retenção, finalidade e acesso mínimo.

Instalação segura

O download local é um espelho documental auditado. Ele contém o SKILL.md original, a licença Apache-2.0 e um ORIGEM.md com commit, hashes e limites. O ZIP não contém Python, pandas, executáveis, scripts auxiliares, logs, regras prontas, credenciais ou resultados.

Baixar o pacote auditado analyzing-api-gateway-access-logs.zip

Abrir a pasta oficial no commit auditado

Depois do download, confira o SHA-256 808837648223242d669c4138a50db9ee2e01f1050eea30d5e9921fd498953084. Extraia em uma pasta de inspeção, leia ORIGEM.md e só então copie analyzing-api-gateway-access-logs para o diretório de Skills aceito pelo seu agente.

Configuração antes da análise

Crie um mapa entre os campos reais e os nomes usados pela Skill. Registre, por exemplo, qual chave representa a identidade autenticada, qual campo contém o objeto solicitado, como a rota foi normalizada e se o endereço de origem veio diretamente do cliente ou de um proxy confiável. Sem esse mapa, a mesma coluna pode misturar conceitos diferentes.

Defina também uma janela de tempo e uma linha de base. Um usuário que acessa muitos objetos em cinco minutos tem significado diferente de um processo de integração que lê o mesmo volume durante um dia. Mantenha timezone, atraso de ingestão e amostragem visíveis no relatório.

Primeiro uso

Comece com uma amostra sintética ou minimizada que reproduza o esquema, não com todo o histórico de produção. Confirme que cada linha foi lida e que os tipos das colunas estão corretos. A função pandas.read_json aceita o modo lines=True para JSON Lines, que é o formato usado no exemplo da Skill.

import pandas as pd

df = pd.read_json("api_gateway_logs.json", lines=True)
required = {"user_id", "endpoint", "resource_id", "status_code", "source_ip"}
missing = required.difference(df.columns)
if missing:
    raise ValueError(f"Campos ausentes: {sorted(missing)}")

Esse preflight evita uma conclusão baseada em coluna ausente, vazia ou renomeada. Antes de qualquer agrupamento, verifique também quantidade de linhas, período mínimo e máximo e proporção de valores nulos.

Como a triagem de BOLA funciona

A fonte agrupa eventos por user_id e endpoint, conta quantos resource_id distintos aparecem e seleciona grupos acima de 50. Esse raciocínio tenta encontrar uma identidade percorrendo muitos objetos na mesma rota. A OWASP API Security Top 10 de 2023 descreve BOLA como falha de autorização no nível do objeto, não como simples volume elevado.

Logo, a contagem é um sinal, não a vulnerabilidade. Para confirmar o problema, a equipe precisa demonstrar que a identidade acessou um objeto que a política não permitia. O CWE-639 ajuda a separar chave controlada pelo usuário de autorização ausente ou insuficiente.

401 em série e varredura de credenciais

O segundo exemplo filtra respostas 401, agrupa por source_ip e seleciona origens acima de 100 falhas. Esse padrão pode apontar tentativa automatizada, mas também pode aparecer quando um cliente legítimo mantém credencial expirada, um proxy concentra muitos usuários ou uma integração entra em loop.

Valide o agente de usuário, a rota, o intervalo entre requisições, o mecanismo de autenticação e a distribuição por conta antes de escalar. Se a origem passar por CDN, balanceador ou gateway intermediário, confirme qual campo representa o cliente e qual registra apenas o último salto confiável.

Rate limit, injeção e métodos incomuns

A Skill também sugere procurar manipulação de cabeçalhos para contornar rate limit, conteúdo suspeito em parâmetros e métodos como DELETE ou PATCH em endpoints normalmente usados para leitura. Nenhum desses sinais deve ser avaliado isoladamente. Um método incomum pode fazer parte de uma nova versão da API; uma sequência parecida com SQL pode ser texto legítimo; um cabeçalho alternativo pode ter sido introduzido pelo próprio proxy.

Use a configuração do gateway e o contrato da rota como referência. A técnica MITRE ATT&CK T1190 descreve exploração de aplicação exposta em nível mais amplo, mas o mapeamento não confirma que um evento específico realizou exploração.

Como escolher limiares sem inventar precisão

Os números 50 e 100 aparecem no exemplo original. Eles não são limites universais, recomendação da OWASP ou resultado de benchmark publicado pela Skill. Trate-os como valores didáticos. Calibre por rota, identidade, cliente e janela temporal, usando histórico limpo o suficiente para estimar volume normal.

A API de GroupBy do pandas facilita agregações, mas não resolve o desenho da detecção. Documente o denominador, a janela, exclusões conhecidas e a razão de cada limiar. Revise falsos positivos depois de mudanças de versão, campanhas, importações ou testes.

Resultado esperado

Uma boa saída lista candidatos com período, identidade pseudonimizada, rota normalizada, quantidade de eventos, objetos distintos, códigos de resposta, origens e motivo da seleção. Acrescente campos para evidência confirmada, hipótese alternativa, responsável pela revisão e decisão.

Preserve a consulta ou o notebook usado, a versão do esquema e o hash do conjunto de entrada quando a política permitir. O guia NIST SP 800-92 é antigo, mas continua útil para lembrar que geração, armazenamento, análise e proteção dos logs fazem parte do mesmo processo.

Permissões e riscos

O principal risco não está no Markdown, mas nos dados e nas ações seguintes. Logs podem revelar tokens, parâmetros, identificadores pessoais, rotas internas e comportamento de clientes. Uma exportação ampla pode aumentar a exposição. Uma regra automática mal calibrada pode bloquear tráfego legítimo ou esconder o problema ao alterar a coleta.

Comece somente leitura, use dados minimizados, restrinja a pasta de saída e não autorize mudanças em WAF, gateway, autenticação ou rate limit dentro da mesma etapa de triagem. O NIST Cybersecurity Framework pode ajudar a ligar detecção, resposta e governança, sem transformar a Skill em controle completo.

Erros comuns e como corrigir

• O JSON não abre: confirme se é JSON Lines, a codificação e a existência de linhas truncadas antes de converter o arquivo inteiro.
• As colunas não existem: construa o mapa do esquema do gateway e adapte nomes explicitamente.
• Tudo parece suspeito: reduza o período, separe rotas e clientes e compare com uma linha de base documentada.
• O IP não identifica um cliente: revise proxies e cabeçalhos confiáveis; não atribua identidade a um endereço compartilhado.
• O agrupamento estoura memória: filtre o escopo, selecione apenas colunas necessárias e processe por janelas controladas.
• A anomalia virou incidente automaticamente: volte ao evento bruto, à política de autorização e ao contexto do serviço.

Versão, licença e pacote auditado

A Skill declara versão 1.0 e licença Apache-2.0. O arquivo LICENSE no commit auditado contém a licença Apache 2.0. Essa licença permite redistribuir os documentos preservando os termos aplicáveis, por isso o Bastidores oferece o espelho.

O pacote tem três arquivos e SHA-256 808837648223242d669c4138a50db9ee2e01f1050eea30d5e9921fd498953084. O hash verifica os bytes do ZIP publicado, não garante que a lógica detecte ataques, que o ambiente esteja seguro ou que os dados estejam corretos.

Limites do pacote local

O espelho é estritamente documental. Não inclui pandas, runtime Python, dependências, scripts, arquivos de log, amostras, regras de produção, dashboards, credenciais, tokens, chaves ou resultados. O trecho Python do SKILL.md foi preservado para leitura, mas não foi executado durante a curadoria.

Os documentos não configuram AWS API Gateway, Kong ou NGINX. Também não criam autorização por objeto, não corrigem BOLA, não ajustam rate limit e não implantam bloqueios. Essas mudanças pertencem a um fluxo separado, com teste, aprovação e rollback.

Checklist antes de usar

• Confirme autorização, ambiente, API, período e responsável.
• Revise o esquema e os campos confiáveis de identidade e origem.
• Masque segredos e minimize dados pessoais antes da análise.
• Valide leitura, tipos, nulos e timezone antes de agrupar.
• Calibre limiares por rota e janela, sem copiar 50 ou 100 como regra universal.
• Trate cada saída como candidato e confirme autorização e contexto no evento bruto.
• Aprove separadamente qualquer bloqueio, regra, alteração de gateway ou resposta a incidente.

Fontes oficiais consultadas

Foram consultados o repositório do mantenedor, o SKILL.md fixado, a licença do repositório, a documentação da AWS, NGINX e pandas, a OWASP API Security Top 10, o CWE, o MITRE ATT&CK e materiais do NIST. O pacote foi montado em 19 de setembro; commit, licença, bytes de origem, metadados e disponibilidade foram revalidados em 22 de setembro de 2026.