# Coraza role

This role installs the Coraza WAF SPOA connector, an HTTP filtering layer that integrates the OWASP Core Rule Set (CRS) via HAProxy's SPOE mechanism.

It is intended for production environments where applications require firewalling, and it supports tuning of security behavior through multiple paranoia levels and customizable directives.

<!-- TOC -->
* [Coraza role](#coraza-role)
  * [Variable reference](#variable-reference)
    * [Mandatory variables](#mandatory-variables)
    * [Optional variables](#optional-variables)
  * [Configuration](#configuration)
  * [Usefull links](#usefull-links)
<!-- TOC -->

## Variable reference

### Optional variables

| Variable                           | Description                                                        | Type of variable | Default value                                      | Other value                                        |
|------------------------------------|--------------------------------------------------------------------|------------------|----------------------------------------------------|----------------------------------------------------|
| `coraza_spoa_transaction_ttl_ms`   | Transaction lifetime in milliseconds                               | `integer`        | `500`                                              | `300`, `900`, `3000`                             |
| `coraza_directives`                | Block of Coraza/ModSecurity directives to inject                   | `multiline`      | _Default OWASP CRS directives block_               | `SecRuleEngine DetectionOnly`, custom directives   |
| `coraza_sec_rule_engine`           | Enables or disables Coraza traffic processing                      | `string`         | `DetectionOnly`                                    | `On`, `DetectionOnly`, `Off`                       |
| `coraza_paranoia_level`            | OWASP CRS paranoia level: strictness & false positive sensitivity  | `integer`        | `1`                                                | `1`, `2`, `3`, `4`                                 |

## Configuration

By default, this role applies a moderate Coraza WAF configuration, using the lowest paranoia level and loading all available OWASP CRS rules and plugins:

```yaml
SecAction "id:1000001,phase:1,pass,t:none,nolog,setvar:tx.blocking_paranoia_level=1
Include /etc/coraza/coraza.conf
Include /etc/coraza/crs-setup.conf
Include /etc/coraza/plugins/*.conf
Include /etc/coraza/rules/*.conf
```
This default setup is safe for most production environments, with minimal risk of blocking legitimate traffic. However, if your application requires stricter protections, you can adjust the behavior using the `coraza_paranoia_level` variable, which supports **4 levels of rule strictness**:

* **1** - **Baseline** - Minimal false positives, safe for most applications. There should be no tuning needed.
* **2** - **Enhanced** - Rules that are adequate when real customer data is involved. Expect false positives, might require tuning.
* **3** - **Strict** - Online banking level security with many false positives, frequent tuning needed.
* **4** - **Aggressive** - Rules that are super aggressive. There will be a lot of false positives, lots of tuning needed (essential).

If you choose a paranoia level higher than 1, be aware that false positives are more likely, potentially blocking legitimate traffic. In such cases, it is strongly advised to tune the WAF directives for your specific application by overriding the default rules with the `coraza_directives` variable.

This allows you to include only selected rule sets or inject custom SecRule logic that satisfies your needs.

You can check [what's in the rules](https://coreruleset.org/docs/3-about-rules/rules/) in OWASP CRS documentation.

## Usefull links

* [Coraza SPOA repository](https://github.com/corazawaf/coraza-spoa)
* [Coraza SPOA documentation](https://coraza.io/connectors/coraza-spoa/)
* [Coraza documentation](https://coraza.io/docs/tutorials/introduction/)
* [Coraza/ModSecurity directives ](https://coraza.io/docs/seclang/directives/)
* [OWASP CRS repository](https://github.com/coreruleset/coreruleset)
* [OWASP CRS documentation](https://owasp.org/www-project-modsecurity-core-rule-set/)
* [Working with paranoia levels](https://coreruleset.org/20211028/working-with-paranoia-levels/)