owasp-modsecurity/modsecurity
ModSecurity es un motor de cortafuegos de aplicaciones web (WAF) de código abierto y multiplataforma para Apache, IIS y Nginx. Cuenta con un robusto lenguaje de programación basado en eventos que proporciona protección contra una amplia gama de ataques contra aplicaciones web y permite la monitorización del tráfico HTTP, el registro y el análisis en tiempo real.
Libmodsecurity es uno de los componentes del proyecto ModSecurity v3. El código base de la biblioteca sirve como interfaz para los conectores de ModSecurity, que reciben tráfico web y aplican el procesamiento tradicional de ModSecurity. En general, proporciona la capacidad de cargar/interpretar reglas escritas en el formato SecRules de ModSecurity y aplicarlas al contenido HTTP proporcionado por su aplicación a través de Conectores.
Si busca ModSecurity para Apache (también conocido como ModSecurity v2.x), aún está en mantenimiento y disponible: aquí.
Libmodsecurity es una reescritura completa de la plataforma ModSecurity. Cuando se concibió originalmente, el proyecto ModSecurity comenzó como un simple módulo de Apache. Con el tiempo, el proyecto se ha ampliado, debido a la demanda popular, para soportar otras plataformas que incluyen (pero no se limitan a) Nginx e IIS. Para satisfacer la creciente demanda de soporte para plataformas adicionales, se ha vuelto necesario eliminar las dependencias de Apache subyacentes a este proyecto, haciéndolo más independiente de la plataforma.
Como resultado de este objetivo, hemos rediseñado Libmodsecurity de modo que ya no depende del servidor web Apache (tanto en compilación como en tiempo de ejecución). Un efecto secundario de esto es que en todas las plataformas los usuarios pueden esperar un mayor rendimiento. Además, hemos aprovechado esta oportunidad para sentar las bases de algunas nuevas funcionalidades que los usuarios han estado buscando durante mucho tiempo. Por ejemplo, estamos buscando soportar de forma nativa los registros de auditoría en formato JSON, junto con una serie de otras funcionalidades en versiones futuras.
La rama 'ModSecurity' ya no contiene la lógica de módulo tradicional (para Nginx, Apache e IIS) que tradicionalmente se empaquetaba junta. En cambio, esta rama solo contiene la parte de la biblioteca (libmodsecurity) para este proyecto. Esta biblioteca es consumida por lo que hemos denominado 'Conectores'. Estos conectores interactuarán con su servidor web y proporcionarán a la biblioteca un formato común que ella entienda. Cada uno de estos conectores se mantiene como un proyecto separado en GitHub. Por ejemplo, el conector para Nginx es proporcionado por el proyecto ModSecurity-nginx (https://github.com/owasp-modsecurity/ModSecurity-nginx).
Mantener estos conectores separados permite que cada proyecto tenga diferentes ciclos de lanzamiento, problemas y árboles de desarrollo. Además, significa que cuando instale ModSecurity v3, obtendrá exactamente lo que necesita, sin extras que no utilizará.
Antes de iniciar el proceso de compilación, asegúrese de que todas las dependencias requeridas estén instaladas.
Consulte la sección Dependencias y Submódulos de Git para obtener más información.
Después de la compilación, asegúrese de que no haya problemas en su compilación/plataforma.
Recomendamos encarecidamente ejecutar las pruebas unitarias y las pruebas de regresión. Estas utilidades de prueba se encuentran en la subcarpeta tests/.
Como biblioteca dinámica, libmodsecurity debe instalarse en una ubicación donde su sistema operativo pueda encontrar bibliotecas dinámicas.
En sistemas similares a Unix, el proyecto utiliza autotools para el proceso de compilación.
Si está trabajando con un checkout de git, asegúrese de clonar el repositorio de forma recursiva o inicializar todos los submódulos antes de compilar.
Consulte también la sección Submódulos de Git.
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity
Este repositorio utiliza submódulos de git. Después de clonar, asegúrese de inicializar y obtener todos los submódulos:
git submodule update --init --recursive
Puede verificar que todos los submódulos estén correctamente inicializados con:
git submodule status
Los submódulos que están inicializados correctamente muestran un hash de commit.
Un - inicial indica que el submódulo no ha sido inicializado.
Luego puede iniciar el proceso de compilación:
./build.sh
./configure
make
sudo make install
Los detalles sobre compilaciones específicas de distribuciones se pueden encontrar en nuestra Wiki: Recetas de compilación
La información de compilación para Windows se puede encontrar aquí.
El procesamiento de expresiones regulares en SecRules se implementa mediante la utilidad Regex (src/utils/regex.*).
Por defecto, ModSecurity utiliza PCRE2 para el manejo de expresiones regulares.
Esto es utilizado por operadores como @rx, @rxGlobal y @verifyCC.
Comportamiento en tiempo de compilación:
--with-pcre (WITH_PCRE).En otras palabras, las compilaciones actuales esperan PCRE2 a menos que se configure explícitamente lo contrario.
Todas las demás dependencias están relacionadas con operadores especificados dentro de SecRules o directivas de configuración y pueden no ser necesarias para la compilación.
libinjection es necesario para los operadores @detectXSS y @detectSQL.curl es necesario para la directiva SecRemoteRules.Si faltan esas bibliotecas, ModSecurity se compilará sin soporte para los operadores o directivas respectivos.
El repositorio incluye los siguientes submódulos:
others/libinjection – utilizado por los operadores @detectSQLi y @detectXSS.
others/mbedtls (subconjunto TF-PSA-Crypto) – utilizado para funciones criptográficas y ayudantes (por ejemplo, hash, base64).
Nota: La disposición más reciente de mbedTLS v4 no es compatible con la estructura anterior de v3. La estructura interna ha cambiado significativamente y muchos componentes se han movido a submódulos (por ejemplo, TF-PSA-Crypto).
Después de fusionar el PR #3532, es necesario ejecutar:
git submodule update --init --recursive
Esto asegura que se obtengan todos los submódulos requeridos. Sin este paso, el proyecto no se compilará correctamente.
Puede verificar que todos los submódulos estén correctamente inicializados con:
git submodule status
Ejemplo de salida:
bc625d5... bindings/python
2117822... others/libinjection (v4.0.0)
0fe989b... others/mbedtls (v4.1.0)
a3d4405... test/test-cases/secrules-language-tests
Si falta un submódulo, se mostrará con un - inicial, por ejemplo:
-bc625d5... bindings/python
others/libinjection y others/mbedtls son efectivamente necesarios para las compilaciones desde el código fuente y deben inicializarse antes de compilar.
Varias bibliotecas externas son opcionales y habilitan funcionalidades adicionales, incluyendo:
libcurl – necesario para SecRemoteRules
LMDB – soporte de almacenamiento persistente
Lua – soporte de scripting
Bibliotecas XML – procesamiento XML extendido
GeoIP (legado) / MaxMind
La API C de GeoIP legada (libGeoIP) está obsoleta y ya no recibe mantenimiento por parte de MaxMind. El repositorio upstream ha sido archivado y no debe utilizarse para nuevas implementaciones.
En su lugar, ModSecurity soporta la moderna API MaxMind DB (libmaxminddb), que recibe mantenimiento activo.
Durante la configuración, es posible que vea algo como:
+ GeoIP/MaxMind ....found
* (MaxMind) v1.12.2
-lmaxminddb , -I/usr/include/x86_64-linux-gnu
Esto indica que se está utilizando libmaxminddb (recomendado).
Se recomienda encarecidamente usar MaxMind DB en lugar de la biblioteca GeoIP legada.
La documentación de la biblioteca está escrita dentro del código en formato Doxygen. Para generar esta documentación, utilice la utilidad doxygen con el archivo de configuración proporcionado, "doxygen.cfg", ubicado en la subcarpeta "doc/". Esto generará documentación formateada en HTML que incluye ejemplos de uso.
La biblioteca proporciona una interfaz en C++ y C. Algunos recursos actualmente solo están disponibles a través de la interfaz C++, por ejemplo, la capacidad de crear un mecanismo de registro personalizado (consulte la prueba de regresión para ver cómo funcionan esos mecanismos de registro). El objetivo es que ambas API (C, C++) proporcionen la misma funcionalidad. Si encuentra un aspecto de la API que falta en una interfaz en particular, por favor abra un issue.
Dentro de la subcarpeta examples, hay ejemplos simples sobre cómo usar la API. A continuación se ilustran algunos:
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;
}
Está más que bienvenido a contribuir a este proyecto y esperamos hacer crecer la comunidad en torno a esta nueva versión de ModSecurity. Las áreas de interés incluyen: Nuevas funcionalidades, correcciones, informes de errores, soporte para usuarios principiantes, o cualquier cosa con la que esté dispuesto a ayudar.
Preferimos tener su parche dentro de la infraestructura de GitHub para facilitar nuestro trabajo de revisión y nuestra integración de Q.A. GitHub proporciona una excelente documentación sobre cómo realizar "Pull Requests", más información disponible aquí: https://help.github.com/articles/using-pull-requests/
Por favor, respete el estilo de codificación. Los pull requests pueden incluir varios commits, así que proporcione una corrección o una pieza de funcionalidad por commit. No cambie nada fuera del alcance de su trabajo objetivo (por ejemplo, estilo de codificación en una función que haya pasado). Para obtener más información sobre el estilo de codificación utilizado en este proyecto, consulte: https://www.chromium.org/blink/coding-style
Proporcione mensajes de commit explicativos. Su primera línea debe dar lo más destacado de su parche; a partir de la tercera línea, proporcione una explicación más detallada/detalles técnicos sobre su parche. La explicación del parche es valiosa durante el proceso de revisión.
Dentro de nuestro código hay varios elementos marcados como TODO o FIXME que pueden necesitar su atención. Consulte la lista de elementos realizando un grep:
$ cd /path/to/modsecurity-nginx
$ egrep -Rin "TODO|FIXME" -R *
También hay una lista TODO disponible como parte de la documentación de Doxygen.
Junto con las pruebas manuales, le recomendamos encarecidamente que utilice nuestras pruebas de regresión y pruebas unitarias. Si ha implementado un operador, no olvide crear pruebas unitarias para él. Si implementa cualquier otra cosa, se recomienda que desarrolle pruebas de regresión complementarias para ello.
Las utilidades de prueba de regresión y prueba unitaria son nativas y no requieren ninguna herramienta o script externo, aunque necesita obtener los casos de prueba de otros repositorios, ya que se comparten con otras versiones de ModSecurity, esos otros repositorios son submódulos de git. Para obtener el repositorio de submódulos y ejecutar las utilidades, siga los comandos que se enumeran a continuación:
$ cd /path/to/your/ModSecurity
$ git submodule update --init --recursive
$ make check
Antes de iniciar el proceso de depuración, asegúrese de dónde está su error. El problema podría estar en su conector o en libmodsecurity. Para identificar dónde está el error, se recomienda que desarrolle una prueba de regresión que imite el escenario donde ocurre el error. Si el error es reproducible con la utilidad de prueba de regresión, entonces será mucho más simple depurarlo y asegurarse de que nunca vuelva a ocurrir. En Linux, se recomienda que cualquier persona que realice depuración utilice gdb y/o valgrind según sea necesario.
Durante el tiempo de configuración/compilación, es posible que desee deshabilitar la optimización del compilador para que sus "back traces" estén poblados con datos legibles. Utilice las CFLAGS para deshabilitar los parámetros de optimización de compilación:
$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure --enable-assertions=yes
$ make
$ sudo make install
"Las aserciones nos permiten documentar suposiciones y detectar violaciones temprano en el proceso de desarrollo. Es más, las aserciones nos permiten detectar violaciones con un mínimo esfuerzo." https://dl.acm.org/doi/pdf/10.1145/240964.240969
Se recomienda el uso de aserciones cuando sea aplicable, y habilitarlas con '--enable-assertions=yes' durante el flujo de trabajo de pruebas y depuración.
El árbol fuente incluye una herramienta de Benchmark que puede ayudar a medir el rendimiento de la biblioteca. La herramienta se encuentra en el directorio test/benchmark/. El proceso de compilación también crea el binario aquí, por lo que tendrá la herramienta después de que finalice la compilación.
Para ejecutar, simplemente escriba:
cd test/benchmark
$ ./benchmark
Doing 1000000 transactions...
También puede pasar un valor más bajo:
$ ./benchmark 1000
Doing 1000 transactions...
Para medir el tiempo:
$ time ./benchmark 1000
Doing 1000 transactions...
real 0m0.351s
user 0m0.337s
sys 0m0.022s
Esto es muy rápido porque el benchmark utiliza la configuración mínima modsecurity.conf.default, que no incluye demasiadas reglas:
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
Para medir con reglas reales, ejecute uno de los scripts de descarga en el mismo directorio:
$ ./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"
Ahora el comando dará un valor mucho más alto.
La herramienta es una aplicación envolvente directa que utiliza la biblioteca. Crea una instancia de ModSecurity y una instancia de RuleSet, luego ejecuta un bucle basado en el número especificado. Dentro de este bucle, crea un objeto Transaction para emular transacciones HTTP reales.
Cada transacción es una solicitud HTTP/1.1 GET con algunos parámetros GET. Se agregan encabezados comunes, seguidos de los encabezados de respuesta y un cuerpo XML. Entre fases, la herramienta verifica si ha ocurrido una intervención. Todas las transacciones se crean con los mismos datos.
Tenga en cuenta que la herramienta no llama a la última fase (registro).
Por favor, recuerde restablecer basic_rules.conf si desea probar con un conjunto de reglas diferente.
Si enfrenta un problema de configuración o algo no funciona como esperaba, utilice la lista de correo de usuarios de ModSecurity. Los issues en GitHub también son bienvenidos, pero preferimos que los usuarios hagan preguntas primero en la lista de correo para que puedan llegar a toda una comunidad. Además, no olvide buscar issues existentes antes de abrir uno nuevo.
Si va a abrir un nuevo issue en GitHub, no olvide decirnos la versión de su libmodsecurity y la versión de un conector específico si lo hay.
No haga público ningún problema de seguridad. Contáctenos en: [email protected] reportando el problema. Una vez que el problema esté solucionado, se le dará crédito.
Estamos abiertos a discutir cualquier solicitud de nueva funcionalidad con la comunidad a través de las listas de correo. Alternativamente, siéntase libre de abrir issues en GitHub solicitando nuevas funcionalidades. Antes de abrir un nuevo issue, verifique si ya hay uno abierto sobre el mismo tema.
El diseño de libModSecurity permite la integración con enlaces (bindings). Hay un esfuerzo para evitar romper la compatibilidad [binaria] de la API para facilitar la integración con posibles enlaces. Actualmente, hay algunos proyectos notables mantenidos por la comunidad:
Tener nuestros paquetes en las distribuciones a tiempo es un deseo que tenemos, así que háganos saber si hay algo que podamos hacer para facilitar su trabajo como empaquetador.
El desarrollo de ModSecurity está patrocinado por Trustwave. El patrocinio finalizará el 1 de julio de 2024. Se puede encontrar información adicional aquí https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/
Un - inicial indica que el submódulo no ha sido inicializado u obtenido.
test/test-cases/secrules-language-tests – conjunto de pruebas de conformidad y regresión de SecRules compartido utilizado por make check.
bindings/python – enlaces de Python para ModSecurity (no necesario para la compilación de la biblioteca principal).