Skip to content

Commit a14cdc4

Browse files
authored
Merge pull request #3182 from airween/v3/readmeupdate
Update README.md: use submodule and use benchmark tool
2 parents 4b38435 + 6449310 commit a14cdc4

File tree

1 file changed

+80
-1
lines changed

1 file changed

+80
-1
lines changed

README.md

Lines changed: 80 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,13 @@ As a dynamic library, don’t forget that libmodsecurity must be installed to a
5757

5858
### Unix (Linux, MacOS, FreeBSD, …)
5959

60-
On unix the project uses autotools to help the compilation process.
60+
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:
61+
```shell
62+
$ git clone --recursive https://github.com/owasp-modsecurity/ModSecurity ModSecurity
63+
$ cd ModSecurity
64+
```
65+
66+
You can then start the build process:
6167

6268
```shell
6369
$ ./build.sh
@@ -235,6 +241,79 @@ $ make
235241
$ sudo make install
236242
```
237243

244+
### Benchmarking
245+
246+
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.
247+
248+
To run, just type:
249+
250+
```shell
251+
cd test/benchmark
252+
$ ./benchmark
253+
Doing 1000000 transactions...
254+
255+
```
256+
257+
You can also pass a lower value:
258+
259+
```shell
260+
$ ./benchmark 1000
261+
Doing 1000 transactions...
262+
```
263+
264+
To measure the time:
265+
```shell
266+
$ time ./benchmark 1000
267+
Doing 1000 transactions...
268+
269+
real 0m0.351s
270+
user 0m0.337s
271+
sys 0m0.022s
272+
```
273+
274+
This is very fast because the benchmark uses the minimal `modsecurity.conf.default` configuration, which doesn't include too many rules:
275+
276+
```shell
277+
$ cat basic_rules.conf
278+
279+
Include "../../modsecurity.conf-recommended"
280+
281+
```
282+
283+
To measure with real rules, run one of the download scripts in the same directory:
284+
285+
```shell
286+
$ ./download-owasp-v3-rules.sh
287+
Cloning into 'owasp-v3'...
288+
remote: Enumerating objects: 33007, done.
289+
remote: Counting objects: 100% (2581/2581), done.
290+
remote: Compressing objects: 100% (907/907), done.
291+
remote: Total 33007 (delta 2151), reused 2004 (delta 1638), pack-reused 30426
292+
Receiving objects: 100% (33007/33007), 9.02 MiB | 16.21 MiB/s, done.
293+
Resolving deltas: 100% (25927/25927), done.
294+
Switched to a new branch 'tag3.0.2'
295+
/path/to/ModSecurity/test/benchmark
296+
Done.
297+
298+
$ cat basic_rules.conf
299+
300+
Include "../../modsecurity.conf-recommended"
301+
302+
Include "owasp-v3/crs-setup.conf.example"
303+
Include "owasp-v3/rules/*.conf"
304+
```
305+
306+
Now the command will give much higher value.
307+
308+
#### How the benchmark works
309+
310+
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.
311+
312+
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.
313+
314+
Note that the tool does not call the last phase (logging).
315+
316+
Please remember to reset `basic_rules.conf` if you want to try with a different ruleset.
238317

239318
## Reporting Issues
240319

0 commit comments

Comments
 (0)