Implement Phase 4 handling for ModSecurity-nginx by Easton97-Jens · Pull Request #377 · owasp-modsecurity/ModSecurity-nginx · GitHub

What changed

This PR introduces and stabilizes dedicated phase:4 handling for the nginx ModSecurity connector.

Main additions include:

Support for configurable phase4 handling modes:
- minimal
- safe
- strict
Explicit late-intervention handling when response headers were already sent
Dedicated phase4 JSON logging via:
- modsecurity_phase4_log
Configurable content-type scoping through:
- modsecurity_phase4_content_types_file
Additional parser, logging, HTTP/2, proxy, and regression test coverage
Production-oriented example configurations and documentation

Additional fixes included in this PR:

Fixed multiple phase4-related build issues
Corrected raw-rule and status logging order
Added missing parser and regression test cases
Improved validation and configuration parsing behavior

Why these changes

phase:4 operates on response bodies. At this stage, nginx may already have sent response headers or even part of the response body.

Because of this technical limitation, actions such as:

deny
status
redirect

cannot always be converted into a clean client-visible HTTP response once headers are already sent.

This PR introduces explicit and predictable handling for those late-intervention scenarios:

minimal
→ downgrade to log_only
safe
→ downgrade to log_only (default-safe production behavior)
strict
→ optional connection_abort

The goal is to:

avoid false guarantees around late blocking behavior,
make phase4 handling transparent and deterministic,
improve operational visibility,
provide safer production defaults,
clearly separate production behavior from test/demo behavior.

Logging and observability

The new phase4 logging implementation provides structured JSON-lines logging including fields such as:

intervention mode
requested vs actual action
header-sent state
response status
content type
rule ID
downgrade reason

Tests also verify that response-body payload data is not leaked into phase4 logs.

Testing

This PR adds and extends coverage for:

parser validation
regression handling
proxy paths
HTTP/2 handling
late-intervention scenarios
content-type scoping
logging behavior

Documentation

Comprehensive documentation for the implemented behavior was added, including:

operational limitations of phase:4
behavior differences between modes
production configuration examples
logging semantics
known technical boundaries and guarantees

…strict test config

…rvention-handling-in-modsecurity-nginx Phase 4: configurable handling, content-type scoping and JSON logging

…igs-and-document-phase-4-functionality docs: add bilingual Phase-4 handling docs and example configurations

…n-modsecurity-proxy Guard allocations, tighten phase4 content-type parsing, and update tests

…nability-issues-in-modsecurity-nginx Reduce nesting and split declarations to address SonarQube maintainability issues

…in-src/ngx_http_modsecurity_body_filter Fix SonarQube issues in body filter (split declarations, reduce nesting)

Pull request overview

This PR adds configurable Phase 4 response-body intervention handling for the ModSecurity nginx connector, including safer late-intervention behavior, scoped content-type handling, structured logging, and related tests/docs.

Changes:

Adds minimal, safe, and strict Phase 4 modes with late-intervention downgrade/abort behavior.
Adds Phase 4 JSON logging and content-type scoping configuration.
Expands regression, proxy, HTTP/2, parser, documentation, and example coverage.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/ngx_http_modsecurity_module.c	Adds new Phase 4 directives, config parsing, defaults, and intervention metadata capture.
src/ngx_http_modsecurity_common.h	Extends request/location config structs for Phase 4 state.
src/ngx_http_modsecurity_body_filter.c	Implements Phase 4 scope checks, late-intervention handling, and JSON logging.
tests/modsecurity.t	Enables strict mode for existing Phase 4 baseline tests.
tests/modsecurity-h2.t	Enables strict mode for HTTP/2 Phase 4 tests.
tests/modsecurity-proxy.t	Enables strict mode and adds in-scope proxy backend responses for Phase 4 triggers.
tests/modsecurity-proxy-h2.t	Enables strict mode for HTTP/2 proxy Phase 4 tests.
tests/modsecurity-phase4-regression.t	Adds large-response minimal-mode regression/logging coverage.
tests/modsecurity-phase4-modes.t	Adds mode behavior and JSON-line logging tests.
tests/modsecurity-phase4-invalid-config.t	Adds intended invalid content-type config coverage.
tests/modsecurity-phase4-content-types.t	Adds content-type scoping behavior tests.
docs/phase4-handling.en.md	Documents English Phase 4 behavior, modes, logging, and limits.
docs/phase4-handling.de.md	Adds German Phase 4 behavior documentation.
docs/examples/phase4-minimal.conf	Adds minimal-mode production example.
docs/examples/phase4-safe.conf	Adds safe-mode production example.
docs/examples/phase4-strict.conf	Adds strict-mode production example.
docs/examples/phase4-content-types.conf	Adds example scoped content-type list.

Comments suppressed due to low confidence (1)

src/ngx_http_modsecurity_module.c:659

Read failures are also returned as a generic configuration error without the file path or errno. Please log the read error before returning so operators can distinguish truncated/unreadable content-type files from parser validation failures.

    n = ngx_read_file(&file, buf, ngx_file_size(&fi), 0);
    ngx_close_file(file.fd);
    if (n < 0) return NGX_CONF_ERROR;

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Excellent PR, thanks @Easton97-Jens!

Please take a look at Copilot's suggestions.

I think it would be great to add some minimal description about the new directives to main README.

Other than that, I would like to test this PR locally, and play with it for a wile - I need some time for that.

Thanks again.

…pilot-comments-for-pr-#377 Address Copilot review feedback for phase‑4 handling

…-new-nginx-directives docs: document phase4 nginx directives in README

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Thanks!
I’ve already addressed most of the feedback and also updated the README with a short description of the new directives.

The only remaining thing is one Copilot suggestion that I currently can’t apply cleanly without changing behavior, so I left it as-is for now.

Take your time testing the PR locally, and let me know if you find anything or have more feedback 🙂

https://github.com/Easton97-Jens/ModSecurity-test-Framework

I split out a small evidence/test framework that runs the same YAML-derived cases through real Apache and NGINX connector paths. It currently verifies ARGS, ARGS_NAMES, REQUEST_BODY, REQUEST_COOKIES, REQUEST_HEADERS, FILES, XML, AUDIT_LOG, RESPONSE_HEADERS, etc. RESPONSE_BODY remains xfail/mapped-only, and RAW argument collections are mapped-only with the current local v3 source because the ARGS_RAW family is not present there yet.

Easton97-Jens added 21 commits May 3, 2026 21:49

Add remaining phase4 parser/logging/regression test cases

97eab11

Merge remote-tracking branch 'origin/master' into work

25aa9e9

Fix phase4 build issues and raw rule/status logging order

88d0339

Fix phase4 event logging paths and JSON output correctness

4d1bb87

Fix phase4 log sanitization, deterministic reasons, and proxy phase4 …

6962d42

…strict test config

Fix phase4 C-level string safety issues

3e35548

Merge pull request #6 from Easton97-Jens/codex/implement-phase-4-inte…

440ee43

…rvention-handling-in-modsecurity-nginx Phase 4: configurable handling, content-type scoping and JSON logging

docs: add bilingual phase4 handling and config examples

e2ede45

Fix json escape alloc safety and phase4 modes log-line assertions

2e2c792

Fix phase4-modes test plan count mismatch

d73f9ea

docs: expand phase4 guidance and generalize production examples

a7bb6e4

Fix phase4-modes JSON line assertion for CRLF log lines

4775f32

Add diagnostics for failing phase4 modes JSON-line assertion

1f37b84

Fix MSVC pointer type warning in ngx_file_info call

0e8720e

Merge pull request #7 from Easton97-Jens/codex/review-nginx-test-conf…

be7d24b

…igs-and-document-phase-4-functionality docs: add bilingual Phase-4 handling docs and example configurations

Merge pull request #9 from Easton97-Jens/codex/fix-remaining-issues-i…

5c39034

…n-modsecurity-proxy Guard allocations, tighten phase4 content-type parsing, and update tests

Refactor phase4 code to address Sonar maintainability issues

2a31a5b

Flatten processed-chain branch in body filter

0d3ad62

Merge pull request #10 from Easton97-Jens/codex/fix-sonarqube-maintai…

d1b375c

…nability-issues-in-modsecurity-nginx Reduce nesting and split declarations to address SonarQube maintainability issues

Fix remaining SonarQube issues in body filter

06f99af

Merge pull request #11 from Easton97-Jens/codex/fix-sonarqube-issues-…

e35b7fa

…in-src/ngx_http_modsecurity_body_filter Fix SonarQube issues in body filter (split declarations, reduce nesting)

airween requested a review from Copilot May 14, 2026 06:47

Copilot started reviewing on behalf of airween May 14, 2026 06:47 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

Address Copilot review feedback for phase4 handling

505d4af

Easton97-Jens mentioned this pull request May 14, 2026

Address Copilot review feedback for phase‑4 handling Easton97-Jens/ModSecurity-nginx#12

Merged

Easton97-Jens added 3 commits May 14, 2026 19:04

Fix sanity-check redeclaration and narrow phase4 log capture

cfc7e22

Rewrite phase4 invalid-config test to use nginx -t output

0051975

Use repository Test::Nginx harness in phase4 invalid-config test

329f269

Easton97-Jens added 4 commits May 14, 2026 19:26

Stabilize phase4 invalid-config test nginx -t setup

8b766e4

Merge pull request #12 from Easton97-Jens/codex/fetch-and-evaluate-co…

beb3e87

…pilot-comments-for-pr-#377 Address Copilot review feedback for phase‑4 handling

docs: document phase4 nginx directives in README

20d7aca

Merge pull request #13 from Easton97-Jens/codex/update-readme.md-with…

3d72b00

…-new-nginx-directives docs: document phase4 nginx directives in README

Implement Phase 4 handling for ModSecurity-nginx by Easton97-Jens · Pull Request #377 · owasp-modsecurity/ModSecurity-nginx · GitHub

Uh oh!

Implement Phase 4 handling for ModSecurity-nginx - #377

Implement Phase 4 handling for ModSecurity-nginx#377
Easton97-Jens wants to merge 29 commits into
owasp-modsecurity:masterfrom
Easton97-Jens:master-phase4

Easton97-Jens commented May 11, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

airween commented May 14, 2026

Uh oh!

sonarqubecloud Bot commented May 14, 2026

Uh oh!

Easton97-Jens commented May 14, 2026

Uh oh!

Easton97-Jens commented May 15, 2026 •
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

                       }
                       location /phase4 {
                           modsecurity on;
+                          modsecurity_phase4_mode strict;

Implement Phase 4 handling for ModSecurity-nginx by Easton97-Jens · Pull Request #377 · owasp-modsecurity/ModSecurity-nginx · GitHub

Uh oh!

Implement Phase 4 handling for ModSecurity-nginx - #377

Implement Phase 4 handling for ModSecurity-nginx#377Easton97-Jens wants to merge 29 commits intoowasp-modsecurity:masterowasp-modsecurity/ModSecurity-nginx:masterfrom Easton97-Jens:master-phase4Easton97-Jens/ModSecurity-nginx:master-phase4Copy head branch name to clipboard

Conversation

Easton97-Jens commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Why these changes

Logging and observability

Testing

Documentation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

airween commented May 14, 2026

Uh oh!

sonarqubecloud Bot commented May 14, 2026

Quality Gate passed

Uh oh!

Easton97-Jens commented May 14, 2026

Uh oh!

Easton97-Jens commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Implement Phase 4 handling for ModSecurity-nginx#377
Easton97-Jens wants to merge 29 commits into
owasp-modsecurity:masterfrom
Easton97-Jens:master-phase4

Easton97-Jens commented May 11, 2026 •
edited
Loading

Easton97-Jens commented May 15, 2026 •
edited
Loading