ModSecurity logging and troubleshooting

Reviewed by Atomicorp WAF Research Team

Start with the audit log

A useful event answers five questions:

1. Which request and client triggered the event?
2. Which rule ID and message matched?
3. Which variable contained the matched data?
4. Was the transaction only logged or actually disrupted?
5. Which engine, connector, and rule versions were loaded?

Keep the complete audit transaction when escalating an issue, but remove credentials, session cookies, tokens, and personal data before sharing it.

Relevant-only logging

SecAuditEngine RelevantOnly
SecAuditLogRelevantStatus "^(?:5|4(?!04))"
SecAuditLogParts ABIJDEFHZ

Audit-log parts control which transaction sections are recorded. More data helps debugging but can increase storage and expose sensitive request content. Choose parts deliberately and protect the log directory.

A rule logged but did not block

Check:

• Whether SecRuleEngine is DetectionOnly.
• Whether the matched rule has a disruptive action or inherits one.
• Whether an earlier allow, skip, or skipAfter changed processing.
• Whether ctl modified rule-engine behavior for the transaction.
• Whether the connector supports the directive or action in use.

A legitimate request was blocked

Record the rule ID, match details, request path, application and version, and a safe reproduction. Prefer a narrow exclusion for the affected parameter or route over disabling an entire rule globally.

Atomic commercial-rule users should report qualifying false positives for an upstream same-day fix under the Zero False Positive Guarantee.

Configuration will not load

Look for duplicate rule IDs, unsupported directives, quoting errors, missing included files, unreadable directories, or syntax intended for a different engine generation. Validate Apache or Nginx configuration before restart and inspect the web-server error log for the exact file and line.

Upstream debugging guidance provides deeper engine-level diagnostics.