Como implementar proteção contra SSRF em APIs que acessam URLs externas: guia prático para produção

APIs que buscam URLs informadas por usuários, parceiros ou sistemas integrados precisam tratar cada destino como não confiável. Sem controles, uma funcionalidade legítima de webhook, importação ou preview pode se tornar uma porta de acesso a recursos internos.

Este guia apresenta uma estratégia em camadas para implementar proteção contra SSRF em APIs, combinando validação de URL, resolução DNS segura, restrições de rede e monitoramento operacional.

Entenda como o SSRF compromete APIs que acessam URLs externas

Server-Side Request Forgery (SSRF) ocorre quando um atacante induz o servidor a realizar uma requisição para um destino escolhido por ele. A diferença essencial é que a chamada parte da infraestrutura da aplicação, com a visibilidade de rede e as permissões disponíveis para ela.

São fluxos de risco comuns: webhooks, leitores de documentos remotos, importadores, crawlers e geradores de prévia de links. Uma URL aparentemente comum pode apontar para localhost, uma porta administrativa, uma faixa privada ou um serviço de metadados em cloud.

A autenticação do usuário não elimina esse risco: uma conta legítima comprometida também pode enviar destinos maliciosos. Por isso, SSRF deve fazer parte das boas práticas de segurança em APIs.

Exemplo: se uma API de preview faz download de qualquer URL recebida, um atacante pode tentar solicitar http://127.0.0.1 ou um endereço privado acessível apenas pelo backend.

Mapeie todos os pontos onde sua aplicação faz chamadas de saída

Antes de corrigir, descubra onde a aplicação cria conexões externas. Procure parâmetros de URL, campos JSON, configurações de integração, jobs em fila, workers e bibliotecas HTTP usadas diretamente.

Para cada fluxo, registre o endpoint de origem, o serviço que faz a busca, os domínios esperados, métodos permitidos, necessidade de redirects e tamanho máximo de resposta. Esse inventário de ativos de aplicação torna visíveis exceções que costumam escapar de revisões pontuais.

Classifique os fluxos por criticidade. Uma integração com fornecedor conhecido normalmente aceita allowlist; um recurso que precisa consultar páginas públicas exigirá controles mais rigorosos de DNS, IP e egress.

Normalize e valide a URL antes de qualquer conexão

Use o parser de URL da linguagem ou biblioteca madura; não dependa de uma expressão regular isolada. Extraia esquema, hostname, porta, caminho e credenciais antes de abrir a conexão.

Como política inicial, aceite apenas https e, se houver justificativa explícita, http. Rejeite esquemas como file, gopher e ftp, URLs com usuário e senha embutidos, hostname vazio, portas inesperadas e entradas longas demais.

Aplique validação de entrada em APIs também a URLs indiretas, como valores montados a partir de vários campos. Normalize o hostname, trate IDN quando aplicável e deixe a política explícita e testável.

Uma regra simples pode exigir HTTPS, hostname válido, ausência de credenciais e porta 443. Qualquer valor fora desse contrato deve ser rejeitado antes da resolução DNS.

Prefira allowlists de domínios e rotas de integração

Quando a API chama parceiros previsíveis, uma allowlist é a melhor escolha. Em vez de tentar bloquear todos os destinos perigosos, permita somente hosts, subdomínios e portas aprovados.

Compare o hostname completo. Uma regra que procura apenas uma palavra pode aceitar domínios enganosos. Defina se subdomínios são permitidos, quais portas podem ser usadas e quais ambientes podem acessar cada destino.

Mantenha essa política centralizada, versionada e auditável. Para uma integração de pagamentos, por exemplo, aceite somente os hosts oficiais configurados para o fornecedor e recuse uma URL arbitrária enviada pelo cliente.

Resolva DNS e bloqueie IPs privados, locais e reservados

Validar o texto do domínio não basta. Um domínio permitido pode resolver para um endereço interno; por isso, resolva o hostname e valide todos os IPs retornados antes da conexão.

Bloqueie loopback, endereços não especificados, link-local, faixas privadas, multicast e intervalos reservados, tanto em IPv4 quanto IPv6. Isso inclui, entre outros, 127.0.0.1, 10.0.0.0/8, 169.254.0.0/16 e ::1.

Considere DNS rebinding: o resultado da resolução pode mudar entre validação e conexão. Sempre que a biblioteca permitir, conecte ao IP já validado preservando o hostname para TLS; caso contrário, revalide imediatamente antes de conectar.

Essa medida complementa a proteção de ambientes em cloud, onde serviços internos e endpoints de metadados merecem bloqueio específico por rede e credenciais de mínimo privilégio.

Controle redirects, métodos HTTP e protocolos suportados

Uma URL inicial segura pode responder com redirect para um destino proibido. Desabilite redirects se não forem necessários. Se forem indispensáveis, limite os saltos e reaplique toda a validação de URL, DNS e IP a cada destino.

Restrinja métodos ao mínimo necessário, normalmente GET ou HEAD. Não encaminhe automaticamente cookies, tokens de serviço, cabeçalhos internos ou credenciais para hosts externos.

Defina também limites de timeout, resposta e conteúdo. Isso reduz a superfície para SSRF, consumo excessivo de recursos e downloads inesperados.

Implemente uma camada centralizada para requisições externas

Não espalhe regras de SSRF pelos controllers e workers. Crie um cliente HTTP seguro, por exemplo fetchApprovedUrl(), que seja o único caminho autorizado para chamadas externas.

Essa camada deve analisar a URL, aplicar allowlist quando houver, resolver e validar IPs, controlar redirects, limitar métodos, impor timeouts e tamanho máximo de resposta, além de gerar logs estruturados.

Impeça o uso direto do cliente HTTP comum fora desse módulo. A centralização reduz divergências e facilita testes e revisões de segurança quando uma nova integração é adicionada.

Inclua validação de tipo MIME, limites para conteúdo compactado e autenticação de serviço apropriada para cada destino. O objetivo é permitir apenas o tráfego necessário, sem transformar a API em um proxy genérico.

Use controles de rede como segunda linha de defesa

Controles no código são indispensáveis, mas não devem ser a única barreira. Configure egress para que workloads da API alcancem apenas redes, portas e protocolos necessários.

Firewalls de saída, proxies com política, segmentação de rede e políticas de Kubernetes reduzem o impacto de uma falha de validação. Bloqueie o acesso da aplicação a redes administrativas, bancos de dados e endpoints de metadados quando esse acesso não for necessário.

Em ambientes containerizados, aplique políticas por workload e separe serviços expostos, dados e administração. Assim, mesmo uma tentativa bem-sucedida de SSRF encontra limites relevantes na infraestrutura.

Monitore tentativas de SSRF e teste sua proteção continuamente

Registre rejeições por esquema, domínio, IP, porta e redirect, sem armazenar tokens, credenciais ou o conteúdo sensível das respostas. Métricas de bloqueios por regra ajudam a detectar abuso e políticas excessivamente restritivas.

Crie testes automatizados para 127.0.0.1, ::1, IPs privados, endereços link-local, representações alternativas de IP e redirects para redes internas. O comportamento esperado deve ser bloqueio consistente.

Inclua esses cenários em testes de integração e em revisões de mudanças que adicionem importação remota, webhooks ou novos clientes HTTP. Tentativas recorrentes devem acionar investigação e ajuste da política.

Checklist de proteção SSRF para colocar em produção

• URLs são analisadas e normalizadas por um parser confiável.
• Somente esquemas, portas e métodos necessários são permitidos.
• Destinos usam allowlist sempre que a funcionalidade permitir.
• IPs locais, privados, link-local, multicast e reservados são bloqueados em IPv4 e IPv6.
• Redirects são desabilitados ou revalidados a cada salto.
• Toda chamada externa usa uma camada HTTP centralizada.
• A infraestrutura restringe e monitora o tráfego de saída.
• Logs, alertas e testes automatizados cobrem tentativas de SSRF.

Use esta lista em pull requests que introduzam download remoto, preview de links, webhooks de terceiros ou qualquer conexão HTTP iniciada pelo backend.

Sua API faz chamadas para URLs fornecidas por usuários ou integrações? Avalie esses fluxos agora e implemente uma camada centralizada de requisições externas com validação, restrição de rede e monitoramento.