Aula 30: NAXSI — WAF alternativo para Nginx: configuração e regras de proteção

O NAXSI — abreviação de Nginx Anti XSS & SQL Injection — é um Web Application Firewall (WAF) de código aberto projetado especificamente para operar como módulo do Nginx. Diferentemente de soluções que dependem de assinaturas extensas e atualizações constantes, o NAXSI adota um modelo de detecção baseado em pontuação e em regras genéricas de anomalias, tornando-o extremamente eficaz contra ataques de injeção SQL, Cross-Site Scripting (XSS), inclusão de arquivos remotos e outras classes de exploração web. Nesta aula avançada do curso Segurança Linux — Do Zero ao Avançado, você mergulhará na instalação, configuração e operação do NAXSI em ambientes Linux reais.

Ao longo da aula, você aprenderá não apenas a compilar o Nginx com o módulo NAXSI, mas também a compreender profundamente sua arquitetura de regras, o modelo de pontuação (score-based detection), o modo de aprendizado (LearningMode) e as estratégias de whitelist. O domínio dessas técnicas permite implantar uma camada adicional de segurança que complementa, e muitas vezes supera, soluções tradicionais em termos de desempenho e flexibilidade. Em nossos projetos na JRT Technology Solutions, nossos especialistas utilizam diariamente o NAXSI para proteger aplicações web críticas de clientes, justamente pela robustez e transparência operacional que ele oferece.

Este conteúdo é voltado para administradores de sistemas, engenheiros DevOps, analistas de segurança e entusiastas que já concluíram as aulas anteriores do curso e possuem familiaridade com linha de comando Linux, configuração do Nginx e conceitos básicos de segurança em aplicações web. Se você seguiu todas as aulas até aqui, já está apto a realizar os procedimentos descritos, incluindo compilação de software, manipulação de arquivos de configuração e teste de políticas de segurança.

Os pré-requisitos para esta aula incluem: uma máquina Linux com distribuição Ubuntu/Debian ou CentOS/RHEL/Rocky Linux, acesso root ou via sudo, Nginx em execução ou possibilidade de compilar uma versão compatível, ferramentas de compilação instaladas (gcc, make, pcre, zlib, openssl) e conhecimento básico de configuração de server blocks. Ao final desta aula, você será capaz de instalar o NAXSI, escrever regras de proteção customizadas, implementar whitelists eficientes, testar bloqueios e diagnosticar problemas comuns — tudo isso com base em procedimentos reais e validados.

O que você vai aprender nesta aula

• Conceitos fundamentais do NAXSI e como ele se diferencia de outros WAFs, como o ModSecurity.
• Arquitetura interna do NAXSI: regras básicas, regras principais, pontuação e limiares de bloqueio.
• Compilação e instalação do Nginx com o módulo NAXSI em Ubuntu/Debian e CentOS/RHEL/Rocky Linux.
• Configuração completa do arquivo nginx.conf com diretivas do NAXSI.
• Criação de regras customizadas, ajuste de pontuação e implementação de whitelists.
• Ativação do modo de aprendizado para evitar falsos positivos e gerar regras de exceção.
• Verificação prática de bloqueios de ataques com curl e análise de logs.
• Diagnóstico e correção de erros comuns, com sintomas e soluções detalhadas.

Pré-requisitos e Ambiente

Antes de iniciar os procedimentos desta aula, assegure-se de que seu ambiente atenda aos seguintes requisitos. Em primeiro lugar, você precisará de um servidor Linux com pelo menos 1 GB de RAM, 2 vCPUs e 10 GB de disco livre. As distribuições recomendadas são Ubuntu 22.04/24.04 LTS, Debian 11/12, CentOS Stream 9, RHEL 9 ou Rocky Linux 9. O acesso deve ser feito como usuário root ou por meio de sudo.

O Nginx é o servidor web base para a instalação do NAXSI, pois este atua como um módulo integrado ao processo do Nginx, e não como um serviço separado. Verifique a versão instalada com o comando nginx -v. Se o Nginx já estiver em produção, você deverá compilar uma versão idêntica à instalada, com o mesmo conjunto de módulos, acrescentando apenas o módulo NAXSI. Isso garante compatibilidade total e evita regressões. Caso o Nginx não esteja instalado, você fará uma instalação limpa a partir do código-fonte.

Tenha também instaladas as ferramentas essenciais de compilação e as bibliotecas de desenvolvimento: build-essential (Ubuntu/Debian) ou Development Tools (CentOS/RHEL), além de pcre, zlib e openssl com seus pacotes -dev ou -devel. Isso é fundamental, pois o processo de compilação do Nginx com NAXSI exige essas dependências para gerar os binários corretamente. Recomendamos também que você tenha uma cópia do código-fonte do NAXSI obtida diretamente do repositório oficial no GitHub.

Por fim, familiarize-se com a estrutura de diretórios do Nginx: /etc/nginx/ para configuração, /var/log/nginx/ para logs e /usr/sbin/nginx para o binário. Ao longo da aula, trabalharemos nesses caminhos. Se você qualificou seu ambiente com esses pré-requisitos, pode prosseguir com segurança. Em nossos projetos na JRT Technology Solutions, sempre padronizamos esses requisitos mínimos para garantir que o processo de compilação e configuração ocorra sem surpresas, e recomendamos que você faça o mesmo.

Conceitos Fundamentais: o que é o NAXSI e por que ele é diferente

O NAXSI é um WAF de terceira geração que trabalha com um modelo de segurança negativo baseado em score. Em vez de manter uma enorme base de assinaturas de ataques específicos — como faz o ModSecurity com o OWASP CRS —, o NAXSI define um conjunto relativamente pequeno de regras básicas (BasicRules) que detectam padrões genéricos de anomalias. Cada regra básica atribui uma pontuação a determinados caracteres ou sequências suspeitas encontradas na requisição HTTP. Ao final da avaliação, o NAXSI soma os pontos de todas as regras acionadas e, se o total ultrapassar um limiar definido (CheckRule), a requisição é bloqueada.

Essa abordagem traz vantagens significativas. Primeiramente, ela reduz drasticamente a superfície de falsos negativos, pois os padrões genéricos detectam variações de ataques ainda desconhecidos, como novos vetores de SQL injection que ainda não possuem assinatura específica. Em segundo lugar, o NAXSI exige muito menos atualizações de regras do que um WAF baseado em assinaturas. O núcleo de regras do NAXSI permanece estável por longos períodos, e novas proteções são implementadas principalmente por meio de whitelists e customizações específicas do site. Isso reduz a carga operacional da equipe de segurança.

Outra característica marcante do NAXSI é o seu desempenho. Por ser um módulo integrado ao Nginx e operar com regras simples e eficientes, o impacto na latência é mínimo, geralmente na casa de poucos milissegundos. Isso o torna uma escolha excelente para aplicações de alta concorrência, onde cada milissegundo conta. Diferentemente de WAFs externos que exigem proxy reverso adicional, o NAXSI processa as requisições no mesmo processo do Nginx, eliminando saltos de rede e reduzindo a complexidade da infraestrutura.

No centro do funcionamento do NAXSI estão dois tipos principais de regras: as MainRules (regras principais) e as BasicRules (regras básicas). As MainRules são definidas no arquivo naxsi_core.rules e contêm a grande maioria das detecções, cobrindo padrões como sequências de caracteres SQL, palavras-chave de comandos e caracteres de escape. As BasicRules, por sua vez, são utilizadas para estender ou customizar a detecção, permitindo criar regras adicionais para casos específicos do seu ambiente. O NAXSI também possui as CheckRules, que definem o limiar de pontuação para diferentes contextos da requisição, como URL, argumentos, cabeçalhos, cookies e corpo do POST.

Por fim, é essencial compreender o conceito de Whitelist no NAXSI. Como o modelo de detecção é genérico, algumas requisições legítimas podem gerar pontuações altas, resultando em falsos positivos. Para lidar com isso, o NAXSI permite criar regras de exceção que zeram ou reduzem a pontuação em contextos específicos, como um parâmetro de busca que contém caracteres especiais. O uso correto de whitelists é o segredo para um WAF eficaz sem interrupções no serviço. Ao longo desta aula, você aprenderá a configurar tudo isso em detalhes.

Arquitetura e Modelo de Detecção do NAXSI

Para operar o NAXSI com maestria, é necessário entender sua arquitetura interna e o fluxo de processamento de uma requisição. Quando uma requisição HTTP chega ao Nginx com o módulo NAXSI ativo, o WAF analisa separadamente cada componente da requisição: a URL, os argumentos da query string, os cabeçalhos HTTP, os cookies e o corpo da mensagem (para métodos POST). Em cada um desses contextos, o NAXSI aplica as regras de detecção definidas e acumula a pontuação correspondente.

As regras de detecção do NAXSI são compostas por quatro elementos principais: MatchZone (a zona onde a regra se aplica, como ARGS, URL, HEADERS, BODY), MatchType (o tipo de casamento, como RX para expressão regular ou STR para string literal), MatchPattern (o padrão a ser detectado) e Score (a pontuação atribuída quando a regra é acionada). Por exemplo, uma regra pode detectar a presença da palavra DROP em argumentos e atribuir 8 pontos a cada ocorrência.

O limiar de bloqueio é definido pelas diretivas CheckRule. Cada CheckRule especifica um contexto e um valor máximo de pontuação permitido. Por exemplo, CheckRule "$SQL >= 8" BLOCK; bloqueia a requisição se a pontuação acumulada na categoria SQL for maior ou igual a 8. O NAXSI categoriza as regras em grupos como SQL, XSS, RFI, UPLOAD, TRAVERSAL, entre outros. Essa categorização permite criar políticas de bloqueio diferenciadas por tipo de ameaça.

Outra característica poderosa do NAXSI é a possibilidade de habilitar o LearningMode. Quando ativado, o NAXSI não bloqueia requisições, mas registra em logs todas as detecções que teriam sido bloqueadas, juntamente com as pontuações obtidas. Essa funcionalidade é extremamente útil durante a implantação inicial, pois permite analisar o tráfego legítimo e criar whitelists precisas antes de ativar o bloqueio real. O LearningMode é ativado por meio da diretiva LearningMode; dentro de um bloco location.

O NAXSI também suporta a criação de regras de exceção (whitelists) com granularidade fina. Uma whitelist pode zerar a pontuação em um contexto específico, para um padrão específico, ou mesmo para uma regra específica identificada pelo seu ID. Essa flexibilidade permite liberar apenas o necessário, mantendo a proteção máxima para o restante do tráfego. A sintaxe de uma whitelist é BasicRule wl:ID "matchzone:pattern";, onde ID é um identificador numérico único atribuído à regra de exceção.

Por fim, é importante destacar que o NAXSI é stateless por padrão: ele analisa cada requisição isoladamente, sem manter estado de sessão. Isso simplifica a operação em clusters e evita problemas de sincronização. Para cenários que exigem análise mais sofisticada, como detecção de força bruta ou rate limiting, recomenda-se combinar o NAXSI com outras camadas, como ngx_http_limit_req_module ou ferramentas externas. Em nossos projetos na JRT Technology Solutions, frequentemente integramos NAXSI com sistemas de monitoramento e SIEM para correlação de eventos e resposta a incidentes.

Passo a Passo: Instalação do NAXSI no Ubuntu/Debian

Nesta seção, você realizará a instalação do NAXSI em sistemas baseados em Debian, como Ubuntu 22.04/24.04 e Debian 11/12. O procedimento consiste em instalar as dependências de compilação, obter o código-fonte do Nginx e do NAXSI, compilar tudo em um único binário e, em seguida, substituir a instalação atual ou instalar do zero. Siga os passos na ordem exata para garantir o sucesso.

Passo 1: Atualizar o sistema e instalar dependências

O primeiro passo é atualizar os repositórios e instalar as ferramentas e bibliotecas necessárias. Esses pacotes incluem o compilador GCC, o utilitário Make, as bibliotecas PCRE para expressões regulares, Zlib para compressão e OpenSSL para suporte a TLS. Execute os comandos abaixo como usuário root ou com sudo:

# Atualiza a lista de pacotes e o sistema
sudo apt update && sudo apt upgrade -y

# Instala as dependências de compilação do Nginx com NAXSI
sudo apt install -y build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev wget git

Cada pacote tem uma função específica. O build-essential fornece o compilador gcc, o make e outras ferramentas de construção. As bibliotecas libpcre3-dev e zlib1g-dev são necessárias para o suporte a expressões regulares e compressão no Nginx. O pacote libssl-dev habilita o módulo HTTPS. Os utilitários wget e git são usados para baixar os códigos-fonte.

Passo 2: Verificar a versão atual do Nginx

Antes de compilar, verifique a versão exata do Nginx instalada no seu sistema. Isso é crucial se você estiver atualizando uma instalação existente, pois a versão compilada deve corresponder exatamente à versão em produção para evitar conflitos de módulos. Execute:

# Exibe a versão do Nginx instalada
nginx -v

A saída esperada será semelhante a esta:

nginx version: nginx/1.24.0

Anote essa versão. Se o Nginx não estiver instalado, você pode escolher a versão estável mais recente disponível no site oficial. Para esta aula, utilizaremos a versão 1.24.0 como referência, mas os passos são idênticos para outras versões.

Passo 3: Baixar os códigos-fonte do Nginx e do NAXSI

Agora, faça o download do código-fonte do Nginx correspondente à sua versão instalada e clone o repositório do NAXSI do GitHub. Execute os comandos abaixo em um diretório temporário, como /usr/local/src:

# Acessa o diretório de fontes
cd /usr/local/src

# Baixa o código-fonte do Nginx 1.24.0
sudo wget http://nginx.org/download/nginx-1.24.0.tar.gz

# Extrai o arquivo compactado
sudo tar -xzvf nginx-1.24.0.tar.gz

# Clona o repositório oficial do NAXSI
sudo git clone https://github.com/nbs-system/naxsi.git

O comando wget baixa o tarball do Nginx. O tar -xzvf extrai o conteúdo do arquivo. O git clone copia o repositório do NAXSI, que contém o código-fonte do módulo e os arquivos de regras padrão. Após a conclusão, você terá dois diretórios: nginx-1.24.0 e naxsi.

Passo 4: Compilar o Nginx com o módulo NAXSI

Entre no diretório do Nginx e execute o script configure com os parâmetros necessários. O parâmetro --add-module adiciona o módulo NAXSI à compilação. Os demais parâmetros definem os caminhos de instalação e os módulos padrão do Nginx. Execute:

# Acessa o diretório do código-fonte do Nginx
cd /usr/local/src/nginx-1.24.0

# Executa o script de configuração com o módulo NAXSI
sudo ./configure \
  --add-module=/usr/local/src/naxsi/naxsi_src \
  --prefix=/etc/nginx \
  --sbin-path=/usr/sbin/nginx \
  --modules-path=/usr/lib/nginx/modules \
  --conf-path=/etc/nginx/nginx.conf \
  --error-log-path=/var/log/nginx/error.log \
  --http-log-path=/var/log/nginx/access.log \
  --pid-path=/var/run/nginx.pid \
  --lock-path=/var/run/nginx.lock \
  --http-client-body-temp-path=/var/cache/nginx/client_temp \
  --http-proxy-temp-path=/var/cache/nginx/proxy_temp \
  --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp \
  --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp \
  --http-scgi-temp-path=/var/cache/nginx/scgi_temp \
  --user=nginx \
  --group=nginx \
  --with-http_ssl_module \
  --with-http_realip_module \
  --with-http_stub_status_module \
  --with-http_v2_module \
  --with-http_gzip_static_module \
  --with-http_sub_module

Cada flag do configure tem uma finalidade específica. A flag --add-module=/usr/local/src/naxsi/naxsi_src é a mais importante, pois instrui o compilador a incluir o NAXSI. As demais flags definem os diretórios de instalação, os caminhos de logs, o usuário e grupo de execução, e habilitam módulos essenciais como SSL, HTTP/2 e status. A saída do configure deve terminar com um resumo da configuração, sem erros.

Passo 5: Compilar e instalar

Após a configuração bem-sucedida, compile o código-fonte e instale os binários gerados. Execute os comandos abaixo. O processo de compilação pode levar alguns minutos, dependendo da velocidade do seu servidor:

# Compila o Nginx com todos os módulos configurados
sudo make -j$(nproc)

# Instala o binário e os arquivos de configuração padrão
sudo make install

O comando make -j$(nproc) acelera a compilação utilizando todos os núcleos de CPU disponíveis. O make install copia o binário para /usr/sbin/nginx e os arquivos de configuração para /etc/nginx/. Após a instalação, verifique se o binário foi substituído corretamente:

# Verifica a versão e os módulos compilados
nginx -V 2>&1 | grep -i naxsi

A saída esperada deve conter o módulo NAXSI na lista de módulos compilados:

--add-module=/usr/local/src/naxsi/naxsi_src

Essa confirmação garante que o módulo NAXSI foi corretamente integrado ao binário do Nginx. Agora, prossiga para a configuração dos arquivos de regras.

Passo a Passo: Instalação do NAXSI no CentOS/RHEL/Rocky Linux

Para sistemas baseados em Red Hat, como CentOS Stream 9, RHEL 9 e Rocky Linux 9, o processo de instalação do NAXSI segue os mesmos princípios, mas com comandos de gerenciamento de pacotes diferentes. Utilizaremos o dnf para instalar as dependências e realizaremos a compilação a partir do código-fonte, exatamente como no caso do Debian/Ubuntu. Siga os passos abaixo com atenção.

Passo 1: Instalar dependências de compilação

O primeiro passo é instalar as ferramentas e bibliotecas de desenvolvimento. No CentOS/RHEL/Rocky, os pacotes têm nomes diferentes dos do Debian. Execute:

# Instala o repositório EPEL e as ferramentas de desenvolvimento
sudo dnf install -y epel-release
sudo dnf groupinstall -y "Development Tools"

# Instala as bibliotecas de desenvolvimento necessárias
sudo dnf install -y pcre pcre-devel zlib zlib-devel openssl openssl-devel wget git

O pacote epel-release adiciona o repositório Extra Packages for Enterprise Linux, que contém pacotes adicionais não incluídos nos repositórios oficiais. O grupo "Development Tools" instala o compilador GCC, o Make e outras ferramentas de construção. As bibliotecas pcre-devel, zlib-devel e openssl-devel fornecem os cabeçalhos necessários para a compilação do Nginx.

Passo 2: Verificar a versão do Nginx e baixar os fontes

Assim como no procedimento para Debian, verifique a versão instalada do Nginx e baixe os códigos-fonte correspondentes. Se o Nginx não estiver instalado, utilize a versão estável mais recente. Execute os comandos abaixo:

# Verifica a versão do Nginx instalada
nginx -v

# Acessa o diretório de fontes
cd /usr/local/src

# Baixa o código-fonte do Nginx 1.24.0
sudo wget http://nginx.org/download/nginx-1.24.0.tar.gz

# Extrai o arquivo compactado
sudo tar -xzvf nginx-1.24.0.tar.gz

# Clona o repositório oficial do NAXSI
sudo git clone https://github.com/nbs-system/naxsi.git

A saída do comando nginx -v exibirá a versão atual, por exemplo nginx version: nginx/1.24.0. O restante dos comandos baixa e extrai os fontes do Nginx e clona o repositório do NAXSI, exatamente como no procedimento anterior.

Passo 3: Compilar e instalar

Agora, compile o Nginx com o módulo NAXSI. O comando configure é o mesmo utilizado no Debian/Ubuntu, pois os parâmetros são independentes da distribuição. Execute:

# Acessa o diretório do código-fonte do Nginx
cd /usr/local/src/nginx-1.24.0

# Configura a compilação com o módulo NAXSI
sudo ./configure \
  --add-module=/usr/local/src/naxsi/naxsi_src \
  --prefix=/etc/nginx \
  --sbin-path=/usr/sbin/nginx \
  --modules-path=/usr/lib/nginx/modules \
  --conf-path=/etc/nginx/nginx.conf \
  --error-log-path=/var/log/nginx/error.log \
  --http-log-path=/var/log/nginx/access.log \
  --pid-path=/var/run/nginx.pid \
  --lock-path=/var/run/nginx.lock \
  --http-client-body-temp-path=/var/cache/nginx/client_temp \
  --http-proxy-temp-path=/var/cache/nginx/proxy_temp \
  --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp \
  --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp \
  --http-scgi-temp-path=/var/cache/nginx/scgi_temp \
  --user=nginx \
  --group=nginx \
  --with-http_ssl_module \
  --with-http_realip_module \
  --with-http_stub_status_module \
  --with-http_v2_module \
  --with-http_gzip_static_module \
  --with-http_sub_module

# Compila e instala
sudo make -j$(nproc)
sudo make install

Após a instalação, verifique novamente se o módulo NAXSI está presente no binário:

# Verifica os módulos compilados
nginx -V 2>&1 | grep -i naxsi

A saída esperada será a linha contendo --add-module=/usr/local/src/naxsi/naxsi_src, confirmando o sucesso da compilação.

Configuração Detalhada do NAXSI: arquivos de regras e diretivas principais

Agora que o módulo NAXSI está compilado e instalado, é hora de configurá-lo. O NAXSI utiliza dois arquivos de regras principais: naxsi_core.rules (regras principais) e naxsi.rules (regras de configuração e whitelist). Você deve copiar esses arquivos do diretório de fontes para o diretório de configuração do Nginx. Execute os comandos abaixo:

# Copia as regras principais do NAXSI para /etc/nginx/
sudo cp /usr/local/src/naxsi/naxsi_config/naxsi_core.rules /etc/nginx/naxsi_core.rules

# Copia o arquivo de regras de configuração e whitelist
sudo cp /usr/local/src/naxsi/naxsi_config/naxsi.rules /etc/nginx/naxsi.rules

O arquivo naxsi_core.rules contém milhares de regras de detecção categorizadas por tipo de ataque. Ele é fornecido pelo projeto NAXSI e raramente precisa ser modificado. O arquivo naxsi.rules contém as BasicRules, CheckRules e Whitelists que você personalizará de acordo com suas necessidades.

O próximo passo é editar o arquivo /etc/nginx/nginx.conf para incluir as diretivas do NAXSI nos blocos http, server e location. Abaixo está um exemplo completo de configuração com NAXSI ativo. Preste atenção aos comentários explicativos:

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    sendfile on;
    keepalive_timeout 65;

    # Inclui as regras principais do NAXSI (MainRules)
    include /etc/nginx/naxsi_core.rules;

    server {
        listen 80;
        server_name exemplo.com.br;

        # Ativa o modo de aprendizado em fase inicial
        # LearningMode;

        # Ativa o processamento das regras do NAXSI
        SecRulesEnabled;

        # Define a URL de bloqueio (página de erro customizada)
        DeniedUrl "/403.html";

        # Inclui as regras de configuração e whitelist
        include /etc/nginx/naxsi.rules;

        # Verificações de pontuação para bloqueio
        CheckRule "$SQL >= 8" BLOCK;
        CheckRule "$RFI >= 8" BLOCK;
        CheckRule "$TRAVERSAL >= 5" BLOCK;
        CheckRule "$XSS >= 8" BLOCK;
        CheckRule "$UPLOAD >= 8" BLOCK;
        CheckRule "$EVADE >= 4" BLOCK;

        location / {
            root /usr/share/nginx/html;
            index index.html;
        }

        location /403.html {
            internal;
            root /usr/share/nginx/html;
            return 403;
        }

        location /admin {
            # Ativa proteção reforçada para área administrativa
            SecRulesEnabled;
            CheckRule "$SQL >= 4" BLOCK;
            CheckRule "$XSS >= 4" BLOCK;
            proxy_pass http://127.0.0.1:8080;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
    }
}

Cada diretiva tem um papel crucial. A diretiva SecRulesEnabled; ativa o processamento das regras do NAXSI para o contexto onde está inserida. A diretiva DeniedUrl define a URL interna para onde as requisições bloqueadas serão redirecionadas. A diretiva CheckRule estabelece os limiares de pontuação por categoria, como $SQL, $XSS, $RFI, $TRAVERSAL, $UPLOAD e $EVADE. Quando a pontuação acumulada em uma categoria ultrapassa o valor definido, a requisição é negada com HTTP 403.

O modo de aprendizado, representado pela diretiva LearningMode;, é fundamental nas primeiras semanas de implantação. Com ela ativa, o NAXSI NÃO bloqueia requisições, mas registra em /var/log/nginx/error.log todas as detecções que teriam sido bloqueadas. Isso permite identificar falsos positivos e criar whitelists antes de ativar o bloqueio real. Para desativar o modo de aprendizado e ativar o bloqueio, basta comentar ou remover a linha LearningMode; e recarregar o Nginx.

O arquivo /etc/nginx/naxsi.rules é onde você define as BasicRules e as Whitelists. Abaixo está um exemplo completo de conteúdo para esse arquivo, com regras comentadas e explicadas:

# Arquivo /etc/nginx/naxsi.rules
# Regras de configuração e whitelist do NAXSI

# ===== Whitelists globais =====

# Libera o parâmetro 'query' do aplicativo de busca, que pode conter caracteres especiais
BasicRule wl:1000 "mz:ARGS|NAME:query";

# Libera o cabeçalho User-Agent para todos os tipos de detecção SQL
BasicRule wl:1001 "mz:HEADERS|NAME:User-Agent";

# Libera o parâmetro 'token' do tipo XSS
BasicRule wl:1002 "mz:ARGS|NAME:token:^[a-zA-Z0-9_-]+$";

# ===== Regras customizadas =====

# Bloqueia acesso direto a arquivos .env, atribuindo pontuação alta
BasicRule str:.env "mz:URL|BODY|ARGS" "s:DENY:10";

# Bloqueia tentativas de path traversal com padrão ../ ou ..\
BasicRule str:../ "mz:URL|ARGS|BODY" "s:TRAVERSAL:8";

# Detecta a presença da string 'union select' em argumentos e corpo
BasicRule str:"union select" "mz:ARGS|BODY" "s:SQL:8";

# ===== Fim do arquivo =====

Nesse arquivo, as whitelists utilizam a sintaxe BasicRule wl:ID "contexto:padrão";. O ID é um número único para cada whitelist. O contexto pode ser mz:ARGS|NAME:query, que significa “apenas o argumento chamado query”. As regras customizadas utilizam BasicRule com o tipo de casamento (str: para string literal), o padrão a detectar, o contexto e a pontuação atribuída. A flag s: define a categoria e o escore, por exemplo s:SQL:8 atribui 8 pontos à categoria SQL.

É importante destacar que o NAXSI já possui milhares de regras de detecção genéricas no arquivo naxsi_core.rules. As customizações no arquivo naxsi.rules servem para refinar a proteção, adicionar regras específicas do seu ambiente ou criar exceções para evitar falsos positivos. Em nossos projetos na JRT Technology Solutions, sempre recomendamos iniciar com o modo de aprendizado ativado e, após coletar dados por pelo menos uma semana, revisar os logs e ajustar as whitelists antes de ativar o bloqueio definitivo.

Verificando a Instalação / Testando a Configuração

Após configurar o NAXSI, é essencial verificar se a instalação está correta e se o WAF está bloqueando requisições maliciosas. O primeiro passo é testar a sintaxe do arquivo de configuração do Nginx. Execute o comando abaixo:

# Testa a sintaxe da configuração do Nginx
sudo nginx -t

A saída esperada, se tudo estiver correto, será:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Em seguida, recarregue o Nginx para aplicar as alterações:

# Recarrega a configuração do Nginx
sudo systemctl reload nginx

# Verifica o status do serviço
sudo systemctl status nginx --no-pager -l | head -20

A saída esperada do status deve mostrar o Nginx ativo e sem erros, similar a:

● nginx.service - A high performance web server and reverse proxy server
   Loaded: loaded (/usr/lib/systemd/system/nginx.service; disabled; vendor preset: disabled)
   Active: active (running) since Sun 2026-08-30 10:15:22 UTC; 5s ago
     Docs: man:nginx(8)
  Process: 12345 ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf (code=exited, status=0/SUCCESS)
 Main PID: 12346 (nginx)
    Tasks: 3 (limit: 4915)
   Memory: 4.2M
   CGroup: /system.slice/nginx.service
           ├─12346 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf
           ├─12347 nginx: worker process
           └─12348 nginx: worker process

Agora, teste o bloqueio de uma tentativa de SQL injection enviando uma requisição maliciosa com curl. Execute:

# Envia uma requisição com payload de SQL injection
curl -v "http://localhost/?id=1' OR '1'='1" 2>&1 | grep -E "HTTP/|403|denied"

Se o NAXSI estiver ativo e configurado corretamente, a saída deve mostrar o código HTTP 403 Forbidden:

< HTTP/1.1 403 Forbidden
< Server: nginx/1.24.0
< Content-Type: text/html
< Content-Length: 153
< Connection: keep-alive

Para confirmar que o bloqueio foi registrado, verifique o log de erros do Nginx:

# Verifica os registros de detecção do NAXSI no log de erros
sudo tail -50 /var/log/nginx/error.log | grep -i naxsi

A saída esperada deve conter as informações da detecção, incluindo a regra acionada e a pontuação:

2026/08/30 10:20:15 [error] 12348#12348: *1 NAXSI_FMT: ip=127.0.0.1&server=localhost&uri=/&id=1000&zone=


Quer aprender na prática com especialistas?
A JRT Technology Solutions oferece treinamentos e implementação de Segurança Linux para equipes corporativas.
  

    

    Falar no WhatsApp