Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 30 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,27 @@ to be generated).
Logs are read from memory using `WEBSERVER_ERROR_LOG` variable, so plugin does
not need any permissions to access log files on filesystem.

> [!WARNING]
> **Use at your own risk.**
>
> This plugin should only be used if the **number of false positives is sufficiently low**.
> With a high volume of false positives, e-mails will **flood the recipient inbox** and
> will **clog the SMTP server**, potentially backing up e-mails for hours.
>
> **The CRS team cannot and will not support** issues with the SMTP server or e-mail floods
> resulting from the use of this plugin.


## Prerequisities

* ModSecurity compiled with Lua support
* LuaSocket library
* LuaSec library (optional, for TLS)
* plugin is able to catch only messages returned by rules with `log` action
* ModSecurity compiled with Lua support
* LuaSocket library
* LuaSec library (optional, for TLS)
* Rules for which an e-mail is expected to be sent have the `log` action. The plugin relies
on the `log` action to work.
* A working SMTP server (configuration not covered by this documentation). The SMTP
server should be configured with rate limiting to prevent e-mail floods in case of
a sudden large volume of triggered CRS rules.

## How to determine whether you have Lua support in ModSecurity

Expand Down Expand Up @@ -56,6 +71,17 @@ For full and up to date instructions for the different available plugin
installation methods, refer to [How to Install a Plugin](https://coreruleset.org/docs/concepts/plugins/#how-to-install-a-plugin)
in the official CRS documentation.

### Setup verification

After installation and configuration (see next section), the plugin should be tested
to ensure that it works as desired. A simple test for the SMTP setup is to send a
request that is known trigger CRS to the server:
```
curl "http://localhost?test=/etc/passwd"
```
After sending the request, an e-mail should arrive in the configured e-mail inbox.


## Configuration

All settings can be done in file `plugins/false-positive-report-config.conf`.
Expand Down Expand Up @@ -261,11 +287,6 @@ special meaning. If you want to match such characeters, you need to escape them
using `%` character. For example, this pattern can be used to match
`wp-config.php`: `wp%-config`

## Testing

After configuration, plugin should be tested, for example, using:
...

## License

Copyright (c) 2022-2025 OWASP Core Rule Set project. All rights reserved.
Expand Down
17 changes: 17 additions & 0 deletions tests/regression/false-positive-report-plugin/111111.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
meta:
author: "azurit"
description: "False positive report plugin"
tests:
- test_title: 9500100-1
desc: Dummy test to satisfy CI
stages:
- input:
dest_addr: 127.0.0.1
headers:
Host: localhost
User-Agent: OWASP CRS
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
port: 80
method: GET
uri: /
Loading