# Chaitin WAF 配置选项

chaitin-waf 插件将请求发送到 SafeLine 进行 Web 威胁检测，支持监控和阻断模式、响应上报及诊断响应头。<!-- --> <!-- -->配置涵盖插件参数和插件元数据。

## 参数[​](#参数 "参数的直接链接")

请参阅插件[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)，了解所有插件通用的配置选项。

* mode

  string

  默认值：`monitor`

  有效值：

  `off`、`monitor` 或 `block`

  ***

  确定插件对匹配请求的行为模式。

  在 `off` 模式下，跳过 WAF 检查。在 `monitor` 模式下，记录潜在威胁的请求但不阻止。在 `block` 模式下，具有威胁的请求将按照 WAF 服务的决定被阻止。

* match

  array\[object]

  ***

  匹配规则数组。插件使用这些规则来决定是否对请求执行 WAF 检查。如果列表为空，则处理所有请求。

  * vars

    array\[array]

    ***

    一个或多个匹配条件数组，格式为 [APISIX 表达式](https://docs.apiseven.com/apisix/reference/apisix-expressions.md)，用于有条件地执行插件。

* append\_waf\_resp\_header

  boolean

  默认值：`true`

  ***

  如果为 true，则添加响应头 `X-APISIX-CHAITIN-WAF`、`X-APISIX-CHAITIN-WAF-TIME`、`X-APISIX-CHAITIN-WAF-ACTION` 和 `X-APISIX-CHAITIN-WAF-STATUS`。

* append\_waf\_debug\_header

  boolean

  默认值：`false`

  ***

  如果为 true，则在响应中添加调试头 `X-APISIX-CHAITIN-WAF-ERROR` 和 `X-APISIX-CHAITIN-WAF-SERVER`。仅当 `append_waf_resp_header` 为 `true` 时有效。

* allow\_degradation

  boolean

  默认值：`` 插件元数据中的值；元数据未设置时为 `false` ``

  ***

  如果为 `true`，当插件元数据缺失、没有健康的 WAF 节点或 WAF 请求失败时，允许请求继续执行。路由或服务上的配置会覆盖插件元数据，包括显式设置的 `false`。

  该字段从 APISIX 3.20.0 开始可用，API7 企业版 3.9.23 和 3.10.10 不提供此字段。

* config

  object

  ***

  Chaitin WAF 服务配置。指定时，这些设置会覆盖相应的元数据默认值。

  * connect\_timeout

    integer

    默认值：`1000`

    ***

    到 WAF 服务的连接超时时间，单位为毫秒。

  * send\_timeout

    integer

    默认值：`1000`

    ***

    向 WAF 服务发送数据的超时时间，单位为毫秒。

  * read\_timeout

    integer

    默认值：`1000`

    ***

    从 WAF 服务接收数据的读取超时时间，单位为毫秒。

  * req\_body\_size

    integer

    默认值：`1024`

    ***

    允许的最大请求体大小，单位为 KB。

  * keepalive\_size

    integer

    默认值：`256`

    ***

    可以并发维护的到 WAF 检测服务的最大空闲连接数。

  * keepalive\_timeout

    integer

    默认值：`60000`

    ***

    WAF 服务的空闲连接超时时间，单位为毫秒。

  * real\_client\_ip

    boolean

    默认值：`true`

    ***

    如果为 true，则使用网关已解析的客户端 IP，其中包括受信任代理和 Real IP 配置的影响。如果为 false，则使用连接的直接对端地址。插件不会直接读取客户端提供的转发请求头。

  * log\_resp

    boolean

    ***

    如果为 true，在响应已经返回给客户端之后，除请求外还把响应一并上报给 WAF 检测服务。该上报仅供参考，不会阻断也不会修改响应。引入于 API7 企业版 3.9.20、3.10.7 和 APISIX 3.19.0。

  * resp\_body\_size

    integer

    ***

    上报的响应体最大大小，单位为 KiB。设置为 `0` 表示只上报响应状态和响应头。仅当 `log_resp` 为 true 时生效。引入于 API7 企业版 3.9.20、3.10.7 和 APISIX 3.19.0。

  * extra\_ignored\_content\_types

    string

    ***

    以逗号分隔的额外响应 content type 列表，在内置忽略列表之外。命中的响应完全不会上报给 WAF 检测服务，响应头也不会上报。仅当 `log_resp` 为 true 时生效。引入于 API7 企业版 3.9.20、3.10.7 和 APISIX 3.19.0。

## 插件元数据[​](#插件元数据 "插件元数据的直接链接")

* nodes

  array\[object]

  必填

  ***

  Chaitin WAF 服务的地址数组。

  * host

    string

    必填

    ***

    Chaitin WAF 服务地址。支持 IPv4、IPv6、Unix Socket 等。

  * port

    integer

    默认值：`80`

    ***

    Chaitin WAF 服务端口。

* mode

  string

  默认值：`monitor`

  ***

  确定插件对匹配请求的行为模式。

  在 `off` 模式下，跳过 WAF 检查。在 `monitor` 模式下，记录潜在威胁的请求但不阻止。在 `block` 模式下，具有威胁的请求将按照 WAF 服务的决定被阻止。

* allow\_degradation

  boolean

  默认值：`false`

  ***

  省略 `allow_degradation` 的插件实例所使用的默认降级行为。如果为 `true`，当插件无法获得 WAF 判定结果时，请求会继续执行。路由或服务可以覆盖此值。

  该字段从 APISIX 3.20.0 开始可用，API7 企业版 3.9.23 和 3.10.10 不提供此字段。

* config

  object

  ***

  Chaitin WAF 服务配置。

  * connect\_timeout

    integer

    默认值：`1000`

    ***

    到 WAF 服务的连接超时时间，单位为毫秒。

  * send\_timeout

    integer

    默认值：`1000`

    ***

    向 WAF 服务发送数据的超时时间，单位为毫秒。

  * read\_timeout

    integer

    默认值：`1000`

    ***

    从 WAF 服务接收数据的读取超时时间，单位为毫秒。

  * req\_body\_size

    integer

    默认值：`1024`

    ***

    允许的最大请求体大小，单位为 KB。

  * keepalive\_size

    integer

    默认值：`256`

    ***

    可以并发维护的到 WAF 检测服务的最大空闲连接数。

  * keepalive\_timeout

    integer

    默认值：`60000`

    ***

    WAF 服务的空闲连接超时时间，单位为毫秒。

  * real\_client\_ip

    boolean

    默认值：`true`

    ***

    如果为 true，则使用网关已解析的客户端 IP，其中包括受信任代理和 Real IP 配置的影响。如果为 false，则使用连接的直接对端地址。插件不会直接读取客户端提供的转发请求头。

  * log\_resp

    boolean

    默认值：`false`

    ***

    如果为 true，在响应已经返回给客户端之后，除请求外还把响应一并上报给 WAF 检测服务。该上报仅供参考，不会阻断也不会修改响应。引入于 API7 企业版 3.9.20、3.10.7 和 APISIX 3.19.0。

  * resp\_body\_size

    integer

    默认值：`4`

    ***

    上报的响应体最大大小，单位为 KiB。设置为 `0` 表示只上报响应状态和响应头。仅当 `log_resp` 为 true 时生效。引入于 API7 企业版 3.9.20、3.10.7 和 APISIX 3.19.0。

  * extra\_ignored\_content\_types

    string

    ***

    以逗号分隔的额外响应 content type 列表，在内置忽略列表之外。命中的响应完全不会上报给 WAF 检测服务，响应头也不会上报。仅当 `log_resp` 为 true 时生效。引入于 API7 企业版 3.9.20、3.10.7 和 APISIX 3.19.0。
