Gaunter

Hidden Service Reverse Proxy & Web Application Firewall

Explore the docs »

Benchmarks · Security

Table of Contents

1. Overview
2. Features
3. How It Works
4. Technology Stack
5. Quick Start
6. Configuration
7. Verifying Releases
8. Limitations
9. License

Overview

Gaunter is a reverse proxy with integrated WAF designed for Tor and I2P hidden services, built on Cloudflare's Pingora framework.

Features

Security

• Circuit-Based Rate Limiting — Per-circuit throttling via Tor's PROXY protocol
• WAF Engine — SQLi, XSS, Path Traversal, RFI, SSRF detection using libinjection + Aho-Corasick pattern matching
• No-JS CAPTCHA — Endgame-style interactive CSS challenge, works in Tor Browser "Safest" mode
• Automated Defense — Traffic scoring triggers Defense Mode or Tor PoW based on attack intensity
• Stateless Sessions — XChaCha20-Poly1305 encryption, no database required

Tor & I2P Integration

• Circuit ID Extraction — Via HiddenServiceExportCircuitID haproxy
• Active Monitoring — Uses stem-rs to communicate with Tor Control Port for PoW management and circuit observation
• I2P Support — Built-in i2pd integration

Performance

• Connection Management — Optimized upstream connection reuse via Pingora's built-in pooling
• Compression — Gzip and Brotli support
• Async I/O — Built on Tokio runtime

How It Works

graph LR
    A[Tor Browser] --> B[Tor Daemon]
    B -->|PROXY Protocol| C[Gaunter]
    C -->|Layer 4| D{Rate Limit}
    D -->|Pass| E{WAF Rules}
    E -->|Pass| F[Backend]
    D -->|Block| G[Queue / Challenge]
    E -->|Block| H[400 Response]
    C -->|Defense Mode| I[CAPTCHA Challenge]

1. Ingress: Tor forwards traffic with PROXY header containing circuit ID
2. Layer 4: Connection filtering/dropping for malicious circuits before HTTP parsing
3. Layer 7: WAF rules inspect headers, body, and query parameters
4. Decision: Connection drop (L4), Pass, Challenge (CAPTCHA/PoW), or Block (L7)

Technology Stack

Component	Technology
Core Framework	Pingora
Runtime	Tokio
Tor Daemon	Tor v0.4.9.x
i2pd Daemon	i2pd v2.60.x
Control Protocol	stem-rs
WAF Detection	libinjection, Aho-Corasick, RegexSet
Session Encryption	XChaCha20-Poly1305
Connection Pool	Built-in Pingora Pooling
CAPTCHA	Custom image generation with ab_glyph

Performance

Gaunter is designed for sub-millisecond latency overhead.

Detailed latency metrics for WAF, Rule Engine, and Session management can be found in the Benchmarks Documentation.

Quick Start

Docker (Recommended)

# Pull image (Docker Hub)
docker pull mrmave/gaunter:latest

# Alternative: Pull from my repository
docker pull git.mrmave.work/maverick/gaunter:latest

# Configure
cp docs/.env.example .env
# Edit .env with your settings

# Run
docker compose up -d

Building from Source

Requires Linux. Tor/i2pd are optional but needed for hidden service integration.

# 1. Clone
git clone https://git.mrmave.work/maverick/gaunter.git

# Via Tor
git -c http.proxy=socks5h://127.0.0.1:9050 clone http://mavegitwskioz7tpppmjtj7fn24pwezciii3nvc7kdyltn5iu5uakfqd.onion/gaunter

# 2. Build & Run
cd gaunter
cp docs/.env.example .env
cargo build --release
./target/release/gaunter

Note: Manual Tor/i2pd setup required if running outside Docker.

Configuration

Gaunter is configured via environment variables. See the Configuration Reference for all available options.

cp docs/.env.example .env

Required Variables

Variable	Description
BACKEND_URL	Your upstream application URL
SESSION_SECRET	32-byte hex key (generate)
CAPTCHA_SECRET	Random string for token signing

Tor Setup

Your torrc must enable PROXY protocol:

HiddenServiceDir /var/lib/tor/hidden_service/
HiddenServicePort 80 127.0.0.1:8080
HiddenServiceExportCircuitID haproxy

ControlPort 127.0.0.1:9051
HashedControlPassword 16:YOUR_HASHED_PASSWORD

Generate Tor control password:

tor --hash-password "your_password"

Docker Compose

services:
  gaunter:
    image: mrmave/gaunter:latest
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./tor_keys:/var/lib/tor/hidden_service/
      - ./torrc:/etc/tor/torrc:ro
      - ./i2p_keys:/var/lib/i2pd/

Logging

RUST_LOG=warn           # Production
RUST_LOG=debug          # Development
LOG_FORMAT=json         # Structured output

All security events include: circuit_id, http_method, http_path, action, rule.

Verifying Releases

Detailed information about dependency audits and fuzzing status can be found in the Security Documentation.

Docker Image (Cosign)

wget https://git.mrmave.work/maverick/gaunter/raw/branch/main/certs/cosign.pub
cosign verify --key cosign.pub git.mrmave.work/maverick/gaunter:latest
cosign verify --key cosign.pub mrmave/gaunter:latest

Binary (GPG)

You can download the latest release from the Releases Page.

# Example for v1.0.5
wget https://git.mrmave.work/maverick/gaunter/releases/download/v1.0.5/gaunter-v1.0.5-linux-amd64
wget https://git.mrmave.work/maverick/gaunter/releases/download/v1.0.5/gaunter-v1.0.5-linux-amd64.sha256
wget https://git.mrmave.work/maverick/gaunter/releases/download/v1.0.5/gaunter-v1.0.5-linux-amd64.asc

# Verify using WKD (Web Key Directory)
gpg --locate-keys mail@mrmave.work

# Or import manually
wget https://git.mrmave.work/maverick/gaunter/raw/branch/main/certs/maverick.asc
gpg --import maverick.asc

sha256sum -c gaunter-v1.0.5-linux-amd64.sha256
gpg --verify gaunter-v1.0.5-linux-amd64.asc gaunter-v1.0.5-linux-amd64

Blog post about this project: https://mrmave.work/blog/gaunter

Limitations

• Clustering: Not supported. Designed for single-instance deployment.
• File Uploads: Buffered in memory for inspection. Limits are enforced via MAX_BODY_SIZE.

License

AGPL-3.0