From 30ddc32c6fbc1f84fe34e0a36e2ccf4d9829159f Mon Sep 17 00:00:00 2001 From: Ervin Hegedus Date: Thu, 11 Jul 2024 22:07:16 +0200 Subject: [PATCH 1/5] Update README.md: use submodule and use benchmark tool --- README.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 99a664a7ae..5e802bc374 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,15 @@ As a dynamic library, don’t forget that libmodsecurity must be installed to a ### Unix (Linux, MacOS, FreeBSD, …) -On unix the project uses autotools to help the compilation process. +On unix the project uses autotools to help the compilation process. Please note that if you work with `git`, do not forget to initialize submodules and update them. Here is a brief howto: +```shell +$ git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity +$ cd ModSecurity +$ git submodule init +$ git submodule update +``` + +After that, you can start the build process: ```shell $ ./build.sh @@ -235,6 +243,79 @@ $ make $ sudo make install ``` +### Benchmarking + +The source tree has a Benchmark tool which can help to measure the library's performance. The tool is under the `test/benchmark/` directory. The build process also makes the binary here, so after the end of compiling you will have the tool. + +To run, just type: + +```shell +cd test/benchmark +$ ./benchmark +Doing 1000000 transactions... + +``` + +Okay, this is a bit much, but you can pass a lower value: + +```shell +$ ./benchmark 1000 +Doing 1000 transactions... +``` + +To measure the time: +```shell +$ time ./benchmark 1000 +Doing 1000 transactions... + +real 0m0.351s +user 0m0.337s +sys 0m0.022s +``` + +This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which has not so much rules: + +```shell +$ cat basic_rules.conf + +Include "../../modsecurity.conf-recommended" + +``` + +To measure it with real rules, you should run one of the download scripts in the same directory: + +```shell +$ ./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" +``` + +Now the command will give much higher value. + +#### How the benchark works + +The tool is a simple embedding application which uses the library. It creates a ModSecurity and a RuleSet instance, then runs a loop with number of you passed. Creates a Transaction (object) and emulates real HTTP transactions. + +A transaction is a HTTP/1.1 GET request with a few GET parameters. Added common headers then the response: headers and an XML body. Between the phases it checks did any intervention happen or not. Every transaction is created with same data. + +Note, that the tool does not call the last phase (logging). + +Please don't forget to reset the `basic_rules.conf` content if you want to try it with another rule set. ## Reporting Issues From 714e531134c32221743e0d5a642789034c7b9f7d Mon Sep 17 00:00:00 2001 From: Ervin Hegedus Date: Fri, 12 Jul 2024 09:15:19 +0200 Subject: [PATCH 2/5] Content improve --- README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 5e802bc374..dd780ac4ca 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ As a dynamic library, don’t forget that libmodsecurity must be installed to a ### Unix (Linux, MacOS, FreeBSD, …) -On unix the project uses autotools to help the compilation process. Please note that if you work with `git`, do not forget to initialize submodules and update them. Here is a brief howto: +On unix the project uses autotools to help the compilation process. Please note that if you are working with `git`, don't forget to initialize and update the submodules. Here's a quick how-to: ```shell $ git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity $ cd ModSecurity @@ -65,7 +65,7 @@ $ git submodule init $ git submodule update ``` -After that, you can start the build process: +You can then start the build process: ```shell $ ./build.sh @@ -245,7 +245,9 @@ $ sudo make install ### Benchmarking -The source tree has a Benchmark tool which can help to measure the library's performance. The tool is under the `test/benchmark/` directory. The build process also makes the binary here, so after the end of compiling you will have the tool. +The source tree includes a Benchmark tool that can help measure library performance. The tool is located in the test/benchmark/ directory. The build process also creates the binary here, so you will have the tool after the compilation is finished. + +The source tree includes a Benchmark tool that can help measure library performance. The tool is located in the `test/benchmark/` directory. The build process also creates the binary here, so you will have the tool after the compilation is finished. To run, just type: @@ -273,7 +275,7 @@ user 0m0.337s sys 0m0.022s ``` -This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which has not so much rules: +This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't not too much rules: ```shell $ cat basic_rules.conf @@ -282,7 +284,7 @@ Include "../../modsecurity.conf-recommended" ``` -To measure it with real rules, you should run one of the download scripts in the same directory: +To measure with real rules, run one of the download scripts in the same directory: ```shell $ ./download-owasp-v3-rules.sh @@ -309,13 +311,13 @@ Now the command will give much higher value. #### How the benchark works -The tool is a simple embedding application which uses the library. It creates a ModSecurity and a RuleSet instance, then runs a loop with number of you passed. Creates a Transaction (object) and emulates real HTTP transactions. +The tool is a simple wrapper application that uses the library. Creates a ModSecurity instance and a RuleSet instance, then runs a loop with the passed number. Creates a Transaction (object) and emulates real HTTP transactions. -A transaction is a HTTP/1.1 GET request with a few GET parameters. Added common headers then the response: headers and an XML body. Between the phases it checks did any intervention happen or not. Every transaction is created with same data. +The transaction is an HTTP/1.1 GET request with some GET parameters. Added common headers then the response: headers and an XML body. Between phases it checks whether an intervention has taken place or not. All transactions are created with same data. -Note, that the tool does not call the last phase (logging). +Note that the tool does not call the last phase (logging). -Please don't forget to reset the `basic_rules.conf` content if you want to try it with another rule set. +Please remember to reset `basic_rules.conf` if you want to try with a different ruleset. ## Reporting Issues From baa7e694f937c3b9f586fbb674e06621cfbf1627 Mon Sep 17 00:00:00 2001 From: Ervin Hegedus Date: Fri, 12 Jul 2024 11:28:52 +0200 Subject: [PATCH 3/5] Typo fixes --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index dd780ac4ca..810b483f5f 100644 --- a/README.md +++ b/README.md @@ -245,8 +245,6 @@ $ sudo make install ### Benchmarking -The source tree includes a Benchmark tool that can help measure library performance. The tool is located in the test/benchmark/ directory. The build process also creates the binary here, so you will have the tool after the compilation is finished. - The source tree includes a Benchmark tool that can help measure library performance. The tool is located in the `test/benchmark/` directory. The build process also creates the binary here, so you will have the tool after the compilation is finished. To run, just type: @@ -258,7 +256,7 @@ Doing 1000000 transactions... ``` -Okay, this is a bit much, but you can pass a lower value: +You can also pass a lower value: ```shell $ ./benchmark 1000 @@ -275,7 +273,7 @@ user 0m0.337s sys 0m0.022s ``` -This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't not too much rules: +This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't much too much rules: ```shell $ cat basic_rules.conf From 8d06e4c47ba9ca57247117351a3f998fc3be92d1 Mon Sep 17 00:00:00 2001 From: Ervin Hegedus Date: Fri, 12 Jul 2024 18:09:33 +0200 Subject: [PATCH 4/5] Typo fixes --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 810b483f5f..18060b6dd7 100644 --- a/README.md +++ b/README.md @@ -273,7 +273,7 @@ user 0m0.337s sys 0m0.022s ``` -This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't much too much rules: +This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't include too many rules: ```shell $ cat basic_rules.conf From 644931083103000e791bd15a9b12fb35654c2904 Mon Sep 17 00:00:00 2001 From: Ervin Hegedus Date: Wed, 31 Jul 2024 14:23:52 +0200 Subject: [PATCH 5/5] Fix typos --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 18060b6dd7..36201735ff 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,8 @@ As a dynamic library, don’t forget that libmodsecurity must be installed to a On unix the project uses autotools to help the compilation process. Please note that if you are working with `git`, don't forget to initialize and update the submodules. Here's a quick how-to: ```shell -$ git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity +$ git clone --recursive https://github.com/owasp-modsecurity/ModSecurity ModSecurity $ cd ModSecurity -$ git submodule init -$ git submodule update ``` You can then start the build process: @@ -307,11 +305,11 @@ Include "owasp-v3/rules/*.conf" Now the command will give much higher value. -#### How the benchark works +#### How the benchmark works -The tool is a simple wrapper application that uses the library. Creates a ModSecurity instance and a RuleSet instance, then runs a loop with the passed number. Creates a Transaction (object) and emulates real HTTP transactions. +The tool is a straightforward wrapper application that utilizes the library. It creates a ModSecurity instance and a RuleSet instance, then runs a loop based on the specified number. Within this loop, it creates a Transaction object to emulate real HTTP transactions. -The transaction is an HTTP/1.1 GET request with some GET parameters. Added common headers then the response: headers and an XML body. Between phases it checks whether an intervention has taken place or not. All transactions are created with same data. +Each transaction is an HTTP/1.1 GET request with some GET parameters. Common headers are added, followed by the response headers and an XML body. Between phases, the tool checks whether an intervention has occurred. All transactions are created with the same data. Note that the tool does not call the last phase (logging).