chaitin-waf
Sends requests to a Chaitin WAF for inspection.
chaitin-wafPriority 2700What it does
chaitin-waf asks a Chaitin web application firewall about each request on the route before it goes on to the backend. The firewall's nodes are named once for the environment, under Nodes in the plugin metadata. The route sets its Mode and, under Match, the requests the firewall is asked about.
In block mode a request the firewall flags is refused, in monitor mode it is only recorded, and off skips the check. Every route that carries the plugin depends on the nodes in the plugin metadata, whatever its mode.
When to use it
- An orders API open to the internet, where requests that carry attacks should stop at the gateway instead of reaching the backend.
- A firewall rollout in steps: every route starts in
monitormode, and a route moves toblockonce its verdicts have been watched for a while. - Only the writes of an API, POST, PUT, PATCH and DELETE, sent to the firewall under Match by a condition on
request_method. - A security team that already runs the firewall's nodes, named once in the plugin metadata for every API behind the gateway.
Not for refusing clients by their address — see ip-restriction (Allows or denies clients by IP address or CIDR range), refusing requests to paths you list yourself — see uri-blocker (Blocks requests whose URI matches a rule) or checking requests against the API's own OpenAPI description — see oas-validator (Validates requests against an OpenAPI document; responses are not checked).
Set it up
Block requests the firewall flags on POST, PUT, PATCH and DELETE
Needs the firewall nodes named in the plugin's environment-wide settings.
Set Mode to block, fill Match as in the JSON below and turn off Add firewall response headers.
{
"mode": "block",
"match": [
{
"vars": [
[
"request_method",
"in",
[
"POST",
"PUT",
"PATCH",
"DELETE"
]
]
]
}
],
"append_waf_resp_header": false
}
More scenarios
Name the firewall nodes every route that carries the plugin sends its requests throughenvironment-wide settings
Fill Nodes as in the JSON below and set Mode to monitor.
{
"nodes": [
{
"host": "10.0.3.10",
"port": 8000
},
{
"host": "10.0.3.11",
"port": 8000
}
],
"mode": "monitor"
}
Things to know
- Mode — Until the plugin's environment-wide settings list the firewall's nodes, every request through the route answers 500, even in off mode.
- The Mode in the plugin metadata applies to every route whose chaitin-waf sets none of its own. With none there and none on the route, the firewall is asked in
monitormode. - Plugin metadata that lists no node is refused when you save.
- Mode — A mode other than
block,monitorandoff,reportfor example, is refused when you save. - Match — A row of Match that carries no condition is refused when you save.
- Vars — An operator the gateway does not know,
starts_withfor example, is refused when you save. - AdviceStart each route in
monitormode and read what the firewall flags before you switch it toblock.
Settings
The fields as the console shows them, section by section.
modestringBlock refuses what the firewall flags, monitor only records it, off skips the check. This overrides the mode in the environment-wide settings.
matcharray of objectsmatch[].varsarrayRequiredconfigobjectOverrides the environment-wide settings field by field; a value left blank keeps the environment-wide one.
config.log_respbooleanAlso reports each response to the detector after the client has received it; the response size and the ignored content types below are read only then.
config.resp_body_sizeintegerKilobytes of the response body reported to the detector while responses are logged; zero reports the headers alone.
config.extra_ignored_content_typesstringA comma-separated list of response content types, beside the built-in ones, whose responses are not reported at all while responses are logged.
config.connect_timeoutintegerconfig.keepalive_sizeintegerconfig.keepalive_timeoutintegerconfig.read_timeoutintegerconfig.real_client_ipbooleanNot set, it follows the environment-wide setting, which is on unless changed there.
config.req_body_sizeintegerKilobytes: a longer body is cut to this many before the detector reads it.
config.send_timeoutintegerappend_waf_resp_headerbooleandefault trueOff, the answer carries none of the firewall headers, the error one included.
append_waf_debug_headerbooleandefault falseEnvironment-wide settings
Set once per environment, under Plugins › chaitin-waf. Every chaitin-waf in the environment uses these.
nodesarray of objectsRequirednodes[].hoststringRequiredpattern
^\*?[0-9a-zA-Z-._\[\]:/]+$nodes[].portintegerdefault 80configobjectdefault {}config.log_respbooleandefault falseAlso reports each response to the detector after the client has received it; the response size and the ignored content types below are read only then.
config.resp_body_sizeintegerdefault 4Kilobytes of the response body reported to the detector while responses are logged; zero reports the headers alone.
config.extra_ignored_content_typesstringA comma-separated list of response content types, beside the built-in ones, whose responses are not reported at all while responses are logged.
config.connect_timeoutintegerdefault 1000config.keepalive_sizeintegerdefault 256config.keepalive_timeoutintegerdefault 60000config.read_timeoutintegerdefault 1000config.real_client_ipbooleandefault trueconfig.req_body_sizeintegerdefault 1024Kilobytes: a longer body is cut to this many before the detector reads it.
config.send_timeoutintegerdefault 1000modestringThe mode every route that writes no mode of its own runs in; with none here and none on the route the firewall is asked in monitor mode.