Bandwidth Guard

Monitor and enforce per-process network bandwidth limits on Linux using eBPF.

Features

• 🚀 Real-time tracking - See which apps are using your bandwidth
• ⚡ eBPF-powered - Kernel-level monitoring with minimal overhead
• 🎯 Smart enforcement - Set limits per app (kill or warn when exceeded)
• 📊 Rich CLI - Beautiful terminal UI with history reports
• 🔔 Desktop notifications - Get alerts at 80% and 100% usage
• 📅 Daily tracking - Automatic daily reset with historical data

Quick Install

One-line installer

curl -fsSL https://raw.githubusercontent.com/Ndukiye/bandwidth-guard/main/install.sh | sudo bash

Or manual installation:

1. Download latest release

wget https://github.com/Ndukiye/bandwidth-guard/releases/latest/download/bandwidth-guard-installer.tar.gz2.

2. Extract and install

tar -xzf bandwidth-guard-installer.tar.gz
cd bandwidth-guard
sudo ./install.sh

3. Test it:

bwguard status

Usage

View today's usage

bwguard status

View last 30 days

bwguard history --days 30

Set Firefox limit (2GB/day, kill when exceeded)

bwguard set-limit firefox 2048

Set Spotify limit (500MB/day, warn only)

bwguard set-limit spotify 500 --action warn

List configured limits

bwguard limits

Remove a limit

bwguard remove-limit firefox

How It Works

┌─────────────────────────────────────────┐
│  eBPF Hooks (bpftrace)                  │
│  Kernel-level network tracking          │
└────────────┬────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────┐
│  Systemd Daemon (monitor.py)            │
│  • Aggregates per-process stats         │
│  • Enforces limits (kill/warn)          │
│  • Sends desktop notifications          │
└────────────┬────────────────────────────┘
             │ Writes to
             ▼
┌─────────────────────────────────────────┐
│  /var/lib/bandwidth-guard/              │
│  • config.yaml                          │
│  • data.json                            │
│  • multi_tracker_history.json           │
└────────────▲────────────────────────────┘
             │ Reads from
┌────────────┴────────────────────────────┐
│  CLI Snap (bwguard)                     │
│  • View status                          │
│  • Set limits                           │
│  • View history                         │
└─────────────────────────────────────────┘

Installation

See INSTALL.md for detailed installation instructions.

Development

See CONTRIBUTING.md for local development setup.

Platform Support

• ✅ Ubuntu 20.04+ (tested)
• ✅ Debian/Fedora/Arch (should work)
• ✅ WSL2 (Windows users)
• ❌ macOS/Windows native (eBPF is Linux-only)

Requirements

• Linux kernel 5.2+ (for eBPF)
• bpftrace 0.18+
• Python 3.8+
• Root access (for eBPF monitoring)

Tech Stack

• eBPF/bpftrace - Kernel-level network hooks
• Python 3 - Main logic & CLI
• Systemd - Background daemon management
• Snap - Distribution packaging
• Rich - Terminal UI
• PyYAML - Configuration management

Contributing

Contributions welcome! See CONTRIBUTING.md.

Areas to improve:

• Web dashboard (Flask + React)
• Traffic control (tc) integration for throttling
• Email/Slack alerts
• Container support

License

MIT License - see LICENSE for details.

Acknowledgments

• Built as a learning project for systems programming and eBPF
• Inspired by nethogs and iftop
• Thanks to the bpftrace and eBPF communities

Author

Orukaria Ndukiye
GitHub • LinkedIn

---

Found this useful? Star the repo! ⭐