Saltar para o conteúdo

Regras avançadas (DSL)

A linguagem de regras da FortFox permite combinar múltiplas condições do pedido (endereço, método, cabeçalhos, IP, país…) numa só regra com a ação que escolheres. Esta página é a referência completa.

Intermédio12 min de leitura

Anatomia de uma regra

Uma regra completa tem:

ParteOndeExemplo
NomeCampo do editor"Bloquear /admin do exterior"
ExpressãoEditor de códigohttp.request.uri starts_with "/admin" and ip.src ne "203.0.113.7"
AçãoDropdownBloquear o pedido
PrioridadeCampo100 (menor = avaliada primeiro)
AtivaCheckbox✓

A expressão é apenas a condição. A ação não vai dentro da expressão — é o dropdown separado.

Sintaxe geral

<campo> <operador> <valor>

Combinadas com and, or, not, parênteses:

(campo1 op valor1 and campo2 op valor2) or campo3 op valor3

Strings entre aspas duplas ("...") ou simples ('...'). Números sem aspas. Booleanos: true, false.

Campos disponíveis

Pedido HTTP

CampoTipoO que é
http.request.methodstringGET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD
http.request.uristringCaminho + query string (/produtos?cor=azul)
http.request.pathstringSó o caminho (/produtos)
http.request.querystringSó a query string (cor=azul)
http.request.bodystringCorpo do pedido (POST/PUT)
http.request.body.sizenumberTamanho do corpo em bytes

Cabeçalhos

CampoTipoO que é
http.request.header.user_agentstringIdentificação do browser
http.request.header.refererstringPágina de onde veio o pedido
http.request.header.hoststringDomínio pedido
http.request.header.accept_languagestringLínguas preferidas
http.request.header.cookiestringCookies brutos
http.request.header["<nome>"]stringQualquer cabeçalho por nome

Origem (IP e geo)

CampoTipoO que é
ip.srcstringIP do visitante (IPv4 ou IPv6)
ip.geoip.countrystringCódigo ISO de 2 letras (PT, US...)
ip.geoip.citystringCidade aproximada
ip.geoip.asnnumberASN do provedor
ip.is_datacenterboolVerdadeiro se o IP é de um datacenter
ip.is_vpnboolVerdadeiro se for VPN comercial conhecida
ip.is_torboolVerdadeiro se for exit node Tor

Decisão prévia

CampoTipoO que é
waf.scorenumberPontuação WAF até este ponto (0-100+)
bot.scorenumberPontuação de bot (0-100)
bot.is_botboolConclusão da gestão de bots

Operadores

Comparação simples

OperadorSignificadoFunciona em
eqIgualstrings, numbers, bools
neDiferentestrings, numbers, bools
gtMaiornumbers
ltMenornumbers
geMaior ou igualnumbers
leMenor ou igualnumbers

Texto

OperadorSignificadoExemplo
containsContém substringhttp.request.uri contains "/admin"
not_containsNão contémhttp.request.uri not_contains "/api"
starts_withComeça porhttp.request.uri starts_with "/wp-"
ends_withTermina emhttp.request.uri ends_with ".php"
matchesRegex (PCRE compatível)http.request.uri matches "^/users/[0-9]+$"

Coleções

OperadorSignificadoExemplo
inEstá em listahttp.request.method in {"GET", "POST"}
not_inNão está em listaip.geoip.country not_in {"PT", "ES", "FR"}

Listas usam chavetas e itens separados por vírgula.

Lógicos

OperadorSignificado
andE
orOU
notNegação (not <expr>)

Usa parênteses para clarificar precedência: (a or b) and c ≠ a or b and c.

Ações

AçãoO que faz
blockBloqueia o pedido, devolve 403
challengeMostra verificação ao visitante (humano passa, bot fica preso)
logNão bloqueia, só anota no log (modo teste)
allowAceita o pedido e salta as restantes regras
ban_ipBloqueia este pedido e bane o IP por algum tempo (default 1 h) em todos os edges

A ação allow é poderosa — usa-a para criar exceções a regras mais agressivas. Exemplo: tens nível de proteção Alto e queres garantir que tráfego do dashboard admin (vindo do teu IP) passa sempre:

Expressão: http.request.uri starts_with "/wp-admin" and ip.src eq "203.0.113.7"
Ação: allow
Prioridade: 1

Esta regra (prioridade 1, baixa) corre primeiro, faz match, e o pedido salta tudo o resto.

Prioridade

Regras são avaliadas por ordem de prioridade ascendente. Menor = primeiro.

  • Prioridade 1: avaliada primeiro
  • Prioridade 100: avaliada depois

Usa prioridade baixa para exceções (whitelist), prioridade alta para regras catch-all (block everything else).

Exemplos completos

Restringir uma área aos teus IPs

Cenário: o /admin só deve ser acessível do escritório e da casa do administrador.

Nome: Restringir /admin aos meus IPs
Expressão: http.request.uri starts_with "/admin" and ip.src ne "203.0.113.7" and ip.src ne "198.51.100.4"
Ação: block
Prioridade: 10

Bloquear países

Nome: Bloquear países hostis
Expressão: ip.geoip.country in {"RU", "KP", "IR"}
Ação: block
Prioridade: 20

Permitir só estes países

Nome: Site só para PT/ES
Expressão: ip.geoip.country not_in {"PT", "ES"}
Ação: block
Prioridade: 20

Limitar métodos a um endpoint

Nome: API só aceita GET e POST
Expressão: http.request.path starts_with "/api/" and http.request.method not_in {"GET", "POST"}
Ação: block
Prioridade: 30

Bloquear User-Agent específico

Nome: Bloquear scrapper conhecido
Expressão: http.request.header.user_agent contains "BadBot/2.0"
Ação: block
Prioridade: 40

Banir abuso de login

Cenário: pedido POST a /login com body > 1 MB é claramente abuso (login normal é < 1 KB).

Nome: Banir abuso de /login
Expressão: http.request.path eq "/login" and http.request.method eq "POST" and http.request.body.size gt 1048576
Ação: ban_ip
Prioridade: 50

Combinar bot score com path

Cenário: nem bloqueias tudo o que parece bot, mas em /checkout queres tolerância zero.

Nome: Checkout só humanos
Expressão: http.request.path starts_with "/checkout" and bot.score gt 30
Ação: challenge
Prioridade: 25

Permitir Googlebot no admin (raro mas exemplo)

Cenário: tens uma regra geral a bloquear /admin exceto teu IP, mas queres que o Googlebot consiga indexar /admin/sitemap.xml.

Nome: Exceção: Googlebot no sitemap admin
Expressão: http.request.uri eq "/admin/sitemap.xml" and http.request.header.user_agent contains "Googlebot"
Ação: allow
Prioridade: 5

Esta regra (prioridade 5) avalia antes da regra anterior (prioridade 10) e deixa passar o caso específico.

Padrões comuns

Whitelist override

Prioridade 1-9:  Regras allow para tráfego de confiança
Prioridade 10-50: Regras block para tráfego suspeito
Prioridade 51-100: Regras catch-all genéricas

Mode-switching durante teste

Em vez de criar uma regra com block direto, cria com log e observa em Atividade. Quando confirmas que afeta o tráfego certo, muda para block. Equivalente ao modo sombra mas regra-a-regra.

Limites

LimiteValor
Comprimento da expressão1024 caracteres
Nº de regras DSL por site100 por omissão; mais por proposta
Profundidade de aninhamento10 níveis de parênteses
Prioridade1 a 1000
Em mais detalhe técnico

Parser: a expressão é parseada uma vez no servidor (validação) e o AST resultante (JSON) é guardado em BD ao lado da fonte. O agent recebe ambos no payload do edge — runtime usa só o AST (sem reparse).

Engine no edge: avaliação em Lua via lua-resty-waflang. Cada nó do AST mapeia para uma função stateless que recebe o contexto do pedido. Performance: ~5 µs por regra simples, ~20 µs por regra complexa com várias condições.

Cache de campos: campos derivados (geoip lookup, header parse) são cache-locked por pedido. Várias regras a ler ip.geoip.country resultam num único lookup.

Validação: o endpoint POST /v1/waf/dsl/validate parsa a expressão e devolve { valid, error }. O editor no painel chama-o debounced 500 ms; é a mesma rota que valida no save.

Compatibilidade futura: a sintaxe é versionada. Novas funcionalidades (exclusões de regras CRS, lookup em base de dados externa para reputação, etc.) serão adicionadas mantendo backwards-compat. Expressões antigas continuam a funcionar.

Diferença de DSL vs regra simples: regras simples (WafCustomRule) suportam um único <field> <operator> <value> — sem and/or. Use-as quando o caso é simples; use DSL quando precisas de combinar várias condições.

Comparação com Cloudflare WAF: a DSL inspira-se na linguagem de filter expressions da Cloudflare (http.request.uri.path contains "/api"). Sintaxe similar, mas conjuntos de campos e operadores diferentes — a FortFox foca-se nos campos mais comuns e mantém a linguagem deliberadamente pequena.

Próximos passos

← Toda a documentação