blog
Servidores

ModSecurity: 7 dias em DetectionOnly antes de bloquear

Procedimento de medição em DetectionOnly por 7 dias, contagem por ID, host e URI, e exceções por escopo de vhost antes de ligar o bloqueio.

JR · · 12 min de leitura · 1 tabela · 10 blocos de código

Resposta curta: não existe número universal: o número que decide é o que o seu próprio `modsec_audit.log` acusa depois de 7 dias com `SecRuleEngine DetectionOnly`, contando requisições que excederam o anomaly score, não hits de regra. Só depois disso escreva exceções e vire para On.

Neste artigo
  1. O que muda entre ModSecurity 2.9, libmodsecurity 3 e LiteSpeed
  2. As diretivas que deixam o audit log contável durante a detecção
  3. Três agregações que transformam log bruto em decisão
  4. Por que somar hits de regra superestima o bloqueio
  5. Exceção por campo e por rota, em vez de desligar a regra
  6. Virar para On, verificar e reverter
  7. Trocar de conjunto de regras sem janela descoberta
  8. Os três erros que repetem

Ligar ModSecurity com um conjunto de regras novo direto em SecRuleEngine On é apostar que nenhuma das milhares de regras vai casar com o checkout, com o wp-json, com o webhook do gateway ou com o upload multipart do cliente. Às vezes dá certo. Quando não dá, o sintoma chega como "o site caiu" três dias depois, sem correlação óbvia.

Existe um caminho que troca a aposta por contagem: subir o conjunto em modo de detecção, deixar o tráfego real passar por um ciclo completo, e só então decidir paranoia level, threshold e exceções a partir do que o log acusou. O número que sustenta a decisão não vem de benchmark de terceiro. Vem do seu modsec_audit.log.

O que muda entre ModSecurity 2.9, libmodsecurity 3 e LiteSpeed

Antes de qualquer coisa, saiba qual engine você está operando. As diretivas abaixo não são intercambiáveis.

Item ModSecurity 2.9 (Apache) libmodsecurity 3 (nginx/connector) LiteSpeed (modo compatível)
Arquivo de config principal modsecurity.conf via IncludeOptional modsecurity.conf carregado pelo connector modsecurity.conf lido pelo LSWS
Audit log serial/concorrente SecAuditLogType Serial ou Concurrent Serial é o caminho previsível Serial
SecAuditLogParts suportado suportado, com partes a menos em algumas versões suportado
Remoção por ID SecRuleRemoveById SecRuleRemoveById SecRuleRemoveById
Escopo por vhost <VirtualHost> / <Directory> location / server contexto do vhost

Confirme a versão antes de copiar qualquer coisa:

httpd -M 2>/dev/null | grep -i security
# ou
nginx -V 2>&1 | tr ' ' '\n' | grep -i modsecurity

No WHM, o conjunto de regras não é escolhido à mão: o ModSecurity Vendors instala e atualiza conjuntos a partir de um arquivo de metadados do fornecedor, conforme a documentação oficial do cPanel. Isso importa para este procedimento por dois motivos. Primeiro, o conjunto do fornecedor pode ser atualizado automaticamente, trocando o universo de regras no meio da sua janela de medição. Segundo, a interface permite habilitar e desabilitar o vendor inteiro, o que é diferente de desabilitar uma regra. Se você vai medir sete dias, decida de forma consciente se a atualização automática do vendor fica ligada durante a janela, e registre a decisão.

As diretivas que deixam o audit log contável durante a detecção

O objetivo é produzir log que permita contar por ID de regra, por host e por URI. Nada mais.

SecRuleEngine DetectionOnly
SecAuditEngine RelevantOnly
SecAuditLogRelevantStatus "^(?:5|4(?!04))"
SecAuditLogParts ABIJDEFHZ
SecAuditLogType Serial
SecAuditLog /var/log/apache2/modsec_audit.log
SecRequestBodyAccess On
SecResponseBodyAccess Off

Os caminhos abaixo e em todos os comandos deste texto são de Apache em Debian/Ubuntu. Em cPanel/WHM o audit log costuma ficar em /usr/local/apache/logs/modsec_audit.log e os logs de domínio em /usr/local/apache/domlogs/; em EL com httpd de distro, /var/log/httpd/. Confirme antes de copiar:

grep -RhsE '^\s*SecAuditLog\s' /usr/local/apache/conf /etc/apache2 /etc/httpd /etc/nginx 2>/dev/null

O porquê de cada escolha:

Um aviso que custa caro ignorar: DetectionOnly não é modo grátis. A engine faz o mesmo trabalho de casamento de regex, o mesmo parsing de corpo, a mesma alocação. A diferença é só a ação final. Se o servidor já está em 80% de CPU, a janela de detecção vai doer igual ao modo bloqueante. Meça loadavg antes e depois, e dimensione o disco: audit log em serial, com I e J ligados, cresce em função direta do volume de requisições relevantes.

Por que sete dias e não um

A janela precisa conter um ciclo operacional inteiro, não um pico de tráfego. Um dia de medição não vê o backup semanal, não vê o cron de madrugada de sexta, não vê a importação de pedidos que o ERP dispara no fim de semana, não vê a publicação de post longa com upload de mídia, não vê o retry do webhook do gateway quando a adquirente teve instabilidade. Esses são exatamente os fluxos que viram falso positivo: corpo grande, payload serializado, header incomum, método PUT ou DELETE em rota REST.

Se o ambiente tem fechamento mensal ou campanha, estenda a janela para cobrir isso. Janela curta demais é o erro mais comum deste procedimento, e ele só aparece depois que você ligou o bloqueio.

Ciclo de medição antes do bloqueioDetectionOnlyEngine avalia, não bloqueiaJanela de sete diasCobre cron, backup, fechamentoAgregar audit logPor ID, host e URIClassificar e excetuarExceção por campo e rotaSecRuleEngine OnReload com reversão pronta
Ciclo completo antes de ligar o bloqueio. Nenhuma etapa depende de benchmark externo: a decisão sai do seu modsec_audit.log.

Três agregações que transformam log bruto em decisão

Com o log rodando, o trabalho é contar. Três agregações bastam para decidir.

Quantas vezes cada ID de regra apareceu:

grep -oP '\[id "\d+"\]' /var/log/apache2/modsec_audit.log \
  | sort | uniq -c | sort -rn | head -40

Quais hosts concentram os eventos:

grep -oP '^Host: .*' /var/log/apache2/modsec_audit.log \
  | sort | uniq -c | sort -rn | head -30

Quais URIs concentram os eventos (primeira linha da requisição, parte B):

grep -oP '^(GET|POST|PUT|DELETE|PATCH) \S+' /var/log/apache2/modsec_audit.log \
  | awk '{print $1, $2}' | sort | uniq -c | sort -rn | head -40

Essas contagens são propositalmente simples. Elas rodam em qualquer servidor, sem instalar parser, e o resultado é verificável por quem vai aprovar a mudança. Se o volume for alto, corte a janela com awk por intervalo de data antes de agregar, ou use mlogc e um coletor externo.

O número que você está procurando é um só: quantas requisições teriam sido bloqueadas, e quantas delas são tráfego legítimo. A separação não é automática. É trabalho manual de olhar o top de IDs e classificar.

Como separar ataque de fluxo legítimo

Heurísticas que funcionam na prática, em ordem de confiança:

  1. Origem autenticada. Se o evento tem cookie de sessão válido e veio depois de login, é quase sempre fluxo do cliente, não varredura.
  2. URI de API conhecida. /wp-json/, /xmlrpc.php, /api/v1/, rotas de webhook do gateway. Varredura também bate nesses caminhos, então cruze com o IP de origem: faixa da adquirente ou do ERP é legítimo; IP residencial estrangeiro em rajada não é.
  3. Repetição com o mesmo payload em horário de cron. Importação, sincronização e backup geram evento com assinatura idêntica em janela fixa.
  4. Content-Type multipart com J preenchido. Upload de mídia pelo editor dispara regras de detecção de arquivo e de corpo. Compare com o files_tmpname da parte J.
  5. Nenhuma das anteriores e ID da família de SQLi/RCE/LFI com payload clássico. Trate como ataque e não crie exceção.

Monte uma planilha com quatro colunas: ID da regra, contagem, host, veredito (ataque / legítimo / inconclusivo). Inconclusivo volta para o log e se resolve com mais uma janela, não com exceção no escuro.

Por que somar hits de regra superestima o bloqueio

Aqui mora a confusão que mais estraga a decisão. No OWASP CRS 4.x, a maioria das regras de detecção não bloqueia: ela soma pontos numa variável de anomalia. O bloqueio acontece na regra de avaliação final, quando o score acumulado da requisição ultrapassa o threshold de entrada ou de saída.

Consequência prática: contar "IDs que casaram" superestima o bloqueio. Uma requisição pode casar com três regras de severidade baixa e ainda ficar abaixo do limite. O que você precisa contar é requisições cujo score agregado passaria do threshold, não hits de regra.

No CRS, o evento relevante traz a mensagem da regra de avaliação com o score total da transação. Isole esses registros antes de concluir:

grep -i 'Inbound Anomaly Score Exceeded' /var/log/apache2/modsec_audit.log | wc -l

Esse número, e não o total de hits, é a estimativa de requisições que teriam sido bloqueadas com o threshold vigente no crs-setup.conf. Rode as duas contagens e guarde as duas. A diferença entre elas é a sua margem para aumentar paranoia level sem aumentar bloqueio.

Escolhendo paranoia level e threshold com a contagem na mão

O crs-setup.conf controla os dois. Paranoia level mais alto habilita famílias adicionais de regra, que somam mais pontos; threshold mais baixo bloqueia com menos pontos. Eles se multiplicam, não se somam.

A leitura da sua planilha indica o caminho:

Mexer no threshold global é o último recurso, porque ele vale para todo mundo no servidor, inclusive para o vhost que não tinha problema nenhum.

Da contagem ao paranoia level e thresholdContar hits por IDSuperestima o bloqueio realContar anomaly score excedidoRequisições que seriam bloqueadasScore excedido só em ataquesSuba paranoia level um degrauScore excedido em poucos IDs legítimosEscreva exceção, não mexa no thresholdScore excedido espalhadoBaixe paranoia level e remeça
Caminho de decisão a partir das duas contagens. A diferença entre hits e score excedido é a margem para endurecer sem bloquear tráfego legítimo.

Exceção por campo e por rota, em vez de desligar a regra

Três diretivas resolvem quase tudo, em ordem crescente de precisão:

# remove a regra inteira: use só quando o ID não serve ao seu ambiente
SecRuleRemoveById 942100

# remove uma faixa ou uma tag
SecRuleRemoveByTag "attack-protocol"

# mantém a regra, exclui um alvo específico dela
SecRuleUpdateTargetById 942100 "!ARGS:conteudo_post"

Prefira sempre SecRuleUpdateTargetById. Ele mantém a proteção para todos os outros parâmetros e abre exceção só para o campo que gerou o falso positivo. Desligar a regra inteira por causa de um campo de editor de texto é jogar fora cobertura.

E aplique no escopo mínimo. Em Apache:

<VirtualHost *:443>
    ServerName loja.exemplo.com.br
    <LocationMatch "^/webhook/pagamento">
        SecRuleUpdateTargetById 942190 "!REQUEST_BODY"
        SecRuleUpdateTargetById 920470 "!REQUEST_HEADERS:Content-Type"
    </LocationMatch>
</VirtualHost>

(exemplo fictício de host e rota; os IDs devem vir da sua contagem, não daqui)

Repare que o exemplo não toca em 949110. Essa é a regra de avaliação de anomalia inbound do CRS: removê-la dentro de um LocationMatch não abre exceção para um campo, desliga o bloqueio inteiro naquela rota, mantendo só a pontuação. Isso é o oposto de exceção por escopo. Existe um uso legítimo, como paliativo de horas enquanto você coleta mais uma janela sobre um incidente, e com data marcada para sair do arquivo. Fora disso, exceção se escreve no ID de detecção que pontuou, não na regra que decide.

No WHM, cuidado com uma armadilha de manutenção: desabilitar regra pela interface e editar arquivo de vendor à mão não são a mesma coisa. A documentação do cPanel descreve que conjuntos de fornecedor são instalados e atualizados pelo mecanismo de vendors, a partir do arquivo de metadados do fornecedor. A conclusão operacional é minha, não da página: se a atualização substitui os arquivos do conjunto, qualquer edição sua dentro da árvore do vendor tem que ser tratada como volátil. Como prática, mantenha suas exceções em arquivo próprio, carregado depois do conjunto, fora da árvore do fornecedor, e valide após a primeira atualização se as exceções continuam valendo.

Virar para On, verificar e reverter

A ordem importa.

O que precisa estar pronto antes de trocar para SecRuleEngine On

  1. Exceções commitadas em arquivo versionado, fora do diretório do vendor.
  2. apachectl configtest (ou nginx -t) limpo.
  3. Trocar para SecRuleEngine On e recarregar, não reiniciar, se a engine suportar reload gracioso.

Comparar 403 por vhost nas duas primeiras horas

Nas primeiras duas horas, compare taxa de 403 por vhost antes e depois, usando o access log, não o audit log:

# Debian/Ubuntu; em cPanel use /usr/local/apache/domlogs/dominio.com.br
awk '$9==403 {print $7}' /var/log/apache2/dominio-access.log \
  | sort | uniq -c | sort -rn | head -20

Se aparecer URI que você classificou como legítima na planilha, a exceção não pegou. Verifique escopo e ordem de carregamento antes de culpar a regra.

Execute também um smoke test funcional dos fluxos críticos: login, checkout completo, publicação de post com upload, chamada autenticada à API, disparo manual do webhook. Esses cinco cobrem a maior parte dos falsos positivos que sobrevivem à medição.

Voltar para DetectionOnly sem perder a base de comparação

A reversão é uma linha: voltar SecRuleEngine para DetectionOnly e recarregar. Não desinstale o conjunto, não desabilite o vendor, não limpe exceção. Você perde a base de comparação. Volte para detecção, colete mais uma janela sobre o incidente específico, corrija a exceção, suba de novo.

Tenha o comando de reversão pronto e testado antes de virar para On. Reverter sob pressão com configtest quebrado é o que transforma meia hora de indisponibilidade em duas.

Trocar de conjunto de regras sem janela descoberta

A mesma lógica serve para migrar de um conjunto para outro, por exemplo de um conjunto de fornecedor do painel para o OWASP CRS 4.x, ou entre vendors.

O erro é remover o antigo e instalar o novo no mesmo reload. Entre um e outro existe uma janela sem proteção, e depois dela você não tem com o que comparar.

O caminho sem buraco:

  1. Mantenha o conjunto atual em SecRuleEngine On, como está.
  2. Instale o novo conjunto em paralelo, com suas regras carregadas mas em modo de detecção. Em ModSecurity 2.9 isso se faz colocando o novo conjunto depois, com as ações de disrupção neutralizadas via SecDefaultAction "phase:2,pass,log" no escopo do include do conjunto novo. Teste em homologação primeiro: a ordem de SecDefaultAction e de SecRuleEngine por contexto tem pegadinhas de herança.
  3. Deixe rodar a mesma janela de sete dias.
  4. Compare os hits dos dois conjuntos no mesmo log, pelas faixas de ID. CRS usa faixas conhecidas (9xxxxx); conjuntos de fornecedor usam faixas próprias documentadas pelo fornecedor. A contagem por faixa responde se o novo cobre o que o antigo pegava.
  5. Só depois da comparação, remova o antigo e vire o novo para bloqueio.

A pergunta que a comparação responde não é "qual conjunto tem mais regras". É "quais eventos o antigo pegava que o novo não pega, e quais eventos novos o novo gera em tráfego que eu já classifiquei como legítimo". Com as duas listas lado a lado, a troca deixa de ser fé no fornecedor.

Os três erros que repetem

Janela curta. Medir 24 horas e concluir. O cron semanal, a importação de fim de mês e o retry do gateway não couberam na amostra. O falso positivo aparece em produção, com bloqueio ligado.

Achar que detecção é grátis. DetectionOnly gasta a mesma CPU de casamento de regra e ainda escreve disco. Em servidor apertado, a janela de medição pode ser o evento de capacidade, não a virada para On. Dimensione antes.

Confundir hit de regra com bloqueio. No CRS, somar os [id ...] do log superestima o impacto, porque a maioria das regras só pontua. Conte as requisições que excederam o anomaly score. A diferença entre as duas contagens é informação, não ruído: ela mostra quanto espaço você tem para endurecer sem quebrar nada.

O conjunto de regras bom é o que você conseguiu justificar com número extraído do seu log. Qualquer outro critério é preferência de quem instalou.

Referências

  1. Documentação oficial (cpanel) — ModSecurity Vendors. Consultado em 2026-09-25.
Leia também