Baoyuantop commented on code in PR #12029:
URL: https://github.com/apache/apisix/pull/12029#discussion_r1989398017
##########
docs/en/latest/plugins/chaitin-waf.md:
##########
@@ -40,35 +40,35 @@ The response headers are listed below:
- **X-APISIX-CHAITIN-WAF**: Whether APISIX forwards the request to the WAF
server.
- yes: forwarded
- - no: no forwarded
+ - no: not forwarded
- unhealthy: matches the match variables, but no WAF server is available.
- - err: an error occurred during the execution of the plugin. Also with
**X-APISIX-CHAITIN-WAF-ERROR** request header
- - waf-err: Error while interacting with the WAF server. Also with
**X-APISIX-CHAITIN-WAF-ERROR** request header
- - timeout: Timeout for request to the WAF server
-- **X-APISIX-CHAITIN-WAF-ERROR**: Debug header. WAF error message
+ - err: an error occurred during the execution of the plugin. Also includes
the **X-APISIX-CHAITIN-WAF-ERROR** header.
+ - waf-err: error while interacting with the WAF server. Also includes the
**X-APISIX-CHAITIN-WAF-ERROR** header.
+ - timeout: request to the WAF server timed out.
+- **X-APISIX-CHAITIN-WAF-ERROR**: Debug header. Contains WAF error message.
- **X-APISIX-CHAITIN-WAF-TIME**: The time in milliseconds that APISIX spent
interacting with WAF.
- **X-APISIX-CHAITIN-WAF-STATUS**: The status code returned to APISIX by the
WAF server.
-- **X-APISIX-CHAITIN-WAF-ACTION**: Processing result returned to APISIX by the
WAF server.
- - pass: request valid and passed
- - reject: request rejected by WAF service
-- **X-APISIX-CHAITIN-WAF-SERVER**: Debug header. Picked WAF server.
+- **X-APISIX-CHAITIN-WAF-ACTION**: The action returned to APISIX by the WAF
server.
+ - pass: request valid and passed.
+ - reject: request rejected by WAF service.
+- **X-APISIX-CHAITIN-WAF-SERVER**: Debug header. Indicates which WAF server
was selected.
## Plugin Metadata
| Name | Type | Required | Default value |
Description
|
|--------------------------|---------------|----------|---------------|------------------------------------------------------------------------------------------------------------------------------|
| nodes | array(object) | true | | A list
of addresses for the Chaitin SafeLine WAF service.
|
-| nodes[0].host | string | true | | The
address of Chaitin SafeLine WAF service. Supports IPV4, IPV6, Unix Socket, etc.
|
-| nodes[0].port | string | false | 80 | The
port of Chaitin SafeLine WAF service.
|
-| config | object | false | |
Configuration of the Chaitin SafeLine WAF service. The parameters configured
here will be used when route is not configured. |
-| config.connect_timeout | integer | false | 1000 |
connect timeout, in milliseconds
|
-| config.send_timeout | integer | false | 1000 | send
timeout, in milliseconds
|
-| config.read_timeout | integer | false | 1000 | read
timeout, in milliseconds
|
-| config.req_body_size | integer | false | 1024 |
request body size, in KB
|
-| config.keepalive_size | integer | false | 256 |
maximum concurrent idle connections to the SafeLine WAF detection service
|
-| config.keepalive_timeout | integer | false | 60000 | idle
connection timeout, in milliseconds
|
-
-An example configuration is as follows.
+| nodes[0].host | string | true | | The
address of Chaitin SafeLine WAF service. Supports IPv4, IPv6, Unix Socket, etc.
|
+| nodes[0].port | integer | false | 80 | The
port of the Chaitin SafeLine WAF service.
|
+| mode | string | false | (fallback) | The
global default mode if a Route doesn't specify its own: `off`, `monitor`, or
`block`. Defaults to `block` if not set. |
+| config | object | false | | WAF
configuration defaults if none are specified on the Route.
|
+| config.connect_timeout | integer | false | 1000 |
Connect timeout, in milliseconds.
|
+| config.send_timeout | integer | false | 1000 | Send
timeout, in milliseconds.
|
+| config.read_timeout | integer | false | 1000 | Read
timeout, in milliseconds.
|
+| config.req_body_size | integer | false | 1024 |
Request body size, in KB.
|
+| config.keepalive_size | integer | false | 256 |
Maximum concurrent idle connections to the SafeLine WAF detection service.
|
+| config.keepalive_timeout | integer | false | 60000 | Idle
connection timeout, in milliseconds.
|
+| config.real_client_ip | boolean | false | true |
Whether to use the `X-Forwarded-For` as the client IP (if present). If `false`,
uses the direct client IP from the connection. |
Review Comment:
```suggestion
| config.real_client_ip | boolean | false | true |
Specifies whether to use the `X-Forwarded-For` as the client IP (if present).
If `false`, uses the direct client IP from the connection. |
```
##########
docs/en/latest/plugins/chaitin-waf.md:
##########
@@ -40,35 +40,35 @@ The response headers are listed below:
- **X-APISIX-CHAITIN-WAF**: Whether APISIX forwards the request to the WAF
server.
- yes: forwarded
- - no: no forwarded
+ - no: not forwarded
- unhealthy: matches the match variables, but no WAF server is available.
- - err: an error occurred during the execution of the plugin. Also with
**X-APISIX-CHAITIN-WAF-ERROR** request header
- - waf-err: Error while interacting with the WAF server. Also with
**X-APISIX-CHAITIN-WAF-ERROR** request header
- - timeout: Timeout for request to the WAF server
-- **X-APISIX-CHAITIN-WAF-ERROR**: Debug header. WAF error message
+ - err: an error occurred during the execution of the plugin. Also includes
the **X-APISIX-CHAITIN-WAF-ERROR** header.
+ - waf-err: error while interacting with the WAF server. Also includes the
**X-APISIX-CHAITIN-WAF-ERROR** header.
+ - timeout: request to the WAF server timed out.
+- **X-APISIX-CHAITIN-WAF-ERROR**: Debug header. Contains WAF error message.
- **X-APISIX-CHAITIN-WAF-TIME**: The time in milliseconds that APISIX spent
interacting with WAF.
- **X-APISIX-CHAITIN-WAF-STATUS**: The status code returned to APISIX by the
WAF server.
-- **X-APISIX-CHAITIN-WAF-ACTION**: Processing result returned to APISIX by the
WAF server.
- - pass: request valid and passed
- - reject: request rejected by WAF service
-- **X-APISIX-CHAITIN-WAF-SERVER**: Debug header. Picked WAF server.
+- **X-APISIX-CHAITIN-WAF-ACTION**: The action returned to APISIX by the WAF
server.
+ - pass: request valid and passed.
+ - reject: request rejected by WAF service.
+- **X-APISIX-CHAITIN-WAF-SERVER**: Debug header. Indicates which WAF server
was selected.
## Plugin Metadata
| Name | Type | Required | Default value |
Description
|
|--------------------------|---------------|----------|---------------|------------------------------------------------------------------------------------------------------------------------------|
| nodes | array(object) | true | | A list
of addresses for the Chaitin SafeLine WAF service.
|
-| nodes[0].host | string | true | | The
address of Chaitin SafeLine WAF service. Supports IPV4, IPV6, Unix Socket, etc.
|
-| nodes[0].port | string | false | 80 | The
port of Chaitin SafeLine WAF service.
|
-| config | object | false | |
Configuration of the Chaitin SafeLine WAF service. The parameters configured
here will be used when route is not configured. |
-| config.connect_timeout | integer | false | 1000 |
connect timeout, in milliseconds
|
-| config.send_timeout | integer | false | 1000 | send
timeout, in milliseconds
|
-| config.read_timeout | integer | false | 1000 | read
timeout, in milliseconds
|
-| config.req_body_size | integer | false | 1024 |
request body size, in KB
|
-| config.keepalive_size | integer | false | 256 |
maximum concurrent idle connections to the SafeLine WAF detection service
|
-| config.keepalive_timeout | integer | false | 60000 | idle
connection timeout, in milliseconds
|
-
-An example configuration is as follows.
+| nodes[0].host | string | true | | The
address of Chaitin SafeLine WAF service. Supports IPv4, IPv6, Unix Socket, etc.
|
+| nodes[0].port | integer | false | 80 | The
port of the Chaitin SafeLine WAF service.
|
+| mode | string | false | (fallback) | The
global default mode if a Route doesn't specify its own: `off`, `monitor`, or
`block`. Defaults to `block` if not set. |
Review Comment:
```suggestion
| mode | string | false | block | The
global default mode if a Route doesn't specify its own: `off`, `monitor`, or
`block`. |
```
##########
docs/en/latest/plugins/chaitin-waf.md:
##########
@@ -82,46 +82,66 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
```bash
curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/chaitin-waf -H
"X-API-KEY: $admin_key" -X PUT -d '
{
- "nodes":[
- {
- "host": "unix:/path/to/safeline/resources/detector/snserver.sock",
- "port": 8000
- }
- ]
+ "nodes": [
+ {
+ "host": "unix:/path/to/safeline/resources/detector/snserver.sock",
+ "port": 8000
+ }
+ ],
+ "mode": "block",
+ "config": {
+ "real_client_ip": true
+ }
}'
+
```
## Attributes
| Name | Type | Required | Default value |
Description
|
|--------------------------|---------------|----------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| match | array[object] | false | | The
list of matching rules, default is empty
|
-| match.vars | array[array] | false | | List
of variables to match for filtering requests for conditional traffic split. It
is in the format `{variable operator value}`. For example, `{"arg_name", "==",
"json"}`. The variables here are consistent with NGINX internal variables. For
details on supported operators,
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list). |
-| append_waf_resp_header | bool | false | true |
Whether to add response headers
|
-| append_waf_debug_header | bool | false | false |
Whether or not to add debugging headers, effective when `add_header` is `true`.
|
-| config | object | false | |
Configuration of the Chaitin SafeLine WAF service. When the route is not
configured, the parameters configured in the metadata are used.
|
-| config.connect_timeout | integer | false | |
connect timeout, in milliseconds
|
-| config.send_timeout | integer | false | | send
timeout, in milliseconds
|
-| config.read_timeout | integer | false | | read
timeout, in milliseconds
|
-| config.req_body_size | integer | false | |
request body size, in KB
|
-| config.keepalive_size | integer | false | |
maximum concurrent idle connections to the SafeLine WAF detection service
|
-| config.keepalive_timeout | integer | false | | idle
connection timeout, in milliseconds
|
-
-A sample configuration is shown below, using `httpbun.org` as the example
backend, which can be replaced as needed:
+| mode | string | false | block |
Determines how the plugin behaves for matched requests. Valid values are `off`,
`monitor`, or `block`. When set to `off`, the plugin skips WAF checks. In
`monitor` mode, the plugin logs potential blocks without actually blocking the
request. In `block` mode, the plugin enforces blocks as determined by the WAF
service. |
+| match | array[object] | false | | A list
of matching rules. The plugin evaluates these rules to decide whether to
perform the WAF check on a request. If empty, all requests are processed.
|
+| match.vars | array[array] | false | | List
of variables used for matching requests. Each rule is specified as `[variable,
operator, value]` (for example, `["http_waf", "==", "true"]`). These variables
refer to NGINX internal variables. For supported operators, see
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list).
|
+| append_waf_resp_header | bool | false | true |
Determines whether the plugin adds WAF-related response headers (such as
`X-APISIX-CHAITIN-WAF`, `X-APISIX-CHAITIN-WAF-ACTION`, etc.) to the response.
|
+| append_waf_debug_header | bool | false | false |
Determines whether debugging headers (such as `X-APISIX-CHAITIN-WAF-ERROR` and
`X-APISIX-CHAITIN-WAF-SERVER`) are added. Effective only when
`append_waf_resp_header` is enabled.
|
+| config | object | false | |
Provides route-specific configuration for the Chaitin SafeLine WAF service.
Settings here override the corresponding metadata defaults when specified.
|
+| config.connect_timeout | integer | false | 1000 | The
connect timeout for the WAF server, in milliseconds.
|
+| config.send_timeout | integer | false | 1000 | The
send timeout for transmitting data to the WAF server, in milliseconds.
|
+| config.read_timeout | integer | false | 1000 | The
read timeout for receiving data from the WAF server, in milliseconds.
|
+| config.req_body_size | integer | false | 1024 | The
maximum allowed request body size, in KB.
|
+| config.keepalive_size | integer | false | 256 | The
maximum number of idle connections to the WAF detection service that can be
maintained concurrently.
|
+| config.keepalive_timeout | integer | false | 60000 | The
idle connection timeout for the WAF service, in milliseconds.
|
+| config.real_client_ip | boolean | false | true |
Specifies whether to determine the client IP from the `X-Forwarded-For` header.
If set to `false`, the plugin uses the direct client IP from the connection.
|
+
+Below is a sample Route configuration that uses:
+
+- httpbun.org as the upstream backend.
+- mode set to monitor, so the plugin only logs potential blocks.
+- A matching rule that triggers the plugin when the custom header waf: true is
set.
+- An override to disable the “real client IP” logic by setting
config.real_client_ip to false.
Review Comment:
```suggestion
- An override to disable the `real client IP` logic by setting
config.real_client_ip to false.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
