https://github.com/paulshpilsher/router-flood

Advanced network stress testing tool for controlled environments. Multi-protocol packet generation (UDP/TCP/ICMP/IPv6/ARP) with built-in safety validation, audit logging, and real-time statistics. Designed for authorized network testing and educational purposes only.
https://github.com/paulshpilsher/router-flood

arp authorized-testing ddos ddos-tool educational-tool icmp ip4 ip6 network-protocols network-security network-testing rust safety-first security-tools sockets stress-testing tcp tokio udp

Last synced: 13 days ago
JSON representation

Advanced network stress testing tool for controlled environments. Multi-protocol packet generation (UDP/TCP/ICMP/IPv6/ARP) with built-in safety validation, audit logging, and real-time statistics. Designed for authorized network testing and educational purposes only.

• Host: GitHub
• URL: https://github.com/paulshpilsher/router-flood
• Owner: PaulShpilsher
• License: other
• Created: 2025-08-12T05:00:27.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2025-09-03T14:34:15.000Z (about 1 month ago)
• Last Synced: 2025-09-03T15:29:01.588Z (about 1 month ago)
• Topics: arp, authorized-testing, ddos, ddos-tool, educational-tool, icmp, ip4, ip6, network-protocols, network-security, network-testing, rust, safety-first, security-tools, sockets, stress-testing, tcp, tokio, udp
• Language: Rust
• Homepage:
• Size: 938 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Security: SECURITY.md

Awesome Lists containing this project

README

          
# router-flood

[![Main](https://github.com/PaulShpilsher/router-flood/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/PaulShpilsher/router-flood/actions/workflows/main.yml)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[![Rust](https://img.shields.io/badge/rust-1.85%2B-blue.svg)](https://www.rust-lang.org)

[![Platform](https://img.shields.io/badge/platform-linux-lightgrey.svg)](https://www.kernel.org/)

[![Safety](https://img.shields.io/badge/safety-enforced-green.svg)](SECURITY.md)

A high-performance network stress testing tool for authorized testing of network infrastructure resilience.

## ⚠️ Important

**Educational and authorized testing only.** Only use on networks you own or have explicit permission to test. Unauthorized use is illegal.

## Features

* **Safety-first design** - Enforces private IP ranges (RFC 1918), includes rate limiting and dry-run mode

* **High performance** - SIMD-accelerated packet generation (3-5x speedup), lock-free memory pools, CPU affinity

* **Multi-protocol support** - TCP (SYN/ACK/FIN/RST), UDP, ICMP, IPv6 with configurable protocol mix

* **Zero-allocation hot paths** - Pre-allocated buffers, batched RNG, and Treiber stack memory management

* **Real-time monitoring** - Live statistics with JSON/CSV export and Prometheus metrics support

* **Capability-based security** - Runs with CAP_NET_RAW only (no root required), tamper-proof audit logging

* **Advanced packet control** - Multi-port targeting, configurable payload sizes, intelligent rate limiting

* **Production ready** - Graceful shutdown, signal handling, comprehensive error messages with guidance

## Installation

### From source

```bash

# Clone and build

git clone https://github.com/PaulShpilsher/router-flood.git

cd router-flood

cargo build --release

# Grant network capabilities (recommended over running as root)

sudo setcap cap_net_raw+ep ./target/release/router-flood

```

### Prerequisites

* Linux system with kernel 3.10+

* Rust 1.85+ (install via [rustup](https://rustup.rs/))

* Network interface with raw socket support

## Quick start

```bash

# Test configuration without sending packets (simulates 98% success rate)

router-flood --target 192.168.1.1 --ports 80,443 --dry-run

# Perfect dry-run - 100% success rate for pure configuration validation

router-flood --target 192.168.1.1 --ports 80,443 --dry-run --perfect-simulation

# Basic stress test with 4 threads

router-flood --target 192.168.1.1 --ports 80 --threads 4 --rate 100

# Time-limited test

router-flood --target 192.168.1.1 --ports 80,443 --duration 60

# Using configuration file

router-flood --config stress-test.yaml

```

## Usage

See [USAGE.md](USAGE.md) for comprehensive usage documentation with examples.

### Command-line options

```

router-flood [OPTIONS]

OPTIONS:

    -t, --target            Target IP address (must be private range)

    -p, --ports          Target ports (comma-separated)

    --threads              Number of worker threads [default: 4]

    --rate                 Packets per second per thread [default: 100]

    -d, --duration     Test duration in seconds

    -c, --config          Load configuration from YAML file

    -i, --interface       Network interface to use

    --export            Export statistics (json, csv, yaml, text)

    --dry-run                   Test configuration without sending packets

    --perfect-simulation        Use 100% success rate in dry-run mode

    --audit-log           Custom audit log file path

    --list-interfaces           List available network interfaces

```

### Common examples

```bash

# Test web server

router-flood --target 192.168.1.100 --ports 80,443 --threads 4 --rate 500

# DNS server stress test

router-flood --target 10.0.0.53 --ports 53 --threads 4 --rate 2000 --duration 120

# Safe configuration testing

router-flood --target 192.168.1.1 --ports 80 --dry-run --perfect-simulation

```

For configuration files, advanced usage, and more examples, see [USAGE.md](USAGE.md).

## Building from source

```bash

# Standard build

cargo build --release

# Run tests

cargo test

# Run benchmarks

cargo bench

# Build with specific features

cargo build --release --features "json-export,prometheus"

```

## Performance tuning

For optimal performance:

1. **CPU affinity**: Workers are automatically pinned to CPU cores

2. **Memory pools**: Pre-allocated buffers minimize allocation overhead

3. **SIMD operations**: Automatic detection and use of AVX2/SSE4.2 for payload generation

4. **Batch size**: Adjust statistics batch size for your workload (default: 50)

## Safety features

* **IP validation**: Only accepts RFC 1918 private addresses

* **Rate limiting**: Built-in limits prevent accidental network saturation

* **Resource limits**: Enforces reasonable thread and memory constraints

* **Dry-run mode**: Test configurations without network impact (98% success rate by default)

* **Perfect simulation**: Optional 100% success rate in dry-run for pure config validation

* **Capability-based security**: Runs with minimal privileges (CAP_NET_RAW)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## Security

For security concerns, see [SECURITY.md](SECURITY.md) or report issues privately.

## License

MIT License - see [LICENSE](LICENSE) file for details.