Add performance audit document for ModSecurity v3

[Easton97-Jens]

Motivation

• Provide a concise, code-focused performance audit of libmodsecurity v3 to document hot paths, parsing and rule-engine bottlenecks and to guide optimization efforts.

Description

• Add doc/performance_audit_modsecurity_2026-04-03.md which contains a technical analysis of the request lifecycle, rule-evaluation hot paths (RulesSet::evaluate, RuleWithOperator::evaluate), parsing (URL-encoded/JSON/XML/multipart), regex/operator costs, collection locking behavior and a prioritized list of optimization opportunities; this change only adds documentation and does not modify runtime code.

Testing

• Verified the new file was added and committed and inspected repository state using git status --short, git rev-parse --short HEAD, and git show --stat --oneline -1.

---

Codex Task

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[lbrndnr]

@Easton97-Jens Thanks for your thorough analysis! Would you mind elaborating your findings on the regex overhead? In particular, I would be interested in your methodology, i.e. how you came up with the 45–70% CPU share in the worst case? Would you mind sharing the traces/ruleset that you used?

I tried to reproduce your results but found that the regex engine scales fairly well and only makes up around 15% of the run time, even for pathological cases. Your help would be very much appreciated :)

Cheers,
Laurin

[Easton97-Jens]

Thanks for checking this and trying to reproduce it. You are right to ask for the methodology here. The 45–70% figure was generated as a code-focused/heuristic worst-case estimate rather than from a reproducible benchmark run with attached traces. I do not currently have perf traces or a concrete ruleset/payload matrix that supports that exact range.
I agree the document should make this clearer. I can revise the report to either remove the specific 45–70% claim or rephrase it as a hypothesis to be validated, and add a note that actual measurements depend heavily on CRS version/paranoia level, PCRE/JIT settings, payloads, match limits, and logging configuration. If useful, I can also add a reproducible benchmark section before making any quantified CPU-share claims.

[lbrndnr]

@Easton97-Jens Thanks for the quick reply! I think if we want to be super thorough we could adapt test/benchmark/benchmark.cc to allow for varying input messages.
The confusing thing I found is that even in the worst case (PL = 2, large match limits), the overall performance drops significantly, but regex scales just fine. To me, this indicates that regex is not a huge overhead, but something else. But I haven't quite found the culprit.

[Easton97-Jens]

Thanks, Laurin — that makes sense.

I agree that adapting "test/benchmark/benchmark.cc" to support varying input messages would be a better way to validate this properly. Your observation is also important: if overall performance drops under PL=2 / large match-limit scenarios while regex still scales reasonably, then the audit should not assume regex is the main culprit.

I’ll update the benchmark direction accordingly and treat the actual bottleneck as an open measurement question. I’ll also make sure the audit wording reflects that regex is only one candidate area to validate, not a proven dominant overhead.

[Easton97-Jens]

#118

[lbrndnr]

Brilliant, I keep you posted if I find anything out :)