Skip to content

README.md

Latest commit

 

History

History
245 lines (190 loc) · 7.34 KB

README.md

File metadata and controls

245 lines (190 loc) · 7.34 KB
Raw

📡 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