Skip to content

Commit 3443648

Browse files
umerfarokumerfarok
authored
Addmore functionality (#5)
* Enhance platform-specific functionality for network monitoring - Refactored launcher.py to include OS-specific imports and logging for Windows, macOS, and Linux. - Added LinuxNetworkMonitor class for Linux-specific network functionalities, including interface management and device control. - Introduced MacOSNetworkMonitor class for macOS-specific network functionalities, including interface management and device control. - Updated monitor.py to utilize platform-specific network monitor classes for better modularity and maintainability. - Improved error handling and logging throughout the codebase for better debugging and user feedback. - Added new dependencies for macOS and Linux in requirements.txt to support platform-specific features. * feat: add device management features for Windows, including speed limiting and blocking * feat: initialize NetworkMonitor application with core backend, web UI, installation scripts, documentation, and CI workflow.
1 parent d5f1523 commit 3443648

22 files changed

Lines changed: 3292 additions & 664 deletions

‎.github/workflows/ci.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,25 @@ jobs:
148148
choco install nsis
149149
choco install gtk-runtime
150150
151+
- name: Bundle Npcap and VC++ Runtime (Windows)
152+
if: runner.os == 'Windows'
153+
shell: pwsh
154+
run: |
155+
# Create bundled_resources directories
156+
New-Item -ItemType Directory -Force -Path "bundled_resources/Npcap"
157+
New-Item -ItemType Directory -Force -Path "bundled_resources/vcruntime"
158+
159+
# Download Npcap installer (silent/OEM version)
160+
Write-Host "Downloading Npcap installer..."
161+
Invoke-WebRequest -Uri "https://npcap.com/dist/npcap-1.79.exe" -OutFile "bundled_resources/Npcap/npcap-installer.exe"
162+
163+
# Download VC++ Runtime
164+
Write-Host "Downloading VC++ Runtime..."
165+
Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vc_redist.x64.exe" -OutFile "bundled_resources/vcruntime/vc_redist.x64.exe"
166+
167+
Write-Host "Bundled resources ready!"
168+
Get-ChildItem bundled_resources -Recurse
169+
151170
- name: Install system dependencies (macOS)
152171
if: runner.os == 'macOS'
153172
run: |

‎INSTALLATION.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
# 🚀 NetworkMonitor Installation Guide
2+
3+
This guide will help you install and run NetworkMonitor on your computer in just a few minutes!
4+
5+
---
6+
7+
## 📥 Download Options
8+
9+
### Option 1: Download from GitHub Releases (Recommended)
10+
11+
1. Go to [**Releases Page**](https://github.com/umerfarok/networkmonitor/releases)
12+
2. Download the latest version for your operating system:
13+
14+
| Platform | Download | Type |
15+
|----------|----------|------|
16+
| **Windows** | `NetworkMonitor-Windows-Setup-x.x.x.zip` | Installer (Recommended) |
17+
| **Windows** | `NetworkMonitor-Windows-x.x.x.zip` | Portable Version |
18+
| **Linux** | `NetworkMonitor-Linux-x.x.x.tar.gz` | Executable |
19+
| **macOS** | `NetworkMonitor-macOS-x.x.x.zip` | Application Bundle |
20+
21+
---
22+
23+
## 🪟 Windows Installation
24+
25+
### Prerequisites (One-Time Setup)
26+
27+
Before running NetworkMonitor, you need **Npcap** for network packet capture:
28+
29+
1. Download Npcap from [https://npcap.com](https://npcap.com)
30+
2. Run the installer **as Administrator**
31+
3. ✅ **Important**: Check the box **"Install Npcap in WinPcap API-compatible Mode"**
32+
4. Complete the installation
33+
34+
### Installing NetworkMonitor
35+
36+
#### Method A: Using the Installer (Recommended)
37+
38+
1. Download `NetworkMonitor-Windows-Setup-x.x.x.zip`
39+
2. Extract the ZIP file
40+
3. Right-click `NetworkMonitor_Setup.exe` and select **"Run as administrator"**
41+
4. Follow the installation wizard
42+
5. Launch from Start Menu or Desktop shortcut
43+
44+
#### Method B: Portable Version (No Installation)
45+
46+
1. Download `NetworkMonitor-Windows-x.x.x.zip`
47+
2. Extract to any folder (e.g., `C:\NetworkMonitor`)
48+
3. Right-click `NetworkMonitor.exe` and select **"Run as administrator"**
49+
50+
### Running NetworkMonitor
51+
52+
```
53+
⚠️ IMPORTANT: Always run NetworkMonitor as Administrator!
54+
Right-click → "Run as administrator"
55+
```
56+
57+
1. Double-click `NetworkMonitor.exe` (or use Start Menu shortcut)
58+
2. A status dashboard will appear
59+
3. Your web browser will open automatically to `http://localhost:5000`
60+
4. You'll see all devices connected to your network!
61+
62+
---
63+
64+
## 🐧 Linux Installation
65+
66+
### Prerequisites
67+
68+
```bash
69+
# Ubuntu/Debian
70+
sudo apt update
71+
sudo apt install -y libpcap-dev net-tools iptables
72+
73+
# Fedora/RHEL
74+
sudo dnf install -y libpcap-devel net-tools iptables
75+
76+
# Arch Linux
77+
sudo pacman -S libpcap net-tools iptables
78+
```
79+
80+
### Installation
81+
82+
```bash
83+
# 1. Download the latest release
84+
wget https://github.com/umerfarok/networkmonitor/releases/latest/download/NetworkMonitor-Linux-x.x.x.tar.gz
85+
86+
# 2. Extract the archive
87+
tar -xzf NetworkMonitor-Linux-*.tar.gz
88+
89+
# 3. Make it executable
90+
chmod +x NetworkMonitor
91+
92+
# 4. Run with sudo (required for network access)
93+
sudo ./NetworkMonitor
94+
```
95+
96+
### Running
97+
98+
```bash
99+
# Always run with sudo for network scanning
100+
sudo ./NetworkMonitor
101+
```
102+
103+
Open your browser and go to: `http://localhost:5000`
104+
105+
---
106+
107+
## 🍎 macOS Installation
108+
109+
### Prerequisites
110+
111+
```bash
112+
# Install libpcap (usually pre-installed, but just in case)
113+
brew install libpcap
114+
```
115+
116+
### Installation
117+
118+
1. Download `NetworkMonitor-macOS-x.x.x.zip`
119+
2. Extract the ZIP file
120+
3. If you see a security warning:
121+
- Go to **System Preferences** → **Security & Privacy**
122+
- Click **"Open Anyway"**
123+
124+
### Running
125+
126+
```bash
127+
# Run with sudo for network access
128+
sudo ./NetworkMonitor
129+
```
130+
131+
Or right-click the app and select **"Open"**, then enter your password.
132+
133+
Open your browser and go to: `http://localhost:5000`
134+
135+
---
136+
137+
## 🌐 Using the Web Dashboard
138+
139+
Once NetworkMonitor is running, the dashboard provides:
140+
141+
### Features
142+
- 📊 **Device List**: See all devices on your network
143+
- 🔍 **Device Details**: IP, MAC, Hostname, Vendor
144+
- ⚡ **Speed Monitoring**: Real-time bandwidth usage
145+
- 🔒 **Protection**: Protect devices from ARP attacks
146+
- ✂️ **Network Cut**: Disconnect devices from the network
147+
- 🚦 **Speed Limiting**: Control bandwidth per device
148+
149+
### Dashboard URL
150+
```
151+
http://localhost:5000
152+
```
153+
154+
---
155+
156+
## ☁️ Using with Vercel-Hosted Frontend
157+
158+
NetworkMonitor supports a **hybrid setup** where the beautiful dashboard is hosted on Vercel:
159+
160+
### How It Works
161+
162+
```
163+
┌─────────────────────┐ ┌──────────────────────┐
164+
│ Your Computer │ │ Vercel (Cloud) │
165+
│ │ │ │
166+
│ NetworkMonitor.exe │◄────────│ Web Dashboard │
167+
│ (Backend API) │ API │ (React Frontend) │
168+
│ :5000 │ calls │ │
169+
└─────────────────────┘ └──────────────────────┘
170+
```
171+
172+
### Setup
173+
174+
1. **Start the local backend** on your computer:
175+
```bash
176+
# Windows
177+
NetworkMonitor.exe
178+
179+
# Linux/macOS
180+
sudo ./NetworkMonitor
181+
```
182+
183+
2. **Access the Vercel dashboard**:
184+
- Go to the deployed Vercel URL (e.g., `https://your-app.vercel.app`)
185+
- The dashboard connects to `http://localhost:5000` automatically
186+
187+
3. **That's it!** The cloud dashboard controls your local network.
188+
189+
---
190+
191+
## 🔧 Troubleshooting
192+
193+
### "Npcap not found" (Windows)
194+
195+
1. Download Npcap from [npcap.com](https://npcap.com)
196+
2. Run installer as Administrator
197+
3. ✅ Enable "WinPcap API-compatible Mode"
198+
4. Restart NetworkMonitor
199+
200+
### "Permission denied" (Linux/macOS)
201+
202+
```bash
203+
# Must run with sudo
204+
sudo ./NetworkMonitor
205+
```
206+
207+
### "Cannot bind to port 5000"
208+
209+
Another application is using port 5000. Either:
210+
- Close the other application
211+
- Or change the port in settings
212+
213+
### "No devices found"
214+
215+
1. Make sure you're connected to a network
216+
2. Run as Administrator/root
217+
3. Check firewall settings
218+
4. Try restarting NetworkMonitor
219+
220+
### Dashboard shows "Cannot connect to server"
221+
222+
1. Make sure NetworkMonitor.exe is running
223+
2. Check if the firewall is blocking port 5000
224+
3. Try accessing `http://localhost:5000/api/status` in your browser
225+
226+
---
227+
228+
## 📞 Getting Help
229+
230+
- **GitHub Issues**: [Report a bug](https://github.com/umerfarok/networkmonitor/issues)
231+
- **Documentation**: [Read the docs](https://umerfarok.github.io/networkmonitor)
232+
- **Logs**: Check application logs at:
233+
- Windows: `%LOCALAPPDATA%\NetworkMonitor\logs`
234+
- Linux/macOS: `~/.networkmonitor/logs`
235+
236+
---
237+
238+
## 🎉 Quick Reference
239+
240+
| Action | Command/Steps |
241+
|--------|---------------|
242+
| **Start** | Run `NetworkMonitor.exe` as Admin |
243+
| **Access Dashboard** | Open `http://localhost:5000` |
244+
| **Stop** | Click "Exit" or close the window |
245+
| **View Logs** | `%LOCALAPPDATA%\NetworkMonitor\logs` |
246+
247+
---
248+
249+
## ⚠️ Important Notes
250+
251+
1. **Administrator/Root Required**: Network scanning requires elevated privileges
252+
2. **ARP Scanning**: Some networks/routers may flag ARP scanning as suspicious activity
253+
3. **Firewall**: Make sure port 5000 is allowed through your firewall
254+
4. **Use Responsibly**: Only use on networks you own or have permission to monitor
255+
256+
---
257+
258+
**Happy Network Monitoring! 🎯**

‎QUICK_START.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# ⚡ Quick Start Guide
2+
3+
**Get NetworkMonitor running in 2 minutes!**
4+
5+
---
6+
7+
## 🪟 Windows (One-Line Install)
8+
9+
### Step 1: Install Npcap (one-time)
10+
1. Download from [npcap.com](https://npcap.com)
11+
2. Run as Administrator
12+
3. ☑️ Check "WinPcap API-compatible Mode"
13+
14+
### Step 2: Install NetworkMonitor
15+
16+
**Option A - One-Line PowerShell:**
17+
```powershell
18+
irm https://raw.githubusercontent.com/umerfarok/networkmonitor/main/scripts/install.ps1 | iex
19+
```
20+
21+
**Option B - Manual Download:**
22+
1. [**Download Latest Release**](https://github.com/umerfarok/networkmonitor/releases/latest)
23+
2. Get `NetworkMonitor-Windows-Setup-*.zip`
24+
3. Extract and run `NetworkMonitor_Setup.exe` as Administrator
25+
26+
### Step 3: Run
27+
Right-click **NetworkMonitor** → **Run as administrator**
28+
29+
Dashboard opens at: `http://localhost:5000`
30+
31+
---
32+
33+
## 🐧 Linux (One-Line Install)
34+
35+
```bash
36+
curl -sSL https://raw.githubusercontent.com/umerfarok/networkmonitor/main/scripts/install.sh | sudo bash
37+
```
38+
39+
Or manually:
40+
```bash
41+
# Install dependencies
42+
sudo apt install -y libpcap-dev
43+
44+
# Download and run
45+
wget https://github.com/umerfarok/networkmonitor/releases/latest/download/NetworkMonitor-Linux-*.tar.gz
46+
tar -xzf NetworkMonitor-Linux-*.tar.gz
47+
sudo ./NetworkMonitor
48+
```
49+
50+
Dashboard: `http://localhost:5000`
51+
52+
---
53+
54+
## 🍎 macOS (One-Line Install)
55+
56+
```bash
57+
curl -sSL https://raw.githubusercontent.com/umerfarok/networkmonitor/main/scripts/install.sh | bash
58+
```
59+
60+
Or manually:
61+
```bash
62+
curl -LO https://github.com/umerfarok/networkmonitor/releases/latest/download/NetworkMonitor-macOS-*.zip
63+
unzip NetworkMonitor-macOS-*.zip
64+
sudo ./NetworkMonitor
65+
```
66+
67+
Dashboard: `http://localhost:5000`
68+
69+
---
70+
71+
## ☁️ Using with Vercel (Cloud Dashboard)
72+
73+
1. **Start NetworkMonitor locally** (see above)
74+
2. **Visit** your Vercel deployment URL
75+
3. Dashboard connects to `localhost:5000` automatically
76+
77+
---
78+
79+
## 🖥️ What You Can Do
80+
81+
| Feature | Description |
82+
|---------|-------------|
83+
| 📊 **View Devices** | See all devices on your network |
84+
| ✂️ **Cut Connection** | Disconnect any device instantly |
85+
| 🔄 **Restore** | Bring device back online |
86+
| 🔒 **Protect** | Shield device from attacks |
87+
| ⚡ **Limit Speed** | Set bandwidth limits |
88+
| 📈 **Monitor** | Real-time traffic stats |
89+
90+
---
91+
92+
## 🆘 Quick Troubleshooting
93+
94+
| Problem | Solution |
95+
|---------|----------|
96+
| "Npcap not found" | [Download & install Npcap](https://npcap.com) |
97+
| "Permission denied" | Run as Admin / with sudo |
98+
| "Cannot connect" | Check if port 5000 is open |
99+
| "No devices found" | Connect to WiFi/Ethernet first |
100+
101+
---
102+
103+
**Need more help?** See [INSTALLATION.md](INSTALLATION.md) for detailed instructions.

0 commit comments

Comments
 (0)