Libmodsecurity является одной из составляющих проекта ModSecurity v3. Библиотека предоставляет интерфейс для ModSecurity Connectors, которые принимают веб-трафик и применяют традиционную обработку ModSecurity. В общем, она предоставляет возможность загрузки/интерпретации правил, написанных в формате ModSecurity SecRules, и применения их к HTTP-контенту, предоставленному вашим приложением через Connectors.

Если вы ищете ModSecurity для Apache (также известный как ModSecurity v2.x.x), он все еще поддерживается и доступен: здесь.

Какая разница между этим проектом и старым ModSecurity (v2.x.x)?

Все зависимости от Apache были удалены
Высокая производительность
Новые функции
Новая архитектура

Libmodsecurity — это полное переписание платформы ModSecurity. Когда проект был впервые задуман, ModSecurity начался как просто модуль для Apache. Со временем проект был расширен, благодаря популярному спросу, для поддержки других платформ, включая (но не ограничиваясь) Nginx и IIS. Для удовлетворения растущего спроса на поддержку дополнительных платформ, стало необходимым убрать зависимости от Apache, что сделало проект более независимым от платформы. В результате этой цели мы переработали Libmodsecurity таким образом, что он больше не зависит от веб-сервера Apache (как при компиляции, так и во время выполнения). Одним из побочных эффектов этого изменения является то, что пользователи на всех платформах могут ожидать увеличения производительности. Кроме того, мы воспользовались этой возможностью, чтобы заложить основу для некоторых новых функций, которые пользователи давно хотели видеть. Например, мы рассматриваем возможность нативной поддержки журналов аудита в формате JSON, а также множество других функций в будущих версиях.

Это больше не просто модуль.

Ветка 'ModSecurity' больше не содержит традиционную логику модуля (для Nginx, Apache и IIS), которая ранее упаковывалась вместе. Вместо этого эта ветка содержит только библиотечную часть (libmodsecurity) для этого проекта. Эта библиотека используется коннекторами, которые мы называем 'Connectors'. Эти коннекторы будут взаимодействовать с вашим веб-сервером и предоставлять библиотеке общий формат, который она понимает. Каждый из этих коннекторов поддерживается как отдельный проект GitHub. Например, коннектор для Nginx поставляется проектом ModSecurity-nginx (https://github.com/owasp-modsecurity/ModSecurity-nginx). Поддержание этих коннекторов отдельно позволяет каждому проекту иметь разные циклы выпуска, проблемы и деревья разработки. Кроме того, это означает, что при установке ModSecurity v3 вы получаете именно то, что вам нужно, без дополнительных компонентов, которые вы не будете использовать.

Компиляция

Перед началом процесса компиляции убедитесь, что у вас есть все необходимые зависимости. Прочитайте подраздел "Зависимости" для получения дополнительной информации.

После компиляции убедитесь, что на вашей сборке/платформе нет проблем. Мы настоятельно рекомендуем использовать единичные тесты и регрессионные тесты. Эти тестовые утилиты находятся в подпапке 'tests'.

Как динамическая библиотека, не забудьте, что libmodsecurity должна быть установлена в место (папку), где ваша ОС будет искать динамические библиотеки.

Unix (Linux, MacOS, FreeBSD, …)

На Unix проект использует autotools для помощи в процессе компиляции. Пожалуйста, обратите внимание, что если вы работаете с git, не забудьте инициализировать и обновить подмодули. Вот краткое руководство:

$ git clone --recursive https://github.com/owasp-modsecurity/ModSecurity ModSecurity
$ cd ModSecurity

Вы можете запустить процесс сборки:

$ ./build.sh
$ ./configure
$ make
$ sudo make install

Детали по распределенным сборкам можно найти в нашей Вики: Рецепты компиляции

Windows

Информация по сборке для Windows доступна здесь.

Зависимости

Эта библиотека написана на C++ с использованием стандартов C++17. Также она использует Flex и Yacc для создания парсера языка "Sec Rules Language". Другие обязательные зависимости включают YAJL, так как ModSecurity использует JSON для создания логов и тестового фреймворка, libpcre (ещё не обязательная) для обработки регулярных выражений в SecRules, и libXML2 (ещё не обязательная), которая используется для парсинга XML-запросов.

Все остальные зависимости связаны с операторами, указанными внутри SecRules или директивами конфигурации, и могут не требоваться для компиляции. Краткий список таких зависимостей следующий:

libinjection необходим для оператора @detectXSS и @detectSQL
curl необходим для директивы SecRemoteRules.

Если эти библиотеки отсутствуют, ModSecurity будет собран без поддержки оператора @detectXSS и директивы конфигурации SecRemoteRules.

Документация библиотеки

Документация библиотеки написана внутри кода в формате Doxygen. Чтобы сгенерировать эту документацию, пожалуйста, используйте утилиту doxygen с предоставленным файлом конфигурации "doxygen.cfg", расположенным в подпапке "doc/". Это сгенерирует документацию в формате HTML, включая примеры использования.

Использование библиотеки

Библиотека предоставляет интерфейсы C++ и C. Некоторые ресурсы в настоящее время доступны только через интерфейс C++, например, возможность создания пользовательских механизмов логирования (см. регрессионные тесты для проверки работы этих механизмов логирования). Цель состоит в том, чтобы оба API (C, C++) предоставляли одинаковые функциональные возможности. Если вы обнаружите аспект API, который отсутствует через определённый интерфейс, пожалуйста, откройте issue. В подпапке examples находятся простые примеры использования API. Ниже приведены некоторые из них:

Простой пример использования C++

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 << "Вмешательство произошло" << std::endl;
}

Простой пример на C

#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 для упрощения нашего процесса проверки и интеграции Q.A. GitHub предоставляет отличную документацию о том, как выполнять "pull requests", более подробная информация доступна здесь: https://help.github.com/articles/using-pull-requests/

Пожалуйста, соблюдайте стиль кодирования. Pull requests могут включать различные коммиты, поэтому предоставьте одно исправление или одну функциональность на каждый коммит. Пожалуйста, не изменяйте ничего вне рамок вашей целевой работы (например, стиль кодирования в функции, которую вы прошли мимо). Для получения дополнительной информации о стиле кодирования, используемом в этом проекте, пожалуйста, проверьте: https://www.chromium.org/blink/coding-style

Предоставьте объяснительные сообщения коммитов. Ваш первый абзац должен содержать основные моменты вашего патча, третий и последующие абзацы должны содержать более подробное объяснение/технические детали вашего патча. Объяснение патча ценно во время процесса проверки.

Не знаете, с чего начать?

В нашем коде есть различные элементы, помеченные как TODO или FIXME, которые могут потребовать вашего внимания. Проверьте список элементов, выполнив поиск с помощью команды grep:

$ cd /path/to/modsecurity-nginx
$ egrep -Rin "TODO|FIXME" -R *

Список TODO также доступен как часть документации Doxygen.

Тестирование вашего патча

В дополнение к ручному тестированию, мы настоятельно рекомендуем использовать наши регрессионные тесты и модульные тесты. Если вы реализовали оператор, не забудьте создать модульные тесты для него. Если вы реализовали что-то другое, рекомендуется разработать дополнительные регрессионные тесты для него. Инструменты для регрессионных и модульных тестов являются нативными и не требуют каких-либо внешних инструментов или скриптов, хотя вам потребуется получить тестовые случаи из других репозиториев, так как они совместно используются с другими версиями ModSecurity. Для получения подмодулей репозитория и запуска инструментов используйте следующие команды:

$ cd /path/to/your/ModSecurity
$ git submodule foreach git pull
$ cd test
$ ./regression_tests
$ ./unit_tests

Отладка

Перед началом процесса отладки убедитесь, где находится ваша ошибка. Проблема может быть в вашем соединителе или в libmodsecurity. Чтобы определить, где находится ошибка, рекомендуется разработать регрессионный тест, который имитирует сценарий, где происходит ошибка. Если ошибка воспроизводится с помощью инструмента регрессионных тестов, то отладка и устранение ошибки станет намного проще. На Linux рекомендуется использовать gdb и/или valgrind по мере необходимости.

Во время конфигурации/компиляции вы можете отключить оптимизацию компилятора, чтобы ваши откаты были заполнены читаемыми данными. Используйте 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 во время тестирования и отладки.

Проведение бенчмаркинга

Исходное дерево включает в себя инструмент для бенчмаркинга, который может помочь измерить производительность библиотеки. Инструмент расположен в директории test/benchmark/. Процесс сборки также создаёт бинарник здесь, поэтому после завершения компиляции у вас будет доступен инструмент.

Для запуска просто введите:

cd test/benchmark
$ ./benchmark
Выполняется 1000000 транзакций...

Вы также можете передать меньшее значение:

$ ./benchmark 1000
Выполняется 1000 транзакций...

Для измерения времени:

$ time ./benchmark 1000
Выполняется 1000 транзакций...

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
Клонирование в 'owasp-v3'...
remote: Перечисление объектов: 33007, завершено.
remote: Подсчет объектов: 100% (2581/2581), завершено.
remote: Сжатие объектов: 100% (907/907), завершено.
remote: Всего 33007 (дельта 2151), переиспользовано 2004 (дельта 1638), переиспользовано 30426.
Получение объектов: 100% (33007/33007), 9.02 MiB | 16.21 MiB/s, завершено.
Решение дельт: 100% (25927/25927), завершено.
Переключение на новую ветку 'tag3.0.2'
/path/to/ModSecurity/test/benchmark
Завершено.

$ 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. Сообщения об ошибках на GitHub также приветствуются, но мы предпочитаем, чтобы пользователи сначала задавали вопросы на почтовом списке, чтобы они могли обратиться к целому сообществу. Не забудьте также посмотреть на существующие сообщения об ошибках перед тем, как открыть новое.

Если вы собираетесь открыть новое сообщение об ошибке на GitHub, не забудьте сообщить нам версию вашей libmodsecurity и версию конкретного соединителя, если он есть.

Безопасность

Пожалуйста, не делайте публичными сообщения об ошибках безопасности. Обратитесь к нам по адресу: modsecurity@owasp.org с сообщением об ошибке. Как только проблема будет исправлена, ваш вклад будет признан.

Запрос на новую функцию

Мы открыты для обсуждения любых новых запросов на функции с сообществом через почтовые списки. Вы также можете открыть сообщения об ошибках на GitHub с запросом на новую функцию. Перед открытием нового сообщения об ошибке, пожалуйста, проверьте, нет ли уже открытого сообщения на ту же тему.

Взаимодействие с библиотеками

Проектирование libModSecurity позволяет интеграцию с библиотеками. Существуют усилия по избеганию нарушения совместимости API [бинарной] для удобной интеграции с возможными библиотеками. В настоящее время есть несколько значимых проектов, поддерживаемых сообществом:

Python - https://github.com/actions-security/pymodsecurity
Rust - https://github.com/rkrishn7/rust-modsecurity
Varnish - https://github.com/xdecock/vmod-modsecurity

Упаковка

Мы стремимся иметь наши пакеты в дистрибутивах вовремя, поэтому сообщите нам, если есть что-то, что мы можем сделать, чтобы облегчить вашу работу как упаковщика.

Спонсорство

Разработка 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/

OSCHINA-MIRROR/mirrors-ModSecurity

Какая разница между этим проектом и старым ModSecurity (v2.x.x)?

Это больше не просто модуль.

Компиляция

Unix (Linux, MacOS, FreeBSD, …)

Windows

Зависимости

Документация библиотеки

Использование библиотеки

Простой пример использования C++

Простой пример на C

Вклад

Предоставление патчей

Не знаете, с чего начать?

Тестирование вашего патча

Отладка

Проведение бенчмаркинга

Как работает бенчмаркинг

Сообщение об ошибках

Безопасность

Запрос на новую функцию

Взаимодействие с библиотеками

Упаковка

Спонсорство

Опубликовать ( 0 )

Введение

Обновления

Участники

Язык

Недавние действия

OSCHINA-MIRROR/mirrors-ModSecurity .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Какая разница между этим проектом и старым ModSecurity (v2.x.x)?

Это больше не просто модуль.

Компиляция

Unix (Linux, MacOS, FreeBSD, …)

Windows

Зависимости

Документация библиотеки

Использование библиотеки

Простой пример использования C++

Простой пример на C

Вклад

Предоставление патчей

Не знаете, с чего начать?

Тестирование вашего патча

Отладка

Проведение бенчмаркинга

Как работает бенчмаркинг

Сообщение об ошибках

Безопасность

Запрос на новую функцию

Взаимодействие с библиотеками

Упаковка

Спонсорство

Опубликовать ( 0 )

Введение

Обновления

Участники

Язык

Недавние действия

OSCHINA-MIRROR/mirrors-ModSecurity