coraza-waf

A Web Application Firewall (WAF) HTTP filter plugin that provides layer 7 security for web applications using the Coraza WAF engine.

Features

This plugin provides comprehensive web application security:

• OWASP CRS (Core Rule Set): Built-in protection against common web attacks
• Request inspection: Analyzes HTTP requests for malicious patterns and anomalies
• Response inspection: Examines HTTP responses to prevent data leakage
• Flexible rule engine: Supports custom security rules and policies
• Multiple operation modes: Detection-only or active blocking modes
• Detailed logging: Comprehensive audit logging of security events

Security Rules

The WAF comes with support for OWASP CRS, formerly known as ModSecurity Core Rule Set (CRS), as well as some recommended configurations and allows custom rule configuration for specific security requirements. It is recommended to review the provided configuration files before deploying, to ensure they align with the target environment and the expected security posture. To use the bundled rules, you can include them with the Coraza Include directives as shown in this example:

{
  "directives": [
    "Include @coraza.conf",
    "Include @crs-setup.conf",
    "Include @owasp_crs/*.conf"
  ]
}

Available special names are:

Name	Aliases	Description
@coraza.conf-recommended	—	Coraza upstream configuration file example
@coraza.conf	@recommended.conf, @recommended-conf	Coraza configuration file tailored for Coraza dynamic module implementation
@crs-setup.conf.example	—	CRS upstream configuration file example
@crs-setup.conf	@crs-setup-conf	CRS configuration file tailored for Coraza dynamic module implementation
@owasp_crs/	—	CRS rules directory

Note: Aliases are provided for backward compatibility, but are deprecated and may be removed in future releases. It is recommended to use the primary names for new configurations.

To create custom rules, refer to the SecLang reference docs.

Mode

The optional mode setting controls which parts of the HTTP exchange are evaluated by the WAF. Use the narrowest mode that matches your policy to avoid unnecessary processing.

• REQUEST_ONLY (default): Inspect request headers, body, and trailers only. This is the best choice for typical OWASP CRS deployments that focus on inbound attack detection.
• RESPONSE_ONLY: Inspect response headers, body, and trailers only. Use this when you only need outbound inspection, such as detecting sensitive data in responses.
• FULL: Inspect both request and response phases. Use this when your rules need visibility into both directions of traffic.

{
  "mode": "FULL",
  "directives": [
    "Include @coraza.conf",
    "Include @crs-setup.conf",
    "Include @owasp_crs/*.conf"
  ]
}

Note: mode only decides which request and response phases are passed to Coraza. It does not enable body access by itself. For example, FULL allows response-phase evaluation, but response body inspection still requires directives such as SecResponseBodyAccess On.

Metadata

The plugin emits the following filter dynamic metadata when requests are blocked by the WAF:

Namespace	Key	Description
io.builtonenvoy.waf	block_phase	Phase in which the requests has been blocked. See the execution flow for details on the possible values.
io.builtonenvoy.waf	block_rule	ID of the rule that triggered the block.

Metrics

The extension exposes the following metrics:

Metric	Tags	Type	Description
waf_tx_total	-	Counter	Total amount of transactions processed by the WAF.
waf_tx_blocked	authority, phase, rule_id	Counter	Total amount of transactions blocked by the WAF. The rule_id will not be set if the request is not blocked by a concrete rule but by a WAF internal error.

Per Route Configuration

The extension supports per-route configuration, allowing you to specify different WAF rules and policies for different routes in your application. This is useful for tailoring security measures to specific endpoints or services.

The per-route configuration share the same format as the extension configuration and see Envoy's Dynamic Per Route Configuration for more details on how to set it up.