High-Performance Layer-2 LAN Bandwidth Manager & ARP Controller
NetCtrl is a modern Layer-2 network management and bandwidth control suite designed for local area networks (LAN). Utilizing high-performance ARP spoofing and packet filtering, NetCtrl allows network administrators to monitor real-time traffic per host, inspect visited domains, enforce bandwidth speed limits, or completely block network access.
NetCtrl provides two user interface modes suited for different workflows:
A fluid, modern UI powered by PyWebView featuring hardware-accelerated animations, live traffic sparklines, automated vendor logo badges, visited sites drawer, and preset rate limits.
- Real-time Sparklines: 60 FPS live activity graph per connected device.
- Smart Vendor Detection: Automatically identifies device manufacturers (Apple, Samsung, Xiaomi, TP-Link, Intel, Dell, etc.) and detects randomized MAC addresses (
Private / Phone 📱). - Visited Websites Drawer: Smooth sliding side-drawer displaying captured DNS requests per device in real time, with instant domain search and one-click copy.
- Speed Limiter Presets: Modal dialog with quick bandwidth presets (64 KB/s, 128 KB/s, 256 KB/s, 1 MB/s, Unlimited) and custom rate input.
- One-Click Emergency Restore: Top-bar "Restore All" button to instantly un-monitor, unblock, and heal the entire network's ARP tables.
- Inline Renaming: Double-click or click ✏️ to customize device names with instant persistent JSON storage.
A minimalist, zero-overhead desktop window designed for quick diagnostics and ultra-low system resource consumption.
# Launch Modern Cyber Dashboard (Default):
NetCtrl.exe
# Launch Classic Lightweight GUI:
NetCtrl.exe --classic-gui
# (or NetCtrl.exe --legacy-gui)# Launch Modern Cyber Dashboard (Default):
python main.py --rust
# Launch Classic Lightweight GUI:
python main.py --rust --classic-gui- Subnet-Aware Discovery: Broadcast ARP scanning tailored to your actual subnet mask (e.g.
/24), preventing interference with VPN virtual adapters. - Dual Architecture Engine:
- Rust High-Throughput Engine: Token-bucket rate limiting, sub-millisecond layer-2 packet forwarding, zero packet drops under load.
- Python Fallback Engine: Pure-Python implementation if running without the compiled binary.
- Local HTTP REST API: Binds to
127.0.0.1:8765and requires a fresh, per-launch Bearer token; the token is passed only through the desktop UI bridge and is not logged or persisted. Cross-origin requests from arbitrary websites are rejected. - DNS Inspection & Domain Logging: Inspects outgoing port 53 DNS queries to provide a visited website history per target host.
- Automatic Gateway & Local Host Protection: Your local machine is permanently identified, pinned at the top, and protected against accidental blocking or rate-limiting.
- Operating System: Windows 10 or Windows 11 (64-bit)
- Administrator Privileges: Required for raw packet capture and ARP transmission.
- Npcap Driver: Must be installed on the machine (Download Npcap).
For immediate plug-and-play installation without manually installing Python, Rust, or configuring drivers:
- Download
NetCtrl_Setup.exefrom the GitHub Releases page. The installer is not stored in the source tree. - Run
NetCtrl_Setup.exeas Administrator. - The setup automatically installs the required Npcap driver in WinPcap-compatible mode, extracts all core components, and creates a desktop shortcut.
- Launch NetCtrl directly!
If you already have Npcap installed and prefer a single portable .exe without installation:
- Ensure Npcap is installed from npcap.com (with "Install Npcap in WinPcap API-compatible Mode" enabled).
- Download or locate
NetCtrl.exeindist/. - Right-click and choose Run as administrator (or double-click; it will automatically request UAC elevation).
- On first launch, select your active network interface (Wi-Fi or Ethernet).
git clone https://github.com/Limitless728/netctrl.git
cd netctrlpip install -r requirements.txtMake sure you have Rust installed and Visual Studio C++ Build Tools.
cd rust_engine
cargo build --release
copy target\release\rust_engine.exe ..\rust_engine.exe
cd ..# Run with Modern Dashboard:
python main.py --rust
# Run with Classic GUI:
python main.py --rust --classic-guiTo bundle everything (Python code, Rust engine, Web dashboard assets, and icons) into a single standalone dist/NetCtrl.exe:
Simply run:
build_exe.batOr manually using PyInstaller:
pyinstaller --onefile --noconsole --uac-admin \
--add-data "rust_engine.exe;." \
--add-data "device_names.json;." \
--add-data "web;web" \
--icon icon.ico \
--workpath build_pkg \
--distpath dist \
--exclude-module matplotlib \
--exclude-module pygame \
--exclude-module PIL \
--exclude-module IPython \
--clean \
--name "NetCtrl" \
main.pynetctrl/
├── main.py # Application entrypoint & engine coordinator
├── gui_web.py # PyWebView bridge for modern dashboard
├── gui.py # Classic native Tkinter GUI
├── device_names.json # Persistent custom device name mappings
├── requirements.txt # Python dependencies
├── build_exe.bat # One-click Windows build script
├── screenshot.png # Classic GUI screenshot
├── Screenshot_NewGui.png # Modern Dashboard screenshot
├── web/ # Modern Cyber Dark Dashboard
│ ├── index.html # Semantic dashboard markup
│ ├── style.css # Cyber dark responsive styles & transitions
│ └── app.js # REST client, live polling, sparkline canvas
└── rust_engine/ # High-performance Rust L2 Core
├── Cargo.toml
└── src/
├── main.rs # Rust engine startup & CLI
├── server.rs # Axum HTTP REST server (:8765)
├── l2_forwarder.rs # Layer-2 forwarding & token-bucket rate limiter
├── spoofer.rs # Raw ARP poisoning & healing routines
├── scanner.rs # Active broadcast subnet ARP scanner
└── device_registry.rs # Thread-safe concurrent device & DNS records
| Issue | Cause & Solution |
|---|---|
Gateway MAC shows -- or ?? |
Make sure you are running as Administrator. NetCtrl needs raw socket access. |
| No devices discovered | Click Rescan LAN. Ensure you picked the correct network interface during initial setup. You can reset your interface in netctrl_config.json. |
| "Npcap not found" / Packet errors | Reinstall Npcap from npcap.com and ensure "WinPcap API-compatible Mode" is checked. |
| HTTP 401 / 403 API Error | All REST API requests require a per-launch Bearer token (NETCTRL_API_TOKEN) passed via Authorization: Bearer <token> and are restricted to the local WebView null Origin. If sending custom API calls, pass the active token generated on launch. |
| Antivirus false positive | Network administration tools that craft ARP frames may trigger heuristic detections. Download only from the official GitHub Releases page, verify the checksum when published, and report false positives to the antivirus vendor. Do not disable protections or add broad exclusions. |
NetCtrl is developed for network administration, performance diagnostics, and educational research only. Intercepting or modifying network traffic on networks without explicit authorization from the network owner is illegal in many jurisdictions. The developers assume no liability for misuse of this software.
This project is licensed under the MIT License.