NetPulse

I used to have a router that tracked data usage for all connected devices. But for some reason, my current one doesn't, so I decided to build one.

It monitors the network by sitting between devices. Logging intercepted data and pushing it to a dashboard where I can visualize everything in realtime.

What it does

NetPulse uses ARP spoofing to position itself as a man-in-the-middle between your router and any device on your network. It captures packets, counts bytes, and stores traffic data for each device. Then displays it all on a live dashboard.

Features

• ARP Spoofing: Intercepts traffic between devices and the router
• Real-time Monitoring: Watch traffic as it happens
• Per-Device Tracking: See upload/download stats for each connected device
• Live Dashboard: Charts and graphs that update automatically via WebSocket
• Traffic History: Browse historical data and trends
• REST API: Access all data programmatically

Tech Stack

• Backend: Django, Django REST Framework
• Network: Scapy (for ARP spoofing and packet capture)
• Real-time: Django Channels + Redis (WebSockets)
• Frontend: Vanilla JS + Chart.js
• Database: SQLite (can use PostgreSQL)

Setup

Requirements

• Python 3.12+
• Redis (for WebSocket support)
• Root/sudo privileges (required for packet capture and ARP spoofing)

Installation

1. Clone the repo:

git clone <repo-url>
cd net-pulse

2. Install dependencies with uv:

uv sync

3. Run migrations:

uv run python manage.py migrate

4. Start Redis:

docker run -d -p 6379:6379 redis

Usage

Start the Dashboard

uv run python manage.py runserver

Visit http://localhost:8000/ to see the dashboard.

Start Monitoring

In another terminal, start the monitoring process (requires sudo):

sudo .venv/bin/python manage.py start_monitor \
  --interface wlp108s0 \
  --gateway 192.168.0.1 \
  --targets 192.168.0.100 192.168.0.102

Replace:

• wlp108s0 with your network interface (find it with ip a)
• 192.168.0.1 with your router's IP
• Target IPs with the devices you want to monitor

The dashboard will now show live traffic data updating every 5 seconds.

How it Works

1. ARP Spoofing: Sends spoofed ARP packets to the target device and router, making them think we're the other party
2. IP Forwarding: Enables packet forwarding so traffic actually reaches its destination (devices stay connected)
3. Packet Capture: Uses Scapy to capture and analyze all packets passing through
4. Data Storage: Saves traffic stats to the database every 5 seconds
5. WebSocket Broadcast: Pushes updates to the dashboard in real-time via Redis

API Endpoints

• GET /api/devices/ - List all discovered devices
• GET /api/devices/{mac}/ - Get device details
• GET /api/devices/{mac}/traffic_history/?hours=24 - Traffic history
• GET /api/devices/active/ - Active devices only
• GET /api/traffic-snapshots/latest/ - Latest traffic snapshot
• ws://localhost:8000/ws/traffic/ - WebSocket for real-time updates

Admin Interface

Access the Django admin at http://localhost:8000/admin/ to:

• View all devices and their details
• Browse traffic logs and snapshots
• Manually edit device information

Create a superuser first:

uv run python manage.py createsuperuser

Security Warning

This tool performs network interception and should only be used on networks you own or have explicit permission to monitor.

ARP spoofing can be detected and may violate terms of service on networks you don't control. Use responsibly.

Upcoming Features

• Automatic device discovery (network scanning)
• Start/stop monitoring from the dashboard
• Device renaming/custom names
• Export traffic reports
• Bandwidth alerts

License

MIT