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::{framework::TriggerEvent, machine::Machine};
use maybenot_simulator::{parse_trace, network::Network, sim};
use std::{str::FromStr, time::Duration};

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

// 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));

// 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 of 1000 bytes 20
// milliseconds after the first NonPaddingSent is sent.
let m = "789cedcfc10900200805506d82b6688c1caf5bc3b54823f4a1a2a453b7021ff8ff49\
41261f685323426187f8d3f9cceb18039205b9facab8914adf9d6d9406142f07f0";
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::NonPaddingSent { bytes_sent } => {
            println!(
                "sent {} bytes at {} ms",
                bytes_sent,
                (p.time - starting_time).as_millis()
            );
        }
        TriggerEvent::PaddingSent { bytes_sent, .. } => {
            println!(
                "sent {} bytes of padding at {} ms",
                bytes_sent,
                (p.time - starting_time).as_millis()
            );
        }
        TriggerEvent::NonPaddingRecv { bytes_recv } => {
            println!(
                "received {} bytes at {} ms",
                bytes_recv,
                (p.time - starting_time).as_millis()
            );
        }
        TriggerEvent::PaddingRecv { bytes_recv, .. } => {
            println!(
                "received {} bytes of padding at {} ms",
                bytes_recv,
                (p.time - starting_time).as_millis()
            );
        }
        _ => {}
    });

Prints the following output:

sent 52 bytes at 0 ms
received 52 bytes at 19 ms
sent 1000 bytes of padding at 20 ms
sent 52 bytes at 183 ms
received 52 bytes at 243 ms
sent 40 bytes at 1696 ms
sent 52 bytes at 2047 ms
received 52 bytes at 2055 ms
sent 73 bytes at 9401 ms
sent 73 bytes at 9401 ms
received 191 bytes at 9420 ms

Modules

• integration
• network
  For simulating network activity: sending and receiving packets between the client and server.
• peek
  Functions for peeking at the possible next events in the simulation.
• queue
  The main queue of events in the simulator.

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.