Multi-Layered DDoS Mitigation and Access Control for Tor Onion Services
⚠️ PROJECT STATUS: Cerberus is in the planning and design phase. All architecture and specifications are documented. Code implementation begins with Phase 1.
Cerberus is a specialized, defense-in-depth reverse proxy designed exclusively for Tor Onion Services operating in hostile environments. It provides four layers of protection between the Tor network and your backend service, starting with a Layer 0 XDP/eBPF flood shield at the NIC.
Make the cost of being wrong trivial for humans and expensive for bots.
- Humans breeze through: One easy CAPTCHA, quick solve, mistakes forgiven
- Bots drown: Failed attempts trigger escalation → multi-CAPTCHA chains → soft-locks → bans
Real-world impact: A bot needs 38+ days to make 10,000 requests. A human needs seconds.
- L2 (XDP/eBPF - Kernel Shield): Drops abusive packets at the NIC, per-relay rate limiting, SYN/malformed flood protection
- L3/L4 (TC eBPF - Flow Shaper): Stateful relay-aware flow shaping, latency/delay, probabilistic drops, skb marks for L4
- L4 (Kernel TCP Policy): SYN cookies, backlog caps, aggressive cleanup, timeouts
- L4 (HAProxy - Connection Governor): Connection management, circuit reputation tracking, stick tables, HTTP protocol correctness, header limits
- L7 (Protocol Normalization): Path/header normalization, CRLF, canonical Host, parser differential defense (HAProxy/Nginx or Rust filter)
- L7 (Nginx - Gatekeeper): Protocol sanitization, static CAPTCHA delivery, header scrubbing, session/cookie check
- L7 (Nginx ↔ Fortify Isolation): UNIX socket, strict timeouts, memory caps, queue governor
- L7+ (Fortify - Logic & CAPTCHA): Rust application for CAPTCHA verification, threat analysis, adaptive defense, RAM pool (ammo box), queue, passport protocol
Backend .onion secrecy: Only Cerberus nodes know the real backend .onion address, and the backend only allows connections from Cerberus nodes.
- Tor-Native: Leverages Tor's PROXY protocol for per-circuit tracking
- PoW-Enabled: Integrates with Tor's Proof-of-Work defenses
- Zero JavaScript: Works in Tor Browser Safest Mode (100% server-side)
- Privacy-First: No IP logging, no fingerprinting—behavior-based defense only
Goal: Working reverse proxy that serves a static "Hello World" page through all layers (except XDP).
- HAProxy → Nginx → Fortify → Static HTML response
- Verify traffic flows through the complete stack
- No CAPTCHA, no threat detection—just connectivity proof
- Exit Criteria: Tor Browser can reach
hello.htmlthrough your .onion
Goal: Survive volumetric attacks before sockets are allocated.
- XDP program drops excess packets per Tor relay IP
- SYN flood and malformed packet detection
- eBPF maps for relay rate tracking
- Exit Criteria: Machine stays responsive under raw packet flood
Goal: Connection management, circuit tracking, stick tables, and basic observability.
- Parse Tor PROXY protocol for circuit IDs
- Implement rate limiting with stick tables
- Add connection limits per circuit
- Configure slowloris protection (aggressive timeouts)
- Prometheus metrics for all connection events
- Exit Criteria: HAProxy blocks flooding from single circuit, metrics visible
Goal: Protocol sanitization and security headers.
- Header scrubbing (remove fingerprinting vectors)
- Strict CSP and security headers
- Body size limits and timeout tuning
- Static file serving optimization
- Exit Criteria: No leaky headers, clean protocol handling
Goal: First working CAPTCHA gate in Fortify.
- Distorted Text CAPTCHA (single variant)
- Pre-generation pool for fast response
- Constant-time verification
- Basic session token management
- Exit Criteria: CAPTCHA blocks automated requests, passes Tor Browser
Goal: Dynamic defense intensity (1-10 levels).
- Implement threat level state machine
- Automatic escalation based on load metrics
- Per-level CAPTCHA difficulty adjustment
- HAProxy rate limit integration
- Exit Criteria: System auto-escalates during simulated attack
Goal: All 6 CAPTCHA variants with Human-Cost Asymmetry.
| Variant | Description |
|---|---|
| Distorted Text | Warped text with noise overlays |
| Object Recognition | "Click all images containing X" |
| Pattern Completion | "Which image completes this pattern?" |
| Color-Text Mismatch | Color names in wrong colors |
| PoET (Proof-of-Elapsed-Time) | Minimum viewing time (4-8 seconds) |
| Interaction Puzzles | Contextual memory tests |
- Behavioral profiling and soft-lock escalation
- Multi-CAPTCHA chains for suspicious actors
- Exit Criteria: Bots need 38+ days for 10k requests
Goal: Browser-side waiting room with priority lanes.
- Three lanes: VIP (validated), PoW (working), Normal (waiting)
- Client-side PoW puzzle generation
- Server-side PoW verification
- Token-based position management
- Exit Criteria: Queue absorbs 10k connection burst gracefully
Goal: Automated threat classification without fingerprinting.
- Request timing pattern analysis
- Endpoint diversity scoring
- Session behavior tracking
- Soft-lock escalation chains
- Exit Criteria: Bot patterns detected in <5 requests
Goal: Grafana dashboards and operator controls.
- Prometheus metrics export
- Pre-built Grafana dashboards
- Remote Grafana streaming (optional VPS)
- Admin panel for manual overrides
- Exit Criteria: Full visibility into system state
Goal: Multi-node deployment with shared state.
- WireGuard peer-to-peer mesh
- Redis Cluster for shared stick tables
- Each node fully independent (no leader)
- Private network: 10.100.0.0/24
- Exit Criteria: 3-node cluster handles failover
Goal: Monero micropayments for queue fast-pass.
- Monero wallet integration
- Payment verification via RPC
- VIP lane promotion on payment
- Rate-limited to prevent abuse
- Exit Criteria: XMR payment grants instant access
Goal: Security audit and production readiness.
- External security audit
- Load testing (10k+ concurrent)
- Docker/systemd deployment
- Ansible automation playbooks
- Exit Criteria: Production-ready v1.0 release
| Category | Feature | Phase | Status |
|---|---|---|---|
| Core Proxy | HAProxy → Nginx → Fortify chain | 1 | 📋 Planned |
| Core Proxy | Circuit ID tracking (PROXY protocol) | 2 | 📋 Planned |
| Core Proxy | Stick table reputation | 2 | 📋 Planned |
| Security | Header scrubbing & CSP | 3 | 📋 Planned |
| CAPTCHA | Distorted Text variant | 4 | 📋 Planned |
| CAPTCHA | 6 AI-resistant variants | 6 | 📋 Planned |
| CAPTCHA | Human-Cost Asymmetry design | 6 | 📋 Planned |
| Defense | Threat Dial (1-10 levels) | 5 | 📋 Planned |
| Defense | Behavioral profiling | 8 | 📋 Planned |
| Queue | Virtual Queue (3 lanes) | 7 | 📋 Planned |
| Queue | Client-side PoW | 7 | 📋 Planned |
| Monitoring | Grafana dashboards | 9 | 📋 Planned |
| Monitoring | Remote streaming (VPS) | 9 | 📋 Planned |
| Cluster | WireGuard P2P mesh | 10 | 📋 Planned |
| Cluster | Redis Cluster state sync | 10 | 📋 Planned |
| Premium | XMR micropayments | 11 | 📋 Planned |
┌────────────────────────────────────────────────────────────────────────────┐
│ The Internet │
└────────────────────────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────────────────────────┐
│ Tor Network (3 hops) │
└────────────────────────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────────────────────────┐
│ NIC / XDP / eBPF (Flood Shield) │
│ • Drops excess packets per relay IP │
│ • SYN flood/malformed packet detection │
└────────────────────────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────────────────────────┐
│ Kernel TCP Stack │
└────────────────────────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────────────────────────┐
│ Tor Daemon │
│ • Proof-of-Work enabled (HiddenServicePoWDefensesEnabled) │
│ • Vanguards protection │
│ • PROXY protocol (circuit IDs → downstream) │
└────────────────────────────────────────────────────────────────────────────┘
↓ (127.0.0.1:10000)
┌────────────────────────────────────────────────────────────────────────────┐
│ Layer 1: HAProxy (The Shield) │
│ • Connection limits & stick tables │
│ • Circuit reputation tracking │
│ • Rate limiting & slowloris protection │
│ • Prometheus metrics │
└────────────────────────────────────────────────────────────────────────────┘
↓ (127.0.0.1:10001)
┌────────────────────────────────────────────────────────────────────────────┐
│ Layer 2: Nginx (The Filter) │
│ • Static CAPTCHA delivery │
│ • Header scrubbing & CSP │
│ • Protocol sanitization │
└────────────────────────────────────────────────────────────────────────────┘
↓ (127.0.0.1:10002)
┌────────────────────────────────────────────────────────────────────────────┐
│ Layer 3: Fortify (The Keeper) │
│ • CAPTCHA generation & verification │
│ • Threat Dial control │
│ • Behavioral profiling │
│ • Session management │
└────────────────────────────────────────────────────────────────────────────┘
↓
┌────────────────────────────────────────────────────────────────────────────┐
│ Target Backend Service │
└────────────────────────────────────────────────────────────────────────────┘
Defense in Depth: Each layer is optimized for what it does best. L2/L3 (XDP) keeps the box alive, L4 (HAProxy) shapes connections, L7 (Nginx/Fortify) enforces identity and behavior.
All architecture and specifications are complete. Implementation begins with Phase 1: Minimal Viable Proxy.
| Component | Version | Purpose |
|---|---|---|
| OS | Ubuntu 22.04 / Debian 12 | Primary targets |
| Tor | 0.4.8+ | PoW support |
| HAProxy | 2.8+ LTS | Connection management |
| Nginx | 1.26+ | Static delivery |
| Rust | 1.82+ | Fortify application |
| RAM | 2GB (4GB rec.) | All services |
| CPU | 2 cores (4 rec.) | Concurrent handling |
# Phase 1 implementation will provide:
git clone https://github.com/Nespartious/Cerberus.git
cd Cerberus
./deploy/cerberus.sh install
./deploy/cerberus.sh startCore Documentation:
- Master Architecture: Complete system design and philosophy
- Project Scaffold: Folder structure and project organization
- Instructions: Security gotchas, Tor best practices, roles, user stories, and development workflow
Defense Layers (0100-series):
- XDP/eBPF Layer: NIC-level flood shield, per-relay rate limiting
- TC eBPF Flow Shaping: Stateful relay-aware flow shaping, latency/delay, skb marks
- Kernel TCP Tuning: SYN cookies, backlog caps, timeouts
- HAProxy Layer: Connection management and circuit tracking
- HAProxy HTTP Gate: HTTP protocol correctness, header limits
- Protocol Normalization: Path/header normalization, CRLF, canonical Host
- Nginx Layer: Protocol sanitization and static delivery
- Nginx ↔ Fortify Isolation: UNIX socket, timeouts, memory caps, queue governor
- Fortify Layer: Rust application logic and CAPTCHA system Security & Threat Modeling (0200-series):
- Threat Model: Practical and STRIDE threat models for Cerberus
- Attack Kill Table: What dies at which layer, mapped to Cerberus stack
See docs/0205-attack-kill-table.md for the full table.
| Attack Type | XDP | TC eBPF | Kernel TCP | HAProxy | Nginx | Fortify |
|---|---|---|---|---|---|---|
| Packet flood | ✅ | — | — | — | — | — |
| SYN flood | ✅ | ✅ | ✅ | — | — | — |
| TCP exhaustion | — | ✅ | ✅ | ✅ | — | — |
| Connection churn | — | ✅ | — | ✅ | — | — |
| Slowloris | — | — | — | ✅ | ✅ | — |
| HTTP floods | — | — | — | ✅ | ✅ | — |
| Malformed HTTP | — | — | — | — | ✅ | — |
| CAPTCHA bypass | — | — | — | — | — | ✅ |
| Bot navigation | — | — | — | — | — | ✅ |
| CAPTCHA farms | — | — | — | — | — | |
| Human users | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Legend: ✅ = attack dies here,
See docs/0204-threat-model.md for both practical and STRIDE threat models.
Assets: Backend onion service, host CPU/memory, Tor intro capacity, human access Adversaries: Script kiddies, botnets, Tor-aware attackers, well-funded adversaries Trust Boundaries: Untrusted → XDP → TC eBPF → Kernel TCP → HAProxy → Nginx → Fortify → Backend Design Invariants: No layer assumes previous succeeded; each layer validates, caps, fails closed
Defense Features (0200-series):
- Virtual Queue System: Browser-side waiting room with PoW priority
- Threat Dial System: Dynamic defense intensity control
- XMR Priority System: Monero payment-based queue fast-pass
- Advanced CAPTCHA System: AI-resistant image CAPTCHAs with multiple variants
Operations (0300-series):
- Monitoring & UI: Grafana dashboards, admin panel, metrics
- Vanity Onion Generation: mkp224o integration for branded addresses
Cluster & Scaling (0500-series):
- Cluster System: Multi-node deployment with shared state and load distribution
Infrastructure (0400-series):
- Dependencies Audit: Version matrix and compatibility
- CI/CD Workflows: Automated checks and code review standards
- Development Environment: Cross-platform development setup (Windows + Ubuntu VM)
- High-Value Tor Onion Services (marketplaces, forums, whistleblower platforms)
- Services expecting constant DDoS (circuit-based defense, not IP-based)
- Privacy-first operations (no fingerprinting, no JavaScript requirements)
- Security researchers (testing Tor infrastructure defenses)
- Clearnet websites (use Cloudflare instead)
- Low-traffic personal sites (overkill)
- Rich JavaScript applications (Cerberus prioritizes NoJS)
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-defense) - Write tests for your changes
- Ensure all tests pass (
cargo test, integration tests, Tor Browser tests) - Commit with clear messages (
git commit -m 'Add circuit clustering detection') - Push to your fork (
git push origin feature/amazing-defense) - Open a Pull Request with detailed description
- ✅ All CI/CD checks pass (security audit, lint, tests)
- ✅ At least one maintainer approval
- ✅ No security vulnerabilities introduced
- ✅ Documentation updated (if user-facing changes)
- ✅ Tested in Tor Browser (Safest + Standard modes)
DO NOT open public issues for security vulnerabilities.
- Security Contact: TBD (will be announced with v1.0 release)
- Non-Security Issues: Use GitHub Issues
We follow responsible disclosure and will credit researchers in our security advisories.
- Last Audit: Pending (project in active development)
- Audit Scope: Full stack (Tor, HAProxy, Nginx, Fortify)
- Bug Bounty: Planned (post-v1.0 release)
| Metric | Target | Rationale |
|---|---|---|
| Concurrent Connections | 10,000 | HAProxy + kernel tuning |
| CAPTCHA Generation | <100ms | Pre-generation pool |
| CAPTCHA Verification | <10ms | Constant-time comparison |
| Static Page Delivery | <5ms | Nginx direct serve |
| Circuit Ban Latency | <50ms | Stick table update |
| Memory (all services) | ~100MB | Lean deployment |
- Master architecture design (including XDP/eBPF Layer 0)
- 17 planning documents
- User stories for all features
- CI/CD workflow specifications
- Security guidelines and Tor best practices
- Project structure setup
- HAProxy basic configuration
- Nginx pass-through
- Fortify "Hello World" response
- End-to-end connectivity test
- Circuit tracking and stick tables
- Header scrubbing and CSP
- CAPTCHA system (all 6 variants)
- Threat Dial implementation
- Virtual Queue with PoW
- Behavioral profiling
- Monitoring dashboards
- WireGuard cluster mesh
- XMR priority payments
- Security audit and v1.0 release
MIT License - Free and Open Source
Copyright (c) 2025 Cerberus Project
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- The Tor Project for building the foundation of anonymous communication
- HAProxy Team for the most robust load balancer/firewall
- Nginx Team for high-performance web serving
- Rust Community for a secure systems programming language
- Vanguards Developers for protecting onion services from advanced attacks
- GitHub: https://github.com/Nespartious/Cerberus
- Issues: Report bugs or request features
- Discussions: Project discussions
Cerberus is designed to protect legitimate Tor Onion Services from abuse. Users are responsible for ensuring their use of this software complies with applicable laws and regulations. The developers of Cerberus do not condone illegal activity and provide this software for defensive security purposes only.
Remember: Operating a Tor Onion Service comes with responsibilities. Understand your threat model, follow best practices, and respect user privacy.
Designing the future of Tor Onion Service defense.
A work in progress for the Tor community 🛡️