Blog

Restrição de IP por chave de API: o que ela protege e o que ela quebra

UNIFOKAL7 min de leituraProduto e integração

A allowlist de IP limita o estrago de uma credencial vazada, mas quebra em CGNAT, serverless e failover. O que ela cobre, onde falha e com o que combiná-la.

A ideia é simples e boa: cada credencial de API declara de quais endereços de origem ela pode ser usada, e qualquer requisição que chegue de fora dessa lista é recusada antes mesmo de o segredo ser conferido. Se a chave vazar em um repositório público, em um log de terceiro ou no laptop de alguém, ela sozinha não abre a porta: o atacante precisaria também estar saindo de um endereço que você declarou.

O problema não é a ideia, é a expectativa. Times ligam a restrição de IP achando que fecharam o assunto, e descobrem em produção que o endereço de saída mudou, que a função sem servidor subiu em outra faixa, que o failover para outra região trouxe outros endereços. O resultado é uma integração fora do ar num horário ruim, com uma causa que ninguém suspeita de primeira porque o código não mudou.

Este texto trata dos dois lados: onde a allowlist de IP realmente ajuda e onde ela quebra de forma previsível, para que a decisão de ligar ou não seja tomada antes e não durante o incidente.

Segunda camada, nunca a primeira

A restrição de IP é um controle de rede aplicado a uma credencial. Ela não substitui nenhuma das camadas anteriores: a chave continua precisando ser longa, aleatória, guardada em cofre e nunca embarcada em código de cliente. O que a allowlist faz é reduzir o valor de uma chave roubada, não impedir o roubo.

Vale insistir nessa ordem porque a lista de riscos mais comuns em APIs, publicada pelo OWASP API Security Top 10 na edição de 2023, é dominada por falhas de autorização e de autenticação, não por falta de filtro de rede. Credencial com permissão excessiva, objeto acessível por identificador previsível ou endpoint sem checagem de propriedade continuam abertos qualquer que seja o endereço de origem.

O corolário desagradável é o que ela não protege. Se quem obteve a chave está dentro da sua rede, saindo pelo mesmo gateway que a sua aplicação, o filtro simplesmente aprova. Isso cobre casos nada exóticos: um servidor comprometido no seu próprio ambiente, um contêiner vizinho, um processo de build que roda no mesmo cluster, um proxy de saída compartilhado. Contra o insider e contra o ambiente comprometido, a allowlist não faz nada, e a defesa volta a ser a de sempre, com controle de acesso e escopo mínimo por credencial.

Os cenários que quebram, e eles são comuns

O endereço de saída da sua aplicação parece uma constante, mas raramente é. Estes são os casos que mais derrubam integração.

  • IP de saída dinâmico. Instâncias que recebem endereço público efêmero mudam de endereço a cada substituição, escala ou reinício. A allowlist escrita na quinta-feira deixa de valer no primeiro deploy da semana seguinte.
  • CGNAT. Provedores que compartilham endereços entre assinantes usam a faixa 100.64.0.0/10, reservada pela RFC 6598 justamente para tradução em escala de operadora. Do lado de fora, milhares de clientes aparecem com o mesmo endereço público. Autorizar esse endereço é autorizar todo mundo que compartilha ele, e o valor de segurança da lista vira quase zero.
  • Funções sem servidor. Plataformas de execução sob demanda costumam sair por faixas amplas e mutáveis, publicadas como listas que o provedor atualiza sem aviso individual. Colar essas faixas na allowlist é aceitar uma lista enorme que envelhece sozinha.
  • Failover regional. O plano de continuidade sobe a aplicação em outra região, com outro conjunto de endereços de saída. A allowlist, feita para a região principal, transforma o failover em outro incidente, exatamente no momento em que ninguém tem paciência para depurar.

A saída de engenharia para todos esses casos é a mesma: forçar o tráfego por um ponto de saída fixo, tipicamente um gateway NAT com endereço estático, e declarar só ele. Vale o custo quando a credencial é sensível, mas note o que aconteceu: a allowlist deixou de ser uma caixa marcada na interface e virou decisão de arquitetura de rede.

Um lembrete que evita uma confusão frequente: endereços das faixas privadas descritas na RFC 1918, como 10.0.0.0/8 e 192.168.0.0/16, não servem de allowlist para uma API pública. Eles não são roteáveis na internet, e o que chega ao fornecedor é o endereço público que o NAT usou na saída, nunca o interno.

Quem é o IP de origem, afinal

Toda a discussão assume que quem verifica sabe qual é o endereço de origem. Nem sempre sabe. Se existe balanceador, CDN ou proxy reverso no caminho, o endereço da conexão vista pelo servidor de aplicação é o do último salto, e o endereço real do cliente viaja num cabeçalho.

Esse cabeçalho é dado enviado pelo cliente, e o cliente pode escrever o que quiser nele. O cabeçalho que a maior parte dos proxies escreve, o X-Forwarded-For, nasceu como convenção e nunca teve especificação; a RFC 7239 foi publicada justamente para propor um substituto padronizado, o cabeçalho Forwarded. Nenhuma das duas formas torna o valor confiável por si. Um receptor que lê o primeiro endereço da lista e o trata como origem autêntica aceita qualquer origem que o atacante declarar, e a allowlist inteira vira teatro.

A regra correta é contar os saltos: a aplicação precisa saber quantos proxies confiáveis existem à sua frente e ler a posição correspondente a partir do fim da cadeia, descartando o que veio antes. Isso significa que ligar a restrição de IP tem um pré-requisito de configuração explícita da borda, e que qualquer mudança na topologia de rede pede revisão desse número.

Em IPv6, especificado pela RFC 8200, aparece outra diferença prática: um cliente costuma ter à disposição um prefixo inteiro, e o endereço específico usado numa conexão pode variar entre requisições. Allowlist de IPv6 que registra um endereço exato tende a falhar; o que faz sentido é declarar o prefixo delegado, aceitando que a granularidade é menor por natureza.

O par natural da allowlist

Restrição de IP funciona bem quando é uma peça de um conjunto, e não uma medida solitária.

A primeira companheira é a rotação. Se a hipótese que justifica a allowlist é o vazamento de credencial, então o plano precisa incluir trocar a credencial vazada sem derrubar a integração. A publicação NIST SP 800-57 Part 1 Revision 5, do National Institute of Standards and Technology, formaliza esse hábito com o conceito de criptoperíodo, o intervalo durante o qual uma chave permanece autorizada. Uma allowlist muito restritiva às vezes cria a ilusão de que a rotação pode esperar, e é o contrário: as duas se complementam.

A segunda é a telemetria por credencial. Sem saber de quais endereços cada chave está sendo usada, e quando foi seu último uso, montar a lista é adivinhação. O registro de uso responde às três perguntas do dia a dia: quais endereços declarar, se alguém está tentando usar a chave de fora da lista, e se uma chave antiga ainda tem tráfego. Esses dados alimentam o acompanhamento contínuo da integração, onde a subida de recusas por origem não autorizada é um alerta de primeira linha.

A terceira é a separação de ambientes. Credencial de teste e credencial de produção saem de lugares diferentes, e uma allowlist por ambiente é mais fácil de manter do que uma lista única cheia de exceções. É mais um motivo, entre os já conhecidos, para manter sandbox e produção realmente separados, inclusive na topologia de saída.

Por fim, uma escolha de produto que muda a experiência: aplicar a restrição como configuração da credencial, e não da conta inteira. Assim uma chave de integração servidor a servidor pode ter lista estreita enquanto uma chave administrativa, operada de redes variáveis, fica sem restrição e compensa com escopo menor e prazo curto. Em plataformas de verificação de identidade, incluindo a UNIFOKAL, é essa granularidade que torna a allowlist utilizável, em vez de um botão que ninguém liga por medo de derrubar o cadastro.

Fontes citadas