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.
Anatomia de uma regra
Uma regra completa tem:
| Parte | Onde | Exemplo |
|---|---|---|
| Nome | Campo do editor | "Bloquear /admin do exterior" |
| Expressão | Editor de código | http.request.uri starts_with "/admin" and ip.src ne "203.0.113.7" |
| Ação | Dropdown | Bloquear o pedido |
| Prioridade | Campo | 100 (menor = avaliada primeiro) |
| Ativa | Checkbox | ✓ |
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
| Campo | Tipo | O que é |
|---|---|---|
http.request.method | string | GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD |
http.request.uri | string | Caminho + query string (/produtos?cor=azul) |
http.request.path | string | Só o caminho (/produtos) |
http.request.query | string | Só a query string (cor=azul) |
http.request.body | string | Corpo do pedido (POST/PUT) |
http.request.body.size | number | Tamanho do corpo em bytes |
Cabeçalhos
| Campo | Tipo | O que é |
|---|---|---|
http.request.header.user_agent | string | Identificação do browser |
http.request.header.referer | string | Página de onde veio o pedido |
http.request.header.host | string | Domínio pedido |
http.request.header.accept_language | string | Línguas preferidas |
http.request.header.cookie | string | Cookies brutos |
http.request.header["<nome>"] | string | Qualquer cabeçalho por nome |
Origem (IP e geo)
| Campo | Tipo | O que é |
|---|---|---|
ip.src | string | IP do visitante (IPv4 ou IPv6) |
ip.geoip.country | string | Código ISO de 2 letras (PT, US...) |
ip.geoip.city | string | Cidade aproximada |
ip.geoip.asn | number | ASN do provedor |
ip.is_datacenter | bool | Verdadeiro se o IP é de um datacenter |
ip.is_vpn | bool | Verdadeiro se for VPN comercial conhecida |
ip.is_tor | bool | Verdadeiro se for exit node Tor |
Decisão prévia
| Campo | Tipo | O que é |
|---|---|---|
waf.score | number | Pontuação WAF até este ponto (0-100+) |
bot.score | number | Pontuação de bot (0-100) |
bot.is_bot | bool | Conclusão da gestão de bots |
Operadores
Comparação simples
| Operador | Significado | Funciona em |
|---|---|---|
eq | Igual | strings, numbers, bools |
ne | Diferente | strings, numbers, bools |
gt | Maior | numbers |
lt | Menor | numbers |
ge | Maior ou igual | numbers |
le | Menor ou igual | numbers |
Texto
| Operador | Significado | Exemplo |
|---|---|---|
contains | Contém substring | http.request.uri contains "/admin" |
not_contains | Não contém | http.request.uri not_contains "/api" |
starts_with | Começa por | http.request.uri starts_with "/wp-" |
ends_with | Termina em | http.request.uri ends_with ".php" |
matches | Regex (PCRE compatível) | http.request.uri matches "^/users/[0-9]+$" |
Coleções
| Operador | Significado | Exemplo |
|---|---|---|
in | Está em lista | http.request.method in {"GET", "POST"} |
not_in | Não está em lista | ip.geoip.country not_in {"PT", "ES", "FR"} |
Listas usam chavetas e itens separados por vírgula.
Lógicos
| Operador | Significado |
|---|---|
and | E |
or | OU |
not | Negação (not <expr>) |
Usa parênteses para clarificar precedência: (a or b) and c ≠ a or b and c.
Ações
| Ação | O que faz |
|---|---|
block | Bloqueia o pedido, devolve 403 |
challenge | Mostra verificação ao visitante (humano passa, bot fica preso) |
log | Não bloqueia, só anota no log (modo teste) |
allow | Aceita o pedido e salta as restantes regras |
ban_ip | Bloqueia 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
| Limite | Valor |
|---|---|
| Comprimento da expressão | 1024 caracteres |
| Nº de regras DSL por site | 100 por omissão; mais por proposta |
| Profundidade de aninhamento | 10 níveis de parênteses |
| Prioridade | 1 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
- Firewall de aplicação (WAF) — visão geral do sistema onde as regras se inserem.
- Modos normal, auditoria e sombra — testar regras antes de as ativar a sério.
- Gestão de bots — para perceber o que
bot.scoresignifica nas tuas regras.