Vaultwarden CRS plugin
The Vaultwarden CRS plugin makes the OWASP Core Rule Set (CRS 4) work with Vaultwarden, the Bitwarden-compatible password server written in Rust. It is for admins who put Vaultwarden behind ModSecurity on Angie, NGINX or Apache, or behind Coraza, and are tired of CRS blocking their own password vault.
Out of the box, CRS treats Vaultwarden’s encrypted payloads as attacks. Encrypted vault items, password hashes and admin tokens look like random base64, which trips the SQL injection and PHP injection detectors. The plugin removes those false positives on the routes where they happen, and can also lock the host down to Vaultwarden’s known routes.
→ GitHub · Self-hosted Vaultwarden guide · All CRS plugins
Why Vaultwarden needs a different approach
Vaultwarden is a JSON API. The web vault, browser extensions, mobile and desktop apps and the Bitwarden CLI all send application/json bodies, and the argument names in those bodies are JSON keys that change per endpoint and per client version. An allowlist of argument names, as the ViMbAdmin plugin uses, would block real clients. This plugin therefore has no argument-name allowlist for JSON bodies; its positive-security layer allows paths only.
The bodies are also end-to-end encrypted: vault data travels as EncString blobs (2.<iv>|<ct>|<mac>) and base64. Instead of weakening the whole engine, the plugin switches off only the noisy base64, SQL injection and PHP detector families, and only on the encrypted write paths. CRS keeps scanning everything else.
What the Vaultwarden CRS plugin does
- False-positive exclusions (
vaultwarden-before.conf): narrow exclusions for the Argon2 admintoken, the password-grant hashes on/identity/connect/token, the encrypted cipher, account and Send blobs under/api, and the domains users type for website icons. You get these as soon as you enable the plugin. - Path allowlist (
vaultwarden-after.conf, separate opt-in): allows Vaultwarden’s real mount points (/api,/identity,/admin,/events,/icons,/notifications,/attachments), its built-in static routes and the web-vault files, and answers everything else with a 404. Scanner probes for/.envor/wp-login.phpnever reach the backend. The route map comes from Vaultwarden’s source (src/main.rsmount points andsrc/api/web.rsstatic routes) and from the web-vault tree in the official Docker image. - Method and Content-Type checks, part of the same opt-in: only GET, POST, PUT, DELETE, HEAD and OPTIONS are allowed, and writes to
/apimust sendapplication/json, except Send file uploads and attachment uploads. Every block also adds to the CRS inbound anomaly score, so fail2ban or a CRS DoS layer sees the probe.
Optional switches
Every feature beyond the exclusions has its own variable, all off by default, and all set by the same per-vhost rule that enables the plugin:
tx.vaultwarden-plugin_positive_security=1turns on the path, method and Content-Type allowlist. Since version 2.2.0 it no longer follows the enable flag, so a deployment that relied on the old behaviour must set it explicitly.tx.vaultwarden-plugin_argname_allowlist=1(experimental) checks argument names on the two surfaces that are stable: the/identity/connect/tokenform fields and GET query-string names. JSON bodies are never checked. These rules sit in the before-file, so they run before the CRS blocking decision.tx.vaultwarden-plugin_admin_disabled=1answers every/adminpath with a 404. Two post-authentication remote code execution flaws (CVE-2025-24364 and GHSA-h6cc-rc6q-23j4) are reachable only through the admin panel, and most installs do not need it after first setup.tx.vaultwarden-plugin_basepath=vaulttells the allowlist that Vaultwarden lives under one path segment, such ashttps://host/vault/. Without it, the route map accepts one arbitrary leading segment.
Two rules for published advisories run whenever the plugin is enabled. Rule 9530235 rejects IP literals in the icon path (the SSRF in CVE-2026-47160), and rule 9530236 rejects cross-site requests to the SSO routes (CVE-2026-47158 and CVE-2024-55225). Both are defence in depth: Vaultwarden 1.36.0 and later fix these flaws. The rate-limit advisories are a job for the web server, not the WAF, because libmodsecurity3 keeps no per-IP state; the repository’s Angie example vhost covers them with limit_req zones.
Install and enable
Unlike the WordPress and ViMbAdmin plugins, the Vaultwarden plugin is not part of our modsecurity-crs package, and the GitHub project publishes no release archives. Clone the repository into the package’s plugin directory and link it into plugins-enabled/:
git clone https://github.com/myguard-labs/vaultwarden-crs-plugin /etc/modsecurity/crs/plugins-available/vaultwarden-crs-pluginln -s ../plugins-available/vaultwarden-crs-plugin /etc/modsecurity/crs/plugins-enabled/vaultwarden-crs-plugin
The modsecurity.conf-recommended file from the package already includes every enabled plugin’s config, before and after files in the right order. Then switch the plugin on for the Vaultwarden vhost only, never globally, because it relaxes CRS on Vaultwarden’s routes. On Angie or NGINX with libmodsecurity3:
server {
server_name vault.example.com;
modsecurity on;
modsecurity_rules '
SecAction "id:9530001,phase:1,nolog,pass,setvar:tx.vaultwarden-plugin_enabled=1"
';
}
This works because the ModSecurity connector runs a server block’s own rules before the rules it inherits from http, so the flag is set before the plugin checks it. We tested it on Angie 1.12.5 with libmodsecurity3 3.0.17 and the CRS from modsecurity-crs: the vhost with the rule got the plugin, the vhost next to it did not. The order matters. The same rule placed after the CRS Include did nothing.
On Apache with mod_security2, a SecAction inside <VirtualHost> or <Location> runs after the inherited CRS rules and does not enable the plugin; we saw this with mod_security2 2.9.7 on Debian 12. Put a rule that matches the Vaultwarden host name in the main configuration, before the CRS Include line, for example SecRule REQUEST_HEADERS:Host "@streq vault.example.com" "id:9530002,phase:1,nolog,pass,setvar:tx.vaultwarden-plugin_enabled=1".
Roll out the path allowlist with CRS in DetectionOnly first. Watch the audit log for rule 9530230: each hit is a path the allowlist would have denied. Add any extra routes you serve, such as a proxy health check, to that rule, then switch CRS back to blocking.
Security fixes in the 2.x releases
The current version is 2.2.4. Version 2.0.0 re-checked the route map against fresh Vaultwarden source and fixed four problems found in a security audit:
- Trailing-slash bypass. The root branch of the allowlist matched the trailing slash of any path, so
/wp-login.php/,/.env/and/phpmyadmin/got through. The branch is now anchored. - Enforcement rules that switched themselves off. The deny rules carried the
OWASP_CRStag, so the false-positive strip on the login path (ctl:ruleRemoveByTag=OWASP_CRS) also removed the allowlist there. The tag is gone from those rules. - Deeply nested probes. A mount or static-directory name matched at any depth, so
/wp-content/images/shell.phppassed on theimagessegment. At most one leading segment is allowed now. - Content-Type case. The
application/jsoncheck ignores case, soApplication/JSONno longer draws a false 415.
Later releases fixed more. In 2.2.1 the allowlist opt-in no longer switches off the advisory rules, and a write to /api with no Content-Type header at all is now checked. In 2.2.2 the JSON exclusion is end-anchored, so a made-up path such as /api/ciphersEVIL no longer loses 284 CRS rules. Version 2.2.3 added the basepath setting, and 2.2.4 allows the deeplinkScheme field on the token endpoint.
Tested engines and supported systems
The plugin needs CRS 4 or newer. Its CI runs the go-ftw regression suite on Apache httpd with Debian 12’s mod_security2 and on Angie with libmodsecurity3 and the connector from our APT repository, using the CRS from our modsecurity-crs package. On pull requests, a Coraza v3 gate loads every plugin file and fails on any load error. A separate suite replays real scanner paths against the Apache build to keep the trailing-slash and deep-nesting fixes in place.
The engine, connectors and rule set install with APT once the repository is set up. modsecurity-crs, libmodsecurity3, angie-module-http-modsecurity and libnginx-mod-http-modsecurity are built for Debian 13 trixie, 12 bookworm and 11 bullseye, and for Ubuntu 26.04 resolute, 24.04 noble and 22.04 jammy, on amd64 and arm64. On Debian 11 arm64 only the engine and the rule set are available, without the connector modules.
