Crate vanguards_rs 

vanguards-rs

A Rust implementation of the Python vanguards library for enhanced Tor hidden service security.

Overview

vanguards-rs provides protection against guard discovery attacks through persistent vanguard relay selection, and additional protections through multiple security components:

• Vanguard Selection (vanguards): Persistent layer2/layer3 guard selection
• Bandwidth Monitoring (bandguards): Detect bandwidth-based side-channel attacks
• Rendezvous Point Analysis (rendguard): Detect statistical attacks on rendezvous points
• Log Monitoring (logguard): Monitor Tor logs for security-relevant events
• Circuit Build Timeout Verification (cbtverify): Verify circuit construction timing
• Path Verification (pathverify): Verify circuit paths conform to vanguard configuration

Module Overview

Module	Purpose
api	High-level Vanguards struct for programmatic use
config	Configuration management (TOML, CLI, environment)
error	Error types and Result alias
control	Main event loop and Tor connection management
vanguards	Vanguard state and guard selection
bandguards	Bandwidth monitoring and attack detection
rendguard	Rendezvous point usage tracking
logguard	Tor log monitoring and buffering
cbtverify	Circuit build timeout verification
pathverify	Circuit path verification
node_selection	Bandwidth-weighted relay selection
logger	Logging infrastructure using tracing

What This Library Does NOT Do

• Direct relay communication: Use [stem_rs::client] for ORPort connections
• Descriptor parsing: Use [stem_rs::descriptor] module
• Exit policy evaluation: Use [stem_rs::exit_policy]
• Running a Tor relay: This library protects hidden services, not relays
• Onion service creation: Use Tor’s ADD_ONION command via stem-rs

Quick Start

As a Library

use vanguards_rs::{Config, Vanguards};

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    // Load configuration
    let config = Config::default();
     
    // Create and run vanguards protection
    let mut vanguards = Vanguards::from_config(config).await?;
    vanguards.run().await
}

As a CLI Application

# Run with default settings
vanguards-rs

# Connect to specific control port
vanguards-rs --control-ip 127.0.0.1 --control-port 9051

# Use Unix socket with custom state file
vanguards-rs --control-socket /run/tor/control --state /var/lib/tor/vanguards.state

# Generate default configuration file
vanguards-rs --generate_config vanguards.conf

Configuration

Configuration can be loaded from multiple sources in order of precedence:

┌─────────────────┐
│   CLI Arguments │ ◄── Highest priority (overrides all)
└────────┬────────┘
         │
┌────────▼────────┐
│   Environment   │ ◄── VANGUARDS_STATE, VANGUARDS_CONFIG
│    Variables    │
└────────┬────────┘
         │
┌────────▼────────┐
│   Config File   │ ◄── TOML file (default: vanguards.conf)
│     (TOML)      │
└────────┬────────┘
         │
┌────────▼────────┐
│    Defaults     │ ◄── Sensible defaults for all options
└─────────────────┘

See Config for all available options.

State File Compatibility

State files are compatible with Python vanguards for seamless migration. The library reads and writes Python pickle format state files, allowing you to switch between Python vanguards and vanguards-rs without losing your guard selections.

Security Considerations

• Memory Safety: Passwords are cleared from memory after use (using zeroize)
• File Permissions: State files are written with restrictive permissions (0600)
• Input Validation: All external inputs are validated before use
• Error Handling: Error messages do not leak sensitive information
• Guard Persistence: Vanguard selections persist across restarts to prevent guard discovery through restart attacks

See Also

• Python vanguards - Original Python implementation
• stem-rs documentation - Tor control library used by vanguards-rs
• Tor Control Protocol Specification - Protocol reference
• Vanguards Specification - Tor proposal 292
• Guard Discovery Attacks - Academic paper on the attacks vanguards mitigates

Re-exports

pub use api::SecurePassword;

pub use api::Vanguards;

pub use bandguards::BandwidthStats;

pub use bandguards::BwCircuitStat;

pub use bandguards::BwGuardStat;

pub use bandguards::CircuitLimitResult;

pub use bandguards::ConnectivityStatus;

pub use bandguards::CELL_PAYLOAD_SIZE;

pub use bandguards::MAX_CIRC_DESTROY_LAG_SECS;

pub use bandguards::RELAY_HEADER_SIZE;

pub use bandguards::RELAY_PAYLOAD_SIZE;

pub use cbtverify::CircuitStat;

pub use cbtverify::TimeoutStats;

pub use config::BandguardsConfig;

pub use config::CliArgs;

pub use config::Config;

pub use config::LogLevel;

pub use config::LogguardConfig;

pub use config::RendguardConfig;

pub use config::VanguardsConfig;

pub use error::Error;

pub use error::Result;

pub use logguard::LogEntry;

pub use logguard::LogGuard;

pub use node_selection::is_valid_country_code;

pub use node_selection::is_valid_fingerprint;

pub use node_selection::is_valid_ip_or_network;

pub use node_selection::BwWeightedGenerator;

pub use node_selection::FlagsRestriction;

pub use node_selection::NodeRestriction;

pub use node_selection::NodeRestrictionList;

pub use node_selection::Position;

pub use pathverify::Layer1Guards;

pub use pathverify::Layer1Stats;

pub use pathverify::PathVerify;

pub use pathverify::ROUTELEN_FOR_PURPOSE;

pub use pathverify::ROUTELEN_FOR_PURPOSE_LITE;

pub use rendguard::RendCheckResult;

pub use rendguard::NOT_IN_CONSENSUS_ID;

pub use vanguards::ExcludeNodes;

pub use vanguards::GuardNode;

pub use vanguards::RendGuard;

pub use vanguards::RendUseCount;

pub use vanguards::VanguardState;

pub use control::authenticate_any;

pub use control::configure_tor;

pub use control::control_loop;

pub use control::get_close_circuits;

pub use control::get_consensus_weights;

pub use control::new_consensus_event;

pub use control::run_main;

pub use control::set_close_circuits;

pub use control::signal_event;

pub use control::try_close_circuit;

pub use control::AppState;

pub use control::VERSION;

Modules

api

High-level API for vanguards-rs.

bandguards

Bandwidth monitoring for detecting side-channel attacks.

cbtverify

Circuit Build Timeout verification for monitoring circuit construction timing.

config

Configuration management for vanguards-rs.

control

Control module for Tor controller interaction and main application loop.

error

Error types for vanguards-rs.

logger

Logging infrastructure for vanguards-rs.

logguard

Log monitoring for attacks, protocol issues, and debugging.

node_selection

Node selection and input validation for vanguards-rs.

pathverify

Path verification for ensuring circuits use configured vanguards.

rendguard

Rendezvous point monitoring for detecting statistical attacks.

vanguards

Vanguard state management and ExcludeNodes parsing.

Macros

plog_fmt

Log a formatted message at the specified level.