Adding SafeLine WAF inspection to Apache APISIX with chaitin-waf
If your Apache APISIX gateway already routes API traffic, the next question is whether web attacks such as injection attempts and malicious payloads should be inspected at that same boundary before they reach your upstream services. The chaitin-waf plugin is APISIX's built-in way to do this. According to its documentation, the plugin sends matching requests to a Chaitin SafeLine WAF service, and the address of that service is defined in plugin metadata rather than in each route. The plugin runs in one of three modes: block (the default), where requests judged malicious are rejected, monitor, where inspection happens and results are recorded without blocking, and off. Teams usually need this when they cannot rely on each application team to validate every input, when they must show that web attack prevention sits at the boundary, or when they want one inspection policy across many routes.
The plugin is only the client side of the arrangement. The SafeLine WAF service is a separate component that your team must deploy, patch, size and monitor in infrastructure you control, and the gateway depends on it being reachable. Before you enable the plugin, confirm with the vendor and your own environment how the SafeLine service is deployed, which network path APISIX nodes use to reach it, and what happens to traffic when the service is slow or down. The documented defaults are a 1,000 ms timeout and a 1,024 KB request body limit, so you should decide whether those values fit your largest legitimate request bodies and your latency budget, and set them deliberately rather than inheriting them.
The practical rollout is to start in monitor mode on a small set of non-critical routes, review what the WAF would have blocked, and tune exclusions before switching those routes to block. Keep the real client IP visible to the WAF by confirming how your load balancers and the APISIX real-ip handling pass client addresses, since a WAF that sees only the load balancer address produces misleading logs and weak blocking decisions. Also test response inspection behavior and large uploads in a staging environment, because body limits interact with the request sizes your APIs actually accept.
chaitin-waf modes, timeouts and body limits compared
This table compares the chaitin-waf block, monitor and off modes, the default 1,000 ms timeouts and the default 1,024 KB request body limit, with the effect of each on false positives, latency and large uploads. Read each row as a choice you make per route, and start new routes in monitor mode before switching them to block.
| Setting | What it does | Effect on false positives | When it fits |
|---|---|---|---|
| Block mode (default) | Requests the SafeLine service flags as attacks are rejected at the gateway | Highest risk of blocking legitimate traffic until rules are tuned for the route | Routes already tested with real traffic and reviewed alerts, where enforcement is required |
| Monitor mode | Requests are inspected and logged, but none are rejected by the WAF | Flagged requests are visible without user impact, so tuning is safe to run | First rollout on any route, and routes with unfamiliar or changing payloads |
| Off mode | The plugin does not send traffic to SafeLine | No inspection, so no false positives and no WAF coverage | Temporary isolation during an incident or for routes covered by another control, with a documented reason |
| Timeouts (1,000 ms default) | Limits how long the gateway waits for the SafeLine service | A slow inspection can fail requests if the timeout is too tight for real payloads | Confirm the default against your measured SafeLine latency before changing it, and set it per route if needed |
| Request body limit (1,024 KB default) | Caps how much of a request body is sent for inspection | Bodies above the limit may be handled differently from smaller ones, so test the boundary | Keep the default for form and API traffic; raise it only for routes with known large payloads |
| Large uploads and streaming | Big or long-lived bodies add inspection time and buffer use | Upload endpoints are a common source of unexpected blocks and slow responses | Exclude or tune upload routes separately, and load-test them with realistic file sizes |
| Latency added per request | Each inspected request waits for the SafeLine decision | Not a false positive issue, but higher latency can trip client timeouts | Measure p95 latency in monitor mode before enforcing, and compare it with your client timeouts |
Setting up chaitin-waf in monitor mode first
This sequence brings chaitin-waf into the gateway in monitor mode first, so each route is inspected, verified and tuned before SafeLine can block any traffic. Each step closes with a check that must pass before the next step starts.
Deploy the SafeLine service
The platform or security team deploys SafeLine in infrastructure you control, placed where the gateway nodes can reach it over a private network path. Confirm the supported deployment method, sizing and network requirements with Chaitin before you start, because this page does not set them. Decide who operates the SafeLine console and who owns rule changes. Done means the console loads, a test rule can be created, and a gateway node can open a connection to the SafeLine address and port.
Define the SafeLine service in plugin metadata
Set the SafeLine service address and port in the
chaitin-wafplugin metadata so every route that uses the plugin sends inspection traffic to the same service. Apply the change through the Admin API or your configuration-as-code pipeline, and record who approved it. Keep the Admin API restricted to private networks while you do this, since the metadata determines where request content is sent. Done means a read-back of the metadata shows the intended endpoint and the gateway logs show no errors when the plugin loads on a test route.Enable monitor mode on test routes
Attach
chaitin-wafto a small set of test routes with the mode set tomonitor, which inspects traffic and logs findings without blocking requests. Set the timeout and request body limit explicitly, using the defaults of 1,000 ms and 1,024 KB only as a baseline. Check whether any test route carries larger uploads and note which ones need a higher body limit. Done means a normal request on each test route succeeds and SafeLine logs record the inspection for it.Confirm the real client IP arrives
Send requests from a known client address through the load balancer, then check that the SafeLine log lists that client address as the source. If the log shows the proxy's address instead, fix the trusted proxy and real-IP settings on the gateway before anyone acts on the findings, because detections tied to a shared address are hard to investigate. Repeat the check on every entry point your traffic uses, including any CDN in front of the gateway. Done means a request from a test client appears in SafeLine with the correct source address on every path.
Review monitor logs against test traffic
Build a test set of ordinary application requests and attack-style requests that the test environment is allowed to send, and record the outcome you expect for each. Run the set through the test routes, then compare each SafeLine detection with the expected result. Log every false positive with the route, the rule and the request shape, and agree tuning changes in SafeLine with the application owner before enforcement. Done means each expected result is matched or documented as an exception, and every exception has a named owner.
Test behavior when SafeLine is unavailable
In the test environment, make SafeLine unreachable on purpose, for example by pointing the metadata at a closed port, and send requests through a test route. Observe how the gateway behaves at the timeout you configured and whether requests pass or fail while the route stays in monitor mode. Decide the failure behavior your organization accepts, and record it in the runbook before any route moves to block mode. Done means the result and the accepted behavior are written down, and the correct service address is restored afterward.
Move selected routes to block mode
Change the mode from
monitortoblockon one route at a time, starting with routes where the review found few or no false positives. Block is the plugin's default mode when none is set, so set it explicitly on every route. Keep the monitor configuration saved so that a rollback is a single change, and confirm each move with the route owner. Run the test set again and check that the expected attacks return the block response while ordinary requests pass. Done means each moved route has a recorded owner, a rollback step and a passing test run, and the remaining routes stay in monitor mode until their review is complete.
Passing the real client IP to the WAF
Behind a load balancer or CDN, the connection APISIX receives comes from the proxy, not the client, so the WAF inspects and judges the wrong address unless forwarding is configured deliberately. The cards below cover the parts that must agree: the proxy chain, the trusted proxy list, the headers APISIX accepts, and the checks that prove the WAF sees real clients.
The proxy address problem
Without correct handling, every request reaches the WAF from the load balancer's private address. Blocking decisions, per-client logs and any rate limits then apply to one address, so one abusive client can block everyone or none can be traced. Before enabling block mode, send a test request through the full path and confirm the address the WAF records matches the test client, not the proxy.
Trusted proxy configuration
APISIX should only accept forwarding headers from proxies you control. Define the trusted address ranges for your load balancers and CDN edges, and reject forwarding headers from anywhere else. Confirm the exact configuration keys and their behavior in the APISIX version you run, since the real-ip handling and trusted list interact with the plugins that read the client address.
Forwarding header sanitization
A client can send its own X-Forwarded-For value, and a naive gateway appends to it, so the WAF may read a forged address first. Strip or overwrite forwarding headers that arrive from untrusted sources at the edge, and set them once from the trusted hop. Test with a crafted header to confirm the WAF ignores it.
Ordering of plugins and the real-ip step
The address must be resolved before chaitin-waf runs and before ip-restriction, rate limits or logging read it. If real-ip handling runs after the WAF or a limiter, the WAF may inspect the proxy address while other controls use the client address. Document the plugin order for each route and verify it in your test environment.
Consistency across the WAF and logs
The WAF's event records, the gateway access logs and the SIEM should show the same client address for each request. A mismatch makes incident investigation and false-positive review slow, because analysts cannot match a blocked request to its source. Compare a sample of WAF events with access log entries during monitor mode before you switch to block.
Testing spoofed and IPv6 clients
Validate the setup with spoofed headers, clients on the trusted and untrusted sides, and IPv6 sources if your users reach the platform over IPv6. Record the expected address for each test case and keep the cases in your regression set, because a later load balancer change or APISIX upgrade can silently move the trusted boundary.
What response inspection covers and what to confirm
Response inspection is the first thing to confirm, not an assumption to build on. The chaitin-waf plugin's documented behavior centers on the request: it forwards client traffic to the SafeLine service set in plugin metadata, and the default request body limit of 1,024 KB applies to what the gateway hands over for inspection. Before you write any policy that depends on inspecting responses, such as blocking data leaving the service or scanning for leaked records, open the chaitin-waf plugin documentation for your exact APISIX version and check which response-side inspections it supports. Do not infer support from SafeLine's own feature list, because the plugin is the component that decides what reaches the WAF.
The body limit and response handling interact in ways that affect both security and availability. A request body above the limit is the case most likely to be mishandled, so test what the plugin does with oversized uploads in block mode and in monitor mode, and confirm whether the request is rejected, passed through uninspected, or logged. For streaming APIs, long-lived responses, server-sent events and chunked downloads, ask whether the plugin buffers anything at all. Buffering can add latency and memory pressure at the gateway, and a stream that is never fully inspected may still pass through. Treat any API that streams large payloads as a separate test case with its own sign-off.
Write the answers down before rollout. For each route class, record whether request inspection is enabled, whether any response inspection is supported in your version, what happens above the body limit, and how streaming traffic behaves under the timeout and body settings you chose. Ask your SafeLine and APISIX contacts to confirm these points in writing, and have your own security team review any control you intend to describe to auditors as response protection. If a control is not supported, document it as a residual risk and plan compensating controls in the application or downstream services.
Security and operational risks of a gateway WAF
Putting a WAF in the request path makes the inspection service part of the gateway's availability, security and audit posture. The cards below cover the risks that appear once chaitin-waf is in front of production traffic, and what to confirm before blocking begins.
SafeLine becomes a new dependency
Every request routed through chaitin-waf depends on the SafeLine service being reachable, so the WAF adds a network hop, a service to operate and a new failure point. Confirm who owns SafeLine's uptime, how it is deployed (its own cluster, network path and capacity), and how its health is monitored alongside the gateway. Treat it as a tier-one dependency in your runbooks and capacity plans.
Fail-open or fail-closed under timeouts
When SafeLine does not answer within the configured timeout, the gateway must either pass the request or reject it. Blocking everything during a WAF outage can take the API down, while passing everything silently removes inspection. Decide this explicitly per route, test the behavior by stopping SafeLine in a staging environment, and confirm the timeout and default mode values in the plugin documentation before you rely on them.
Secrets and WAF console access
The gateway's connection to SafeLine and the SafeLine console both carry privileged access. Anyone who can change plugin metadata can redirect traffic or switch modes to off, and anyone with console access can change rules or read captured requests, which may contain session tokens and personal data. Limit console roles, store credentials in your secret manager, and log every mode change as a change-controlled event.
Log retention for captured requests
A WAF records blocked and sometimes inspected requests, and those records can contain credentials, health or payment data. Ask SafeLine's documentation and your deployment how long events are stored, where they are kept, who can search them and how they are exported to your SIEM. Set a retention period with your compliance and privacy owners before go-live, and confirm that deletion works as documented.
Tuning rules before blocking
A rule set tuned on someone else's traffic will flag legitimate requests, including unusual but valid payloads from partner APIs, file uploads and JSON with unusual characters. Run chaitin-waf in monitor mode on production traffic, review detections with API owners, and create exceptions for confirmed false positives. Move each route to block only after the false positive rate is acceptable to the owners of that API.
Questions teams ask before adding a WAF to APISIX
What drives the cost of adding a WAF to APISIX with SafeLine?
The cost comes from three areas: the SafeLine WAF service itself, the time your engineers spend wiring the chaitin-waf plugin into routes, and the tuning and testing needed before blocking is turned on. The SafeLine service is licensed and run by Chaitin, so ask your vendor or reseller for its current terms rather than assuming a figure. The plugin configuration is a one-time build cost, while the SafeLine service, hosting, and ongoing rule review recur. A quote from DeployOpen should list each of these as a separate line, with the number of routes in scope, the environments covered, and the test cases agreed in writing before work starts.
How long does a monitor-first WAF rollout take?
The duration depends mainly on your traffic volume, how many routes are in scope, and how much rule tuning your applications need. The chaitin-waf plugin supports monitor mode, which logs inspection results without blocking, so you can observe false positives before enforcing. No fixed timeline is established here, so ask for a schedule in the written scope that ties each phase to exit criteria, such as a agreed false positive rate reviewed with your application owners. Busy APIs with unusual payloads, such as large uploads or file-based requests, usually need more observation time than simple JSON APIs.
What does the work need from our security and platform staff?
Your platform team needs to provide access to the APISIX Admin API, the SafeLine service endpoint, and the staging and production gateway environments. Your security team should own the decision about which events block, who reviews monitor-mode logs, and how exceptions are approved. Application owners must confirm which request types are legitimate, since most tuning work depends on their knowledge. Plan regular time from these people during the monitor phase, because it is where most of the effort falls. Confirm the named contacts and their availability in the scope document before the build starts.
Can our own team add a WAF to APISIX without a partner?
Yes, a team with APISIX and NGINX experience can configure the chaitin-waf plugin using the plugin documentation, and many do. The harder part is usually not the configuration but the tuning, testing and evidence work: proving that legitimate traffic passes, that attacks are logged and blocked, and that timeouts and body limits do not break large requests. Ask yourself whether your team has time to run a monitor phase alongside normal releases, and whether someone can own the rule exceptions over time. A partner is useful when that capacity or test coverage is missing.
What goes wrong when the WAF is enabled too early?
The most common failure is blocking legitimate traffic, such as JSON bodies or uploads that match a signature, which breaks client integrations silently. Timeouts can also cause errors if the SafeLine service responds slowly under load, and the plugin default timeouts are 1,000 ms, so test them against your own latency. Body size limits matter too: the default request body limit is 1,024 KB, so large API payloads may be rejected unless you raise the limit for those routes. Avoid this by running in monitor mode first, testing timeout and body limit behavior under realistic load, and keeping a documented route to switch back to off or monitor mode.
How do we keep the real client IP visible to the WAF?
When APISIX sits behind a load balancer or CDN, the WAF sees the proxy address unless the client IP is passed correctly and proxies are trusted. Configure the real client address handling in APISIX before enabling blocking, and make sure only your known load balancers can set forwarding headers. If this is wrong, the WAF logs and any IP-based decisions will point at the wrong source, which slows investigations. Confirm the header path with a test request from a known address in staging, and record the trusted proxy list in your configuration as code.
Does response inspection add extra work to the rollout?
Yes, response inspection adds scope because the WAF must read and evaluate outbound content, which can affect latency, memory and body handling for large responses. Decide which routes need response inspection based on data sensitivity, then test those routes separately in monitor mode before enforcing anything. Ask the vendor for their documented behavior with response bodies and streaming, and budget test time for the largest responses your APIs return.
How DeployOpen scopes and delivers SafeLine WAF integration
The scope is agreed in writing before any configuration changes are made. For a chaitin-waf engagement, that document should name the APISIX version and deployment mode in use, which routes will pass through the WAF, the SafeLine service that inspection traffic will reach, and who owns each side of that connection. It should also state which mode each route starts in, the criteria for moving from monitor to block, and what evidence the client receives at the end. DeployOpen does not publish a price list, so the quote follows from that written scope. Ask for the quote to break out the components separately: discovery of the current traffic, plugin and metadata configuration, test cases, the rollout plan, and any work on the SafeLine side that sits outside the gateway.
Delivery follows the rollout plan, and monitor mode comes first. DeployOpen configures the chaitin-waf plugin on the agreed routes and sets the SafeLine service address in plugin metadata, then runs traffic through monitor mode so the team can compare what would have been blocked with what the application actually needs. Timeouts and request body limits are tuned against real payloads, not defaults alone, and the real client IP handling is checked end to end before block mode is enabled. Each route is then moved to block mode in a defined sequence, with a rollback step written for each change. The client receives the configuration as code, the rollout log, and the test evidence, so their own team can reproduce the setup and audit it later.
Testing evidence and ongoing support are separate deliverables. The test record covers representative attack and benign requests, false positive review, latency and timeout behavior under load, and confirmation that inspection failures behave as the chosen mode expects. DeployOpen prepares this evidence for the client's own compliance and security reviews, but it does not issue audit reports or certifications, and independent assessors make those determinations. Rule tuning, SafeLine version updates, new routes and incident support after go-live can be covered by a retainer agreed in writing, which sets response expectations and the scope of changes. Confirm during scoping whether that retainer will cover the SafeLine platform itself or only the gateway configuration.
