# Chaitin WAF Configuration

The `chaitin-waf` plugin sends requests to SafeLine for web threat detection, with monitoring and blocking modes, response reporting, and diagnostic headers.<!-- --> <!-- -->Configuration covers plugin parameters and plugin metadata.

## Parameters[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) for configuration options available to all plugins.

* mode

  string

  default: `monitor`

  valid value:

  `off`, `monitor`, or `block`

  ***

  Mode to determine how the plugin behaves for matched requests.

  In `off` mode, WAF checks are skipped. In `monitor` mode, requests with potential threats are logged but not blocked. In `block` mode, requests with threats are blocked as determined by the WAF service.

* match

  array\[object]

  ***

  An array of matching rules. The plugin uses these rules to decide whether to perform a WAF check on a request. If the list is empty, all requests are processed.

  * vars

    array\[array]

    ***

    An array of one or more matching conditions in the form of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions.md) to conditionally execute the plugin.

* append\_waf\_resp\_header

  boolean

  default: `true`

  ***

  If true, add response headers `X-APISIX-CHAITIN-WAF`, `X-APISIX-CHAITIN-WAF-TIME`, `X-APISIX-CHAITIN-WAF-ACTION`, and `X-APISIX-CHAITIN-WAF-STATUS`.

* append\_waf\_debug\_header

  boolean

  default: `false`

  ***

  If true, add debugging headers `X-APISIX-CHAITIN-WAF-ERROR` and `X-APISIX-CHAITIN-WAF-SERVER` to the response. Effective only when `append_waf_resp_header` is `true`.

* allow\_degradation

  boolean

  default: ``value from plugin metadata, or `false` when metadata omits it``

  ***

  If true, allow the request to continue when plugin metadata is missing, no healthy WAF node is available, or the WAF request fails. A value configured on the route or service overrides plugin metadata, including an explicit `false`.

  Available in APISIX 3.20.0. API7 Enterprise 3.9.23 and 3.10.10 do not expose this field.

* config

  object

  ***

  Chaitin WAF service configurations. These settings override the corresponding metadata defaults when specified.

  * connect\_timeout

    integer

    default: `1000`

    ***

    The connection timeout to the WAF service, in milliseconds.

  * send\_timeout

    integer

    default: `1000`

    ***

    The sending timeout for transmitting data to the WAF service, in milliseconds.

  * read\_timeout

    integer

    default: `1000`

    ***

    The reading timeout for receiving data from the WAF service, in milliseconds.

  * req\_body\_size

    integer

    default: `1024`

    ***

    The maximum allowed request body size, in KB.

  * keepalive\_size

    integer

    default: `256`

    ***

    The maximum number of idle connections to the WAF detection service that can be maintained concurrently.

  * keepalive\_timeout

    integer

    default: `60000`

    ***

    The idle connection timeout for the WAF service, in milliseconds.

  * real\_client\_ip

    boolean

    default: `true`

    ***

    If true, use the client IP already resolved by the gateway, including any trusted-proxy or real-IP configuration. If false, use the direct peer address from the connection. The plugin does not read client-supplied forwarded headers directly.

  * log\_resp

    boolean

    ***

    If true, report the response to the WAF detection service after it has been delivered to the client, in addition to the request. The report is advisory and never blocks or modifies the response. Introduced in API7 Enterprise 3.9.20 and 3.10.7, and in APISIX 3.19.0.

  * resp\_body\_size

    integer

    ***

    The maximum amount of the response body to report, in KiB. Set to `0` to report only the response status and headers. Effective only when `log_resp` is true. Introduced in API7 Enterprise 3.9.20 and 3.10.7, and in APISIX 3.19.0.

  * extra\_ignored\_content\_types

    string

    ***

    A comma-separated list of additional response content types to skip, on top of the built-in ignored list. A response whose content type matches is not reported to the WAF detection service at all, headers included. Effective only when `log_resp` is true. Introduced in API7 Enterprise 3.9.20 and 3.10.7, and in APISIX 3.19.0.

## Plugin Metadata[​](#plugin-metadata "Direct link to Plugin Metadata")

* nodes

  array\[object]

  required

  ***

  An array of addresses for the Chaitin WAF service.

  * host

    string

    required

    ***

    Address of Chaitin WAF service. Supports IPv4, IPv6, Unix Socket, etc.

  * port

    integer

    default: `80`

    ***

    Port of Chaitin WAF service.

* mode

  string

  default: `monitor`

  ***

  Mode to determine how the plugin behaves for matched requests.

  In `off` mode, WAF checks are skipped. In `monitor` mode, requests with potential threats are logged but not blocked. In `block` mode, requests with threats are blocked as determined by the WAF service.

* allow\_degradation

  boolean

  default: `false`

  ***

  Default degradation behavior for plugin instances that omit `allow_degradation`. If true, requests continue when the plugin cannot obtain a WAF verdict. A route or service can override this value.

  Available in APISIX 3.20.0. API7 Enterprise 3.9.23 and 3.10.10 do not expose this field.

* config

  object

  ***

  Chaitin WAF service configurations.

  * connect\_timeout

    integer

    default: `1000`

    ***

    The connection timeout to the WAF service, in milliseconds.

  * send\_timeout

    integer

    default: `1000`

    ***

    The sending timeout for transmitting data to the WAF service, in milliseconds.

  * read\_timeout

    integer

    default: `1000`

    ***

    The reading timeout for receiving data from the WAF service, in milliseconds.

  * req\_body\_size

    integer

    default: `1024`

    ***

    The maximum allowed request body size, in KB.

  * keepalive\_size

    integer

    default: `256`

    ***

    The maximum number of idle connections to the WAF detection service that can be maintained concurrently.

  * keepalive\_timeout

    integer

    default: `60000`

    ***

    The idle connection timeout for the WAF service, in milliseconds.

  * real\_client\_ip

    boolean

    default: `true`

    ***

    If true, use the client IP already resolved by the gateway, including any trusted-proxy or real-IP configuration. If false, use the direct peer address from the connection. The plugin does not read client-supplied forwarded headers directly.

  * log\_resp

    boolean

    default: `false`

    ***

    If true, report the response to the WAF detection service after it has been delivered to the client, in addition to the request. The report is advisory and never blocks or modifies the response. Introduced in API7 Enterprise 3.9.20 and 3.10.7, and in APISIX 3.19.0.

  * resp\_body\_size

    integer

    default: `4`

    ***

    The maximum amount of the response body to report, in KiB. Set to `0` to report only the response status and headers. Effective only when `log_resp` is true. Introduced in API7 Enterprise 3.9.20 and 3.10.7, and in APISIX 3.19.0.

  * extra\_ignored\_content\_types

    string

    ***

    A comma-separated list of additional response content types to skip, on top of the built-in ignored list. A response whose content type matches is not reported to the WAF detection service at all, headers included. Effective only when `log_resp` is true. Introduced in API7 Enterprise 3.9.20 and 3.10.7, and in APISIX 3.19.0.
