A network tool for bandwidth shaping and traffic management on local networks, written in Rust.
harper sits between devices on your network and the internet, giving you control over who gets how much bandwidth. It can throttle a connection to a specific speed, block it entirely, or leave it untouched on a per-device basis.
It operates in two modes:
- MITM mode — harper positions itself between a target device and the gateway using ARP spoofing, without needing to be the actual router.
- Gateway mode — If you are the router or hotspot, harper shapes traffic directly without any ARP manipulation.
- Linux
- Root privileges (for raw sockets, tc, nftables)
- A wired or wireless network interface
- Kernel modules:
ifb,act_mirred,sch_htb,sch_sfq,cls_fw
# Enter the Nix development shell
nix-shell
# Build release binary
build
# or: cargo build --release
# Binary at: target/release/harper# Run unit + BDD tests (no root needed)
cargo test
# Run all tests including live network tests (requires root)
sudo cargo test -- --ignored| Option | Description |
|---|---|
-i, --interface <IFACE> |
Network interface to use (auto-selected if omitted) |
-g, --gateway <IP> |
Gateway IP (MITM mode only, auto-detected if omitted) |
-t, --target <IP|CIDR|RANGE> |
Target IP(s) — skips full scan (can repeat) |
-b, --bandwidth <KBPS> |
Bandwidth cap per host (omit = unlimited) |
--one-sided |
Use gratuitous ARP takeover instead of bidirectional poisoning |
--uplink <IP|MAC> |
Explicitly name the bottleneck uplink device to exclude from shaping |
# Interactive: scan → pick targets → set bandwidth
sudo harper
# Non-interactive: throttle specific targets at 500 kbps
sudo harper -t 192.168.1.10 -t 192.168.1.20 -b 500
# Block a target entirely
sudo harper -t 192.168.1.5 -b 0
# CIDR range
sudo harper -t 10.0.0.0/24 -b 1024
# Last-octet range
sudo harper -t 192.168.1.10-20 -b 512# Shape all discovered clients at 1 Mbps each
sudo harper --gateway-mode --all -b 1024
# Shape specific targets only (skips scan)
sudo harper --gateway-mode -t 10.0.0.5 -t 10.0.0.10 -b 500
# Pool mode: all shaped clients share ONE bandwidth pool
# Unshaped traffic (the "attacker" / uplink) keeps the rest of the line
sudo harper --gateway-mode --all --pool 2048
# Exclude a repeater/uplink by MAC or IP from the victim pool
sudo harper --gateway-mode --all --uplink AA:BB:CC:DD:EE:FF| Aspect | MITM mode | Gateway mode |
|---|---|---|
| ARP spoofing | Yes (bidirectional or one-sided) | No |
| Requires being gateway | No | Yes |
| Target discovery | ARP scan + passive sniff | Kernel ARP cache (instant) + scan fallback |
--target |
Skips scan, resolves only those IPs | Same; skips cache lookup |
--all |
N/A | Shape every discovered client |
--pool |
N/A | Shared bandwidth class for all victims |
--uplink |
Excludes from poisoning | Excludes from victim pool |
| Format | Example | Expands to |
|---|---|---|
| Single IP | 192.168.1.10 |
192.168.1.10 |
| CIDR | 10.0.0.0/24 |
10.0.0.1 – 10.0.0.254 |
| Last-octet range | 192.168.1.10-20 |
192.168.1.10 – 192.168.1.20 |
| Multiple | -t 10.0.0.1 -t 10.0.0.5-10 |
Combined, deduped, sorted |
After the scan completes, you'll see a table:
==============================================================
ARP Spoof — Target Selection
==============================================================
ID IP MAC Status Vendor
[1] 192.168.1.10 AA:BB:CC:DD:EE:01 Discovered Intel
[2] 192.168.1.11 AA:BB:CC:DD:EE:02 Discovered Unknown
[3] 192.168.1.12 AA:BB:CC:DD:EE:03 Discovered Apple
==============================================================
Gateway [4] 192.168.1.1 is excluded from selection.
Formats: "3" "1-3" "1,3,5" "all"
Select target(s) [1-3] or 'q' to quit:
Input formats:
3— single host1-5— inclusive range (skips unavailable IDs)1,3,5— comma-separated list (deduped, sorted)all/ALL/All— all available hosts
Then you'll be prompted for bandwidth (blank = unlimited).
Press Ctrl-C or q + Enter at any time. harper will:
- Stop packet forwarding
- Stop ARP poisoning
- Send ARP restore packets (600 ms per host) to fix victim caches
- Remove tc qdiscs and nftables rules
- Restore kernel sysctl settings (ip_forward, rp_filter, etc.)
Never kill -9 the process — victims will lose connectivity until their ARP caches expire (typically 30–60 s).
This software is provided for educational and research purposes only. You are solely responsible for ensuring your use complies with all applicable laws. Only use harper on networks you own or have explicit written permission to test.
See LICENSE for the full MIT license terms. Also see Legal Notice for a statement from the author.
MIT © 2026 Masrkai