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 集成以保护路由上的流量，立即拒绝恶意请求。

Admin API
ADC
Ingress Controller

使用插件元数据配置 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 相关的调试响应头。

adc.yaml
plugin_metadata:
  chaitin-waf:
    nodes:
      - host: "172.22.222.5"
        port: 8000
services:
  - name: chaitin-waf-service
    routes:
      - name: chaitin-waf-route
        uris:
          - /anything
        plugins:
          chaitin-waf:
            mode: block
            append_waf_resp_header: true
            append_waf_debug_header: true
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

❶ nodes：Chaitin WAF 服务地址列表。请更新 host 和 port，使其与 Chaitin WAF（雷池）部署一致。

❷ 将 mode 设置为 block，阻止被识别为恶意的请求。

❸ 将 append_waf_resp_header 设置为 true，以包含 WAF 相关标准响应头。

❹ 将 append_waf_debug_header 设置为 true，以包含 WAF 相关调试响应头。

更新 GatewayProxy 清单以配置插件元数据。如果 Chaitin WAF 安装在集群外的主机上，请使用该主机的 IP 地址。在大多数部署中，请将 Chaitin WAF 公开为集群内可访问的 Service、IP 地址或 DNS 名称，也可以改用节点或 LoadBalancer 地址。

gatewayproxy.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # ...
      # 你的控制面连接配置
  pluginMetadata:
    chaitin-waf:
      nodes:
        - host: "172.22.222.5"
          port: 8000

❶ nodes：Chaitin WAF 服务地址列表。请更新 host 和 port，使其与 Chaitin WAF（雷池）部署一致。

Gateway API
APISIX CRD

创建启用了 chaitin-waf 的路由以阻止恶意请求：

chaitin-waf-ic.yaml
apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: chaitin-waf-plugin-config
spec:
  plugins:
    - name: chaitin-waf
      config:
        mode: block
        append_waf_resp_header: true
        append_waf_debug_header: true
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: chaitin-waf-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: chaitin-waf-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

将配置应用到集群：

kubectl apply -f gatewayproxy.yaml -f chaitin-waf-ic.yaml

创建启用了 chaitin-waf 的路由以阻止恶意请求：

chaitin-waf-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: chaitin-waf-route
spec:
  ingressClassName: apisix
  http:
    - name: chaitin-waf-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: chaitin-waf
        enable: true
        config:
          mode: block
          append_waf_resp_header: true
          append_waf_debug_header: true

将配置应用到集群：

kubectl apply -f gatewayproxy.yaml -f chaitin-waf-ic.yaml

❷ 将 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 的路由而不拒绝，并在特定路由上拒绝潜在的恶意请求。

Admin API
ADC
Ingress Controller

使用插件元数据配置 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
      }
    }
  }'

adc.yaml
plugin_metadata:
  chaitin-waf:
    nodes:
      - host: "172.22.222.5"
        port: 8000
    mode: monitor
services:
  - name: chaitin-waf-service
    routes:
      - name: chaitin-waf-route
        uris:
          - /anything
        plugins:
          chaitin-waf: {}
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

❶ nodes：Chaitin WAF 服务地址列表。请更新 host 和 port，使其与 Chaitin WAF（雷池）部署一致。

❷ 在插件元数据中将 mode 设置为 monitor。如果路由上未指定 mode，此配置将应用于所有 chaitin-waf 插件实例。

gatewayproxy.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # ...
      # 你的控制面连接配置
  pluginMetadata:
    chaitin-waf:
      nodes:
        - host: "172.22.222.5"
          port: 8000
      mode: monitor

❶ 在插件元数据中将 mode 设置为 monitor。如果未在路由上指定 mode，这将适用于所有 chaitin-waf 插件实例。

Gateway API
APISIX CRD

创建一个启用了 chaitin-waf、但未设置任何插件级配置的路由，使其继承插件元数据中的 monitor 模式：

chaitin-waf-ic.yaml
apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: chaitin-waf-plugin-config
spec:
  plugins:
    - name: chaitin-waf
      config: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: chaitin-waf-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: chaitin-waf-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

将配置应用到集群：

kubectl apply -f gatewayproxy.yaml -f chaitin-waf-ic.yaml

要覆盖 monitor 模式并在路由上阻止恶意请求，请更新 PluginConfig，将 mode 设置为 block：

chaitin-waf-ic.yaml
# 其他配置
# ---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: chaitin-waf-plugin-config
spec:
  plugins:
    - name: chaitin-waf
      config:
        mode: block

将更新后的配置应用到集群：

kubectl apply -f chaitin-waf-ic.yaml

创建一个启用了 chaitin-waf、但未设置任何插件级配置的路由，使其继承插件元数据中的 monitor 模式：

chaitin-waf-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: chaitin-waf-route
spec:
  ingressClassName: apisix
  http:
    - name: chaitin-waf-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: chaitin-waf
        enable: true
        config: {}

将配置应用到集群：

kubectl apply -f gatewayproxy.yaml -f chaitin-waf-ic.yaml

要覆盖 monitor 模式并在路由上阻止恶意请求，请更新 ApisixRoute，将 mode 设置为 block：

chaitin-waf-ic.yaml
# 其他配置
# ---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: chaitin-waf-route
spec:
  ingressClassName: apisix
  http:
    - name: chaitin-waf-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: chaitin-waf
        enable: true
        config:
          mode: block

将更新后的配置应用到集群：

kubectl apply -f chaitin-waf-ic.yaml

向路由发送标准请求：

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，它将优先于插件元数据中的配置。例如，如果你创建一个如下路由：

Admin API
ADC
Ingress Controller

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
      }
    }
  }'

adc.yaml
plugin_metadata:
  chaitin-waf:
    nodes:
      - host: "172.22.222.5"
        port: 8000
    mode: monitor
services:
  - name: chaitin-waf-service
    routes:
      - name: chaitin-waf-route
        uris:
          - /anything
        plugins:
          chaitin-waf:
            mode: block
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

Gateway API
APISIX CRD

更新 PluginConfig，将 mode 设置为 block：

chaitin-waf-ic.yaml
# 其他配置
# ---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: chaitin-waf-plugin-config
spec:
  plugins:
    - name: chaitin-waf
      config:
        mode: block

将更新后的配置应用到集群：

kubectl apply -f chaitin-waf-ic.yaml

更新 ApisixRoute，将 mode 设置为 block：

chaitin-waf-ic.yaml
# 其他配置
# ---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: chaitin-waf-route
spec:
  ingressClassName: apisix
  http:
    - name: chaitin-waf-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: chaitin-waf
        enable: true
        config:
          mode: block

将更新后的配置应用到集群：

kubectl apply -f chaitin-waf-ic.yaml

向路由发送标准请求：

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"}

响应头​

示例​

在路由上阻止恶意请求​

监控恶意意图请求​

响应头

示例

在路由上阻止恶意请求

监控恶意意图请求