Struct Vanguards 

pub struct Vanguards { /* private fields */ }

Main vanguards manager combining all protection components.

This struct provides a high-level interface for running vanguards protection on a Tor hidden service. It manages the complete lifecycle of protection, from initialization through event processing.

Managed Components

The Vanguards struct orchestrates these protection components:

Component	Purpose	Config Flag
Vanguard State	Layer 2/3 guard selection	enable_vanguards
Bandguards	Bandwidth attack detection	enable_bandguards
Rendguard	Rendezvous point monitoring	enable_rendguard
Logguard	Tor log monitoring	enable_logguard
CBT Verify	Circuit timeout verification	enable_cbtverify
Path Verify	Circuit path verification	enable_pathverify

Lifecycle

┌─────────────────┐
│  from_config()  │ ◄── Load config, create state
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     run()       │ ◄── Connect to Tor, start event loop
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Event Loop     │ ◄── Process events until shutdown
│  (control.rs)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Cleanup      │ ◄── Save state, close connection
└─────────────────┘

Thread Safety

Vanguards is Send but not Sync. For concurrent access:

use std::sync::Arc;
use tokio::sync::Mutex;
use vanguards_rs::{Config, Vanguards};

let vanguards = Vanguards::from_config(Config::default()).await?;
let shared = Arc::new(Mutex::new(vanguards));

Example

Basic Usage

use vanguards_rs::{Config, Vanguards};

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

Inspecting State

use vanguards_rs::{Config, Vanguards};

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let config = Config::default();
    let vanguards = Vanguards::from_config(config).await?;
     
    // Access current state
    let state = vanguards.state();
    println!("Layer2 guards: {}", state.layer2_guardset());
    println!("Layer3 guards: {}", state.layer3_guardset());
     
    // Access configuration
    let config = vanguards.config();
    println!("Vanguards enabled: {}", config.enable_vanguards);
    Ok(())
}

Security Considerations

• Passwords are cleared from memory after authentication
• State files are written with restrictive permissions (0600 on Unix)
• All external inputs are validated before use
• Guard selections persist across restarts to prevent discovery attacks

See Also

• Config - Configuration options
• VanguardState - Guard state details
• SecurePassword - Secure password handling
• control::run_main - Event loop implementation

Implementations

impl Vanguards

pub fn new(_controller: Controller, config: Config) -> Result<Self>

Creates a new Vanguards instance from an existing controller and configuration.

This method is useful when you already have a connected and authenticated controller.

Arguments

• controller - An authenticated Tor controller
• config - The vanguards configuration

Errors

Returns an error if state loading fails.

Example

use vanguards_rs::{Config, Vanguards};
use stem_rs::controller::Controller;

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let mut controller = Controller::from_port("127.0.0.1:9051".parse().unwrap()).await?;
    controller.authenticate(None).await?;
     
    let config = Config::default();
    let vanguards = Vanguards::new(controller, config)?;
    Ok(())
}

pub async fn from_config(config: Config) -> Result<Self>

Creates a new Vanguards instance by connecting to Tor.

This method handles connection, authentication, and state initialization. The password (if provided) is securely cleared from memory after use.

Arguments

• config - The vanguards configuration

Errors

Returns an error if:

• Connection to Tor fails
• Authentication fails
• State loading fails

Example

use vanguards_rs::{Config, Vanguards};

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let config = Config::default();
    let vanguards = Vanguards::from_config(config).await?;
    Ok(())
}

pub async fn run(&mut self) -> Result<()>

Runs the main vanguards protection loop.

This method connects to Tor, authenticates, initializes protection components, and processes events until the connection is closed or an error occurs.

Errors

Returns an error if the protection loop fails.

Example

use vanguards_rs::{Config, Vanguards};

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

pub fn state(&self) -> &VanguardState

Returns a reference to the current vanguard state.

Example

use vanguards_rs::{Config, Vanguards};

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let config = Config::default();
    let vanguards = Vanguards::from_config(config).await?;
     
    let state = vanguards.state();
    println!("Layer2 guards: {}", state.layer2_guardset());
    println!("Layer3 guards: {}", state.layer3_guardset());
    Ok(())
}

pub fn config(&self) -> &Config

Returns a reference to the current configuration.

Example

use vanguards_rs::{Config, Vanguards};

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let config = Config::default();
    let vanguards = Vanguards::from_config(config).await?;
     
    let config = vanguards.config();
    println!("Vanguards enabled: {}", config.enable_vanguards);
    Ok(())
}