Expand description
Bandwidth monitoring for detecting side-channel attacks.
This module provides protection against bandwidth-based side-channel attacks by monitoring circuit bandwidth usage and detecting anomalies.
§Overview
The bandguards system monitors:
- Circuit bandwidth: Read/written bytes per circuit
- Dropped cells: Cells received but not delivered (potential attack indicator)
- Circuit age: Old circuits that may be vulnerable
- Guard connections: Connection state and closure correlation
§Circuit State Diagram
Circuits progress through the following states, with bandwidth monitoring at each stage:
┌─────────────────────────────────────────────────────────────────────────┐
│ Circuit State Transitions │
│ │
│ ┌─────────────┐ │
│ │ LAUNCHED │ │
│ │ (created) │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ EXTENDED │◀────────┐ │
│ │ (building) │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
│ ┌───────────┼───────────┐ │ │
│ │ │ │ │ │
│ ▼ ▼ ▼ │ │
│ ┌───────────┐ ┌─────────┐ ┌────────┴───┐ │
│ │ BUILT │ │ FAILED │ │ GUARD_WAIT │ │
│ │ (active) │ │ │ │ │ │
│ └─────┬─────┘ └────┬────┘ └────────────┘ │
│ │ │ │
│ ┌──────────────┼────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌─────────────┐ │
│ │ │ Bandwidth │ │
│ │ │ Monitoring │ │
│ │ │ (CIRC_BW) │ │
│ │ └──────┬──────┘ │
│ │ │ │
│ │ ┌─────────┼─────────┐ │
│ │ │ │ │ │
│ │ ▼ ▼ ▼ │
│ │ ┌──────┐ ┌──────┐ ┌──────────┐ │
│ │ │Normal│ │Attack│ │Tor Bug │ │
│ │ │ │ │Detect│ │Workaround│ │
│ │ └──┬───┘ └──┬───┘ └────┬─────┘ │
│ │ │ │ │ │
│ │ │ ▼ │ │
│ │ │ ┌─────────┐ │ │
│ │ │ │ CLOSE │ │ │
│ │ │ │ CIRCUIT │ │ │
│ │ │ └─────────┘ │ │
│ │ │ │ │
│ └────┼───────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ CLOSED │ │
│ │ (cleanup) │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘§Attack Detection
Several attack vectors are detected and mitigated:
┌─────────────────────────────────────────────────────────────────────────┐
│ Attack Detection Matrix │
│ │
│ Attack Type │ Detection Method │ Response │
│ ─────────────────────┼─────────────────────────┼───────────────────────│
│ Dropped Cells │ read - delivered ≠ 0 │ Close circuit │
│ Excessive Bandwidth │ bytes > max_megabytes │ Close circuit │
│ HSDIR Abuse │ hsdir bytes > limit │ Close circuit │
│ Intro Abuse │ intro bytes > limit │ Close circuit │
│ Old Circuits │ age > max_age_hours │ Close circuit │
│ Guard Conn Kill │ conn close + circ fail │ Log warning │
│ Network Disconnect │ no conns for N secs │ Log warning │
└─────────────────────────────────────────────────────────────────────────┘§Dropped Cell Detection
Dropped cells indicate cells that were received but not delivered to the application. This can indicate a tagging attack or protocol manipulation.
Formula: dropped = read_bytes / CELL_PAYLOAD_SIZE
- (delivered_read + overhead_read) / RELAY_PAYLOAD_SIZE
Where:
CELL_PAYLOAD_SIZE = 509 bytes
RELAY_PAYLOAD_SIZE = 498 bytes (509 - 11 byte header)§Tor Bug Workarounds
This module includes workarounds for known Tor bugs that can cause false positive dropped cell detection:
| Bug ID | Description | Affected Circuits |
|---|---|---|
| #29699 | Intro circuits get duped cells on retries | HS_SERVICE_INTRO |
| #29700 | Service rend circuits fail ntor handshake | HS_SERVICE_REND |
| #29786 | Path bias circuits have dropped cell cases | PATH_BIAS_TESTING |
| #29927 | Client-side dropped cells and protocol errors | HS_CLIENT_* |
| #40359 | Client intro circuits with dropped cells | CIRCUIT_PADDING |
§What This Module Does NOT Do
- Circuit creation: Use Tor’s circuit building
- Guard selection: Use
crate::vanguardsfor guard management - Rendezvous monitoring: Use
crate::rendguardfor RP tracking
§Example
use vanguards_rs::bandguards::{BandwidthStats, CircuitLimitResult};
use vanguards_rs::config::BandguardsConfig;
let mut stats = BandwidthStats::new();
let config = BandguardsConfig::default();
// Process circuit events
stats.circ_event("123", "LAUNCHED", "HS_SERVICE_REND",
Some("HSSR_CONNECTING"), &[], None, 1000.0);
stats.circ_event("123", "BUILT", "HS_SERVICE_REND",
Some("HSSR_CONNECTING"), &["A".repeat(40)], None, 1001.0);
// Process bandwidth events
stats.circbw_event("123", 1000, 500, 800, 400, 100, 50, 1002.0);
// Check for attacks
match stats.check_circuit_limits("123", &config) {
CircuitLimitResult::Ok => println!("Circuit OK"),
CircuitLimitResult::DroppedCells { dropped_cells } => {
println!("Attack detected: {} dropped cells", dropped_cells);
}
_ => {}
}§Security Considerations
- Dropped cell detection may have false positives due to Tor bugs
- Configure appropriate thresholds for your threat model
- Monitor logs for attack patterns
- Consider enabling
close_circuitsonly after testing
§See Also
crate::config::BandguardsConfig- Configuration optionscrate::control- Event handling and circuit closure- Python vanguards bandguards - Original implementation
- Tor Bug Tracker - Bug references
Structs§
- Bandwidth
Stats - Main bandwidth monitoring state for attack detection.
- BwCircuit
Stat - Per-circuit bandwidth statistics for attack detection.
- BwGuard
Stat - Per-guard connection statistics.
Enums§
- Circuit
Limit Result - Result of checking circuit limits.
- Connectivity
Status - Connectivity status result.
Constants§
- CELL_
PAYLOAD_ SIZE - Cell payload size in bytes.
- MAX_
CIRC_ DESTROY_ LAG_ SECS - Maximum lag between guard connection close and circuit destroy events.
- RELAY_
HEADER_ SIZE - Relay header size in bytes.
- RELAY_
PAYLOAD_ SIZE - Relay payload size (cell payload minus relay header).