owasp-modsecurity/modsecurityModSecurity هو محرك جدار حماية لتطبيقات الويب (WAF) مفتوح المصدر ومتعدد المنصات، مخصص لخوادم Apache وIIS وNginx. يمتلك لغة برمجة قوية قائمة على الأحداث توفر الحماية من مجموعة من الهجمات ضد تطبيقات الويب، وتتيح مراقبة حركة مرور HTTP وتسجيلها وتحليلها في الوقت الفعلي.
Libmodsecurity هو أحد مكونات مشروع ModSecurity v3. تعمل قاعدة كود المكتبة كواجهة لموصلات ModSecurity التي تستقبل حركة مرور الويب وتطبّق معالجة ModSecurity التقليدية. بشكل عام، توفر إمكانية تحميل/تفسير القواعد المكتوبة بتنسيق SecRules الخاص بـ ModSecurity وتطبيقها على محتوى HTTP المقدَّم من تطبيقك عبر الموصلات (Connectors).
إذا كنت تبحث عن ModSecurity الخاص بـ Apache (المعروف أيضاً باسم ModSecurity v2.x)، فهو لا يزال قيد الصيانة ومتاح: هنا.
Libmodsecurity هو إعادة كتابة كاملة لمنصة ModSecurity. عندما صُمم لأول مرة، بدأ مشروع ModSecurity كوحدة Apache فقط. ومع مرور الوقت، تم توسيع المشروع، نظراً للطلب المتزايد، لدعم منصات أخرى تشمل (على سبيل المثال لا الحصر) Nginx و IIS. ومن أجل تلبية الطلب المتنامي على دعم منصات إضافية، أصبح من الضروري إزالة تبعيات Apache الكامنة وراء هذا المشروع، مما يجعله أكثر استقلالية عن المنصة.
نتيجة لهذا الهدف، قمنا بإعادة هيكلة Libmodsecurity بحيث لم يعد يعتمد على خادم الويب Apache (سواء في وقت الترجمة أو أثناء التشغيل). ومن الآثار الجانبية لذلك أنه يمكن للمستخدمين توقع أداء محسّن عبر جميع المنصات. بالإضافة إلى ذلك، انتهزنا هذه الفرصة لوضع الأساس لبعض الميزات الجديدة التي طالما سعى إليها المستخدمون. على سبيل المثال، نسعى إلى دعم سجلات التدقيق (auditlogs) بصيغة JSON بشكل أصلي، إلى جانب مجموعة كبيرة من الوظائف الأخرى في الإصدارات المستقبلية.
لم يعد فرع 'ModSecurity' يحتوي على منطق الوحدات التقليدي (لـ Nginx و Apache و IIS) الذي كان يُجمَّع معاً في السابق. بدلاً من ذلك، يحتوي هذا الفرع فقط على جزء المكتبة (libmodsecurity) الخاص بهذا المشروع. يتم استهلاك هذه المكتبة بواسطة ما أسميناه 'الموصلات' (Connectors)؛ ستتفاعل هذه الموصلات مع خادم الويب الخاص بك وتزوّد المكتبة بصيغة موحدة تفهمها. كل من هذه الموصلات يُدار كمشروع GitHub مستقل. على سبيل المثال، يتم توفير موصل Nginx بواسطة مشروع ModSecurity-nginx (https://github.com/owasp-modsecurity/ModSecurity-nginx).
إن إبقاء هذه الموصلات منفصلة يتيح لكل مشروع دورات إصدار وقضايا وأشجار تطوير مختلفة. بالإضافة إلى ذلك، فهذا يعني أنه عند تثبيت ModSecurity v3 فإنك تحصل فقط على ما تحتاجه بالضبط، دون إضافات لن تستخدمها.
قبل بدء عملية التجميع، تأكد من تثبيت جميع التبعيات المطلوبة.
راجع قسمي التبعيات و الوحدات الفرعية Git لمزيد من المعلومات.
بعد التجميع، تأكد من عدم وجود مشاكل في البناء/النظام الأساسي لديك.
نوصي بشدة بتشغيل اختبارات الوحدة واختبارات الانحدار. توجد أدوات الاختبار هذه في المجلد الفرعي tests/.
كمكتبة ديناميكية، يجب تثبيت libmodsecurity في مكان يمكن لنظام التشغيل لديك العثور فيه على المكتبات الديناميكية.
على الأنظمة الشبيهة بيونكس، يستخدم المشروع autotools في عملية التجميع.
إذا كنت تعمل مع استنساخ git، فتأكد من استنساخ المستودع بشكل متكرر (recursively) أو تهيئة جميع الوحدات الفرعية قبل البناء.
راجع أيضاً قسم الوحدات الفرعية Git.
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity
يستخدم هذا المستودع وحدات فرعية (submodules) تابعة لـ git. بعد الاستنساخ، تأكد من تهيئة جميع الوحدات الفرعية وجلبها:
git submodule update --init --recursive
يمكنك التحقق من أن جميع الوحدات الفرعية تمت تهيئتها بشكل صحيح باستخدام:
git submodule status
تُظهر الوحدات الفرعية التي تمت تهيئتها بشكل صحيح تجزئة الالتزام (commit hash).
تشير العلامة البادئة - إلى أن الوحدة الفرعية لم تتم تهيئتها.
يمكنك بعد ذلك بدء عملية البناء:
./build.sh
./configure
make
sudo make install
تفاصيل البناء الخاص بتوزيعات معينة موجودة في الويكي الخاص بنا: وصفات التجميع
يمكن العثور على معلومات بناء ويندوز هنا.
تتم معالجة التعبيرات النمطية في SecRules عبر أداة Regex (src/utils/regex.*).
افتراضياً، يستخدم ModSecurity PCRE2 للتعامل مع التعبيرات النمطية.
تُستخدم هذه الآلية بواسطة عوامل تشغيل مثل @rx و @rxGlobal و @verifyCC.
السلوك أثناء البناء:
--with-pcre بشكل صريح (WITH_PCRE).بعبارة أخرى، تتوقع البنيات الحالية استخدام PCRE2 ما لم يتم تكوين خلاف ذلك صراحة.
جميع التبعيات الأخرى مرتبطة بعوامل تشغيل محددة داخل SecRules أو بتوجيهات الإعداد وقد لا تكون مطلوبة للتجميع.
libinjection مطلوب لعاملي التشغيل @detectXSS و @detectSQL.curl مطلوب للتوجيه SecRemoteRules.إذا كانت هذه المكتبات مفقودة، فسيتم تجميع ModSecurity دون دعم لعوامل التشغيل أو التوجيهات المعنية.
يتضمن المستودع الوحدات الفرعية التالية:
others/libinjection – يُستخدم بواسطة عاملي التشغيل @detectSQLi و @detectXSS.
others/mbedtls (مجموعة فرعية من TF-PSA-Crypto) – يُستخدم للوظائف والأدوات المساعدة الخاصة بالتشفير (مثل التجزئة، base64).
ملاحظة: تخطيط mbedTLS v4 الأحدث غير متوافق مع بنية v3 الأقدم. لقد تغيرت البنية الداخلية بشكل كبير، وتم نقل العديد من المكونات إلى وحدات فرعية (مثل TF-PSA-Crypto).
بعد دمج PR #3532، يلزم تشغيل:
git submodule update --init --recursive
يضمن هذا جلب جميع الوحدات الفرعية المطلوبة. بدون هذه الخطوة، لن ينجح بناء المشروع.
يمكنك التحقق من أن جميع الوحدات الفرعية تمت تهيئتها بشكل صحيح باستخدام:
git submodule status
مثال على الإخراج:
bc625d5... bindings/python
2117822... others/libinjection (v4.0.0)
0fe989b... others/mbedtls (v4.1.0)
a3d4405... test/test-cases/secrules-language-tests
إذا كانت وحدة فرعية مفقودة، فستظهر بعلامة بادئة -، على سبيل المثال:
-bc625d5... bindings/python
others/libinjection و others/mbedtls مطلوبان فعلياً للبناء من المصدر ويجب تهيئتهما قبل البناء.
هناك عدة مكتبات خارجية اختيارية تتيح ميزات إضافية، ومنها:
libcurl – مطلوب لـ SecRemoteRules
LMDB – دعم التخزين الدائم
Lua – دعم البرمجة النصية
مكتبات XML – معالجة موسّعة لـ XML
GeoIP (قديم) / MaxMind
إن واجهة برمجة تطبيقات GeoIP C القديمة (libGeoIP) مهملة ولا تتم صيانتها بعد الآن من قبل MaxMind. تمت أرشفة المستودع الرئيسي ويجب عدم استخدامه للنشر الجديد.
بدلاً من ذلك، يدعم ModSecurity واجهة MaxMind DB API الحديثة (libmaxminddb)، التي تتم صيانتها بنشاط.
أثناء الإعداد قد ترى شيئاً مثل:
+ GeoIP/MaxMind ....found
* (MaxMind) v1.12.2
-lmaxminddb , -I/usr/include/x86_64-linux-gnu
يشير هذا إلى أن libmaxminddb قيد الاستخدام (موصى به).
من المستحسن بشدة استخدام MaxMind DB بدلاً من مكتبة GeoIP القديمة.
تمت كتابة توثيق المكتبة داخل الكود بتنسيق Doxygen. لتوليد هذا التوثيق، يرجى استخدام أداة doxygen مع ملف الإعداد المرفق "doxygen.cfg" الموجود في المجلد الفرعي "doc/". سيؤدي ذلك إلى إنشاء توثيق بتنسيق HTML بما في ذلك أمثلة الاستخدام.
توفر المكتبة واجهة بلغة C++ و C. بعض الموارد متاحة حالياً فقط عبر واجهة C++، على سبيل المثال، إمكانية إنشاء آلية تسجيل مخصصة (راجع اختبار الانحدار للتحقق من كيفية عمل آلية التسجيل هذه). الهدف هو أن توفر كل من الواجهتين (C، C++) نفس الوظائف؛ إذا وجدت جانباً من واجهة البرمجة مفقوداً عبر واجهة معينة، فيرجى فتح Issue.
داخل المجلد الفرعي examples، توجد أمثلة بسيطة حول كيفية استخدام واجهة البرمجة. فيما يلي بعض الأمثلة الموضحة:
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;
}
يسعدنا أن تساهم في هذا المشروع ونتطلع إلى تنمية المجتمع حول هذا الإصدار الجديد من ModSecurity. تشمل مجالات الاهتمام: وظائف جديدة، إصلاحات، تقارير الأخطاء، دعم المستخدمين المبتدئين، أو أي شيء ترغب في المساعدة فيه.
نفضّل أن يكون التصحيح الخاص بك ضمن البنية التحتية لـ GitHub لتسهيل عمل المراجعة والتكامل مع ضمان الجودة. توفر GitHub توثيقاً ممتازاً حول كيفية تنفيذ "طلبات السحب" (Pull Requests)، ومزيد من المعلومات متاح هنا: https://help.github.com/articles/using-pull-requests/
يرجى احترام أسلوب البرمجة. يمكن أن تتضمن طلبات السحب عدة Commits، لذا قدّم إصلاحاً واحداً أو وظيفة واحدة لكل Commit. يرجى عدم تغيير أي شيء خارج نطاق العمل المستهدف (مثل أسلوب البرمجة في دالة مررت بها). لمزيد من المعلومات حول أسلوب البرمجة المستخدم في هذا المشروع، يرجى الاطلاع على: https://www.chromium.org/blink/coding-style
قدّم رسائل Commit توضيحية. يجب أن يعرض السطر الأول أبرز ما في التصحيح، ومن السطر الثالث فصاعداً قدّم شرحاً أكثر تفصيلاً/تفاصيل تقنية حول التصحيح. شرح التصحيح قيّم أثناء عملية المراجعة.
يوجد داخل الكود الخاص بنا عناصر متنوعة موسومة بـ TODO أو FIXME قد تحتاج إلى اهتمامك. تحقق من قائمة العناصر بتنفيذ grep:
$ cd /path/to/modsecurity-nginx
$ egrep -Rin "TODO|FIXME" -R *
قائمة TODO متاحة أيضاً كجزء من توثيق Doxygen.
بالإضافة إلى الاختبار اليدوي، نوصيك بشدة باستخدام اختبارات الانحدار واختبارات الوحدة الخاصة بنا. إذا قمت بتنفيذ عامل تشغيل، فلا تنسَ إنشاء اختبارات وحدة له. إذا قمت بتنفيذ أي شيء آخر، فمن المستحسن أن تطور اختبارات انحدار تكميلية له.
أدوات اختبار الانحدار واختبار الوحدة هي أدوات أصلية ولا تتطلب أي أداة أو سكربت خارجي، على الرغم من أنك تحتاج إلى جلب حالات الاختبار من مستودعات أخرى، لأنها مشتركة مع إصدارات أخرى من ModSecurity؛ تلك المستودعات الأخرى هي وحدات فرعية تابعة لـ git. لجلب مستودعات الوحدات الفرعية وتشغيل الأدوات، اتبع الأوامر المدرجة أدناه:
$ cd /path/to/your/ModSecurity
$ git submodule update --init --recursive
$ make check
قبل بدء عملية التصحيح، تأكد من مكان الخطأ. قد تكون المشكلة في الموصل الخاص بك أو في libmodsecurity. من أجل تحديد مكان الخطأ، يُنصح بتطوير اختبار انحدار يحاكي السيناريو الذي يحدث فيه الخطأ. إذا كان الخطأ قابلًا لإعادة الإنتاج باستخدام أداة اختبار الانحدار، فسيكون التصحيح أبسط بكثير وضمان عدم حدوثه مرة أخرى. على Linux، يُنصح أي شخص يقوم بالتصحيح باستخدام gdb و/أو valgrind حسب الحاجة.
أثناء وقت الإعداد/التجميع، قد ترغب في تعطيل تحسين المترجم لجعل "تتبعات الاستدعاءات الخلفية" (back traces) الخاصة بك تحتوي على بيانات قابلة للقراءة. استخدم CFLAGS لتعطيل معاملات تحسين التجميع:
$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure --enable-assertions=yes
$ make
$ sudo make install
"تسمح لنا التأكيدات (Assertions) بتوثيق الافتراضات واكتشاف الانتهاكات مبكراً في عملية التطوير. علاوة على ذلك، تسمح لنا التأكيدات باكتشاف الانتهاكات بأقل جهد." https://dl.acm.org/doi/pdf/10.1145/240964.240969
يوصى باستخدام التأكيدات حيثما أمكن، وتفعيلها باستخدام '--enable-assertions=yes' أثناء سير عمل الاختبار والتصحيح.
تتضمن شجرة المصدر أداة Benchmark يمكن أن تساعد في قياس أداء المكتبة. توجد الأداة في دليل test/benchmark/. كما تنشئ عملية البناء الملف الثنائي هنا، لذا سيكون لديك الأداة بعد انتهاء التجميع.
للتشغيل، فقط اكتب:
cd test/benchmark
$ ./benchmark
Doing 1000000 transactions...
يمكنك أيضاً تمرير قيمة أقل:
$ ./benchmark 1000
Doing 1000 transactions...
لقياس الوقت:
$ time ./benchmark 1000
Doing 1000 transactions...
real 0m0.351s
user 0m0.337s
sys 0m0.022s
هذا سريع جداً لأن المعيار يستخدم إعداد modsecurity.conf.default الأدنى، والذي لا يتضمن عدداً كبيراً من القواعد:
$ cat basic_rules.conf
Include "../../modsecurity.conf-recommended"
لقياس الأداء بقواعد حقيقية، قم بتشغيل أحد سكربتات التنزيل في نفس الدليل:
$ ./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"
الآن سيعطي الأمر قيمة أعلى بكثير.
الأداة هي تطبيق غلاف بسيط يستخدم المكتبة. يقوم بإنشاء نسخة ModSecurity ونسخة RuleSet، ثم يشغل حلقة بناءً على الرقم المحدد. داخل هذه الحلقة، يقوم بإنشاء كائن Transaction لمحاكاة معاملات HTTP حقيقية.
كل معاملة هي طلب GET بتنسيق HTTP/1.1 مع بعض معاملات GET. تتم إضافة الترويسات الشائعة، متبوعة بترويسات الاستجابة ونص XML. بين المراحل، تتحقق الأداة مما إذا كان هناك تدخل (intervention) قد حدث. يتم إنشاء جميع المعاملات بنفس البيانات.
لاحظ أن الأداة لا تستدعي المرحلة الأخيرة (التسجيل).
يرجى تذكر إعادة تعيين basic_rules.conf إذا كنت تريد التجربة بمجموعة قواعد مختلفة.
إذا كنت تواجه مشكلة في الإعداد أو شيئاً لا يعمل كما توقعت، فيرجى استخدام القائمة البريدية لمستخدمي ModSecurity. كما نرحب بالمشكلات على GitHub، لكننا نفضّل أن يطرح المستخدمون الأسئلة على القائمة البريدية أولاً حتى تتمكن من الوصول إلى المجتمع بأكمله. ولا تنسَ أيضاً البحث عن المشكلات الموجودة قبل فتح مشكلة جديدة.
إذا كنت ستفتح مشكلة جديدة على GitHub، فلا تنسَ إخبارنا بإصدار libmodsecurity الخاص بك وإصدار الموصل المحدد إن وجد.
يرجى عدم نشر أي مشكلة أمنية علناً. تواصل معنا على: [email protected] للإبلاغ عن المشكلة. بمجرد إصلاح المشكلة، سيتم منحك الفضل.
نحن منفتحون لمناقشة أي طلب ميزة جديد مع المجتمع عبر القوائم البريدية. يمكنك بدلاً من ذلك فتح مشكلات على GitHub لطلب ميزات جديدة. قبل فتح مشكلة جديدة، يرجى التحقق مما إذا كانت هناك مشكلة مفتوحة بالفعل حول نفس الموضوع.
يتيح تصميم libModSecurity التكامل مع الروابط (bindings). هناك جهد لتجنب كسر التوافق [الثنائي] لواجهة البرمجة لتسهيل التكامل مع الروابط المحتملة. حالياً، هناك عدد من المشاريع البارزة التي يحتفظ بها المجتمع:
إن توفر حزمنا في التوزيعات في الوقت المحدد هو أمر نرغب فيه، لذا أخبرنا إذا كان هناك أي شيء يمكننا القيام به لتسهيل عملك كمعبئ (packager).
تطوير ModSecurity برعاية Trustwave. ستنتهي الرعاية في 1 يوليو 2024. يمكن العثور على معلومات إضافية هنا https://www.trustwave.com/en-us/resources/security-resources/software-updates/end-of-sale-and-trustwave-support-for-modsecurity-web-application-firewall/
تشير العلامة البادئة - إلى أن الوحدة الفرعية لم تتم تهيئتها أو جلبها.
test/test-cases/secrules-language-tests – مجموعة اختبارات التوافق والانحدار المشتركة الخاصة بـ SecRules والتي يستخدمها make check.
bindings/python – روابط Python الخاصة بـ ModSecurity (غير مطلوبة لتجميع المكتبة الأساسية).