chaitin-waf
chaitin-waf 插件与长亭 WAF (SafeLine) 服务集成，提供先进的 Web 威胁检测和预防功能，增强应用程序安全性并保护敏感用户数据。
响应头
根据 append_waf_resp_header 和 append_waf_debug_header 的配置，插件可以添加以下响应头：
| 响应头 | 描述 |
|---|---|
X-APISIX-CHAITIN-WAF | 指示 APISIX 是否将请求转发给 WAF 服务器。 • yes: 请求已转发给 WAF 服务器。• no: 请求未转发给 WAF 服务器。• unhealthy: 请求匹配配置的规则，但没有可用的 WAF 服务。• err: 插件执行期间发生错误。X-APISIX-CHAITIN-WAF-ERROR 头也包含详细信息。• waf-err: 与 WAF 服务器交互时出错。X-APISIX-CHAITIN-WAF-ERROR 头也包含详细信息。• timeout: 对 WAF 服务器的请求超时。 |
X-APISIX-CHAITIN-WAF-TIME | 请求到 Chaitin WAF 服务器的往返时间 (RTT)（毫秒），包括网络延迟和 WAF 服务器处理时间。 |
X-APISIX-CHAITIN-WAF-STATUS | WAF 服务器返回给 APISIX 的状态码。 |
X-APISIX-CHAITIN-WAF-ACTION | WAF 服务器返回给 APISIX 的动作。 • pass: 请求被 WAF 服务允许。• reject: 请求被 WAF 服务阻止。 |
X-APISIX-CHAITIN-WAF-ERROR | 调试头。包含 WAF 错误消息。 |
X-APISIX-CHAITIN-WAF-SERVER | 调试头。指示选择了哪个 WAF 服务器。 |
示例
以下示例展示了如何在不同场景下配置 chaitin-waf 插件。
在继续之前，请确保你已安装 Chaitin WAF (SafeLine)。
在路由上阻止恶意请求
以下示例演示了如何与 Chaitin WAF 集成以保护路由上的流量，立即拒绝恶意请求。
使用插件元数据配置 Chaitin WAF 连接详细信息（相应地更新地址）：
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/chaitin-waf" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"nodes": [
{
"host": "172.22.222.5",
"port": 8000
}
]
}'
创建一个路由并在路由上启用 chaitin-waf 以阻止被识别为恶意的请求：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "chaitin-waf-route",
"uri": "/anything",
"plugins": {
"chaitin-waf": {
"mode": "block",
"append_waf_resp_header": true,
"append_waf_debug_header": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ 将 mode 设置为 block 以阻止被识别为恶意的请求。
❷ 将 append_waf_resp_header 设置为 true 以包含与 WAF 相关的标准响应头。
❸ 将 append_waf_debug_header 设置为 true 以包含与 WAF 相关的调试响应头。
向路由发送标准请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应。
向路由发送带有 SQL 注入的请求：
curl -i "http://127.0.0.1:9080/anything" -d 'a=1 and 1=1'
你应该看到类似以下的 HTTP/1.1 403 Forbidden 响应：
...
X-APISIX-CHAITIN-WAF-STATUS: 403
X-APISIX-CHAITIN-WAF-ACTION: reject
X-APISIX-CHAITIN-WAF-SERVER: 172.22.222.5
X-APISIX-CHAITIN-WAF: yes
X-APISIX-CHAITIN-WAF-TIME: 3
...
{"code": 403, "success":false, "message": "blocked by Chaitin SafeLine Web Application Firewall", "event_id": "276be6457d8447a4bf1f792501dfba6c"}
监控恶意意图请求
此示例展示了如何与 Chaitin WAF 集成以监控所有带有 chaitin-waf 的路由而不拒绝，并在特定路由上拒绝潜在的恶意请求。
使用插件元数据配置 Chaitin WAF 连接详细信息（相应地更新地址）并配置模式：
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/chaitin-waf" -X PUT \
-H 'X-API-KEY: ${ADMIN_API_KEY}' \
-d '{
"nodes": [
{
"host": "172.22.222.5",
"port": 8000
}
],
"mode": "monitor"
}'
❶ 在插件元数据中将 mode 设置为 monitor。如果未在路由上指定 mode，这将适用于所有 chaitin-waf 插件实例。
创建一个路由并在路由上启用 chaitin-waf 而不做任何配置：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "chaitin-waf-route",
"uri": "/anything",
"plugins": {
"chaitin-waf": {}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
向路由发送标准请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应。
向路由发送带有 SQL 注入的请求：
curl -i "http://127.0.0.1:9080/anything" -d 'a=1 and 1=1'
你应该同样收到 HTTP/1.1 200 OK 响应，因为请求在 monitor 模式下未被阻止，但在日志条目中观察到以下内容：
2025/09/09 11:44:08 [warn] 115#115: *31683 [lua] chaitin-waf.lua:385: do_access(): chaitin-waf monitor mode: request would have been rejected, event_id: 49bed20603e242f9be5ba6f1744bba4b, client: 172.20.0.1, server: _, request: "POST /anything HTTP/1.1", host: "127.0.0.1:9080"
如果你在路由上显式配置 mode，它将优先于插件元数据中的配置。例如，如果你创建一个如下路由：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "chaitin-waf-route",
"uri": "/anything",
"plugins": {
"chaitin-waf": {
"mode": "block"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
向路由发送标准请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应。
向路由发送带有 SQL 注入的请求：
curl -i "http://127.0.0.1:9080/anything" -d 'a=1 and 1=1'
你应该看到类似以下的 HTTP/1.1 403 Forbidden 响应：
...
X-APISIX-CHAITIN-WAF-STATUS: 403
X-APISIX-CHAITIN-WAF-ACTION: reject
X-APISIX-CHAITIN-WAF: yes
X-APISIX-CHAITIN-WAF-TIME: 3
...
{"code": 403, "success":false, "message": "blocked by Chaitin SafeLine Web Application Firewall", "event_id": "c3eb25eaa7ae4c0d82eb8ceebf3600d0"}