“ModSecurity will help you sleep better at night because, above all, it solves the visibility problem: it lets you see your web traffic.”
– Ivan Ristić, creator of ModSecurity
When something is not working as you expect it to, logs are always the first place to look. Good logs can provide valuable insights to help you troubleshoot the problems you’re facing. One of the reasons Ivan Ristić originally created ModSecurity is that he was frustrated with the lack of visibility in the tools he was using. It’s no surprise, then, that ModSecurity has extensive logging and debugging capabilities.
ModSecurity has two types of logs:
- An audit log. For every transaction that’s blocked, ModSecurity provides detailed logs about the transaction and why it was blocked.
- A debug log. When turned on, this log keeps extensive information about everything that ModSecurity does.
The audit log is useful for learning not just why an individual attack was blocked, but for finding out more about overall attack patterns. You might be surprised by how much bot and scanner traffic you get just by exposing ports 80 and/or 443 to the Internet.
In this blog post, we’ll describe the basics of logging and debugging with ModSecurity.
Audit Log
The main log in ModSecurity is the audit log, which logs all attacks, including potential attacks, that occur. If you’ve followed our installation instructions for ModSecurity (with NGINX Open Source) or the NGINX ModSecurity WAF (with NGINX Plus), then by default, ModSecurity will log all transactions that triggered a warning or error, as well as all transactions that resulted in 5xx and 4xx responses, except for 404. (For an Ubuntu 16.04 system only, the audit log is in /var/log/modsec_audit.log.)
The ModSecurity audit log is partitioned into sections. This makes it easier to scan the log and find the information you’re looking for. The table below outlines what each section contains:
| Section | Description |
|---|---|
| A | Audit log header (mandatory) |
| B | Request headers |
| C | Request body |
| D | Reserved |
| E | Response body |
| F | Response headers |
| G | Reserved |
| H | Audit log trailer, which contains additional data |
| I | Compact request body alternative (to part C), which excludes files |
| J | Information on uploaded files |
| K | Contains a list of all rules that matched for the transaction |
| Z | Final boundary (mandatory) |
Each transaction that triggers an audit log entry will have any or all of the above sections logged. You can configure which sections are logged.
Audit Log Example
A sample ModSecurity audit log entry might look like this:
Though it’s not immediately apparent from the table above, the best section to find information on why a particular request was blocked is section H, not section K. From the above audit log example, if we scan through section H, we can see the message "Host header is a numeric IP address" which indicates someone tried to access our site by IP address rather than by hostname. This may be indicative of a scanner.
Audit Logging Configuration
If you followed our instructions for installing and configuring ModSecurity, you’ll find the audit logging configuration in /etc/nginx/modsec/modsecurity.conf. In that file, you’ll see the following three directives that control what is put into the audit log:
where
SecAuditEngine– Controls what should be logged. Options are:Off– Disable the audit log.On– Log all transactions, which can can useful when debugging.RelevantOnly– Log only transactions that have triggered a warning/error, or have a status code that matches what’s in theSecAuditLogRelevantStatusdirective.
SecAuditLogRelevantStatus–If SecAuditEngineis set toRelevantOnly, then this directive controls what HTTP response status codes should be logged. It’s regular expression‑based. The above value will log all5xxand4xxresponses, excluding404s.SecAuditLogParts– Controls what sections should be included in the access log. Removing sections you’re not interested in reduces the size of the audit log and make it easier to scan.
For additional audit‑logging configuration directives, refer to the ModSecurity wiki.
Debug Log
When the debug log is turned on, it provides a wealth of information on everything ModSecurity does. For troubleshooting issues as to why something is not working the way you expect it to, the debug log is your go‑to resource. It’s also great if you’re getting started with ModSecurity and want to observe why it does things a certain way.
Debug Log Example
The debug log looks like the following. It has a lot of details on the actions ModSecurity takes for any and all transactions:
The debug log lists the rule ID number for easy searching. In this example, the output is from our test rule with ID number 1234.
Debug Log Configuration
By default, the debug log is disabled, as it can negatively affect performance. Just as with audit logging, the debug log is configured in /etc/nginx/modsec/modsecurity.conf. In that file, there are two configuration directives that are commented out. To enable debug logging, uncomment them and change them to the following:
where
- SecDebugLog – Specifies the path to the debug log file.
- SecDebugLogLevel –
0–9indicates how much information to log, with9being the most. If you’re troubleshooting, setting this value to9is the most helpful.
Conclusion
In this blog post, we covered how to get started using the extensive logging capabilities within ModSecurity. ModSecurity has both audit logs, which contain information about all blocked transactions, and a debug log to further assist you if you’re having trouble using ModSecurity.
ModSecurity 3.0 is available for both NGINX Open Source and as the NGINX ModSecurity WAF for NGINX Plus. The NGINX ModSecurity WAF is a precompiled dynamic module that is maintained and fully supported by NGINX, Inc. Try it free for 30 days.
[Editor – NGINX ModSecurity WAF officially went End-of-Sale as of April 1, 2022 and is transitioning to End-of-Life effective March 31, 2024. For more details, see F5 NGINX ModSecurity WAF Is Transitioning to End-of-Life<.htmla> on our blog.]
About the Author
Related Blog Posts
Secure Your API Gateway with NGINX App Protect WAF
As monoliths move to microservices, applications are developed faster than ever. Speed is necessary to stay competitive and APIs sit at the front of these rapid modernization efforts. But the popularity of APIs for application modernization has significant implications for app security.
How Do I Choose? API Gateway vs. Ingress Controller vs. Service Mesh
When you need an API gateway in Kubernetes, how do you choose among API gateway vs. Ingress controller vs. service mesh? We guide you through the decision, with sample scenarios for north-south and east-west API traffic, plus use cases where an API gateway is the right tool.
Deploying NGINX as an API Gateway, Part 2: Protecting Backend Services
In the second post in our API gateway series, Liam shows you how to batten down the hatches on your API services. You can use rate limiting, access restrictions, request size limits, and request body validation to frustrate illegitimate or overly burdensome requests.
New Joomla Exploit CVE-2015-8562
Read about the new zero day exploit in Joomla and see the NGINX configuration for how to apply a fix in NGINX or NGINX Plus.
Why Do I See “Welcome to nginx!” on My Favorite Website?
The ‘Welcome to NGINX!’ page is presented when NGINX web server software is installed on a computer but has not finished configuring