A next-generation Web Application Firewall agent for Zentinel reverse proxy. Built in pure Rust with no C dependencies, featuring heuristic anomaly detection with n-gram analysis, anomaly scoring, and 285 detection rules.
- SQL Injection - UNION, blind, time-based, stacked queries, NoSQL
- Cross-Site Scripting (XSS) - Reflected, stored, DOM-based, polyglot
- Path Traversal - Directory traversal, LFI, RFI
- Command Injection - Shell, Windows cmd, expression languages
- Server-Side Template Injection (SSTI) - Jinja2, Twig, Freemarker
- LDAP/XPath Injection
- SSRF Detection - Internal IP ranges, cloud metadata endpoints
- Insecure Deserialization
- API Security - GraphQL introspection blocking, JSON depth limits, JWT validation
- Bot Detection - Scanner fingerprints, behavioral analysis, timing anomalies
- Credential Stuffing Protection - Breach checking, velocity detection
- Sensitive Data Detection - Credit cards, SSN, API keys, PII masking
- Supply Chain Protection - SRI validation, crypto miner detection, Magecart patterns
- Threat Intelligence - IP/domain reputation framework, Tor exit node detection (requires feed configuration)
- Virtual Patching - Built-in CVE signatures (Log4Shell, Spring4Shell, Shellshock)
- Advanced Analytics - Prometheus/OpenTelemetry metrics, latency histograms
- Federated Learning - Privacy-preserving distributed gradient averaging (experimental)
- Anomaly Scoring - Cumulative risk scores instead of binary block/allow
- Statistical Classification - Character n-gram based payload fingerprinting
- Regex Automata - DFA-based multi-pattern matching for O(n) scanning
- Streaming Inspection - Constant memory body inspection with sliding window
- Plugin Traits - Compile-time extensible detection and scoring
# Install just this agent
zentinel bundle install waf
# Or install all bundled agents
zentinel bundle installThe bundle command downloads the correct binary for your platform and places it in the standard location. See the bundle documentation for details.
cargo install zentinel-agent-wafgit clone https://github.com/zentinelproxy/zentinel-agent-waf
cd zentinel-agent-waf
cargo build --release# Basic usage with default settings
zentinel-waf-agent --socket /var/run/zentinel/waf.sock
# With higher sensitivity
zentinel-waf-agent --socket /var/run/zentinel/waf.sock --paranoia-level 2
# Detect-only mode (no blocking)
zentinel-waf-agent --socket /var/run/zentinel/waf.sock --block-mode false| Option | Environment Variable | Description | Default |
|---|---|---|---|
--socket |
AGENT_SOCKET |
Unix socket path | /tmp/zentinel-waf.sock |
--paranoia-level |
WAF_PARANOIA_LEVEL |
Sensitivity (1-4) | 1 |
--block-mode |
WAF_BLOCK_MODE |
Block or detect-only | true |
--config |
WAF_CONFIG |
JSON config file path | - |
{
"paranoia-level": 2,
"scoring": {
"enabled": true,
"block-threshold": 25,
"log-threshold": 10
},
"rules": {
"enabled": ["942*", "941*", "932*"],
"disabled": ["942100"],
"exclusions": [{
"rules": ["942110"],
"conditions": { "paths": ["/api/admin"] }
}]
},
"api-security": {
"graphql-enabled": true,
"block-introspection": true,
"jwt-block-none": true
},
"bot-detection": {
"enabled": true,
"timing-analysis": true
},
"sensitive-data": {
"enabled": true,
"mask-in-logs": true
},
"threat-intel": {
"enabled": true,
"block-tor-exit-nodes": true
},
"virtual-patching": {
"enabled": true,
"log-matches": true
},
"metrics": {
"enabled": true,
"per-rule-metrics": true
}
}| Level | Description | Use Case |
|---|---|---|
| 1 | High-confidence detections only | Production (recommended) |
| 2 | Medium-confidence rules added | Production with tuning |
| 3 | Low-confidence rules added | Staging/testing |
| 4 | Maximum sensitivity | Security audits |
Instead of binary block/allow, the WAF calculates cumulative risk scores:
Total Score = Σ(rule_score × severity_multiplier × location_weight)
| Score Range | Action |
|---|---|
| 0-9 | Allow |
| 10-24 | Log (warning) |
| 25+ | Block |
| Severity | Multiplier |
|---|---|
| Critical | 2.0x |
| High | 1.5x |
| Medium | 1.0x |
| Low | 0.7x |
| Info | 0.3x |
| Location | Weight |
|---|---|
| Query String | 1.5x |
| Cookie | 1.3x |
| Path | 1.2x |
| Body | 1.2x |
| Headers | 1.0x |
- 942100-942199: Basic patterns
- 942200-942299: Database functions
- 942300-942399: SQL keywords
- 942400-942499: Blind injection
- 941100-941199: Script tags
- 941200-941299: Event handlers
- 941300-941399: JavaScript URIs
- 941400-941499: HTML injection
- 932100-932149: Unix commands
- 932150-932199: Windows commands
- 932200-932299: Shell expressions
- 930100-930149: Basic traversal
- 930150-930199: OS file detection
- 920100-920199: Request anomalies
- 920200-920299: Protocol violations
- 913100-913199: User-Agent patterns
- 934100-934199: Template injection
- 92000-92099: Script integrity
- 92100-92199: Malicious patterns
- 92200-92299: Obfuscation
- 93700: Log4Shell (CVE-2021-44228)
- 93701: Spring4Shell (CVE-2022-22965)
- 93702: Shellshock (CVE-2014-6271)
- 94000-94099: IP reputation
- 94100-94199: Domain reputation
- 94200-94299: IoC matches
- Introspection query blocking
- Query depth limiting
- Batch query detection
- "none" algorithm detection
- Weak algorithm warnings
- Expired token detection
- Deep nesting detection
- Prototype pollution patterns
- NoSQL injection patterns
GET /metrics
# HELP waf_requests_total Total requests processed
# TYPE waf_requests_total counter
waf_requests_total 12345
# HELP waf_requests_blocked Total requests blocked
# TYPE waf_requests_blocked counter
waf_requests_blocked 42
# HELP waf_inspection_latency_seconds Request inspection latency
# TYPE waf_inspection_latency_seconds histogram
waf_inspection_latency_seconds_bucket{le="0.001"} 10000
waf_inspection_latency_seconds_bucket{le="0.005"} 12000
GET /metrics?format=json
{
"requests_total": 12345,
"requests_blocked": 42,
"detections_by_attack_type": {
"SQL Injection": 15,
"Cross-Site Scripting": 8
}
}agents {
agent "waf" {
type "custom"
transport "unix_socket" {
path "/var/run/zentinel/waf.sock"
}
events "request_headers" "request_body_chunk" "response_body_chunk"
timeout-ms 50
failure-mode "open"
}
}
routes {
route "api" {
matches { path-prefix "/api" }
upstream "backend"
agents "waf"
}
}X-WAF-Blocked: true
X-WAF-Rule: 942100
X-WAF-Score: 35
X-WAF-Attack-Type: SQL Injection
X-WAF-Detected: 942100,941100
X-WAF-Score: 15
Measured with Criterion. Run
cargo benchto reproduce on your hardware.
| Metric | Target | Actual |
|---|---|---|
| Rule matching (1KB input) | <5ms | ~2ms |
| Memory per request | <1KB | ~500B |
| Throughput | >50K req/s | 65K req/s |
| Binary size | <10MB | ~6MB |
Run benchmarks:
cargo bench# Unit tests
cargo test --lib
# Integration tests
cargo test --test integration_tests
# CRS compatibility tests
cargo test --test crs_compatibility
# All tests
cargo test# Debug build with logging
RUST_LOG=debug cargo run -- --socket /tmp/test.sock
# Release build
cargo build --release
# Check formatting
cargo fmt --check
# Lint
cargo clippy| Feature | zentinel-agent-waf | ModSecurity CRS |
|---|---|---|
| Detection Rules | 285 | 800+ |
| Statistical Detection | ✓ | ✗ |
| Anomaly Scoring | ✓ | ✓ |
| API Security | ✓ (GraphQL, JWT) | Basic |
| Bot Detection | ✓ (behavioral) | UA only |
| Threat Intel | ✓ | ✗ |
| Virtual Patching | ✓ | ✗ |
| Dependencies | Pure Rust | C library |
| Binary Size | ~6MB | ~50MB |
| Latency p99 | <5ms | ~15ms |
┌─────────────────────────────────────────────────────────────┐
│ Zentinel Proxy │
└─────────────────────────┬───────────────────────────────────┘
│ Unix Socket
▼
┌─────────────────────────────────────────────────────────────┐
│ WAF Agent │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Automata │ │ Statistical │ │ Threat Intel │ │
│ │ Engine │ │ Classifier │ │ Engine │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
│ │ │ │ │
│ └────────────────┼─────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Anomaly Scorer │ │
│ └────────┬────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Decision │ → Block / Allow / Log │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Apache-2.0
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
Report security vulnerabilities to security@raskell.io.