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.25.0 at the time of this writing, which can be customized to fit specific security needs.

Installing TEG Envoy image with Coraza WAF

To attach the WAF to Gateways, you need to set the default Envoy Proxy image to the Tetrate Envoy Gateway-provided Envoy image.

It can be done via a helm value config.envoyProxy.provider.kubernetes.envoyDeployment.container.image like this:

helm upgrade --install teg \
  oci://docker.io/tetrate/teg-envoy-gateway-helm \
  -n envoy-gateway-system --create-namespace \
  --set config.envoyProxy.provider.kubernetes.envoyDeployment.container.image=tetrate-envoy-gateway.containers.dl.tetrate.io/envoy:v1.8.0 \
  --set "config.envoyProxy.provider.kubernetes.envoyDeployment.pod.imagePullSecrets[0].name=tetrate-waf-creds" \
  --version v1.8.0

If you are using a custom "EnvoyProxy" resource attached to your Gateway, you can follow the example below to set the image for the Envoy Proxy container.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
spec:
  provider:
    kubernetes:
      envoyDeployment:
        container:
          image: tetrate-envoy-gateway.containers.dl.tetrate.io/envoy:v1.8.0
        pod:
          imagePullSecrets:
            - name: tetrate-waf-creds
    type: Kubernetes
# ... Other fields are omitted for brevity.

The image tetrate-envoy-gateway.containers.dl.tetrate.io/envoy:v1.8.0 can be pulled with a credential that has access to the Tetrate Enterprise Gateway repository. Please contact Tetrate support to obtain the access to the image repository. The distroless/FIPS images are also available as

• tetrate-envoy-gateway.containers.dl.tetrate.io/envoy:distroless-v1.8.0
• tetrate-envoy-gateway.containers.dl.tetrate.io/envoy:v1.8.0-fips
• tetrate-envoy-gateway.containers.dl.tetrate.io/envoy:distroless-v1.8.0-fips

Attaching ExtendedSecurityPolicy to Gateway

WAF can be configured as part of the ExtendedSecurityPolicy resource, which is attached to a Gateway. In short, the ExtendedSecurityPolicy resource allows you to define WAF rules, and the WAF filter will be attached to the Gateways. For details, see API documentation for Extended SecurityPolicy.

First, let's deploy an example application. Then, apply an ExtendedSecurityPolicy as follows:

apiVersion: teg.tetrate.io/v1alpha1
kind: ExtendedSecurityPolicy
metadata:
  name: attach-waf
  namespace: httpbin
spec:
  targetRefs:
    - name: dedicated-gateway
      kind: Gateway
      group: gateway.networking.k8s.io
  waf: {}  # Let's use the default WAF policy.

where we attach the ExtendedSecurityPolicy to the dedicated-gateway Gateway in the httpbin namespace. The waf: {} field indicates that we want to use the default WAF policy.

Let's 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

Default Configuration

The default WAF policy is as follows:

waf-config.yaml

apiVersion: teg.tetrate.io/v1alpha1
kind: ExtendedSecurityPolicy
spec:
  waf:
    directives: |
      Include /etc/teg/waf/teg-default.conf
      Include @crs-setup.conf
      Include @owasp_crs/*.conf

where you can put the WAF directives into the directives field.

The TEG Envoy image packages the default WAF tuning directives in /etc/teg/waf/teg-default.conf, so custom WAF configurations can include TEG's default Coraza settings directly and override only the directives that need to change.

Detailed explanations:

• /etc/teg/waf/teg-default.conf: Loads Coraza's base settings from @coraza.conf, then applies TEG's default WAF tuning. TEG's defaults set SecRuleEngine On, SecDebugLogLevel 2, conservative 4096-byte request and response body inspection limits, SecRequestBodyLimitAction ProcessPartial, SecResponseBodyLimitAction ProcessPartial, and SecResponseBodyAccess Off.
• SecRuleEngine On: Activates blocking of detected threats. You can override this after including /etc/teg/waf/teg-default.conf, for example with SecRuleEngine DetectionOnly.
• SecDebugLogLevel 2: Keeps Coraza warning logs useful while avoiding verbose debug output by default.
• SecRequestBodyLimit 4096, SecRequestBodyInMemoryLimit 4096, and SecRequestBodyLimitAction ProcessPartial: Keep request body inspection below Envoy Gateway's default buffer limit and process partial bodies instead of rejecting traffic only because the body is larger than TEG's conservative inspection window.
• SecResponseBodyLimit 4096, SecResponseBodyLimitAction ProcessPartial, and SecResponseBodyAccess Off: Keep response body buffering conservative and non-disruptive by default. Response body inspection is disabled unless you explicitly opt in.
• @crs-setup.conf: Loads the TEG-provided CRS setup file, which sets up the initial rules and operational parameters.
• @owasp_crs/*.conf: Loads the OWASP CRS rule files from the bundled coraza coreruleset dependency. These files implement the security measures, including request method enforcement and SQL injection detection rules.

Modifying and Testing New Rules

When modifying rules in the ExtendedSecurityPolicy, 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 /etc/teg/waf/teg-default.conf
     SecRuleEngine DetectionOnly
     Include @crs-setup.conf
     Include @owasp_crs/*.conf

2. Every log line 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 TEG controller as well as it will be reflected on the status of ExtendedSecurityPolicy resource. Loading invalid configuration will not affect the ongoing traffic, and the WAF will continue to operate with the last valid configuration.