📡 NetLens

Real-time Network Traffic Analysis Dashboard

A professional-grade network monitoring tool that provides complete visibility into your local network. Discover connected devices, monitor bandwidth usage, track DNS queries, identify network services, and analyze traffic patterns in real-time through an intuitive web interface.

✨ Features

🎯 Core Capabilities

• 📱 Device Discovery - Automatically scan and discover all connected devices on your network with nmap
• 🌐 DNS Tracking - See which websites and domains are being accessed by each device
• 🔌 Service Detection - Identify network services (HTTP, SSH, MySQL, RDP, etc.) using port analysis
• 📊 Bandwidth Analytics - Real-time bandwidth monitoring with per-device and network-wide metrics
• 📈 Traffic Timeline - Visualize network activity over time with interactive charts
• 🎛️ Per-Device Monitoring - Focus on a single device to see detailed statistics and activity

🛠️ Technical Features

• Real-time Processing - Packet capture and analysis with zero latency
• Automatic Discovery - Network range auto-detection
• Device Status Tracking - Online/offline device status
• Low Memory Footprint - Efficient packet storage with circular buffer
• Thread-safe Operations - Robust background processing
• Professional Logging - Comprehensive logging for debugging and monitoring

🚀 Quick Start

Prerequisites

• Python 3.8+
• Ubuntu/Debian (or compatible Linux)
• nmap - Network scanning utility
• Sudo access - Required for packet capture

Installation

1. Clone or download the project:

   cd ~/Desktop/network-dashboard

2. Create virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Ensure nmap is installed:

   sudo apt-get update
   sudo apt-get install -y nmap

Usage

Run the dashboard:

sudo /path/to/.venv/bin/streamlit run dashboard.py

Open in browser:

http://localhost:8501

💡 Note: Requires sudo for packet capture privileges

📋 Requirements

streamlit>=1.28.0          # Web dashboard framework
pandas>=2.0.0              # Data processing
scapy>=2.5.0               # Packet capture
plotly>=5.17.0             # Interactive visualizations
python-nmap>=0.0.1         # Network scanning

🏗️ Project Structure

network-dashboard/
├── README.md               # This file
├── requirements.txt        # Python dependencies
├── config.py              # Configuration constants
├── dashboard.py           # Main Streamlit application
│
├── src/                   # Source modules
│   ├── __init__.py
│   ├── packet_processor.py   # Packet capture & analysis
│   ├── network_scanner.py    # Device discovery
│   └── utils.py             # Utility functions
│
└── .venv/                 # Virtual environment (created after setup)

📖 How It Works

Architecture Overview

┌─────────────────────────────────────────┐
│     Streamlit Web Interface             │
│  (Dashboard • Device Selection • Stats) │
└──────────────────┬──────────────────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
┌───────▼──────────┐  ┌──────▼──────────┐
│ PacketProcessor  │  │ NetworkScanner  │
│                  │  │                 │
│ • Capture        │  │ • nmap scan     │
│ • Extract DNS    │  │ • Device list   │
│ • Port analysis  │  │ • Status track  │
│ • Per-device     │  │                 │
│   stats          │  │                 │
└────────┬─────────┘  └────────┬────────┘
         │                     │
         └────────────┬────────┘
                      │
            ┌─────────▼────────┐
            │   Linux Kernel   │
            │ • Packet capture │
            │ • nmap scanning  │
            └──────────────────┘

Data Flow

1. Device Discovery

   • Scanner runs periodic network scans (every 30 seconds)
   • Identifies online/offline devices
   • Maintains device hostname cache

2. Packet Capture

   • Scapy sniffs all IP packets on the network
   • Extracts protocol, ports, DNS queries
   • Aggregates per-device statistics

3. Data Visualization

   • Streamlit renders real-time dashboard
   • Updates every 2 seconds
   • User selects device to focus monitoring

🎨 Dashboard Sections

Overall Network View

• Top devices by bandwidth and packets
• Protocol distribution (TCP/UDP/ICMP)
• Top network services
• Bandwidth timeline
• All connected devices table

Per-Device View

• Device metrics (packets, bandwidth, services, domains)
• Websites visited (DNS queries)
• Services used (port analysis)
• Traffic timeline
• Recent packets captured

🔧 Configuration

Edit config.py to customize:

# Scan frequency (seconds)
NETWORK_SCAN_INTERVAL = 30

# Network range (auto-detected by default)
DEFAULT_NETWORK_RANGE = "192.168.1.0/24"

# Maximum packets to keep in memory
MAX_PACKETS_STORED = 10000

🐛 Troubleshooting

"Permission denied" error

# Solution: Run with sudo
sudo /path/to/.venv/bin/streamlit run dashboard.py

Devices not showing

1. Check if nmap is installed: which nmap
2. Verify network range: hostname -I
3. Manual scan test: sudo nmap -sn 192.168.1.0/24
4. Click "🔄 Scan Now" button to force rescan

No traffic captured

1. Generate network traffic: ping google.com or curl https://google.com
2. Check packet capture interface
3. Verify running with sudo

Dashboard slow/freezing

1. Reduce MAX_PACKETS_STORED in config
2. Check system resources: free -h
3. Monitor logs for errors

📊 Service Port Mapping

Supports 24+ common services:

• HTTP/HTTPS (80, 443)
• SSH (22)
• DNS (53)
• FTP (20, 21)
• SMTP/POP3/IMAP (25, 110, 143)
• MySQL/PostgreSQL (3306, 5432)
• RDP (3389)
• MongoDB (27017)
• And many more...

🔐 Security Notes

• Packet Capture: Requires root/sudo - ensure you run in trusted environments
• DNS Logging: All DNS queries are captured - be aware of privacy implications
• Network Access: Only use on networks you own or have permission to monitor
• Data Storage: Packets kept in memory only - no persistent storage by default

🤝 Contributing

Improvements welcome! Feel free to:

1. Report bugs and issues
2. Suggest new features
3. Submit improvements
4. Optimize performance

📝 License

MIT License - See LICENSE file for details

👨‍💻 Author

NetLens Contributors - Professional network monitoring made simple.

---

Last Updated: April 2026
Version: 1.0.0
Status: Production Ready