owasp-modsecurity/modsecurityModSecurity ist eine quelloffene, plattformübergreifende Web Application Firewall (WAF)-Engine für Apache, IIS und Nginx. Sie verfügt über eine robuste ereignisbasierte Programmiersprache, die Schutz vor einer Reihe von Angriffen auf Webanwendungen bietet und die Überwachung, Protokollierung und Echtzeitanalyse von HTTP-Datenverkehr ermöglicht.
Libmodsecurity ist eine Komponente des ModSecurity-v3-Projekts. Die Bibliothekscodebasis dient als Schnittstelle zu ModSecurity-Connectors, die Webverkehr entgegennehmen und die traditionelle ModSecurity-Verarbeitung anwenden. Im Allgemeinen bietet sie die Möglichkeit, Regeln zu laden/zu interpretieren, die im ModSecurity-SecRules-Format geschrieben sind, und sie auf HTTP-Inhalte anzuwenden, die Ihre Anwendung über Connectors bereitstellt.
Wenn Sie nach ModSecurity für Apache (auch bekannt als ModSecurity v2.x) suchen, wird dieses weiterhin gewartet und ist verfügbar: hier.
Libmodsecurity ist eine vollständige Neuimplementierung der ModSecurity-Plattform. Als das Projekt ursprünglich konzipiert wurde, startete ModSecurity lediglich als Apache-Modul. Im Laufe der Zeit wurde das Projekt aufgrund großer Nachfrage erweitert, um weitere Plattformen zu unterstützen, darunter (aber nicht beschränkt auf) Nginx und IIS. Um der wachsenden Nachfrage nach zusätzlicher Plattformunterstützung gerecht zu werden, wurde es notwendig, die diesem Projekt zugrunde liegenden Apache-Abhängigkeiten zu entfernen und es damit unabhängiger von der Plattform zu machen.
Als Ergebnis dieses Ziels haben wir Libmodsecurity neu architekturiert, sodass es nicht länger vom Apache-Webserver abhängig ist (sowohl bei der Kompilierung als auch zur Laufzeit). Ein Nebeneffekt davon ist, dass Benutzer auf allen Plattformen eine höhere Leistung erwarten können. Darüber hinaus haben wir diese Gelegenheit genutzt, um die Grundlagen für einige neue Funktionen zu schaffen, nach denen Benutzer seit langem suchen. Beispielsweise beabsichtigen wir, Auditlogs nativ im JSON-Format zu unterstützen, zusammen mit einer Reihe weiterer Funktionen in zukünftigen Versionen.
Der ModSecurity-Zweig enthält nicht länger die traditionelle Modullogik (für Nginx, Apache und IIS), die üblicherweise alles zusammen verpackt wurde. Stattdessen enthält dieser Zweig nur den Bibliotheksteil (libmodsecurity) dieses Projekts. Diese Bibliothek wird von sogenannten „Connectors“ konsumiert. Diese Connectors stellen die Schnittstelle zu Ihrem Webserver her und versorgen die Bibliothek mit einem gemeinsamen Format, das sie versteht. Jeder dieser Connectors wird als separates GitHub-Projekt gepflegt. Beispielsweise wird der Nginx-Connector vom Projekt ModSecurity-nginx bereitgestellt (https://github.com/owasp-modsecurity/ModSecurity-nginx).
Durch die getrennte Pflege dieser Connectors kann jedes Projekt eigene Release-Zyklen, Issues und Entwicklungszweige haben. Darüber hinaus bedeutet dies, dass Sie bei der Installation von ModSecurity v3 genau das erhalten, was Sie benötigen, ohne Extras, die Sie nicht nutzen werden.
Bevor Sie mit dem Kompilierungsprozess beginnen, stellen Sie sicher, dass alle erforderlichen Abhängigkeiten installiert sind.
Weitere Informationen finden Sie im Abschnitt Abhängigkeiten und Git-Submodule.
Stellen Sie nach der Kompilierung sicher, dass es keine Probleme mit Ihrem Build bzw. Ihrer Plattform gibt.
Wir empfehlen dringend, die Unit-Tests und Regressionstests auszuführen. Diese Testprogramme befinden sich im Unterordner tests/.
Als dynamische Bibliothek muss libmodsecurity an einem Ort installiert werden, an dem Ihr Betriebssystem dynamische Bibliotheken finden kann.
Auf Unix-ähnlichen Systemen verwendet das Projekt autotools für den Kompilierungsprozess.
Wenn Sie mit einem Git-Checkout arbeiten, stellen Sie sicher, dass Sie das Repository rekursiv klonen oder alle Submodule vor dem Build initialisieren.
Siehe auch den Abschnitt Git-Submodule.
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity
Dieses Repository verwendet Git-Submodule. Nach dem Klonen stellen Sie sicher, dass alle Submodule initialisiert und abgerufen werden:
git submodule update --init --recursive
Sie können überprüfen, ob alle Submodule ordnungsgemäß initialisiert sind, mit:
git submodule status
Korrekt initialisierte Submodule zeigen einen Commit-Hash.
Ein führendes - zeigt an, dass das Submodul nicht initialisiert wurde.
Anschließend können Sie den Build-Prozess starten:
./build.sh
./configure
make
sudo make install
Details zu distributionsspezifischen Builds finden Sie in unserem Wiki: Kompilierungsrezepte
Windows-Build-Informationen finden Sie hier.
Die Verarbeitung regulärer Ausdrücke in SecRules wird über das Dienstprogramm Regex (src/utils/regex.*) implementiert.
Standardmäßig verwendet ModSecurity PCRE2 für die Behandlung regulärer Ausdrücke.
Dies wird von Operatoren wie @rx, @rxGlobal und @verifyCC verwendet.
Verhalten zur Build-Zeit:
--with-pcre explizit angegeben wird (WITH_PCRE).Mit anderen Worten: Aktuelle Builds erwarten PCRE2, sofern nicht ausdrücklich anders konfiguriert.
Alle anderen Abhängigkeiten stehen im Zusammenhang mit Operatoren, die in SecRules oder Konfigurationsdirektiven angegeben sind, und sind für die Kompilierung möglicherweise nicht erforderlich.
libinjection wird für die Operatoren @detectXSS und @detectSQL benötigt.curl wird für die Direktive SecRemoteRules benötigt.Wenn diese Bibliotheken fehlen, wird ModSecurity ohne Unterstützung für die jeweiligen Operatoren bzw. Direktiven kompiliert.
Das Repository enthält die folgenden Submodule:
others/libinjection – wird von den Operatoren @detectSQLi und @detectXSS verwendet.
others/mbedtls (TF-PSA-Crypto-Teilmenge) – wird für kryptografische Funktionen und Hilfsprogramme verwendet (z. B. Hashing, base64).
Hinweis: Das neuere mbedTLS-v4-Layout ist nicht mit der älteren v3-Struktur kompatibel. Die interne Struktur hat sich erheblich geändert, und viele Komponenten wurden in Submodule verschoben (z. B. TF-PSA-Crypto).
Nach dem Zusammenführen von PR #3532 muss Folgendes ausgeführt werden:
git submodule update --init --recursive
Dadurch wird sichergestellt, dass alle erforderlichen Submodule abgerufen werden. Ohne diesen Schritt lässt sich das Projekt nicht erfolgreich erstellen.
Sie können überprüfen, ob alle Submodule ordnungsgemäß initialisiert sind, mit:
git submodule status
Beispielausgabe:
bc625d5... bindings/python
2117822... others/libinjection (v4.0.0)
0fe989b... others/mbedtls (v4.1.0)
a3d4405... test/test-cases/secrules-language-tests
Fehlt ein Submodul, wird dies mit einem führenden - angezeigt, zum Beispiel:
-bc625d5... bindings/python
others/libinjection und others/mbedtls sind für Quellcode-Builds praktisch erforderlich und müssen vor dem Build initialisiert werden.
Mehrere externe Bibliotheken sind optional und ermöglichen zusätzliche Funktionen, darunter:
libcurl – erforderlich für SecRemoteRules
LMDB – Unterstützung für persistenten Speicher
Lua – Skriptunterstützung
XML-Bibliotheken – erweiterte XML-Verarbeitung
GeoIP (Legacy) / MaxMind
Die Legacy-GeoIP-C-API (libGeoIP) ist von MaxMind veraltet und wird nicht mehr gepflegt. Das Upstream-Repository wurde archiviert und sollte nicht für neue Bereitstellungen verwendet werden.
Stattdessen unterstützt ModSecurity die moderne MaxMind-DB-API (libmaxminddb), die aktiv gepflegt wird.
Während der Konfiguration sehen Sie möglicherweise etwas wie:
+ GeoIP/MaxMind ....found
* (MaxMind) v1.12.2
-lmaxminddb , -I/usr/include/x86_64-linux-gnu
Dies zeigt an, dass libmaxminddb verwendet wird (empfohlen).
Es wird dringend empfohlen, MaxMind DB anstelle der Legacy-GeoIP-Bibliothek zu verwenden.
Die Bibliotheksdokumentation ist im Code im Doxygen-Format geschrieben. Um diese Dokumentation zu erzeugen, verwenden Sie bitte das Doxygen-Dienstprogramm mit der bereitgestellten Konfigurationsdatei „doxygen.cfg“, die sich im Unterordner „doc/“ befindet. Dies erzeugt eine HTML-formatierte Dokumentation einschließlich Verwendungsbeispielen.
Die Bibliothek bietet eine C++- und eine C-Schnittstelle. Einige Ressourcen sind derzeit nur über die C++-Schnittstelle verfügbar, beispielsweise die Möglichkeit, einen benutzerdefinierten Protokollierungsmechanismus zu erstellen (siehe den Regressionstest, um zu prüfen, wie diese Protokollierungsmechanismen funktionieren). Das Ziel ist es, dass beide APIs (C, C++) dieselbe Funktionalität bieten. Wenn Sie einen Aspekt der API finden, der über eine bestimmte Schnittstelle fehlt, eröffnen Sie bitte ein Issue.
Im Unterordner examples befinden sich einfache Beispiele zur Nutzung der API.
Im Folgenden sind einige davon dargestellt:
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;
}
Sie sind herzlich eingeladen, zu diesem Projekt beizutragen. Wir freuen uns darauf, die Gemeinschaft rund um diese neue Version von ModSecurity zu vergrößern. Interessensgebiete umfassen: neue Funktionen, Fehlerbehebungen, Fehlerberichte, Unterstützung für Einsteiger oder alles andere, wobei Sie helfen möchten.
Wir bevorzugen es, dass Ihr Patch innerhalb der GitHub-Infrastruktur eingereicht wird, um unsere Überprüfungsarbeit und unsere Q.A.-Integration zu erleichtern. GitHub bietet eine hervorragende Dokumentation zur Durchführung von „Pull Requests“, weitere Informationen finden Sie hier: https://help.github.com/articles/using-pull-requests/
Bitte respektieren Sie den Codierungsstil. Pull Requests können verschiedene Commits enthalten, also liefern Sie eine Korrektur oder ein Funktionsstück pro Commit. Bitte ändern Sie nichts außerhalb des Umfangs Ihrer Zielarbeit (z. B. Codierungsstil in einer Funktion, an der Sie vorbeigegangen sind). Weitere Informationen zum in diesem Projekt verwendeten Codierungsstil finden Sie unter: https://www.chromium.org/blink/coding-style
Geben Sie erklärende Commit-Nachrichten an. Ihre erste Zeile sollte die Highlights Ihres Patches zusammenfassen, ab der dritten Zeile folgen detailliertere Erklärungen/technische Details zu Ihrem Patch. Die Patch-Erklärung ist während des Überprüfungsprozesses wertvoll.
In unserem Code gibt es verschiedene Elemente, die als TODO oder FIXME markiert sind und möglicherweise Ihre Aufmerksamkeit benötigen. Prüfen Sie die Liste der Elemente mit einem grep:
$ cd /path/to/modsecurity-nginx
$ egrep -Rin "TODO|FIXME" -R *
Eine TODO-Liste ist auch als Teil der Doxygen-Dokumentation verfügbar.
Zusätzlich zu den manuellen Tests empfehlen wir dringend, unsere Regressionstests und Unit-Tests zu verwenden. Wenn Sie einen Operator implementiert haben, vergessen Sie nicht, Unit-Tests dafür zu erstellen. Wenn Sie etwas anderes implementieren, wird empfohlen, ergänzende Regressionstests dafür zu entwickeln.
Die Regressionstest- und Unit-Test-Dienstprogramme sind nativ und erfordern kein externes Werkzeug oder Skript, allerdings müssen Sie die Testfälle aus anderen Repositories abrufen, da diese mit anderen Versionen von ModSecurity geteilt werden; diese anderen Repositories sind Git-Submodule. Um die Submodule-Repositories abzurufen und die Dienstprogramme auszuführen, befolgen Sie die unten aufgeführten Befehle:
$ cd /path/to/your/ModSecurity
$ git submodule update --init --recursive
$ make check
Bevor Sie mit dem Debugging beginnen, stellen Sie sicher, wo sich Ihr Fehler befindet. Das Problem könnte in Ihrem Connector oder in libmodsecurity liegen. Um zu identifizieren, wo sich der Fehler befindet, wird empfohlen, einen Regressionstest zu entwickeln, der das Szenario nachbildet, in dem der Fehler auftritt. Wenn der Fehler mit dem Regressionstest-Dienstprogramm reproduzierbar ist, wird das Debugging erheblich einfacher und es kann sichergestellt werden, dass er nie wieder auftritt. Unter Linux wird allen, die Debugging durchführen, empfohlen, bei Bedarf gdb und/oder valgrind zu verwenden.
Während der Konfigurations-/Kompilierungszeit möchten Sie möglicherweise die Compiler-Optimierung deaktivieren, damit Ihre „Backtraces“ lesbare Daten enthalten. Verwenden Sie die CFLAGS, um die Kompilierungsoptimierungsparameter zu deaktivieren:
$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure --enable-assertions=yes
$ make
$ sudo make install
„Assertionen ermöglichen es uns, Annahmen zu dokumentieren und Verstöße früh im Entwicklungsprozess zu erkennen. Darüber hinaus ermöglichen es Assertionen, Verstöße mit minimalem Aufwand zu erkennen.“ https://dl.acm.org/doi/pdf/10.1145/240964.240969
Es wird empfohlen, Assertionen zu verwenden, wo dies anwendbar ist, und sie während des Test- und Debugging-Workflows mit „--enable-assertions=yes“ zu aktivieren.
Der Quellbaum enthält ein Benchmark-Werkzeug, das bei der Messung der Bibliotheksleistung helfen kann. Das Werkzeug befindet sich im Verzeichnis test/benchmark/. Der Build-Prozess erstellt die Binärdatei ebenfalls dort, sodass Sie das Werkzeug nach Abschluss der Kompilierung zur Verfügung haben.
Zum Ausführen geben Sie einfach ein:
cd test/benchmark
$ ./benchmark
Doing 1000000 transactions...
Sie können auch einen niedrigeren Wert übergeben:
$ ./benchmark 1000
Doing 1000 transactions...
Zum Messen der Zeit:
$ time ./benchmark 1000
Doing 1000 transactions...
real 0m0.351s
user 0m0.337s
sys 0m0.022s
Dies ist sehr schnell, da das Benchmark die minimale Konfiguration modsecurity.conf.default verwendet, die nicht allzu viele Regeln enthält:
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
Zum Messen mit echten Regeln führen Sie eines der Download-Skripte im selben Verzeichnis aus:
$ ./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"
Nun liefert der Befehl einen viel höheren Wert.
Das Werkzeug ist eine einfache Wrapper-Anwendung, die die Bibliothek nutzt. Es erstellt eine ModSecurity-Instanz und eine RuleSet-Instanz und führt dann eine Schleife basierend auf der angegebenen Anzahl aus. Innerhalb dieser Schleife erstellt es ein Transaction-Objekt, um echte HTTP-Transaktionen zu emulieren.
Jede Transaktion ist eine HTTP/1.1-GET-Anfrage mit einigen GET-Parametern. Übliche Header werden hinzugefügt, gefolgt von den Antwortheadern und einem XML-Body. Zwischen den Phasen prüft das Werkzeug, ob eine Intervention stattgefunden hat. Alle Transaktionen werden mit denselben Daten erstellt.
Beachten Sie, dass das Werkzeug die letzte Phase (Protokollierung) nicht aufruft.
Bitte denken Sie daran, basic_rules.conf zurückzusetzen, wenn Sie es mit einem anderen Regelsatz versuchen möchten.
Wenn Sie ein Konfigurationsproblem haben oder etwas nicht wie erwartet funktioniert, nutzen Sie bitte die Mailingliste der ModSecurity-Benutzer. Issues auf GitHub sind ebenfalls willkommen, aber wir bevorzugen es, dass Benutzer zuerst Fragen auf der Mailingliste stellen, damit Sie eine gesamte Gemeinschaft erreichen können. Vergessen Sie auch nicht, nach bereits vorhandenen Issues zu suchen, bevor Sie ein neues eröffnen.
Wenn Sie ein neues Issue auf GitHub eröffnen möchten, vergessen Sie nicht, uns die Version Ihrer libmodsecurity und die Version eines bestimmten Connectors mitzuteilen, falls vorhanden.
Bitte machen Sie kein Sicherheitsproblem öffentlich. Kontaktieren Sie uns unter: [email protected] und melden Sie das Problem. Sobald das Problem behoben ist, wird Ihre Urheberschaft anerkannt.
Wir sind offen dafür, neue Feature-Anfragen über die Mailinglisten mit der Gemeinschaft zu diskutieren. Alternativ können Sie gerne GitHub-Issues eröffnen, um neue Funktionen anzufragen. Bevor Sie ein neues Issue eröffnen, prüfen Sie bitte, ob zu diesem Thema bereits eines eröffnet wurde.
Das libModSecurity-Design ermöglicht die Integration mit Bindings. Es wird darauf geachtet, die API-[Binär-]Kompatibilität nicht zu brechen, um eine einfache Integration mit möglichen Bindings zu ermöglichen. Derzeit gibt es einige bemerkenswerte Projekte, die von der Gemeinschaft gepflegt werden:
Es ist unser Wunsch, unsere Pakete rechtzeitig in den Distributionen zu haben. Lassen Sie uns daher wissen, ob wir etwas tun können, um Ihre Arbeit als Paketierer zu erleichtern.
Die Entwicklung von ModSecurity wird von Trustwave gesponsert. Das Sponsoring endet am 1. Juli 2024. Weitere Informationen finden Sie hier: https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/
Ein führendes - zeigt an, dass das Submodul nicht initialisiert oder abgerufen wurde.
test/test-cases/secrules-language-tests – gemeinsame SecRules-Konformitäts- und Regressionstestsuite, die von make check verwendet wird.
bindings/python – Python-Bindings für ModSecurity (für die Kompilierung der Kernbibliothek nicht erforderlich).