O problema com labels estáticas no AWS WAF
O AWS WAF classifica o tráfego web anexando metadados a cada requisição avaliada. Grupos de regras gerenciadas como o AWS WAF Bot Control e o AWS WAF Fraud Control de prevenção de tomada de conta (ATP) aplicam labels que descrevem o que foi detectado — se uma requisição veio de uma categoria conhecida de bot, por exemplo, ou se ela corresponde a um padrão de credential stuffing.
Esses metadados podem ser encaminhados à sua origem como headers de requisição, dando ao backend visibilidade sobre as decisões tomadas pelo WAF na borda. Também é possível construir políticas em camadas: um sinal de bot de baixa confiança pode disparar um desafio CAPTCHA, enquanto um sinal de alta confiança bloqueia a requisição diretamente.
Com o AWS WAF AI Activity Dashboard, lançado em 24 de fevereiro de 2026, o Bot Control passou a identificar mais de 650 bots e agentes — incluindo crawlers de motores de busca, coletores de dados, assistentes de IA e crawlers de treinamento de modelos de linguagem de grande porte (LLM) — e esse número continua crescendo.
Em um post anterior, a AWS mostrou como agrupar labels do Bot Control em níveis de confiança para criar experiências adaptativas. Essa abordagem funciona bem quando você consegue listar as labels que importam. Mas quando o catálogo cresce além do que é razoável enumerar, escrever uma regra por label vira um fardo de manutenção e consome capacidade de regras que poderia ser usada em outro lugar.
É exatamente esse problema que a interpolação dinâmica de labels resolve.
Como funciona a interpolação dinâmica
Com a interpolação dinâmica, você referencia labels por namespace em vez de pelo nome individual. Uma única regra resolve para qualquer label que tenha correspondido durante a avaliação — sem necessidade de enumeração. A sintaxe usa uma cláusula ${namespace:} no valor de um header ou no corpo de uma resposta customizada, e o AWS WAF substitui os valores correspondentes em tempo de avaliação.
Onde pode ser usado
- Headers de requisição customizados: insere os valores resolvidos das labels em headers que o WAF encaminha à sua origem.
- Corpos de resposta customizados: embute valores de labels e labels sintéticas (como IP do cliente ou ID da requisição) em páginas de bloqueio, desafios e outras respostas customizadas.
- Headers de resposta customizados: insere valores de labels em headers de resposta, como o header
Location para redirecionamentos.
Regras de resolução da sintaxe
O dois-pontos ao final do namespace é o sinal para o AWS WAF realizar a interpolação. O comportamento segue três regras:
- Correspondência única: a cláusula resolve para o valor terminal da label. Se a requisição carrega
awswaf:managed:aws:bot-control:bot:category:scraping, então ${awswaf:managed:aws:bot-control:bot:category:} resolve para scraping.
- Múltiplas correspondências: o AWS WAF remove o prefixo do namespace e retorna os valores como lista separada por vírgulas, como
scraping,advertising.
- Sem correspondência: a cláusula resolve para string vazia. Isso garante compatibilidade retroativa — qualquer valor sem a sintaxe
${...} passa inalterado.
Não há novos campos de API para configurar. A sintaxe é escrita diretamente nos valores de string existentes.
Labels sintéticas
Nem todo valor útil vem de uma correspondência de regra. Labels sintéticas são derivadas da própria requisição e interpoladas com a mesma sintaxe:
${awswaf:request_id:} — identificador único da requisição no AWS WAF${awswaf:ip:} — endereço IP do cliente${awswaf:ja3:} — fingerprint TLS JA3${awswaf:ja4:} — fingerprint TLS JA4
É possível combinar labels sintéticas com labels baseadas em namespace em um único valor e passar tudo para a origem no formato que melhor atender à sua aplicação.
Cenários de uso práticos
1. Sinalização para a aplicação (Application Signaling)
O padrão de sinalização usa as labels e as encaminha à origem como headers de requisição customizados. Assim, sua aplicação recebe a classificação feita pelo WAF e decide como agir com base nela.
Enumerar cada label individualmente não escala. Só o nível de proteção comum do Bot Control rastreia mais de 650 bots e agentes auto-identificáveis. Mapear apenas o namespace bot:category para headers exigiria centenas de regras idênticas, cada uma com um valor diferente fixo no código.
Se você seguiu os passos do post How to use AWS WAF Bot Control for Targeted Bots signals and mitigate evasive bots with adaptive user experience, já mapeou labels para níveis de confiança dessa forma. Veja como era uma regra estática para uma única categoria:
{
"name": "add-header-for-bot-category-advertising",
"statement": {
"label_match_statement": {
"scope": "LABEL",
"key": "awswaf:managed:aws:bot-control:bot:category:advertising"
}
},
"rule_action": {
"count": {
"custom_request_handling": {
"insert_headers": [
{
"name": "bot-category",
"value": "advertising"
}
]
}
}
}
}
Com interpolação, isso colapsa em uma única regra. O escopo muda de LABEL para NAMESPACE, e o valor usa uma cláusula ${...} em vez de uma string fixa:
{
"name": "forward-waf-signals",
"statement": {
"label_match_statement": {
"scope": "NAMESPACE",
"key": "awswaf:managed:aws:bot-control:bot:category:"
}
},
"rule_action": {
"count": {
"custom_request_handling": {
"insert_headers": [
{
"name": "x-waf-bot-category",
"value": "${awswaf:managed:aws:bot-control:bot:category:}"
},
{
"name": "x-waf-bot-name",
"value": "${awswaf:managed:aws:bot-control:bot:name:}"
},
{
"name": "x-waf-bot-signals",
"value": "${awswaf:managed:aws:bot-control:signal:}"
},
{
"name": "x-waf-fingerprint",
"value": "${awswaf:managed:token:fingerprint:}"
},
{
"name": "x-waf-token-id",
"value": "${awswaf:managed:token:id:}"
},
{
"name": "x-waf-client-ip",
"value": "${awswaf:ip:}"
}
]
}
}
}
}
O header x-waf-bot-signals demonstra a resolução de múltiplos valores: o namespace signal: pode conter várias labels ao mesmo tempo, como non_browser_user_agent e automated_browser, que resolvem para uma lista separada por vírgulas. Os headers x-waf-fingerprint e x-waf-token-id carregam valores derivados de token únicos por dispositivo, que sua origem pode usar para correlação de sessão e detecção de fraude. E o x-waf-client-ip usa uma label sintética para passar o IP do cliente como o WAF o enxerga.
Com esses headers, sua aplicação pode tomar decisões que o WAF não consegue tomar sozinho: um cliente autenticado com sinal de bot pode receber uma página simplificada, enquanto uma sessão anônima com o mesmo sinal é bloqueada. Uma requisição com múltiplos sinais de bot durante uma promoção relâmpago pode ser colocada em fila em vez de rejeitada. Um balanceador de carga pode ler os headers e rotear tráfego de search_engine para um serviço de renderização otimizado para crawlers.
Esses headers também estão disponíveis para Amazon CloudFront Functions, permitindo lógica customizada antes mesmo de a requisição chegar à sua origem.
2. Páginas de bloqueio e desafio com informações de diagnóstico
Falsos positivos são um custo inevitável da mitigação de bots. O problema mais difícil geralmente é diagnosticá-los depois que ocorreram. Labels sintéticas ajudam nisso ao embutir o IP do cliente e o ID da requisição do AWS WAF no corpo de uma resposta customizada:
{
"CustomResponseBodies": {
"BlockPage": {
"Content": "Your request was blocked.\n\nIP: ${awswaf:ip:}\nRequestID: ${awswaf:request_id:}\n\nIfyou believe this is an error, contact support with the Request ID above.",
"ContentType": "TEXT_PLAIN"
}
}
}
Isso agiliza o fluxo de suporte: um usuário bloqueado que reporta o problema pode fornecer o ID da requisição exibido na página. Você busca esse ID nos logs do AWS WAF, analisa as regras e labels que corresponderam, e decide se foi um falso positivo — sem precisar pedir ao usuário que reproduza o problema ou tentar adivinhar quando aconteceu.
3. Redirecionamentos de verificação com contexto embutido
Às vezes a resposta certa não é um bloqueio, mas um desvio — enviar tráfego suspeito para uma página de verificação antes de deixá-lo continuar. É possível construir isso no AWS WAF interpolando o IP do cliente e o ID da requisição no destino do redirecionamento:
{
"Action": {
"Block": {
"CustomResponse": {
"ResponseCode": 302,
"ResponseHeaders": [
{
"Name": "Location",
"Value": "/verify?ip=${awswaf:ip:}&rid=${awswaf:request_id:}"
}
]
}
}
}
}
O header Location resolve para algo como /verify?ip=203.0.113.42&rid=a1b2c3d4-.... O endpoint de verificação pode usar o IP para uma verificação de geo ou rate-limit, e o ID da requisição para alinhar a visita com os logs do WAF. Como o redirecionamento é construído no próprio AWS WAF, esse comportamento é obtido sem alterar a aplicação de origem.
4. Segmentação de cache do CloudFront com labels do WAF
Quando o AWS WAF é usado na frente do Amazon CloudFront, um header inserido por uma regra fica disponível para o CloudFront ao calcular a chave de cache. Isso significa que é possível segmentar o cache por classificação de bot.
Usando o header x-waf-bot-category da regra de encaminhamento, você instrui o CloudFront a incluir esse header na chave de cache e manter uma resposta em cache separada por categoria. Na prática: uma requisição de search_engine recebe uma versão pré-renderizada e cacheada na borda, otimizada para crawling. Uma requisição sem label de bot recebe a página dinâmica completa. Uma requisição de scraping recebe uma resposta mínima, também do cache. Crawlers recebem conteúdo indexável, scrapers param de consumir capacidade da origem, e visitantes humanos não percebem diferença alguma.
Também é possível aplicar a mesma abordagem na origem para controle mais fino de atualização: configure sua aplicação para ler o header de classificação e definir o Cache-Control adequadamente — no-store para tráfego humano sem label, e TTLs mais longos para respostas direcionadas a bots.
Um exemplo com labels customizadas
A interpolação não se limita a grupos de regras gerenciadas. Ela funciona com a maioria dos namespaces, incluindo labels de outras AWS Managed Rules (como prevenção de tomada de conta, prevenção de fraude na criação de conta e listas de reputação de IP), grupos de regras gerenciadas do AWS Marketplace, e também com labels customizadas definidas nas suas próprias regras.
Considere uma configuração que classifica requisições em tiers com base em um header de chave de API. A primeira regra identifica requisições cujo header x-api-key começa com pk_enterprise_ e aplica a label app:tier:enterprise:
{
"name": "classify-tier",
"priority": 100,
"statement": {
"byte_match_statement": {
"search_string": "pk_enterprise_",
"field_to_match": {
"single_header": {
"name": "x-api-key"
}
},
"positional_constraint": "STARTS_WITH",
"text_transformations": [
{
"priority": 0,
"type": "NONE"
}
]
}
},
"rule_labels": [
{
"name": "app:tier:enterprise"
}
],
"action": {
"count": {}
}
}
A segunda regra corresponde a labels no namespace app:tier e encaminha o valor resolvido, enterprise, no header x-customer-tier:
{
"name": "forward-tier",
"priority": 200,
"statement": {
"label_match_statement": {
"scope": "NAMESPACE",
"key": "app:tier:"
}
},
"action": {
"count": {
"custom_request_handling": {
"insert_headers": [
{
"name": "x-customer-tier",
"value": "${awswaf::webacl::app:tier:}"
}
]
}
}
}
}
Vale notar: em rule_labels, você usa o nome curto da label (app:tier:enterprise), e o AWS WAF o prefixa com o contexto da web ACL para produzir a label totalmente qualificada. Em uma instrução de correspondência de label, o namespace curto é aceito — mas em uma referência de interpolação, é necessário usar o namespace totalmente qualificado com o contexto de conta e ACL.
O ganho aqui é que você pode adicionar app:tier:standard, app:tier:trial ou outros tiers depois, e a regra de encaminhamento os captura automaticamente, sem alterações.
Conclusão
A interpolação dinâmica de labels não muda como as labels funcionam — ela muda a quantidade de configuração de regras necessária para agir sobre elas. Um namespace que antes exigia uma regra por valor agora exige apenas uma regra total, e ela continua funcionando conforme o catálogo do Bot Control cresce além das 650 entradas atuais.
Junto a isso, o recurso entrega páginas de bloqueio com contexto específico por requisição, redirecionamentos que carregam seu próprio contexto, e segmentação de cache baseada em classificação. Nenhuma dessas capacidades é dramática isoladamente, mas combinadas permitem parear a classificação na borda com julgamento na sua aplicação.
O recurso se encaixa no AWS WAF da forma como você já o usa — sem quebrar nada, tornando a adoção uma questão de editar configurações de regras em vez de reconstruir qualquer coisa.
Para começar, consulte a documentação de labels do AWS WAF e o guia de configuração de requisições e respostas customizadas. Exemplos adicionais estão disponíveis no repositório AWS Samples, e discussões podem ser iniciadas no AWS re:Post.
Fonte
Do more with AWS WAF labels using dynamic label interpolation (https://aws.amazon.com/blogs/security/do-more-with-aws-waf-labels-using-dynamic-label-interpolation/)
