Crate vanguards_rs

Expand description

§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.