
ModSecurity — это движок межсетевого экрана веб-приложений (WAF) с открытым исходным кодом, кросс-платформенный, для Apache, IIS и Nginx. Он имеет надежный язык программирования, основанный на событиях, который обеспечивает защиту от ряда атак на веб-приложения и позволяет осуществлять мониторинг HTTP-трафика, ведение журнала и анализ в реальном времени.
Libmodsecurity — один из компонентов проекта ModSecurity v3. Кодовая база библиотеки служит интерфейсом для коннекторов ModSecurity, принимающих веб-трафик и применяющих традиционную обработку ModSecurity. В целом, она предоставляет возможность загружать и интерпретировать правила, написанные в формате SecRules ModSecurity, и применять их к HTTP-контенту, передаваемому вашим приложением через коннекторы.
Если вы ищете ModSecurity для Apache (также известный как ModSecurity v2.x), он всё ещё поддерживается и доступен: здесь.
Libmodsecurity — это полная переработка платформы ModSecurity. Когда проект ModSecurity только задумывался, он начинался как простой модуль Apache. Со временем, по многочисленным просьбам, проект был расширен для поддержки других платформ, включая (но не ограничиваясь) Nginx и IIS. Чтобы удовлетворить растущий спрос на поддержку дополнительных платформ, стало необходимо удалить зависимости от Apache, лежащие в основе этого проекта, сделав его более независимым от платформы.
В результате этой цели мы переработали Libmodsecurity таким образом, что он больше не зависит от веб-сервера Apache (ни на этапе компиляции, ни во время выполнения). Побочный эффект этого — на всех платформах пользователи могут ожидать повышенной производительности. Кроме того, мы воспользовались этой возможностью, чтобы заложить основу для некоторых новых функций, которые пользователи давно хотели. Например, мы планируем обеспечить нативную поддержку журналов аудита в формате JSON, а также множество других функций в будущих версиях.
Ветка «ModSecurity» больше не содержит традиционной логики модулей (для Nginx, Apache и IIS), которая ранее была объединена. Вместо этого данная ветка содержит только библиотечную часть (libmodsecurity) этого проекта. Эта библиотека используется тем, что мы назвали «коннекторами»; эти коннекторы взаимодействуют с вашим веб-сервером и предоставляют библиотеке общий формат, который она понимает. Каждый из этих коннекторов поддерживается как отдельный проект на GitHub. Например, коннектор для Nginx предоставляется проектом ModSecurity-nginx (https://github.com/owasp-modsecurity/ModSecurity-nginx).
Разделение коннекторов позволяет каждому проекту иметь свои циклы выпуска, проблемы и деревья разработки. Кроме того, это означает, что при установке ModSecurity v3 вы получаете только то, что вам нужно, без лишних дополнений, которые вы не будете использовать.
Перед началом процесса компиляции убедитесь, что все необходимые зависимости установлены.
См. разделы Зависимости и Подмодули Git для получения дополнительной информации.
После компиляции убедитесь, что в вашей сборке/платформе нет проблем.
Мы настоятельно рекомендуем запустить модульные тесты и регрессионные тесты. Эти служебные программы для тестирования находятся в подпапке tests/.
Как динамическая библиотека, libmodsecurity должна быть установлена в место, где ваша операционная система может найти динамические библиотеки.
В Unix-подобных системах проект использует autotools для процесса компиляции.
Если вы работаете с git-клоном, не забудьте рекурсивно клонировать репозиторий или инициализировать все подмодули перед сборкой.
См. также раздел Подмодули Git.
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity
Этот репозиторий использует подмодули Git. После клонирования не забудьте инициализировать и загрузить все подмодули:
git submodule update --init --recursive
Вы можете проверить, что все подмодули правильно инициализированы, с помощью:
git submodule status
Правильно инициализированные подмодули показывают хеш коммита.
Наличие - в начале указывает, что подмодуль не был инициализирован.
Затем вы можете начать процесс сборки:
./build.sh
./configure
make
sudo make install
Подробности сборки для конкретных дистрибутивов можно найти в нашей Вики: Рецепты компиляции
Информацию о сборке в Windows можно найти здесь.
Обработка регулярных выражений в 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
Начальный - означает, что подмодуль не был инициализирован или загружен.
test/test-cases/secrules-language-tests — общий набор тестов соответствия и регрессионных тестов SecRules, используемый make check.
bindings/python — привязки Python для ModSecurity (не требуются для компиляции основной библиотеки).
others/libinjection и others/mbedtls фактически обязательны для сборки из исходников и должны быть инициализированы перед сборкой.
Некоторые внешние библиотеки являются опциональными и включают дополнительные возможности, в том числе:
libcurl — требуется для SecRemoteRules
LMDB — поддержка постоянного хранения
Lua — поддержка скриптинга
XML-библиотеки — расширенная обработка XML
GeoIP (устаревший) / MaxMind
Устаревший C API GeoIP (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++, например, возможность создания собственного механизма журналирования (см. регрессионный тест, чтобы узнать, как работают такие механизмы). Цель состоит в том, чтобы оба API (C, C++) предоставляли одинаковую функциональность; если вы обнаружите аспект API, отсутствующий в конкретном интерфейсе, пожалуйста, создайте issue.
В подпапке examples есть простые примеры использования API. Ниже приведены некоторые из них:
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 для облегчения нашей работы по рецензированию и интеграции QA. GitHub предоставляет отличную документацию о том, как выполнять «Pull Requests», дополнительная информация доступна здесь: https://help.github.com/articles/using-pull-requests/
Пожалуйста, соблюдайте стиль кодирования. Pull-запросы могут содержать различные коммиты, поэтому предоставляйте одно исправление или одну функциональность на коммит. Пожалуйста, не изменяйте ничего за пределами области вашей целевой работы (например, стиль кодирования в функции, которую вы обошли). Для получения дополнительной информации о стиле кодирования, используемом в этом проекте, пожалуйста, посетите: https://www.chromium.org/blink/coding-style
Предоставляйте пояснительные сообщения коммитов. Первая строка должна описывать основные моменты вашего исправления, третья и последующие строки — давать более подробное объяснение/технические детали вашего исправления. Объяснение исправления ценно в процессе рецензирования.
В нашем коде есть различные элементы, помеченные как 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
«Утверждения позволяют нам документировать предположения и выявлять нарушения на ранних этапах разработки. Более того, утверждения позволяют выявлять нарушения с минимальными усилиями.» 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-транзакций.
Каждая транзакция представляет собой HTTP/1.1 GET-запрос с некоторыми GET-параметрами. Добавляются общие заголовки, затем заголовки ответа и тело XML. Между фазами инструмент проверяет, произошло ли вмешательство. Все транзакции создаются с одними и теми же данными.
Обратите внимание, что инструмент не вызывает последнюю фазу (журналирование).
Пожалуйста, не забудьте сбросить basic_rules.conf, если хотите попробовать с другим набором правил.
Если вы столкнулись с проблемой конфигурации или что-то работает не так, как ожидалось, используйте список рассылки пользователей ModSecurity. Issues на GitHub также приветствуются, но мы предпочитаем, чтобы пользователи сначала задавали вопросы в списке рассылки, чтобы вы могли обратиться ко всему сообществу. Также не забывайте искать существующие issues, прежде чем открывать новый.
Если вы собираетесь открыть новую issue на GitHub, не забудьте сообщить нам версию вашего libmodsecurity и версию конкретного коннектора, если он есть.
Пожалуйста, не предавайте огласке любые проблемы безопасности. Свяжитесь с нами по адресу: [email protected], сообщив о проблеме. После исправления проблемы ваше имя будет упомянуто.
Мы открыты для обсуждения любых запросов новых функций с сообществом через списки рассылки. Вы также можете свободно открывать issues на GitHub с запросами новых функций. Перед открытием новой issue, пожалуйста, проверьте, нет ли уже открытой по той же теме.
Дизайн libModSecurity позволяет интеграцию с привязками. Предпринимаются усилия, чтобы избежать нарушения API [двоичной] совместимости для облегчения интеграции с возможными привязками. В настоящее время есть несколько заметных проектов, поддерживаемых сообществом:
Мы хотим, чтобы наши пакеты своевременно появлялись в дистрибутивах, поэтому дайте нам знать, если мы можем что-то сделать, чтобы облегчить вашу работу как сборщика пакетов.
Разработка 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/