aaWAF puts a semantic engine in front of nginx instead of a rule list

A reverse proxy sits between the internet and your origin

aaWAF is described as a free private cloud WAF firewall, and the architecture is the first thing to understand. It uses a reverse proxy approach: site traffic arrives at aaWAF first, and after aaWAF has inspected and filtered the traffic, it is forwarded to the server that originally provided the service.

That has an immediate consequence for deployment. The WAF is a separate thing in front of your application, not a module inside it, so your origin server's address is not what the internet sees, and the WAF becomes a component that can be restarted, upgraded or taken out of the path without touching the application.

The protection list is broad and is stated in the introduction. It protects against SQL injection, XSS, CSRF, SSRF, command injection, code injection, local file inclusion and remote file inclusion.

The compatibility claim is also part of the introduction: it is compatible with ARM and domestic systems, and there is a linked sheet listing ARM and domestic system compatibility.

The project is the Chinese-language aaWAF from aaPanel, and the repository carries both a Chinese README and an english.md with installation instructions, so the international install path exists even though most of the documentation, including the module lists and the update notes, is in Chinese.

It is Go, AGPL-3.0 licensed, and the release history shows a steady line of 7.x versions: 7.5 from 2026-05-08, 7.4 from 2026-04-11 and 7.3 from 2026-02-28. The last push was on 2026-06-03.

The hybrid engine is 95 percent semantic, 5 percent regex

The performance section makes the central design claim. aaWAF uses the high performance OpenResty, and it uses a hybrid pattern matching mode of a semantic analysis engine filtering at 95 percent plus regular expression matching at 5 percent, which it says can effectively filter malicious requests without affecting the normal access speed of the site. The performance test results show that under high concurrency it can exert 100 percent of the machine's performance with no performance limit.

The division is worth thinking about. Regular expressions are good at narrow signatures and bad at general structure, which is the known weakness of ModSecurity-style rules: they fire on things that look like attacks and miss on things that are attacks but look unfamiliar. A semantic engine works on the parsed request rather than the raw text, which is why it can reason about a SQL injection attempt in a parameter that no rule would have matched.

The 5 percent regex share is not a concession, it is the part that handles what a semantic engine cannot easily express, like the user agent checks in the regular expression module list: malicious crawlers, scanner detection using user agent plus headers, malicious downloads of backup files, Nday vulnerabilities in specific products such as DedeCMS and PHPCMS, and weak password protection.

The decoding module is the other half of making semantic analysis work. It decodes up to three layers automatically, and the list covers URL decoding, Unicode decoding, Base64, hexadecimal, JSON, Gzip added in v7.1, an XSS engine that parses HTML encodings added in v7.2, and XML decoding added in v7.2. The point of the decoding stage is that an attacker can hide a payload behind several layers of encoding, and a semantic engine that sees the encoded form sees nothing.

The published benchmark shows the detection and false positive numbers

The project publishes its test results using blazehttp, with a link to a testing tutorial in Test.md, and the comparison table against ModSecurity Level 1 and CloudFlare Free is the most quotable material in the repository.

The headline run used 33877 total samples, and the result was a detection rate of 83.13 percent, with 658 malicious samples of which 547 were correctly blocked and 111 let through as false negatives. The false positive rate was 0.08 percent, from 33219 normal samples of which 33194 were correctly allowed and 25 were wrongly blocked. The accuracy figure is 99.60 percent, calculated as correct blocks plus correct allows over the total, and the average time per request was 5.80 milliseconds.

The comparison table puts the same 33877 samples through three systems. ModSecurity Level 1 shows a 69.74 percent detection rate, a 17.58 percent false positive rate and 82.20 percent accuracy. CloudFlare Free shows 10.70 percent detection, 0.07 percent false positives and 98.40 percent accuracy. aaWAF shows 83.13 percent, 0.08 percent and 99.60 percent.

The comparison to read carefully is the one with ModSecurity, because the false positive gap is the striking number: 17.58 percent against 0.08 percent on the same sample set. The gap to CloudFlare is the opposite shape, since a free CDN tier is not primarily an application-layer firewall, which is why its detection figure is so low.

One caveat belongs here rather than in a footnote. These are the project's own numbers, produced by the project, with the test methodology described in a separate document rather than reproduced in the README, so a reader who wants to check them should look at Test.md and at the linked blazehttp tool.

The command the test was run with is:

root@debian:/tools/bl/blazehttp-master# ./build/blazehttp -t http://192.168.77.79

The module lists are honest about what is not finished

The documentation keeps three lists, and the third one is the interesting one because it is a public to-do list of detection modules that are not implemented.

The semantic analysis module list covers SQL injection, XSS cross-site scripting with a note that the rework was completed in v7.2 on 2026-02-02, file upload, SSRF server-side request forgery reworked in v7.1 on 2026-01-02, command execution, file inclusion, PHP code injection, PHP deserialization vulnerabilities, Java code injection, Java deserialization vulnerabilities such as CC1, CC2 and CC3, template injection across Jinja2, Twig, Smarty, FreeMarker and Velocity, XXE, ASP.NET code injection updated 2025-08-21, and NodeJs code execution updated 2025-12-19.

The regular expression module list is the five items described earlier.

The future modules list is where the project is candid about its gaps. Common PHP, Java and Python CMS vulnerabilities are marked as not done, as are common web framework vulnerabilities. Under CC attacks, both optimising CC attack detection and adding CC attack protection rules are marked not done. And the machine learning module, a semantics-based machine learning model, is also marked not done.

There is also a long list of deserialisation and template injection detectors marked as completed with dates, several of which point at open source parser projects the author has published separately, for SnakeYAML, Twig, FreeMarker, Velocity, OGNL and SpEL. That is a useful detail for anyone evaluating the project, because it means the semantic analysis for those languages is backed by a real parser rather than a pattern, and the parsers are open source in their own right.

Reading the three lists together gives a fair picture: broad coverage of injection classes, real parsers behind the modern ones, and a clearly acknowledged set of gaps in CMS and framework Nday detection.

Installation is a shell script, and Docker is required either way

The online install is a single command run over SSH on the server:

URL=https://download.bt.cn/cloudwaf/scripts/install_cloudwaf.sh && if [ -f /usr/bin/curl ];then curl -sSO "$URL" ;else wget -O install_cloudwaf.sh "$URL";fi;bash install_cloudwaf.sh

The script prefers curl and falls back to wget, then runs the installer. There is also an offline path for servers that cannot reach the public network, and it comes with two conditions: Docker must be installed manually, because otherwise the install is not possible, and before installing you should make sure the server has the tar, gzip, curl, netstat, ss and docker commands. A check command is provided that loops over the list and reports the missing ones.

The offline artefacts are three downloads: the offline install script, the image file named btwaf_mysql_openresty-latest.tar.gz, and the program file named cloudwaf-latest.tar.gz. The naming tells you the stack, since the image bundles MySQL and OpenResty, which is where the interception logs and configuration live.

After uploading them with a tool such as Xftp or WinSCP and placing them at the same path, the offline install is:

bash install_cloudwaf.sh offline

The documentation notes that after installation the login steps are the same as for the online install.

There is a per-release change log in Update.md, an API tutorial in API.md, a payload interception test table in Payload.md, a migration guide for WAF, and a document on adding protected sites.

What the Go code tells you about the deployment

The go.mod file describes a service with a few surprises in it, and reading the dependency list is a fast way to understand the shape of the system.

The module is CloudWaf and it targets go 1.19. The direct dependencies include the Alibaba Cloud DNS API and the Tencent Cloud SDK, including the DNSPod component, which is how a WAF in front of a domain updates DNS records to point at the proxy. There is a MySQL driver, so the interception records are stored in a database. There is a modernc.org/sqlite dependency as well, so there is a second storage option for smaller deployments.

Then the pieces that tell you what the product does. gopsutil for process and system information, which is how the dashboard reports on the host it is running on. gocron for scheduling. maxmind/mmdbinspect, which is the MaxMind GeoIP database format, so the WAF resolves client geography, which is what the attack map in the interface is built on. mojocn/base64Captcha for the captcha challenge on suspicious traffic, and pquerna/otp, which is one-time password support for admin authentication. vmihailenco/msgpack for the wire format.

The interface section of the documentation lists a 3D attack map, a home overview page, interception records, hit records and the attack map. The interception and hit records are two different views, and the distinction is the one that matters operationally: an interception record is a request that was blocked, while a hit record is a rule that fired, so a rule that fires without blocking tells you something different from a blocked request.

The repository layout also carries a set of what look like bundled parsers at the top level, with directories for Ognl, ParserSpel, freemarker-ast, snakeyaml, twig-ast and velocity-ast, which are the open source parsers the semantic analysis relies on.

Editorial conclusion

Adopt aaWAF if you run nginx in front of an origin server and want a reverse-proxy WAF that covers a broad set of injection classes without hand-writing rules for each. Skip it if you need a fully verified detector for one specific vulnerability class, because the project marks several modules as not done, including common CMS and web framework Nday flaws, CC attack protection and the machine learning module. Verify first that your platform is covered, since the project publishes an ARM and domestic system compatibility sheet, that you can accept a reverse proxy in front of your origin rather than an inline module, and that Docker is available, since the online and offline installers both expect it.

Frequently asked questions

Official sources

1. aaPanel/aaWAF on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases