Skip to main content
logoTetrate Enterprise Gateway for Envoy (TEG)Version: v1.0.0

Using the In-Built "Coraza" Web Application Firewall

A Web Application Firewall (WAF) inspects inbound and outbound HTTP traffic. It matches the traffic against a range of signatures in order to detect attack attempts, malformed traffic, and exfiltration of sensitive data. Suspicious traffic can be blocked, alerts can be raised, and logs can be generated for later analysis. Tetrate Enterprise Gateway for Envoy (TEG) has a built-in WAF to protect your application workloads against malicious clients. TEG uses the Coraza WAF.

Coraza is an open-source, high-performance WAF which is configured using the standard mod_security SecLang rules format. Coraza in TEG is pre-configured with the OWASP Core Rule Set (CRS) rules (at the time of writing, CRS v4.0.0-rc2), however these can be tailored.

Enabling Coraza​

Coraza is enabled with a Helm value. The following command will deploy TEG with Coraza enabled. It will also re-configure an existing deployment to enable Coraza, but adjust the Helm release name and TEG version to match your existing deployment.

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

Verify Coraza​

The easiest way to verify that Coraza is enabled is to deploy and expose an example application, and try to send it a malicious request:

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

This request should result in a 403 Forbidden response from the gateway, as Coraza will identify the request as a possible cross-site-scripting (XSS) attack.

If you know how to view the gateway's proxy access logs, you'll see some Coraza logs above the access line for this request.

Customizing WAF Rules​

TEG's Coraza WAF is by default configured with the OWASP Core Rule Set (CRS), which is a good starting point for securing your applications. However it is highly recommended to customize the rule-set according to the specific environment and traffic the WAF will deal with. This is a key step to minimize performance overheads, and false positives while maximizing the effectiveness of the WAF.

Custom WAF config is also provided in the Helm values file. Let's start by recreating the default config:

values.yaml
corazaWaf:
  enabled: true

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

An overview of the default config:

  • Include @recommended-conf - Coraza basic set-up. The full file can be inspected for all details, but it includes:
    • SecRuleEngine: DetectionOnly - permissive ie detect-and-log-only mode
    • Request body access enabled - allows inspection of request bodies including POST parameters
    • Request body inspection limit: 128k
    • Response body access enabled - allows inspection of response bodies
  • SecRuleEngine On - overrides @recommended-conf to make enable blocking of requests
  • SecDebugLogLevel 2 - "warning" log level
  • Include @crs-setup-conf - basic config of the OWASP CRS, full file here, includes:
    • Mode of operation: Anomaly Scoring Mode, with threshold 5
    • Paranoia level: 1 - fewest false positives
  • Include @owasp_crs/*.conf - the main OWASP CRS rules

This configuration can then be altered to your needs. Authoring SecRule rules is outside the scope of this documentation, but bear in mind:

  • Directives' order matters: directives are checked in the order they are listed. It is expected to have Coraza WAF settings, followed by CRS setup, followed by CRS rules
  • Only the last occurrence of a SecLang directive (eg SecRuleEngine) will have effect

When you have a new rule-set you want to try, re-configure the Helm release to use the new settings:

helm upgrade --install tetrate-envoy-gateway \
  oci://docker.io/tetrate/teg-envoy-gateway-helm \
  -n envoy-gateway-system --create-namespace \
  --set-file values.yaml

Rule Tuning Tips​

In order to maximize the effectiveness of the WAF and reduce false-positives as much as possible, iterative tuning of WAF rules is recommended. This can be done thus:

  1. Put Coraza into DetectionOnly mode, so that "bad" rules aren't disruptive (be careful running this in production):
values.yaml
corazaWaf:
  enabled: true

  directives:
    - Include @recommended-conf
    - SecRuleEngine DectectionOnly
    - SecDebugLogLevel 2
    - Include @crs-setup-conf
    - Include @owasp_crs/*.conf
  1. Monitor the logs (ie the Pod logs for the Gateway through which test traffic is flowing). The string Coraza: Warning will be present in every log line pertaining to a triggered rule.
  2. Tune the rules. Generally speaking this involves add exclusions to avoid the false-positives, and extra detection rules to catch false-negatives. OWASP provides a more detailed guide on this.
  3. When you're happy with the rules, switch back from SecRuleEngine DetectionOnly to On.

Next Steps​