Proxy with MITM support and a simple DSL Rule engine
1.0K
High-performance forward HTTP/S proxy with MITM TLS support, built on Hudsucker.
Roxy combines ACL filtering, header mangling, rate limiting, and TLS inspection with a custom rule DSL—designed for scenarios where you need to inspect and control HTTPS traffic (e.g., blocking requests missing required headers).
docker pull adsanz/roxy:latest
cargo build --release
# Run with a config file
docker run -v $(pwd)/config.yaml:/etc/roxy/config.yaml -p 8080:8080 adsanz/roxy:latest
# With TLS certificates for MITM
docker run \
-v $(pwd)/config.yaml:/etc/roxy/config.yaml:ro \
-v $(pwd)/certs:/etc/roxy/certs:ro \
-p 8080:8080 \
adsanz/roxy:latest
services:
roxy:
image: adsanz/roxy:latest
ports:
- "8080:8080"
volumes:
- ./config.yaml:/etc/roxy/config.yaml:ro
# - ./certs:/etc/roxy/certs:ro # For MITM TLS
restart: unless-stopped
# Run with a config file
./target/release/roxy --config config.yaml
# The proxy will start on the configured listen address (default: 127.0.0.1:8080)
Roxy can operate in two modes:
Ephemeral CA (default) - Generates a temporary CA certificate on startup. Useful for testing.
Persistent CA - Provide your own CA certificate and key in the config. Required for production use where clients need to trust the CA.
Generate CA certificates:
# Generate CA private key
openssl genrsa -out ca.key 4096
# Generate CA certificate
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \
-subj "/CN=Roxy Proxy CA/O=Roxy/C=US"
Roxy uses YAML configuration files. Here's a complete example:
# Proxy server settings
listen: "0.0.0.0:8080"
# TLS settings (optional - uses ephemeral CA if omitted)
tls:
ca_cert: "/path/to/ca.crt"
ca_key: "/path/to/ca.key"
# Rule definitions (evaluated in order - first match wins!)
rules:
# Allow health checks without further processing
- name: "allow-healthcheck"
rule: 'path("/health") && method(GET) = pass'
# Allow payment endpoint
- name: "allow-payment"
rule: 'method(POST) && path("/payment") = pass'
# Require authentication header for API requests
- name: "require-auth"
rule: 'host("api.example.com") && !header("X-Auth-Token") = block : pass'
# Rate limit API requests by customer ID
- name: "rate-limit-api"
rule: 'host("api.*") && path("/v1/*") = rate_limit(100/s, header(X-Customer-Id))'
# Mark requests for header modification
- name: "add-trace-headers"
rule: 'host("backend.*") = mangle'
# Block everything else (catch-all - MUST be last!)
- name: "block-all"
rule: 'host("*") = block'
# Header modification rules
headers:
- rules: ["add-trace-headers"] # Apply when these rules trigger mangle action
add:
- name: "X-Proxy-Processed"
value: "true"
- name: "X-Forwarded-By"
value: "roxy"
remove:
- "X-Internal-Only"
- "X-Debug-Info"
Rules are evaluated in the exact order they appear in the config file (first-match-wins).
This is critical for writing correct rules. The proxy stops evaluating rules as soon as one matches and returns an action. To implement allow-list patterns:
rules:
# 1. Specific allows FIRST
- name: "allow-health"
rule: 'path("/health") = pass'
- name: "allow-payment"
rule: 'path("/payment") = pass'
# 2. Catch-all block LAST
- name: "block-all"
rule: 'host("*") = block'
With this config:
GET /health → matches rule 1 → pass (stops here)POST /payment → matches rule 2 → pass (stops here)GET /anything-else → matches rule 3 → block⚠️ Common mistake: Putting the catch-all block first would block everything!
Matchers:
| Matcher | Description | Example |
|---|---|---|
host("pattern") | Match request host | host("*.example.com") |
path("pattern") | Match request path | path("/api/v1/*") |
method(M) | Match HTTP method | method(GET), method(POST) |
header("name") | Check header exists | header("Authorization") |
header("name:value") | Match header value | header("X-Version:v2") |
Operators:
| Operator | Description | Example |
|---|---|---|
&& | Logical AND | host("*") && method(GET) |
|| | Logical OR | path("/a") || path("/b") |
! | Logical NOT | !header("X-Auth") |
() | Grouping | (host("a") || host("b")) && method(POST) |
Actions:
| Action | Description |
|---|---|
pass | Allow request, stop rule evaluation |
block | Deny request with 403 Forbidden |
mangle | Allow request, trigger header modifications |
rate_limit(N/s, key) | Apply rate limiting |
Ternary syntax: condition = action_if_true : action_if_false
Rate limit keys determine how requests are grouped:
# Single key - limit by header value
rate_limit(100/s, header(X-Customer-Id))
# Composite key - limit by combination
rate_limit(50/s, header(X-Customer-Id) + path(*) + host(*))
# Available key sources: header(Name), path(*), host(*), client_ip(*)
Request → [TLS Intercept] → [Parse] → [ACL] → [RateLimit] → [Mangle] → [Forward] → Response
| Module | Responsibility | Key Types |
|---|---|---|
config/ | YAML config parsing | ProxyConfig, RuleConfig |
rules/ | DSL parsing (nom) + method-indexed evaluation | Expr, Action, RuleIndex |
ratelimit/ | Sliding window rate limiting | RateLimiter, SlidingWindow |
proxy/ | Hudsucker HttpHandler implementation | RoxyHandler |
error.rs | Unified error types | RoxyError |
| Crate | Purpose |
|---|---|
| hudsucker | MITM HTTP/S proxy framework with TLS interception |
| nom | Zero-copy parser combinators for the rule DSL |
| globset | Pre-compiled glob pattern matching |
| dashmap | Concurrent hashmap for rate limit storage |
| tokio | Async runtime |
| tracing | Structured logging |
Method-Indexed Rules - Rules are indexed by Option<Method> for O(1) lookup. Rules without a method matcher go in the None bucket and are always evaluated.
Pre-compiled Globs - Glob patterns are compiled to GlobMatcher at config load time, not per-request.
Sliding Window Rate Limiting - Uses a time-bucketed sliding window algorithm stored in DashMap for lock-free concurrent access.
Error Layering - Each layer defines its own error type. Lower layers report what failed; upper layers decide HTTP status codes.
Run the test suite:
# Run all tests
cargo test
# Run tests with output
cargo test -- --nocapture
# Run specific test module
cargo test rules::parser
cargo test ratelimit
src/rules/parser.rs) - DSL syntax parsingsrc/rules/ast.rs) - Expression evaluation logicsrc/rules/engine.rs) - Rule matching with mock requestssrc/ratelimit/limiter.rs) - Sliding window edge casessrc/config/types.rs) - YAML parsing and validationsrc/proxy/handler.rs) - Request processingBenchmarks measure rule parsing and evaluation throughput across different complexity levels and rule counts.
# Run all benchmarks
cargo bench
# Run specific benchmark group
cargo bench -- "rule_parsing"
cargo bench -- "rule_evaluation"
cargo bench -- "bulk_evaluation"
cargo bench -- "rate_limiter"
# Run benchmarks for specific complexity
cargo bench -- "Complex"
cargo bench -- "rule_evaluation/Medium"
# Run with specific rule count
cargo bench -- "/500"
| Group | Description |
|---|---|
rule_parsing | Time to parse rules from config into RuleIndex |
rule_evaluation | Single request evaluation against rule set |
bulk_evaluation | 1000 diverse requests against rule set |
mangle_evaluation | Collecting mangle rules for header modification |
rate_limiter | Rate limiter check throughput |
host("example.com") = passhost("*.api") && method(GET) = pass(host("*") && !header("X-Block")) || method(POST) = block : passrule_parsing/Simple/100 time: [5.5 ms] thrpt: [18.0 Kelem/s]
rule_parsing/Complex/100 time: [12.3 ms] thrpt: [8.1 Kelem/s]
rule_evaluation/Simple/1000/match_early time: [245 ns]
rule_evaluation/Complex/1000/no_match time: [1.2 µs]
bulk_evaluation/Medium_rules_200 thrpt: [1.8 Melem/s]
Roxy uses structured JSON logging via tracing. Set log level with RUST_LOG:
# Info level (default) - forwarded requests and actions
RUST_LOG=info ./target/release/roxy --config config.yaml
# Debug level - rule evaluation details
RUST_LOG=debug ./target/release/roxy --config config.yaml
# Trace specific modules
RUST_LOG=roxy::rules=debug,roxy::proxy=info ./target/release/roxy --config config.yaml
MIT
Content type
Image
Digest
sha256:79bade0bd…
Size
13.4 MB
Last updated
6 months ago
docker pull adsanz/roxy