🦀 Built with Rust

vanguards-rs

Protect Tor onion services from deanonymization with persistent vanguard relay selection.

$ cargo install vanguards-rs && vanguards-rs

Get Started Documentation GitHub

Components

Async

Tokio Runtime

100%

Python Parity

🚀 Get Started

Quick Start

Protect your onion service in under a minute.

Enable Tor Control Port

Add these lines to your torrc configuration file:

ControlPort 9051
CookieAuthentication 1
DataDirectory /var/lib/tor

Or use Unix socket: ControlSocket /run/tor/control

Install vanguards-rs

Install via Cargo from crates.io:

$ cargo install vanguards-rs

Requires Rust 1.70+ and Tokio runtime

Run Protection

Start vanguards-rs alongside your Tor instance:

$ vanguards-rs

✓ Your onion service is now protected against guard discovery attacks.

🛡️ Security

What it protects against

Multiple layers of defense against sophisticated attacks targeting Tor hidden services.

🔒

Guard Discovery Attacks

Persistent vanguard relays at Layer 2 (4-8 relays, 1-45 day lifetime) and Layer 3 (4-8 relays, 1-48 hour lifetime) prevent attackers from identifying your entry guards through circuit manipulation and timing analysis.

Bandwidth-weighted selection Automatic rotation State persistence

📊

Bandwidth Side-Channels

Monitors circuit traffic patterns to detect side-channel attacks. Enforces configurable limits on circuit size (MB threshold), circuit age (default 24h), and HSDIR descriptor sizes (30KB default) to prevent fingerprinting.

Circuit size limits Age monitoring Disconnection warnings

🎯

Rendezvous Point Overuse

Statistical detection of rendezvous point manipulation. Tracks per-relay usage against bandwidth-weighted expected values. Automatically closes circuits when usage exceeds configurable thresholds (default 5x expected ratio).

Usage tracking Statistical analysis Auto circuit closure

📝

Protocol Warning Detection

Monitors Tor logs for security-relevant events and protocol warnings that may indicate attack attempts. Configurable log buffering with security event alerting for real-time threat awareness.

Log monitoring Event alerting Configurable buffering

⏱️

Circuit Build Timeout Verification

Verifies circuit construction timing to detect manipulation attempts. Tracks circuit build times and identifies anomalous patterns that may indicate an attacker trying to influence path selection.

Build time tracking Pattern detection Optional component

🔍

Circuit Path Verification

Verifies that circuit paths conform to vanguard configuration. Ensures guards are used correctly at each layer and detects any path manipulation attempts that bypass vanguard protections.

Guard verification Path validation Optional component

⚡ Command Line

CLI Reference

Full control over vanguards-rs from the command line.

🔌 Connection Options

--control-ip <IP> Tor control IP address (default: 127.0.0.1)

--control-port <PORT> Tor control port (default: 9051)

--control-socket <PATH> Unix socket path (alternative to TCP)

--control-pass <PASS> Control port password (if using password auth)

📁 File Options

--config <FILE> Load configuration from TOML file

--state <FILE> Vanguard state file path (default: vanguards.state)

--generate_config <FILE> Generate default config file and exit

--logfile <FILE> Write logs to file instead of stdout

🎛️ Component Control

--disable-vanguards Disable vanguard layer protection

--disable-bandguards Disable bandwidth monitoring

--disable-rendguard Disable rendezvous point analysis

--disable-logguard Disable Tor log monitoring

--enable-cbtverify Enable circuit build timeout verification

--enable-pathverify Enable circuit path verification

⚙️ Operation Modes

--one-shot-vanguards Set vanguards once and exit immediately

--loglevel <LEVEL> Log verbosity: debug, info, notice, warn, error

--close-circuits Close suspicious circuits (default: true)

📋 Example Commands

# Basic usage with default settings
$ vanguards-rs

# Connect via Unix socket with debug logging
$ vanguards-rs --control-socket /run/tor/control --loglevel debug

# Use custom config and state files
$ vanguards-rs --config /etc/vanguards/vanguards.conf \
    --state /var/lib/tor/vanguards.state

# Enable all optional security components
$ vanguards-rs --enable-cbtverify --enable-pathverify

# One-shot mode for systemd integration
$ vanguards-rs --one-shot-vanguards --logfile /var/log/vanguards.log

⚙️ Settings

Configuration

Fine-tune protection with TOML config files. Configuration precedence: CLI args → Environment variables → Config file → Defaults.

📡 Connection & Logging

# vanguards.conf
control_ip = "127.0.0.1"
control_port = 9051
# control_socket = "/run/tor/control"
# control_pass = "my_password"

state_file = "vanguards.state"
loglevel = "notice"
# logfile = "/var/log/vanguards.log"

🎛️ Component Toggles

# Enable/disable components
enable_vanguards = true
enable_bandguards = true
enable_rendguard = true
enable_logguard = true
enable_cbtverify = false
enable_pathverify = false

# Operational settings
close_circuits = true
one_shot_vanguards = false

🛡️ Vanguard Settings

[vanguards]
num_layer1_guards = 2
num_layer2_guards = 4
num_layer3_guards = 8

# Layer 2: 1-45 days
min_layer2_lifetime_hours = 24
max_layer2_lifetime_hours = 1080

# Layer 3: 1-48 hours
min_layer3_lifetime_hours = 1
max_layer3_lifetime_hours = 48

📊 Bandguards Settings

[bandguards]
circ_max_megabytes = 0
circ_max_age_hours = 24
circ_max_hsdesc_kilobytes = 30
circ_max_disconnected_secs = 30
conn_max_disconnected_secs = 15

[rendguard]
use_global_start_count = 1000
use_scale_at_count = 20000
use_relay_start_count = 100
use_max_use_to_bw_ratio = 5.0