TowerShield
towershield is a small, auditable Rust workspace for rejecting
high-confidence vulnerability-scanner paths before they reach Axum routes or
application handlers. It includes a framework-neutral rule engine, a Tower
middleware layer, and an offline Cloudflare Ruleset Engine exporter.
This project is a path denylist, not a general-purpose web application firewall (WAF). Use it as one inexpensive layer in a defence-in-depth setup.
Workspace crates
| Crate | Purpose | API documentation |
|---|---|---|
towershield |
Tower Layer and Service for rejecting matched requests. |
docs.rs |
towershield-core |
Portable rules, matchers, serialization, and built-in rules. | docs.rs |
towershield-cloudflare |
Offline Cloudflare expression and Rulesets API JSON generation. | docs.rs |
Requirements
- Rust 1.97 or newer (the project's current stable toolchain).
- A Tower-compatible HTTP service. Axum is supported through its Tower integration.
The library performs no network calls and needs no runtime credentials.
Installation
Add the Tower middleware to your application:
[]
= "0.1"
Add towershield-core when you want to construct or serialize rules directly,
and add towershield-cloudflare when you want offline Cloudflare output. The
package and Rust library names follow the same towershield* family:
[]
= "0.1"
= "0.1"
Quick start with Axum
Build the complete router, then wrap it with Layer::layer:
use ;
use ShieldLayer;
use Layer;
The resulting service returns 404 Not Found for a built-in probe such as
/.env and forwards /api/users unchanged.
Do not use router.layer(ShieldLayer::default()) when you need to inspect
unmatched routes. Axum applies router middleware after route matching, so a
scanner probe with no matching route can bypass that layer. The complete
working example demonstrates the preferred wrapping and verifies both blocked
and allowed requests:
Expected output ends with:
All assertions passed.
Configure rules
ShieldLayer::default() uses the built-in rule set. Add a high-confidence
application-specific deny rule with the builder:
use ;
let layer = builder
.add_rule
.build;
Rules are ASCII case-insensitive by default. Opt into case-sensitive matching for a custom rule when your router distinguishes path case:
use ;
let rule = deny
.with_case_sensitivity;
Add an exclusion
Allow rules take precedence over all deny rules. Use a narrow matcher for a legitimate path that would otherwise be blocked:
use ;
let rules = DEFAULT_RULES.get.push;
let layer = builder.with_ruleset.build;
Change the blocked response
Blocked responses contain an empty body and content-length: 0. The default
status is 404 Not Found; change it when your application requires another
status:
use StatusCode;
use ;
let layer = builder
.with_blocked_response
.build;
Observe blocked requests
Register a callback, or use the default tracing feature for structured debug
events:
use ShieldLayer;
let layer = builder
.on_block
.build;
The callback receives the decoded URI path, without its query string. Do not log secrets discovered in paths or add sensitive headers, cookies, or request bodies to this event.
Export rules for Cloudflare
towershield-cloudflare converts the same deny rules into expressions and a
Rulesets API-compatible JSON payload. It does not deploy the payload or access
Cloudflare credentials.
use ;
use DEFAULT_RULES;
Review output.report.diagnostics before deployment. Cloudflare and Tower do
not normalize every path in exactly the same way; see the
towershield_cloudflare::parity
module for the compatibility boundaries.
Enabled allow rules produce export warnings: they are not Cloudflare exclusions. Remove conflicting deny rules from the exported set or configure equivalent edge exclusions before deploying it; a Tower allow cannot undo an edge block.
Built-in rule groups
The default rules cover 14 categories of high-confidence scanner probes:
| Group | Example paths |
|---|---|
| Secrets and environment files | /.env, /.npmrc, /.netrc |
| Source-control metadata | /.git/, /.svn/, /.hg/ |
| Cloud credentials | /.aws/credentials, /gcp-credentials.json |
| SSH keys and certificates | /.ssh/, /id_rsa, *.pem, *.key |
| Build and deployment manifests | /Dockerfile, /terraform.tfstate |
| Framework configuration | /config/master.key, /settings.py, /appsettings.json |
| JavaScript, React, and Next.js tooling | /package.json, /bun.lock, /.next/, /__nextjs_original-stack-frame, /@vite/client |
| WordPress | /wp-login.php, /wp-admin/, /xmlrpc.php |
| Joomla | /administrator/, /installation/ |
| Drupal | /sites/default/, /update.php |
| Magento | /downloader/, /shell/ |
| PHP web shells | /c99.php, /r57.php, /shell.php |
| Debug and actuator endpoints | /debug/pprof/, /actuator, /server-status |
| AI and developer-tool credentials | /.codex/, /.cursor/, /.claude.json |
Applications serving WordPress, Joomla, Drupal, Magento, PHP, build manifests,
developer-tool files, or deliberately exposed Next.js/Vite development
endpoints should review the built-ins and add precise allow rules before
enabling the middleware. Normal production assets such as /_next/static,
/_next/image, JavaScript bundles, and /manifest.json remain allowed.
Additional credential-file rules cover Cargo, uv, Poetry, GitHub CLI, GitLab
Runner, Terraform CLI, Kubernetes, Google application default credentials,
Gemini CLI, and Windsurf. These use slash-bounded, directory-qualified suffixes
(or distinctive secret filenames), so copied home directories are covered even
without regex. They do not block every config.toml, settings.json, or AI
documentation file. PHPUnit eval-stdin.php, Laravel's
/_ignition/execute-solution, Next.js's plural
/__nextjs_original-stack-frames, .user.ini, .DS_Store, and SMTP key/token
files are also denied. See rule evidence and review policy
for sources and scope.
Agent-ready protocol compatibility
TowerShield keeps legitimate public discovery and protocol paths reachable,
including robots.txt, OAuth/OIDC metadata, MCP server cards and endpoints,
Agent Skills, A2A cards, API catalogs, and UCP/ACP commerce discovery. It also
distinguishes public discovery from private configuration: for example,
/.well-known/mcp.json remains allowed while /.mcp.json is blocked.
These protocols are not all path-based. Web Bot Auth uses HTTP signatures;
WebMCP is a browser API; x402 and MPP use HTTP 402, headers, and payment
payloads; and OAuth requires token and issuer validation. TowerShield does not
claim to implement those layers. See the
agent protocol compatibility guide for canonical paths,
standards maturity, MCP Apps versus headless MCP, security boundaries, and the
full compatibility matrix.
Path inspection policy
For every request, the Tower service derives an inspection path:
- Read
http::Uri::path(); query strings are excluded. - Percent-decode the path exactly once.
- Preserve invalid percent sequences verbatim.
- Lazily produce an ASCII-lowercase form only when a rule needs it.
- Evaluate allow rules, then deny rules.
The middleware does not collapse . or .., normalize duplicate slashes,
convert backslashes, or mutate the original request. See
inspection.rs for the exact policy.
Threat model and boundaries
The built-in rules target automated probes for well-known sensitive paths and
cover trivial one-pass percent-encoding variants such as %2eenv.
This project does not provide:
- SQL injection, XSS, RCE, or OWASP Core Rule Set detection.
- Header, query-string, request-body, or response-body inspection.
- IP reputation, rate limiting, DDoS mitigation, or CAPTCHA.
- Authentication, authorization, TLS termination, or redirect management.
- Runtime rule downloads, background workers, or network calls.
- Protection from novel obfuscation, targeted reconnaissance, or vulnerabilities in allowed application routes.
The JavaScript rules reduce exposed-file and development-endpoint probing;
they are not substitutes for framework updates. In particular, path-only
filtering cannot mitigate Next.js middleware-header bypasses such as
CVE-2025-29927
or attacker-controlled React Server Components protocol payloads such as
CVE-2025-55182.
Likewise, Vite's WebSocket fetchModule file-read vulnerability
requires patching and restricting development-server access; denying /@fs/
does not inspect WebSocket messages.
Cargo features
Features are defined per crate:
| Crate | Feature | Default | Purpose |
|---|---|---|---|
towershield-core |
serde |
Yes | Implement Serde traits for rules; applications choose their JSON, TOML, or other serializer. |
towershield-core |
regex |
Yes | Enable regex matchers and 16 broader built-in rules. |
towershield-core |
rayon |
No | Enable regex support and parallelize compilation of large regex-heavy custom rule sets. |
towershield |
tracing |
Yes | Emit structured debug events for blocked requests. |
towershield |
regex |
Yes | Enable regex matchers and the broader built-in rule tier. |
towershield |
rayon |
No | Forward the core crate's opt-in parallel compilation. |
towershield-cloudflare |
serde |
Yes | Serialize Rulesets API output as JSON. |
towershield-cloudflare |
regex |
Yes | Export regex matchers and include the broader built-in rule tier. |
towershield-cloudflare |
rayon |
No | Forward the core crate's opt-in parallel compilation. |
The core serde feature does not depend on serde_json or toml. Add the
serializer your application uses directly. The Cloudflare crate retains
serde_json for its to_json() API.
Disabling regex
Regex support is on by default because it materially improves the built-in coverage. To remove the regex dependency from the Tower middleware:
= { = "0.1", = false, = ["tracing"] }
For towershield-core or towershield-cloudflare, re-enable serde explicitly
if you still need serialization:
= { = "0.1", = false, = ["serde"] }
= { = "0.1", = false, = ["serde"] }
This does not disable TowerShield. The conservative exact, prefix, suffix,
segment, contains, and wildcard baseline remains. It does remove 16 expansion
rules, so nested environment and credential files, nested package manifests and
framework configs, nested CMS installations, PHP shell filenames, debug paths,
and AI-tool metadata receive substantially less coverage. For example,
/package-lock.json remains blocked while /frontend/package-lock.json is no
longer caught by the built-in set.
Cargo features are additive, so another dependency can re-enable regex. Check the resolved graph with:
cargo tree -e features -i towershield-core
The Cloudflare exporter emits diagnostics and skips regex rules when the
selected Cloudflare plan does not support the matches operator.
Performance model
The built-in rules compile once per process and are shared by default layers. Custom rule sets compile when their layer is built. Ordinary lowercase, unencoded paths borrow the URI path and allocate nothing during inspection; percent-decoding and ASCII case folding allocate lazily only when required. Allow and deny rules live in separate compiled tables, so the common built-in deny-only set is scanned once. A blocked decision owns its match metadata and returns before invoking the inner service.
The optional rayon feature is intentionally narrow: it activates only when
an enabled custom set contains at least 256 regex rules. Exact, prefix, suffix,
and ordinary-sized sets remain sequential, and request evaluation is never
parallelized. This keeps Rayon scheduling and memory overhead away from the
latency-sensitive request path.
Run cargo bench -p towershield-core --bench core_checker for the core matcher,
including allocation counts and peak live bytes. Benchmark your own custom
rule set and traffic shape before relying on a latency or throughput target.
Project maintenance
License
Licensed under the MIT License.