owasp-modsecurity/modsecurityModSecurity는 Apache, IIS 및 Nginx를 위한 오픈 소스 크로스 플랫폼 웹 애플리케이션 방화벽(WAF) 엔진입니다. 견고한 이벤트 기반 프로그래밍 언어를 갖추고 있어 웹 애플리케이션에 대한 다양한 공격으로부터 보호하며 HTTP 트래픽 모니터링, 로깅 및 실시간 분석을 지원합니다.
Libmodsecurity는 ModSecurity v3 프로젝트의 한 구성 요소입니다. 이 라이브러리 코드베이스는 웹 트래픽을 수신하고 기존 ModSecurity 처리를 적용하는 ModSecurity 커넥터에 대한 인터페이스 역할을 합니다. 일반적으로 ModSecurity SecRules 형식으로 작성된 규칙을 로드/해석하고 커넥터를 통해 애플리케이션에서 제공하는 HTTP 콘텐츠에 적용하는 기능을 제공합니다.
Apache용 ModSecurity(일명 ModSecurity v2.x)를 찾고 있다면, 해당 버전은 여전히 유지관리되며 사용할 수 있습니다: 여기.
Libmodsecurity는 ModSecurity 플랫폼의 완전한 재작성입니다. 처음 고안되었을 때 ModSecurity 프로젝트는 단순한 Apache 모듈로 시작했습니다. 시간이 지나면서 대중의 요구로 인해 Nginx 및 IIS를 포함한(그러나 이에 국한되지 않는) 다른 플랫폼을 지원하도록 확장되었습니다. 추가 플랫폼 지원에 대한 증가하는 수요를 충족하기 위해 이 프로젝트의 기반이 되는 Apache 의존성을 제거하여 더 플랫폼 독립적으로 만드는 것이 필요해졌습니다.
이 목표의 결과로 우리는 Libmodsecurity를 (컴파일 시와 런타임 모두에서) 더 이상 Apache 웹 서버에 의존하지 않도록 재설계했습니다. 그 부수 효과 중 하나는 모든 플랫폼에서 사용자가 향상된 성능을 기대할 수 있다는 것입니다. 또한, 사용자들이 오랫동안 찾아온 일부 새로운 기능을 위한 기반을 마련할 기회를 잡았습니다. 예를 들어, 향후 버전에서 JSON 형식의 감사 로그(auditlog)를 기본 지원하고 다양한 다른 기능도 제공할 계획입니다.
'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
배포판별 빌드에 대한 자세한 내용은 Wiki에서 확인할 수 있습니다: 컴파일 레시피
Windows 빌드 정보는 여기에서 확인할 수 있습니다.
SecRules의 정규 표현식 처리는 Regex 유틸리티(src/utils/regex.*)를 통해 구현됩니다.
기본적으로 ModSecurity는 정규식 처리를 위해 PCRE2를 사용합니다.
@rx, @rxGlobal, @verifyCC와 같은 연산자에서 사용됩니다.
빌드 시 동작:
--with-pcre가 명시적으로 제공되면(WITH_PCRE) 레거시 PCRE를 사용할 수 있습니다.즉, 명시적으로 다르게 구성하지 않는 한 현재 빌드는 PCRE2를 기대합니다.
다른 모든 의존성은 SecRules 내에 지정된 연산자나 구성 지시문과 관련이 있으며 컴파일에 필요하지 않을 수 있습니다.
@detectXSS 및 @detectSQL 연산자에는 libinjection이 필요합니다.SecRemoteRules 지시문에는 curl이 필요합니다.이러한 라이브러리가 없으면 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 API(libGeoIP)는 MaxMind에 의해 더 이상 사용되지 않으며 유지관리되지 않습니다. 업스트림 저장소는 보관되었으며 새 배포에 사용해서는 안 됩니다.
대신 ModSecurity는 적극적으로 유지관리되는 최신 **MaxMind DB API(libmaxminddb)**를 지원합니다.
구성 중 다음과 같은 내용이 표시될 수 있습니다:
+ GeoIP/MaxMind ....found
* (MaxMind) v1.12.2
-lmaxminddb , -I/usr/include/x86_64-linux-gnu
이는 libmaxminddb가 사용되고 있음을 나타냅니다(권장).
레거시 GeoIP 라이브러리 대신 MaxMind DB를 사용하는 것이 강력히 권장됩니다.
라이브러리 문서는 코드 내에 Doxygen 형식으로 작성되어 있습니다. 이 문서를 생성하려면 "doc/" 하위 폴더에 있는 제공된 구성 파일 "doxygen.cfg"와 함께 doxygen 유틸리티를 사용하세요. 그러면 사용 예제가 포함된 HTML 형식 문서가 생성됩니다.
라이브러리는 C++ 및 C 인터페이스를 제공합니다. 일부 리소스는 현재 C++ 인터페이스로만 사용할 수 있습니다. 예를 들어, 사용자 정의 로깅 메커니즘을 생성하는 기능이 그렇습니다(이러한 로깅 메커니즘이 어떻게 작동하는지 확인하려면 회귀 테스트를 참조하세요). 목표는 두 API(C, C++)가 동일한 기능을 제공하는 것입니다. 특정 인터페이스에서 API의 일부가 누락된 것을 발견하면 이슈를 열어 주세요.
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를 중심으로 커뮤니티가 성장하기를 기대합니다. 관심 분야는 다음과 같습니다: 새로운 기능, 수정, 버그 신고, 초보 사용자 지원, 또는 여러분이 기꺼이 도울 수 있는 모든 것입니다.
저희는 검토 작업과 QA 통합을 위해 GitHub 인프라 내에서 패치를 제공하는 것을 선호합니다. GitHub는 'Pull Requests'를 수행하는 방법에 대한 훌륭한 문서를 제공합니다. 자세한 정보는 여기에서 확인할 수 있습니다: https://help.github.com/articles/using-pull-requests/
코딩 스타일을 존중해 주세요. Pull Request에는 다양한 커밋이 포함될 수 있으므로 커밋당 하나의 수정 또는 하나의 기능을 제공하세요. 대상 작업 범위를 벗어난 것은 변경하지 마십시오(예: 지나친 함수의 코딩 스타일). 이 프로젝트에서 사용되는 코딩 스타일에 대한 자세한 내용은 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'로 어설션을 활성화하는 것이 좋습니다.
소스 트리에는 라이브러리 성능을 측정하는 데 도움이 되는 벤치마크 도구가 포함되어 있습니다. 도구는 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 인스턴스를 생성한 다음 지정된 수에 따라 루프를 실행합니다. 이 루프 내에서 실제 HTTP 트랜잭션을 에뮬레이션하기 위해 Transaction 객체를 생성합니다.
각 트랜잭션은 일부 GET 매개변수가 있는 HTTP/1.1 GET 요청입니다. 공통 헤더가 추가되고 응답 헤더와 XML 본문이 이어집니다. 단계 사이에 도구는 개입(intervention)이 발생했는지 확인합니다. 모든 트랜잭션은 동일한 데이터로 생성됩니다.
도구는 마지막 단계(로깅)를 호출하지 않습니다.
다른 규칙 집합으로 시도하려면 basic_rules.conf를 재설정하는 것을 잊지 마세요.
구성 문제가 발생하거나 예상대로 작동하지 않는 경우 ModSecurity 사용자 메일링 리스트를 사용하세요. GitHub 이슈도 환영하지만, 전체 커뮤니티에 도달할 수 있도록 사용자들이 먼저 메일링 리스트에 질문을 올리는 것을 선호합니다. 새 이슈를 열기 전에 기존 이슈를 검색하는 것도 잊지 마세요.
GitHub에 새 이슈를 열려면 libmodsecurity 버전과 특정 커넥터가 있다면 그 버전을 알려주는 것을 잊지 마세요.
보안 이슈를 공개하지 마십시오. 다음 주소로 연락해 주세요: [email protected] 로 이슈를 신고하세요. 문제가 해결되면 크레딧이 주어집니다.
메일링 리스트를 통해 커뮤니티와 새로운 기능 요청을 논의하는 데 열려 있습니다. 또는 GitHub 이슈를 열어 새 기능을 요청할 수도 있습니다. 새 이슈를 열기 전에 같은 주제로 이미 열린 이슈가 있는지 확인하세요.
libModSecurity 설계는 바인딩과의 통합을 허용합니다. 가능한 바인딩과의 쉬운 통합을 위해 API [바이너리] 호환성을 깨지 않도록 노력하고 있습니다. 현재 커뮤니티에서 유지관리하는 몇 가지 주목할 만한 프로젝트가 있습니다:
배포판에 패키지를 제때 제공하는 것이 우리의 바람입니다. 패키저로서 여러분의 작업을 돕기 위해 할 수 있는 일이 있다면 알려주세요.
ModSecurity 개발은 Trustwave가 후원합니다. 후원은 2024년 7월 1일에 종료됩니다. 추가 정보는 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 – make check에서 사용하는 공유 SecRules 적합성 및 회귀 테스트 모음입니다.
bindings/python – ModSecurity용 Python 바인딩(핵심 라이브러리 컴파일에는 필요하지 않음).