fumble is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install fumble

It will make the fumble command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall fumble uninstalls.

Adding `fumble` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add fumble

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

fumble = "0.6.1"

The fumble library will be automatically available globally.

Back to the crate overview.

Readme

fumble

fumble is an oxidized (Rust-based) implementation of the original clumsy tool, designed to simulate adverse network conditions on Windows systems. Utilizing the powerful capabilities of the WinDivert library, fumble intercepts live network packets and allows users to introduce controlled delays, drops, duplications, and modifications to these packets. This tool is invaluable for debugging network-related bugs, testing application resilience under poor network conditions, and evaluating performance in unreliable network environments.

Just like its predecessor, fumble offers a user-friendly and interactive way to degrade network performance intentionally, making it easier to diagnose issues and improve the robustness of network-dependent applications. Whether you're a developer needing to simulate a flaky connection or a QA engineer stress-testing an application, fumble provides a versatile and reliable solution.

Features

Packet Manipulation Features

Packet Filtering: Use filter expressions to capture specific packets.
Packet Dropping: Drop packets with a specified probability.
Packet Delay: Introduce delays to simulate latency.
Packet Throttling: Temporarily hold or drop packets to simulate sporadic network throttling.
Packet Reordering: Reorder packets by applying a random delay to simulate out-of-order delivery.
Packet Tampering: Modify packet payloads by altering, flipping, or injecting data to simulate corrupted transmissions.
Packet Duplication: Duplicate packets to simulate packet duplication issues.
Bandwidth Limiting: Limit the bandwidth to simulate a constrained network environment.

Binary Features

General CLI Usage: Utilize a comprehensive command-line interface for flexible and detailed control over network manipulation settings. Easily specify parameters for packet filtering, dropping, delaying, throttling, reordering, tampering, duplicating, and bandwidth limiting.
Configuration Support: Easily manage your settings through configuration files. Create, list, and use configuration files to save and load your preferred settings, simplifying the setup and ensuring consistent behavior across different runs.
Text User Interface (TUI) Mode: a Text User Interface (TUI) for users who prefer an interactive and visual interface over the command line. The TUI provides a more user-friendly way to configure and manage network manipulation settings in real-time.

Roadmap

TUI/CLI Enhancements: Enhance the Text User Interface (TUI) to offer a graph visualization of the network traffic and all the modifications being applied by fumble.
Graphical User Interface (GUI): Implement a GUI to cater to users who prefer not to use the command line.

Requirements

Important: fumble requires WinDivert.dll and WinDivert64.sys to function properly. You can download them from the official WinDivert releases page.

Installing WinDivert

Download the latest version of WinDivert.dll and WinDivert64.sys.
Place WinDivert.dll and WinDivert64.sys in the same directory as the fumble binary executable, or add the directory containing these files to your system's PATH environment variable.

Installation

From Source

To build fumble, ensure you have Rust and Cargo installed.
Clone the repository and build the project using Cargo:

git clone https://github.com/bornacvitanic/fumble.git
cd fumble
cargo build --release

To ensure proper functionality, place WinDivert.dll and WinDivert64.sys in the same directory as the fumble binary (typically ./target/debug or ./target/release). Alternatively, you can add the directory containing these files to your system's PATH environment variable.

From GitHub Releases

You can download pre-built binaries from the GitHub Releases page:

Download the appropriate release for your platform.
Extract the files from the release archive.

The release archive already contains a copy of the WinDivert.dll and WinDivert64.sys files.

From crates.io as a CLI

To install fumble as a command-line tool globally, use:

cargo install fumble

This installs the fumble binary, enabling you to use the CLI tool globally. After installation, ensure that WinDivert.dll and WinDivert64.sys are placed in the same directory as the fumble binary (typically located at C:\Users\username\.cargo\bin on Windows). Alternatively, you can add the directory containing these files to your system's PATH environment variable.

Using fumble as a Library

To include fumble as a dependency in your Rust project, add the following to your Cargo.toml:

[dependencies]
fumble = "0.6.0"

Run cargo build to download and compile the crate.
To ensure proper functionality, place WinDivert.dll and WinDivert64.sys in the same directory as the fumble binary (typically ./target/debug or ./target/release). Alternatively, you can add the directory containing these files to your system's PATH environment variable.

Usage

Run the fumble executable with the desired options:

fumble --filter "inbound and tcp" --delay-duration 500 --drop-probability 0.1

TUI Mode

fumble offers a Text User Interface (TUI) mode for those who prefer a more interactive experience. The TUI allows you to view, configure, and manage network manipulation settings in a visual interface, making it easier to adjust settings on the fly. You can initialise the TUI via either a config or normal cli commands.

Launching the TUI

To start fumble in TUI mode, use the following command:

fumble  -t

Once in the TUI, you can navigate through different settings using your keyboard. The TUI provides real-time feedback and allows for quick adjustments to your configurations.

You can initialize the TUI with default values from either individual commands of a config. You can also specify a initial filter:

fumble --filter "outbound and udp"  -t

fumble --filter "outbound and udp" --delay-duration 500  -t

fumble --filter "inbound and udp" --use-config config_name  -t

Command-Line Options

-f, --filter <FILTER>: Filter expression for capturing packets.
--drop-probability <drop-probability>: Probability of dropping packets, ranging from 0.0 to 1.0.
--delay-duration <delay-duration>: Delay in milliseconds to introduce for each packet.
--throttle-probability <throttle-probability>: Probability of triggering a throttle event, ranging from 0.0 to 1.0.
--throttle-duration <throttle-duration>: Duration in milliseconds for which throttling should be applied.
- Default: 30
--throttle-drop: Indicates whether throttled packets should be dropped.
--reorder-probability <reorder-probability>: Probability of reordering packets, ranging from 0.0 to 1.0.
--reorder-max-delay <reorder-max-delay>: Maximum random delay in milliseconds to apply when reordering packets.
- Default: 100
--tamper-probability <tamper-probability>: Probability of tampering packets, ranging from 0.0 to 1.0.
--tamper-amount <tamper-amount>: Amount of tampering that should be applied, ranging from 0.0 to 1.0.
- Default: 0.1
--tamper-recalculate-checksums <tamper-recalculate-checksums>: Whether tampered packets should have their checksums recalculated to mask the tampering and avoid the packets getting automatically dropped.
- Possible values: true, false
--duplicate-probability <duplicate-probability>: Probability of duplicating packets, ranging from 0.0 to 1.0.
--duplicate-count <duplicate-count>: Number of times to duplicate each packet.
- Default: 1
--bandwidth-limit <bandwidth-limit>: Maximum bandwidth limit in KB/s.
-t, --tui: Launch the Text User Interface (TUI).
-h, --help: Print help (see a summary with -h).

Configuration Management:

--create-default <CREATE_DEFAULT>: Command to create a default configuration file with the specified name.
--use-config <USE_CONFIG>: Command to use an existing configuration file based on the specified name.
--list-configs: Command to list all available configuration files.

Examples

Drop 10% of incoming TCP packets:

fumble --filter "inbound and tcp" --drop-probability 0.1

Delay packets by 500 milliseconds:

fumble --filter "inbound and tcp" --delay-duration 500

Throttle packets with a 10% probability for 30 milliseconds and drop them:

fumble --filter "inbound and tcp" --throttle-probability 0.1 --throttle-duration 30 --throttle-drop

Throttle packets with a 20% probability for 50 milliseconds and delay them:

fumble --filter "inbound and tcp" --throttle-probability 0.2 --throttle-duration 50

Reorder packets with a 10% probability and a maximum delay of 100 milliseconds:

fumble --filter "inbound and tcp" --reorder-probability 0.1 --reorder-max-delay 100

Tamper packets with a 25% probability and a tamper amount of 0.2, recalculating checksums:

fumble --filter "inbound and tcp" --tamper-probability 0.25 --tamper-amount 0.2 --tamper-recalculate-checksums true

Tamper packets with a 30% probability, and do not recalculate checksums:

fumble --filter "inbound and tcp" --tamper-probability 0.3 --tamper-recalculate-checksums false

Duplicate packets with a 50% chance:

fumble --filter "inbound and tcp" --duplicate-probability 0.5 --duplicate-count 2

Limit bandwidth to 100 KB/s:

fumble --filter "inbound and tcp" --bandwidth-limit 100

Logging

The tool uses the env_logger crate for logging. By default, informational messages are shown.

Enabling Detailed Logs

To see more detailed logs, set the RUST_LOG environment variable before running fumble.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

clap - A command-line argument parser for Rust that provides a simple and powerful API for defining complex CLI interfaces.
windivert - A Rust binding for the WinDivert library, used for network packet interception and manipulation.
rand - A Rust library for generating random numbers, used for implementing random packet dropping and duplication.
ratatui - A Rust library for building terminal user interfaces with an emphasis on simplicity and ease of use.
tui-textarea - A Rust crate for managing text input within terminal user interfaces.
lazy_static - A Rust macro for defining statically initialized variables that are computed lazily.
ctrlc - A Rust library for handling Ctrl-C signals, enabling graceful shutdowns and clean thread termination.
regex - A Rust library for regular expressions, used for string matching operations.
env_logger - A simple logger for Rust applications that can be configured via environment variables.
log - A logging facade that provides a common interface for various log implementations.
serde - For serialization and deserialization of configuration files.
toml - For parsing and serializing TOML configuration files.
dirs - For handling configuration directories across different operating systems.
thiserror - For ergonomic error handling.

Contact

Email: borna.cvitanic@gmail.com
GitHub Issues: GitHub Issues Page

Installing the command-line executable

Adding fumble library as a dependency

Adding `fumble` library as a dependency