owasp-modsecurity/modsecurityModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis.
O Libmodsecurity é um dos componentes do projeto ModSecurity v3. A base de código da biblioteca serve como interface para os Conectores do ModSecurity, recebendo tráfego web e aplicando o processamento tradicional do ModSecurity. Em geral, fornece a capacidade de carregar/interpretar regras escritas no formato SecRules do ModSecurity e aplicá-las ao conteúdo HTTP fornecido pela sua aplicação através dos Conectores.
Se você está procurando o ModSecurity para Apache (também conhecido como ModSecurity v2.x), ele ainda está em manutenção e disponível aqui.
O Libmodsecurity é uma reescrita completa da plataforma ModSecurity. Quando foi concebido inicialmente, o projeto ModSecurity começou apenas como um módulo Apache. Com o tempo, o projeto foi estendido, devido à demanda popular, para suportar outras plataformas, incluindo (mas não se limitando a) Nginx e IIS. Para atender à crescente demanda por suporte a plataformas adicionais, tornou-se necessário remover as dependências do Apache subjacentes a este projeto, tornando-o mais independente de plataforma.
Como resultado deste objetivo, reestruturamos o Libmodsecurity de modo que ele não dependa mais do servidor web Apache (tanto na compilação quanto durante a execução). Um efeito colateral disso é que, em todas as plataformas, os usuários podem esperar um desempenho aumentado. Além disso, aproveitamos esta oportunidade para estabelecer as bases para algumas novas funcionalidades que os usuários há muito desejam. Por exemplo, pretendemos suportar nativamente logs de auditoria no formato JSON, juntamente com uma série de outras funcionalidades em versões futuras.
O ramo 'ModSecurity' já não contém a lógica tradicional de módulo (para Nginx, Apache e IIS) que tradicionalmente era empacotada toda junta. Em vez disso, este ramo contém apenas a parte da biblioteca (libmodsecurity) para este projeto. Esta biblioteca é consumida pelo que chamamos de 'Conectores', que farão a interface com o seu servidor web e fornecerão à biblioteca um formato comum que ela entende. Cada um destes conectores é mantido como um projeto GitHub separado. Por exemplo, o conector Nginx é fornecido pelo projeto ModSecurity-nginx (https://github.com/owasp-modsecurity/ModSecurity-nginx).
Manter esses conectores separados permite que cada projeto tenha ciclos de lançamento, problemas e árvores de desenvolvimento diferentes. Além disso, significa que quando você instala o ModSecurity v3, você obtém exatamente o que precisa, sem extras que não usará.
Antes de iniciar o processo de compilação, certifique-se de que todas as
dependências necessárias estão instaladas.
Consulte as seções Dependências e Submódulos Git para mais informações.
Após a compilação, certifique-se de que não há problemas na sua
construção/plataforma.
Recomendamos fortemente executar os testes unitários e os testes de regressão.
Esses utilitários de teste estão localizados na subpasta tests/.
Como uma biblioteca dinâmica, o libmodsecurity deve ser instalado em um local
onde seu sistema operacional possa encontrar bibliotecas dinâmicas.
Em sistemas do tipo Unix, o projeto usa autotools para o processo de compilação.
Se você está trabalhando com um checkout git, certifique-se de clonar o
repositório recursivamente ou inicializar todos os submódulos antes de
compilar.
Consulte também a seção Submódulos Git.
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity
Este repositório usa submódulos git. Após clonar, certifique-se de inicializar e buscar todos os submódulos:
git submodule update --init --recursive
Você pode verificar se todos os submódulos foram inicializados corretamente com:
git submodule status
Submódulos que foram inicializados corretamente mostram um hash de commit.
Um - à esquerda indica que o submódulo não foi inicializado.
Você pode então iniciar o processo de compilação:
./build.sh
./configure
make
sudo make install
Detalhes sobre compilações específicas para distribuições podem ser encontrados em nossa Wiki: Receitas de Compilação
As informações de compilação para Windows podem ser encontradas aqui.
O processamento de expressões regulares nas SecRules é implementado através
do utilitário Regex (src/utils/regex.*).
Por padrão, o ModSecurity usa PCRE2 para manipulação de regex.
Isso é usado por operadores como @rx, @rxGlobal e @verifyCC.
Comportamento em tempo de compilação:
--with-pcre for explicitamente
fornecido (WITH_PCRE).Em outras palavras, as compilações atuais esperam PCRE2 a menos que explicitamente configurado de outra forma.
Todas as outras dependências estão relacionadas a operadores especificados dentro das SecRules ou diretivas de configuração e podem não ser necessárias para a compilação.
libinjection é necessário para os operadores @detectXSS e @detectSQL.curl é necessário para a diretiva SecRemoteRules.Se essas bibliotecas estiverem ausentes, o ModSecurity será compilado sem suporte para os respectivos operadores ou diretivas.
O repositório inclui os seguintes submódulos:
others/libinjection – usado pelos operadores @detectSQLi e @detectXSS.
others/mbedtls (subconjunto TF-PSA-Crypto) – usado para funções
criptográficas e auxiliares (ex.: hashing, base64).
Nota: O layout mais recente do mbedTLS v4 não é compatível com a estrutura antiga do v3. A estrutura interna mudou significativamente e muitos componentes foram movidos para submódulos (ex.: TF-PSA-Crypto).
Após mesclar o PR #3532, é necessário executar:
git submodule update --init --recursive
Isso garante que todos os submódulos necessários sejam obtidos. Sem esta etapa, o projeto não será compilado com sucesso.
Você pode verificar se todos os submódulos foram inicializados corretamente com:
git submodule status
Exemplo de saída:
bc625d5... bindings/python
2117822... others/libinjection (v4.0.0)
0fe989b... others/mbedtls (v4.1.0)
a3d4405... test/test-cases/secrules-language-tests
Se um submódulo estiver faltando, ele será mostrado com um - à esquerda,
por exemplo:
-bc625d5... bindings/python
others/libinjection e others/mbedtls são efetivamente necessários para
compilações a partir do código fonte e devem ser inicializados antes de
compilar.
Várias bibliotecas externas são opcionais e habilitam funcionalidades adicionais, incluindo:
libcurl – necessário para SecRemoteRules
LMDB – suporte a armazenamento persistente
Lua – suporte a scripts
Bibliotecas XML – processamento XML estendido
GeoIP (legado) / MaxMind
A API C GeoIP legada (libGeoIP) está obsoleta e não é mais mantida pela MaxMind. O repositório upstream foi arquivado e não deve ser usado para novas implementações.
Em vez disso, o ModSecurity suporta a moderna API MaxMind DB (libmaxminddb), que é ativamente mantida.
Durante a configuração, você pode ver algo como:
+ GeoIP/MaxMind ....found
* (MaxMind) v1.12.2
-lmaxminddb , -I/usr/include/x86_64-linux-gnu
Isso indica que libmaxminddb está sendo usado (recomendado).
É fortemente recomendado usar MaxMind DB em vez da biblioteca GeoIP legada.
A documentação da biblioteca está escrita dentro do código no formato Doxygen. Para gerar esta documentação, utilize o utilitário doxygen com o arquivo de configuração fornecido, "doxygen.cfg", localizado na subpasta "doc/". Isso gerará documentação formatada em HTML incluindo exemplos de uso.
A biblioteca fornece uma interface C++ e C. Alguns recursos estão atualmente disponíveis apenas através da interface C++, por exemplo, a capacidade de criar um mecanismo de logging personalizado (consulte o teste de regressão para verificar como esses mecanismos de logging funcionam). O objetivo é que ambas as APIs (C, C++) forneçam a mesma funcionalidade; se você encontrar um aspecto da API que está faltando em uma interface específica, por favor, abra uma issue.
Dentro da subpasta examples, há exemplos simples de como usar a API. Abaixo, alguns são ilustrados:
using ModSecurity::ModSecurity;
using ModSecurity::Rules;
using ModSecurity::Transaction;
ModSecurity *modsec;
ModSecurity::Rules *rules;
modsec = new ModSecurity();
rules = new Rules();
rules->loadFromUri(rules_file);
Transaction *modsecTransaction = new Transaction(modsec, rules);
modsecTransaction->processConnection("127.0.0.1");
if (modsecTransaction->intervention()) {
std::cout << "There is an intervention" << std::endl;
}
#include "modsecurity/modsecurity.h"
#include "modsecurity/transaction.h"
char main_rule_uri[] = "basic_rules.conf";
int main (int argc, char **argv)
{
ModSecurity *modsec = NULL;
Transaction *transaction = NULL;
Rules *rules = NULL;
modsec = msc_init();
rules = msc_create_rules_set();
msc_rules_add_file(rules, main_rule_uri);
transaction = msc_new_transaction(modsec, rules);
msc_process_connection(transaction, "127.0.0.1");
msc_process_uri(transaction, "http://www.modsecurity.org/test?key1=value1&key2=value2&key3=value3&test=args&test=test");
msc_process_request_headers(transaction);
msc_process_request_body(transaction);
msc_process_response_headers(transaction);
msc_process_response_body(transaction);
return 0;
}
Você é mais do que bem-vindo para contribuir com este projeto e esperamos crescer a comunidade em torno desta nova versão do ModSecurity. Áreas de interesse incluem: Novas funcionalidades, correções, relatórios de bugs, suporte para usuários iniciantes, ou qualquer coisa com a qual você esteja disposto a ajudar.
Preferimos ter seu patch na infraestrutura do GitHub para facilitar nosso trabalho de revisão e nossa integração de Q.A. O GitHub fornece excelente documentação sobre como realizar "Pull Requests", mais informações disponíveis aqui: https://help.github.com/articles/using-pull-requests/
Por favor, respeite o estilo de codificação. Pull requests podem incluir vários commits, então forneça uma correção ou uma funcionalidade por commit. Não altere nada fora do escopo do seu trabalho alvo (ex.: estilo de codificação em uma função que você tenha passado). Para mais informações sobre o estilo de codificação usado neste projeto, por favor, verifique: https://www.chromium.org/blink/coding-style
Forneça mensagens de commit explicativas. Sua primeira linha deve destacar os pontos principais do seu patch; a terceira linha em diante devem fornecer uma explicação mais detalhada/detalhes técnicos sobre seu patch. A explicação do patch é valiosa durante o processo de revisão.
Dentro do nosso código há vários itens marcados como TODO ou FIXME que podem precisar de sua atenção. Verifique a lista de itens executando um grep:
$ cd /path/to/modsecurity-nginx
$ egrep -Rin "TODO|FIXME" -R *
Uma lista TODO também está disponível como parte da documentação do Doxygen.
Juntamente com os testes manuais, recomendamos fortemente que você use nossos testes de regressão e testes unitários. Se você implementou um operador, não se esqueça de criar testes unitários para ele. Se você implementar qualquer outra coisa, é encorajado que desenvolva testes de regressão complementares para isso.
Os utilitários de teste de regressão e teste unitário são nativos e não exigem nenhuma ferramenta ou script externo, embora você precise buscar os casos de teste de outros repositórios, pois eles são compartilhados com outras versões do ModSecurity; esses outros repositórios são submódulos git. Para buscar o repositório de submódulos e executar os utilitários, siga os comandos listados abaixo:
$ cd /path/to/your/ModSecurity
$ git submodule update --init --recursive
$ make check
Antes de iniciar o processo de depuração, certifique-se de onde está o seu bug. O problema pode estar no seu conector ou no libmodsecurity. Para identificar onde está o bug, recomenda-se que você desenvolva um teste de regressão que imite o cenário onde o bug está ocorrendo. Se o bug for reproduzível com o utilitário de teste de regressão, será muito mais simples depurá-lo e garantir que nunca mais ocorra. No Linux, recomenda-se que qualquer pessoa que realize depuração utilize gdb e/ou valgrind conforme necessário.
Durante o tempo de configuração/compilação, você pode querer desabilitar a otimização do compilador, tornando seus "back traces" populados com dados legíveis. Use as CFLAGS para desabilitar os parâmetros de otimização da compilação:
$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure --enable-assertions=yes
$ make
$ sudo make install
"Assertivas nos permitem documentar suposições e detectar violações no início do processo de desenvolvimento. Além disso, assertivas nos permitem detectar violações com um mínimo de esforço." https://dl.acm.org/doi/pdf/10.1145/240964.240969
Recomenda-se usar assertivas onde aplicável e habilitá-las com '--enable-assertions=yes' durante o fluxo de trabalho de teste e depuração.
A árvore fonte inclui uma ferramenta de Benchmark que pode ajudar a medir o
desempenho da biblioteca. A ferramenta está localizada no diretório
test/benchmark/. O processo de compilação também cria o binário aqui, então
você terá a ferramenta após a conclusão da compilação.
Para executar, basta digitar:
cd test/benchmark
$ ./benchmark
Doing 1000000 transactions...
Você também pode passar um valor menor:
$ ./benchmark 1000
Doing 1000 transactions...
Para medir o tempo:
$ time ./benchmark 1000
Doing 1000 transactions...
real 0m0.351s
user 0m0.337s
sys 0m0.022s
Isso é muito rápido porque o benchmark usa a configuração mínima
modsecurity.conf.default, que não inclui muitas regras:
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
Para medir com regras reais, execute um dos scripts de download no mesmo diretório:
$ ./download-owasp-v3-rules.sh
Cloning into 'owasp-v3'...
remote: Enumerating objects: 33007, done.
remote: Counting objects: 100% (2581/2581), done.
remote: Compressing objects: 100% (907/907), done.
remote: Total 33007 (delta 2151), reused 2004 (delta 1638), pack-reused 30426
Receiving objects: 100% (33007/33007), 9.02 MiB | 16.21 MiB/s, done.
Resolving deltas: 100% (25927/25927), done.
Switched to a new branch 'tag3.0.2'
/path/to/ModSecurity/test/benchmark
Done.
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
Include "owasp-v3/crs-setup.conf.example"
Include "owasp-v3/rules/*.conf"
Agora o comando dará um valor muito maior.
A ferramenta é uma aplicação wrapper direta que utiliza a biblioteca. Ela cria uma instância do ModSecurity e uma instância do RuleSet, depois executa um loop com base no número especificado. Dentro deste loop, ela cria um objeto Transaction para emular transações HTTP reais.
Cada transação é uma requisição HTTP/1.1 GET com alguns parâmetros GET. Cabeçalhos comuns são adicionados, seguidos pelos cabeçalhos de resposta e um corpo XML. Entre as fases, a ferramenta verifica se ocorreu uma intervenção. Todas as transações são criadas com os mesmos dados.
Note que a ferramenta não chama a última fase (logging).
Lembre-se de resetar o basic_rules.conf se você quiser tentar com um conjunto
de regras diferente.
Se você está enfrentando um problema de configuração ou algo não está funcionando como esperado, por favor, use a lista de e-mails de usuários do ModSecurity. Issues no GitHub também são bem-vindas, mas preferimos que os usuários façam perguntas primeiro na lista de e-mails para que você possa alcançar toda a comunidade. Além disso, não se esqueça de procurar por issues existentes antes de abrir uma nova.
Se você vai abrir uma nova issue no GitHub, não se esqueça de nos informar a versão do seu libmodsecurity e a versão de um conector específico, se houver.
Por favor, não torne público nenhum problema de segurança. Entre em contato conosco em: [email protected] reportando o problema. Assim que o problema for corrigido, seu crédito será dado.
Estamos abertos a discutir qualquer nova solicitação de funcionalidade com a comunidade através das listas de e-mails. Alternativamente, sinta-se à vontade para abrir issues no GitHub solicitando novas funcionalidades. Antes de abrir uma nova issue, verifique se já existe uma aberta sobre o mesmo tópico.
O design do libModSecurity permite a integração com bindings. Há um esforço para evitar quebrar a compatibilidade da API [binária] para facilitar a integração com possíveis bindings. Atualmente, há alguns projetos notáveis mantidos pela comunidade:
Ter nossos pacotes nas distribuições em tempo hábil é um desejo que temos, então nos informe se há algo que possamos fazer para facilitar seu trabalho como empacotador.
O desenvolvimento do ModSecurity é patrocinado pela Trustwave. O patrocínio terminará em 1º de julho de 2024. Informações adicionais podem ser encontradas aqui https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/
Um - à esquerda indica que o submódulo não foi inicializado ou obtido.
test/test-cases/secrules-language-tests – conjunto de testes de
conformidade e regressão compartilhados das SecRules, usado pelo
make check.
bindings/python – bindings Python para ModSecurity (não necessário para
compilação da biblioteca principal).