Integrate with Coraza

With rapid development of technology, it has become increasingly crucial to secure APIs. APISIX supports the integration with Coraza by using coraza-proxy-wasm to provide reliable security protection and ensure the integrity and reliability of API services.

Coraza is an open-source, enterprise-grade, high-performance Web Application Firewall (WAF). It is designed to safeguard web applications against various cyberattacks by filtering and monitoring HTTP/HTTPS communications between web applications and the internet. Integrating with Coraza, APISIX significantly enhances APISIX's ability to protect upstream services.

This guide will show you how to enable coraza-proxy-wasm to integrate APISIX with Coraza WAF to protect upstream services.

Prerequisite(s)

• Install Docker.
• Install cURL to send requests to the services for validation.
• Install ZIP to unzip the coraza-proxy-wasm binary from the release page.
• Follow the Getting Started tutorial to start a new APISIX instance in Docker.

Download coraza-proxy-wasm

Download coraza-proxy-wasm from the release page and unzip it:

wget https://github.com/corazawaf/coraza-proxy-wasm/releases/download/0.4.0/coraza-proxy-wasm-0.4.0.zip
unzip coraza-proxy-wasm-0.4.0.zip

Copy coraza-proxy-wasm.wasm into the /usr/local/bin directory:

docker cp /path/to/coraza-proxy-wasm.wasm apisix-quickstart:/usr/local/bin/

Load coraza-proxy-wasm in APISIX

Update the config.yaml configuration file by adding coraza-proxy-wasm configurations:

docker exec apisix-quickstart /bin/bash -c "echo '
wasm:
  plugins:
    - name: coraza-filter
      priority: 7999
      file: /usr/local/bin/coraza-proxy-wasm.wasm
' >> /usr/local/apisix/conf/config.yaml"

❶ name: the name of the APISIX plugin corresponding to coraza-proxy-wasm.

❷ priority: the execution priority of the plugin.

❸ file: the absolute path to coraza-proxy-wasm.

Reload APISIX for configuration changes to take effect:

docker exec apisix-quickstart apisix reload

Configure Specific Security Rules

Create a route and enable coraza-filter:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/" -X PUT -d '
{
  "id": "getting-started-waf",
  "uri": "/anything/*",
  "plugins": {
    "coraza-filter": {
      "conf": {
        "directives_map": {
          "default": [
            "SecDebugLogLevel 9",
            "SecRuleEngine On",
            "SecRule REQUEST_URI \"@beginsWith /anything/archive\" \"id:101,phase:1,t:lowercase,deny\""
          ]
        },
        "default_directives": "default"
      }
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

❶ SecDebugLogLevel: configure the debug log level. For details, see SecDebugLogLevel.

❷ SecRuleEngine: configure the rules engine. For details, see SecRuleEngine.

❸ SecRule: check the URI value of your HTTP request to see if the URI value begins with /anything/archive. If matched, the request will be rejected. For details, see SecRule.

Verify

Send a request to the route to verify if the HTTP request with an URI beginning with anything/archive will be rejected:

curl -i "http://localhost:9080/anything/archive/test"

You should receive an HTTP/1.1 403 Forbidden response.

Send a request to the route to verify if the HTTP request with an URI beginning with anything will be allowed:

curl -i "http://localhost:9080/anything/public"

You should receive an HTTP/1.1 200 OK response.

Configure OWASP Core Rule Set

You can also configure the entire OWASP Core Rule Set (CRS) on the route as such:

curl -i "http://127.0.0.1:9180/apisix/admin/routes/" -X PUT -d '
{
  "id": "getting-started-waf",
  "uri": "/anything/*",
  "plugins": {
    "coraza-filter": {
      "conf": {
        "directives_map": {
          "default": [
            "SecDebugLogLevel 9",
            "SecRuleEngine On",
            "Include @crs-setup-conf",
            "Include @owasp_crs/*.conf"
          ]
        },
        "default_directives": "default"
      }
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

❶ Include @crs-setup-conf to support CRS.

❷ Include all CRS rules. You could also include a specific rule, such as @owasp_crs/REQUEST-941-APPLICATION-ATTACK-XSS.conf. See all available rules.

Verify

Send a request with a potential XSS attack to the route:

curl -i "http://localhost:9080/anything/public" -H "Cookie: <body onload='alert(xss)'>"

You should receive an HTTP/1.1 403 Forbidden response and observe the following in log:

2023/12/21 02:27:14 [emerg] 130#130: *116868 [client ""] Coraza: Warning. NoScript XSS InjectionChecker: HTML Injection [file "@owasp_crs/REQUEST-941-APPLICATION-ATTACK-XSS.conf"] [line "7529"] [id "941160"] [rev ""] [msg "NoScript XSS InjectionChecker: HTML Injection"] [data "Matched Data: <body  found within REQUEST_COOKIES_NAMES:<body onload: <body onload"] [severity "critical"] [ver "OWASP_CRS/4.0.0-rc2"] [maturity "0"] [accuracy "0"] [tag "application-multi"] [tag "language-multi"] [tag "platform-multi"] [tag "attack-xss"] [tag "paranoia-level/1"] [tag "OWASP_CRS"] [tag "capec/1000/152/242"] [hostname ""] [uri "/anything/public"] [unique_id "vXZLznnuwaZHkjIBXyN"], client: 172.24.0.1, server: _, request: "GET /anything/public HTTP/1.1", host: "localhost:9080"
2023/12/21 02:27:14 [emerg] 130#130: *116868 [client ""] Coraza: Warning. Javascript method detected [file "@owasp_crs/REQUEST-941-APPLICATION-ATTACK-XSS.conf"] [line "8023"] [id "941390"] [rev ""] [msg "Javascript method detected"] [data "Matched Data: alert( found within REQUEST_COOKIES:<body onload: 'alert(xss)'>"] [severity "critical"] [ver "OWASP_CRS/4.0.0-rc2"] [maturity "0"] [accuracy "0"] [tag "application-multi"] [tag "language-multi"] [tag "attack-xss"] [tag "paranoia-level/1"] [tag "OWASP_CRS"] [tag "capec/1000/152/242"] [hostname ""] [uri "/anything/public"] [unique_id "vXZLznnuwaZHkjIBXyN"], client: 172.24.0.1, server: _, request: "GET /anything/public HTTP/1.1", host: "localhost:9080"
2023/12/21 02:27:14 [emerg] 130#130: *116868 [client ""] Coraza: Access denied (phase 1). Inbound Anomaly Score Exceeded in phase 1 (Total Score: 10) [file "@owasp_crs/REQUEST-949-BLOCKING-EVALUATION.conf"] [line "11098"] [id "949111"] [rev ""] [msg "Inbound Anomaly Score Exceeded in phase 1 (Total Score: 10)"] [data ""] [severity "emergency"] [ver "OWASP_CRS/4.0.0-rc2"] [maturity "0"] [accuracy "0"] [tag "anomaly-evaluation"] [hostname ""] [uri "/anything/public"] [unique_id "vXZLznnuwaZHkjIBXyN"], client: 172.24.0.1, server: _, request: "GET /anything/public HTTP/1.1", host: "localhost:9080"

This verifies that the CRS rules are in effect to protect your route.

Next Steps

APISIX also supports the integration with Chaitin WAF and other WAFs provided by popular cloud vendors. See other guides in this chapter to learn more (coming soon).