Repository navigation
Implement Phase 4 handling for ModSecurity-nginx - #377
Easton97-Jens wants to merge 50 commits into
Conversation
…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)
There was a problem hiding this comment.
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, andstrictPhase 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.
| } | ||
| location /phase4 { | ||
| modsecurity on; | ||
| modsecurity_phase4_mode strict; |
|
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. |
|
Hi @airween, I've pushed updates following your review. The current head is The following changes are implemented:
Two points still need to be settled:
The current behavior is described in the updated English documentation and diff; the PR description still awaits replacement. Could you take another look at the updated diff, especially the remaining |
|
Hi @airween, I've updated the PR following your review and integrated the relevant NGINX corrections from ModSecurity-conector. The current head is Implemented changes include:
Two review points remain explicit: Could you take another look at the current diff and the updated English documentation, particularly those remaining design points? Thank you for reviewing it. |
|



What changed
This PR introduces and stabilizes dedicated
phase:4handling for the nginx ModSecurity connector. It also adapts the relevant native-result and lifecycle corrections from ModSecurity-conector d420a12, preserving this standalone connector and its JSON event schema.Main additions include:
off(default)safestrictmodsecurity_phase4_logSecResponseBodyAccessSecResponseBodyMimeTypeandSecResponseBodyMimeTypesClearSecResponseBodyLimitandSecResponseBodyLimitActionAdditional fixes included in this PR:
minimalmode and the connector MIME-file directive/extra MIME gate from earlier revisions of this PRmodsecurity_phase4_body_limitas a deprecated, ignored compatibility setting, with positive-value validation; inspection limits belong to the enginehttp,server, andlocation, with a server-to-location regression testSIZE_MAXdelivery limitphase4-unit-testsfromtest.ymltotest_new.ymland disabled credential persistence for all ten checkouts in the new workflowerror_pagetarget to render without reblockingTransfer-Encodinginspection headers on HTTP/2/HTTP/3 and checked response status before native integer conversionWhy these changes
phase:4operates 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:
denystatusredirectcannot always be converted into a clean client-visible HTTP response once headers are already sent. Bytes already delivered to the client cannot be recalled.
This PR introduces explicit handling for those late-intervention scenarios:
off→ default; disables the additional safe/strict connector policy while leaving native ModSecurity response inspection and interventions active
safe→ opt-in; attempts
log_onlylogging and continues after headers are sent, diagnosing optional event-log failuresstrict→ opt-in; records
connection_abortand terminates the response after headers are sentBefore headers are committed, interventions can use the normal status/redirect path. Genuine engine, buffer, body-processing allocation, file-read and native audit errors remain failures, including in
safe. Cumulative accounting saturates without cutting large responses. After commitment, optional JSON event-log failures are diagnosed without aborting Safe delivery; the existing pre-commit error path remains. Native response-limit Reject is distinct from a rule intervention: it produces 403 before headers are sent, or fails the committed transport, in all modes. ProcessPartial still allows full forwarding of the original response. Append-time unknown disruptive results cannot become Safe log-only events. Neithersafenorstrictcan guarantee a new client-visible status after headers are sent.The goal is to:
On HTTP/2, a late Strict decision resets the affected stream while unrelated streams and the physical connection remain usable. The bundled host-core patch schedules queued reset delivery even while another stream remains open. Apply it before rebuilding NGINX; dynamic-module installations require the patched host binary as well. Replacing only the connector module cannot correct an existing host.
One compatibility point remains open:
offdoes not reproduce every pre-PR intervention control-flow decision. Native failures remain terminal, and late native intervention handling fails the committed transport without trying to emit a second response header. This PR does not claim exact legacy callback/return-value equivalence.Logging and observability
The new phase4 logging implementation provides optional structured JSON-lines logging including fields such as:
JSON controls are escaped without losing their values; valid UTF-8 is preserved and invalid bytes are explicitly escaped. Rule IDs and presence summaries come only from complete, unambiguous engine metadata, so reflected delimiter-like content cannot override them. Raw engine intervention messages are redacted. Tests also verify that response-body payload data is not leaked into dedicated phase4 events. These events are not a complete inventory of engine errors or a replacement for nginx/ModSecurity logging.
The
interventionfield is still retained alongsiderule_id; the review suggestion to rename or remove it has not been adopted. Late completed-P4 Safe/Strict decisions do not invoke native status replacement or early audit logging. Native limit errors use an nginx error diagnostic rather than a misleading rule-policy event.Testing
This PR adds and extends coverage for:
Reject/ProcessPartialresponse limitsThe standalone helper tests run with GCC and Clang as
phase4-unit-testsin.github/workflows/test_new.yml, rather than the legacy workflow. All ten checkouts there usepersist-credentials: false. The new native matrix covers nginx 1.29.x/1.30.x/1.31.x on Ubuntu 24.04/26.04 and Windows 2022. The duplicate legacy Windows job is removed; the legacy Linux jobs remain.Validation for head
7a5a336:Optional unsafe proxy/HTTP/2 assertions require their test environment; this does not claim that every optional protocol assertion ran in those checks.
Documentation
Comprehensive documentation for the implemented behavior was added and updated, including:
phase:4off,safe, andstrictoffcompatibility differenceCHANGESand the corrected README count of nine directivesThe English documentation is the maintained source. The German translation is removed.
Summary by CodeRabbit
New Features
off,safe, andstrictmodes, plus optional JSON event logging.Behavior Changes
off; this disables the additional safe/strict connector policy while leaving native response inspection active. Full pre-PR intervention control-flow compatibility remains open. Theminimalmode and content-types-file directive are no longer supported.safecontinues rule-only delivery even if optional event logging fails (with a diagnostic), whilestrictterminates the response. Native response-limit Reject remains a failure in every mode.Documentation
CHANGES.