Implement Phase 4 handling for ModSecurity-nginx

[Easton97-Jens]

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

[Copilot]

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.

[airween]

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.

[sonarqubecloud]

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

[Easton97-Jens]

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 🙂