Crate maybenot_simulator 

A simulator for the Maybenot framework. The Maybenot framework is intended for traffic analysis defenses that can be used to hide patterns in encrypted communication. The goal of the simulator is to assist in the development of such defenses.

The simulator consists of two core functions: parse_trace and sim. The intended use is to first parse a trace (e.g., from a pcap file or a Website Fingerprinting dataset) using parse_trace, and then simulate the trace using sim together with one or more Maybenot Machines running at the client and/or server. The output of the simulator can then be parsed to produce a simulated trace that then in turn can be used to, e.g., train a Website Fingerprinting attack.

Example usage

use maybenot::{event::TriggerEvent, Machine};
use maybenot_simulator::{network::Network, parse_trace, sim};
use std::{str::FromStr, time::Duration};

// The first ten packets of a network trace from the client's perspective
// when visiting google.com. The format is: "time,direction\n". The
// direction is either "s" (sent) or "r" (received). The time is in
// nanoseconds since the start of the trace.
let raw_trace = "0,s
19714282,r
183976147,s
243699564,r
1696037773,s
2047985926,s
2055955094,r
9401039609,s
9401094589,s
9420892765,r";

// The network model for simulating the network between the client and the
// server. Currently just a delay.
let network = Network::new(Duration::from_millis(10), None);

// Parse the raw trace into a queue of events for the simulator. This uses
// the delay to generate a queue of events at the client and server in such
// a way that the client is ensured to get the packets in the same order and
// at the same time as in the raw trace.
let mut input_trace = parse_trace(raw_trace, network);

// A simple machine that sends one padding packet 20 milliseconds after the
// first normal packet is sent.
let m = "02eNp1ibEJAEAIA5Nf7B3N0v1cSESwEL0m5A6YvBqSgP7WeXfM5UoBW7ICYg==";
let m = Machine::from_str(m).unwrap();

// Run the simulator with the machine at the client. Run the simulation up
// until 100 packets have been recorded (total, client and server).
let trace = sim(&[m], &[], &mut input_trace, network.delay, 100, true);

// print packets from the client's perspective
let starting_time = trace[0].time;
trace
    .into_iter()
    .filter(|p| p.client)
    .for_each(|p| match p.event {
        TriggerEvent::TunnelSent => {
            if p.contains_padding {
                println!(
                    "sent a padding packet at {} ms",
                    (p.time - starting_time).as_millis()
                );
            } else {
                println!(
                    "sent a normal packet at {} ms",
                    (p.time - starting_time).as_millis()
                );
            }
        }
        TriggerEvent::TunnelRecv => {
            if p.contains_padding {
                println!(
                    "received a padding packet at {} ms",
                    (p.time - starting_time).as_millis()
                );
            } else {
                println!(
                    "received a normal packet at {} ms",
                    (p.time - starting_time).as_millis()
                );
            }
        }
        _ => {}
    });

// Output:
// sent a normal packet at 0 ms
// received a normal packet at 19 ms
// sent a padding packet at 20 ms
// sent a normal packet at 183 ms
// received a normal packet at 243 ms
// sent a normal packet at 1696 ms
// sent a normal packet at 2047 ms
// received a normal packet at 2055 ms
// sent a normal packet at 9401 ms
// sent a normal packet at 9401 ms
// received a normal packet at 9420 ms

Modules

delay

integration

network

For simulating the network stack and network between client and server.

queue

The main queue of events in the simulator.

queue_event

queue_peek

Functions for peeking at the possible next events in the simulation.

Structs

ScheduledAction

ScheduledAction represents an action that is scheduled to be executed at a certain time.

SimEvent

SimEvent represents an event in the simulator. It is used internally to represent events that are to be processed by the simulator (in SimQueue) and events that are produced by the simulator (the resulting trace).

SimState

The state of the client or the server in the simulator.

SimulatorArgs

Arguments for sim_advanced.

Functions

parse_trace

Parse a trace into a SimQueue for use with sim.

parse_trace_advanced

sim

The main simulator function.

sim_advanced

Like sim, but allows to (i) set the maximum padding and blocking fractions for the client and server, (ii) specify the maximum number of iterations to run the simulator for, and (iii) only returning client events.