Real-Time Network Scanner & Monitor

Project Overview

This project is a comprehensive network scanning and monitoring tool written in Python. It provides real-time visibility into network devices, their status, and network performance metrics. The scanner uses multiple discovery methods to detect devices on a local network and continuously monitors their connectivity status.

Features

Core Functionality

• Multi-Method Device Discovery: Uses ARP scanning, nmap integration, and ping sweeps for comprehensive device detection
• Real-Time Monitoring: Continuously monitors device status with configurable scan intervals
• Device Information Gathering: Collects MAC addresses, hostnames, vendor information, and response times
• Port Scanning: Scans common ports on discovered devices to identify running services
• Network Performance Testing: Optional speed test integration using speedtest-cli
• Alerting System: Notifications when devices come online, go offline, or are newly discovered

Advanced Features

• MAC Address Vendor Lookup: Built-in OUI database with API fallback for vendor identification
• Response Time Tracking: Monitors and displays average response times for each device
• Historical Data: Tracks first seen, last seen timestamps for all devices
• Graceful Fallbacks: Works even when optional dependencies are missing
• Cross-Platform Support: Compatible with Linux, macOS, and Windows

Technical Architecture

Class Structure

NetworkDevice

Represents individual network devices with properties:

• IP address and MAC address
• Vendor information and hostname
• Online status and response time history
• Open ports and timestamp tracking

NetworkScanner

Main scanner class handling:

• Network discovery using multiple methods
• Device information management
• Monitoring and alerting functionality
• Performance tracking and statistics

Discovery Methods

1. ARP Scanning

   • Primary method using scapy library
   • Fallback to system ARP table parsing
   • Fast and reliable for local network devices

2. Nmap Integration

   • Uses nmap for comprehensive network scanning
   • Provides additional device information
   • Optional dependency with graceful fallback

3. Ping Sweep

   • Concurrent ping scanning across network range
   • Detects devices that don't respond to ARP/nmap
   • Uses ThreadPoolExecutor for performance

Dependencies

Required

• Python 3.6+
• Standard library modules: socket, subprocess, threading, ipaddress

Optional (with fallbacks)

• scapy - Advanced packet manipulation and ARP scanning
• dnspython - DNS reverse lookups for hostnames
• tabulate - Formatted table output
• speedtest-cli - Network speed testing
• nmap - System tool for advanced network scanning

Installation

1. Clone or download the project files

git clone <repository-url>
cd scanner

2. Install Python dependencies

pip install scapy dnspython tabulate speedtest-cli

3. Install system dependencies (optional)

# Ubuntu/Debian
sudo apt install nmap

# macOS
brew install nmap

# Windows
# Download from https://nmap.org/download.html

4. Set up execution permissions (Linux/macOS)

chmod +x scanner.py
chmod +x run_scanner_sudo.sh

Usage

Basic Usage

python3 scanner.py

Advanced Options

# Enable speed testing
python3 scanner.py --speed-test

# Custom scan interval (seconds)
python3 scanner.py --interval 60

# Combined options
python3 scanner.py --speed-test --interval 45

# Show help
python3 scanner.py --help

Using the Wrapper Script

For enhanced functionality requiring root privileges:

./run_scanner_sudo.sh

Output Format

The scanner displays a real-time table with the following information:

Column	Description
IP Address	Device IP address
MAC Address	Hardware address
Vendor	Device manufacturer
Hostname	Device hostname (if available)
Status	Online/Offline with visual indicators
Avg Response	Average ping response time
Open Ports	List of detected open ports
Last Seen	Timestamp of last successful contact

Example Output

📡 NETWORK SCANNER - LIVE MONITORING
================================================================================
Network: 192.168.1.0/24
Scan #5 | Total Devices: 12 | Online: 8 | Avg Scan Time: 15.3s
Last Scan: 2025-09-06 14:30:15

┌───────────────┬───────────────────┬─────────────────┬──────────────┬──────────┬──────────────┬─────────────┬───────────┐
│ IP Address    │ MAC Address       │ Vendor          │ Hostname     │ Status   │ Avg Response │ Open Ports  │ Last Seen │
├───────────────┼───────────────────┼─────────────────┼──────────────┼──────────┼──────────────┼─────────────┼───────────┤
│ 192.168.1.1   │ AA:BB:CC:DD:EE:FF │ Cisco           │ router.local │ 🟢 Online │ 2.3ms        │ 22, 80, 443 │ 14:30:15  │
│ 192.168.1.100 │ 11:22:33:44:55:66 │ Apple           │ iPhone       │ 🟢 Online │ 15.7ms       │ None        │ 14:30:12  │
└───────────────┴───────────────────┴─────────────────┴──────────────┴──────────┴──────────────┴─────────────┴───────────┘

Project Structure

scanner/
├── scanner.py              # Main scanner application
├── run_scanner_sudo.sh     # Wrapper script for elevated privileges
├── README.md              # This documentation
└── requirements.txt       # Python dependencies (if created)

Key Implementation Details

Network Discovery Algorithm

1. Auto-detect local network range using system routing information
2. Parallel ARP scanning using scapy or system commands
3. Concurrent ping sweep with ThreadPoolExecutor (50 workers)
4. nmap integration for comprehensive device enumeration
5. MAC address resolution for devices found via ping only

Performance Optimizations

• Concurrent execution for ping sweeps and port scans
• Background port scanning to avoid blocking main discovery
• Response time tracking with rolling averages
• Efficient data structures using sets and dictionaries
• Smart caching of vendor information and hostnames

Error Handling

• Graceful degradation when optional dependencies are missing
• Timeout management for all network operations
• Exception handling with informative error messages
• Fallback methods for each discovery technique

Security Considerations

• Local network only: Scanner operates within local subnet
• Non-intrusive scanning: Uses standard network protocols
• Root privileges: Some features may require elevated permissions
• Rate limiting: Built-in delays to avoid network flooding

Troubleshooting

Common Issues

1. Permission denied errors

   • Solution: Use the provided wrapper script or run with sudo
   • Example: sudo python3 scanner.py

2. No devices found

   • Check network connectivity
   • Verify network range auto-detection
   • Try running with elevated privileges

3. Slow performance

   • Reduce scan interval
   • Check network congestion
   • Disable unnecessary features

4. Missing dependencies

   • Scanner provides fallback functionality
   • Install optional dependencies for full features
   • Check error messages for specific missing packages

Future Enhancements

• Web interface for remote monitoring
• Database integration for historical data storage
• Email/SMS alerts for critical events
• Custom port lists and scanning profiles
• Network topology visualization
• SNMP integration for managed devices
• Configuration file support

Technical Specifications

• Language: Python 3.6+
• Architecture: Object-oriented with threading
• Performance: Scans 254 IPs in ~15-30 seconds
• Memory usage: Minimal (<50MB typical)
• Network protocols: ICMP, ARP, TCP
• Supported platforms: Linux, macOS, Windows

License

This project is created for educational and network administration purposes. Please ensure compliance with local network policies and regulations when using this tool.

Contributing

When submitting improvements or bug fixes:

1. Follow existing code style and conventions
2. Add appropriate error handling
3. Update documentation for new features
4. Test across different network environments
5. Consider performance implications

Author Information

• Project Type: Network Security and Monitoring Tool
• Development Language: Python
• Key Technologies: Socket programming, threading, network protocols
• Application Domain: Network administration and security monitoring

---

This documentation provides a comprehensive overview of the Real-Time Network Scanner project, suitable for academic or professional project submissions.