Using the Built-in "Coraza" Web Application Firewall in Tetrate Enterprise Gateway

The Web Application Firewall (WAF) in Tetrate Enterprise Gateway (TEG) examines both inbound and outbound HTTP traffic to identify threats such as attack attempts, malformed traffic, and data exfiltration. By utilizing signature matching, TEG's built-in WAF, powered by Coraza, can block suspicious traffic, issue alerts, and log incidents for further investigation.

Configuration

Coraza is an open-source, high-performance WAF using the widely-accepted mod_security SecLang rules format. It comes pre-configured with the OWASP Core Rule Set (CRS), version 4.3.0 at the time of this writing, which can be customized to fit specific security needs.

Enabling Coraza

Coraza is activated via a Helm configuration. To deploy or update an existing TEG deployment with Coraza enabled, use the following command, adjusting the release name and version as necessary:

helm upgrade --install teg \
  oci://docker.io/tetrate/teg-envoy-gateway-helm \
  -n envoy-gateway-system --create-namespace \
  --set corazaWaf.enabled=true \
  --version v0.0.0-latest

With this setup,

• the WAF is enabled on Gateways.
• a container running Coraza, named coraza-waf-extproc, added to the Envoy deployment managed by Envoy Gateway.
• the WAF configuration will be loaded from the ConfigMap named waf-config in the envoy-gateway-system namespace.

Verification

To verify Coraza's activation, deploy an example application and attempt a malicious request:

curl -i http://${DEDICATED_GATEWAY_IP}/httpbin/get?arg=<script>alert(0)</script>

A 403 Forbidden response indicates Coraza has successfully identified the request as a potential XSS attack. Further evidence can be found in the gateway's proxy access logs.

Customizing WAF Rules

The configuration for Coraza is loaded from a ConfigMap named waf-config in the envoy-gateway-system namespace. The changes to the ConfigMap will take effects in a few seconds by the WAF container without restarts.

While the default configuration uses the OWASP CRS, customization is crucial for adapting to specific operational environments to minimize performance impacts and false positives.

Default Configuration

The default configuration loaded by Coraza is set in the ConfigMap waf-config in the envoy-gateway-system namespace as follows:

waf-config.yaml

kind: ConfigMap
apiVersion: v1
data:
   waf.yaml: |-
      # This is the default configuration for the Coraza WAF.
      directives:
      - Include @recommended-conf
      - SecRuleEngine On
      - SecDebugLogLevel 2
      - Include @crs-setup-conf
      - Include @owasp_crs/*.conf
# Omitted other fields for brevity.

where waf.yaml is the key for the WAF configuration data and directives key contains the configuration directives.

Detailed explanations:

• SecRuleEngine On: Activates blocking of detected threats, overriding the more permissive settings from @recommended-conf.
• SecDebugLogLevel 2: Sets the log level to "warning".
• The configuration files (@recommended-conf and @crs-setup-conf) set up the initial rules and operational parameters. The actual rule files (@owasp_crs/*.conf) implement the security measures.

Modifying and Testing New Rules

When modifying rules in the ConfigMap, the sequence in which directives are listed is crucial; each setting must be strategically placed to ensure proper processing order. Here are steps to fine-tune the WAF behavior:

1. Set Coraza to DetectionOnly mode to non-disruptively observe rule impacts:

   values.yaml

   directives:
     - Include @recommended-conf
     - SecRuleEngine DetectionOnly
     - SecDebugLogLevel 2
     - Include @crs-setup-conf
     - Include @owasp_crs/*.conf

2. Every log line from coraza-waf-extproc container associated with a triggered rule will contain the string Coraza: Warning. Review the gateway pod logs to identify triggered rules and adjust accordingly to balance security and usability.

3. Once satisfied, switch SecRuleEngine back to On to enforce the rules.

For a detailed guide on rule tuning, refer to the OWASP rule tuning documentation.

If the configuration is invalid, you will see an error message in the logs of the coraza-waf-extproc container. Loading invalid configuration will not affect the ongoing traffic, and the WAF will continue to operate with the last valid configuration.