🛡️ NetMapper

Professional Network Discovery & Security Monitoring Tool

NetMapper is a real-time network device discovery and monitoring system built with Python. It provides passive and active network scanning capabilities with an intuitive web-based dashboard for visualizing network topology and detecting unauthorized devices.

---

✨ Features

• 🔍 Active Network Scanning - ARP-based device discovery across your local network
• 📡 Passive Traffic Monitoring - Real-time packet sniffing for automatic device detection
• 🎯 Device Tracking - Persistent device identification via MAC addresses
• 🚨 Alert System - Automatic alerts for new or suspicious devices
• 📊 Web Dashboard - Beautiful, responsive interface for network visualization
• 💾 SQLite Database - Lightweight, serverless data persistence

---

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Windows, Linux, or macOS
• Administrator/root privileges (for network scanning)

Installation

1. Clone or download the repository

   cd Net-Mapper

2. Create a virtual environment

   python -m venv .venv
   .venv\Scripts\activate  # Windows
   source .venv/bin/activate  # Linux/Mac

3. Install dependencies

   pip install -r requirements.txt

4. Start the application

   python run.py

5. Open your browser

   http://localhost:5000
   

---

📁 Project Structure

Net-Mapper/
├── 📂 core/                    # Core functionality
│   ├── discovery.py            # Active network scanning (ARP)
│   ├── passive_sniffer.py      # Passive traffic monitoring
│   ├── correlation_engine.py   # Device tracking & DB sync
│   └── __init__.py
│
├── 📂 db/                      # Database layer
│   ├── database.py             # SQLAlchemy models
│   └── __init__.py
│
├── 📂 web/                     # Web interface
│   ├── app.py                  # Flask application
│   ├── routes.py               # API routes
│   ├── __init__.py
│   ├── templates/             # HTML templates
│   │   └── dashboard.html
│   └── static/                # Static assets
│       ├── css/
│       ├── js/
│       └── img/
│
├── 📂 scripts/                 # Utility scripts
│   ├── quick_scan.py          # Quick network scan tool
│   └── start_monitor.py       # Start passive monitoring
│
├── 📂 docs/                    # Documentation
│   ├── INSTALLATION.md         # Installation guide
│   └── API.md                  # API documentation
│
├── 📂 data/                    # Database storage (auto-generated)
│   └── netmapper.db
│
├── 📄 run.py                   # Application entry point
├── 📄 config.py                # Configuration settings
├── 📄 setup.py                 # Package installation script
├── 📄 requirements.txt         # Python dependencies
├── 📄 LICENSE                  # MIT License
├── 📄 .gitignore               # Git ignore rules
└── 📄 README.md                # This file

---

🎯 Usage

Start the Dashboard

python run.py

Access the dashboard at: http://localhost:5000

Quick Network Scan (Requires Admin)

Windows:

# Run PowerShell as Administrator
python scripts\quick_scan.py

Linux/Mac:

sudo python scripts/quick_scan.py

Start Passive Monitoring (Requires Admin)

Windows:

# Run PowerShell as Administrator
python scripts\start_monitor.py

Linux/Mac:

sudo python scripts/start_monitor.py

Advanced Usage

See API Documentation for programmatic usage and Installation Guide for detailed setup instructions.

---

🔒 Security Considerations

⚠️ Important:

• NetMapper requires administrator/root privileges for raw packet access
• Only use on networks you own or have permission to monitor
• This tool is for educational and authorized security auditing only
• Unauthorized network scanning may be illegal in your jurisdiction

---

🛠️ Configuration

Database Location

The SQLite database is stored in data/netmapper.db. To change the location, edit web/app.py:

db_path = os.path.join(basedir, '..', 'data', 'netmapper.db')

Port Configuration

Default port is 5000. To change it, edit run.py:

app.run(debug=True, port=5000, host='0.0.0.0')

---

📊 Dashboard Features

The web dashboard provides:

• Device Overview - Total device count and active alerts
• Alert Feed - Real-time notifications for new devices
• Device Table - Comprehensive list with:
  • IP Address
  • MAC Address
  • Trust Level (NEW/KNOWN/SUSPICIOUS)
  • First & Last Seen timestamps

---

🔧 Technology Stack

• Backend: Python 3.8+, Flask 3.1
• Database: SQLite with SQLAlchemy ORM
• Network: Scapy for packet manipulation
• Frontend: HTML5, CSS3 (no external frameworks)

---

📝 Database Schema

Devices Table

• id - Primary key
• mac_address - Unique device identifier
• ip_address - Current IP (may change)
• hostname - Device name (if available)
• vendor - MAC vendor lookup
• trust_level - new/known/suspicious
• is_active - Current status
• first_seen - Initial detection timestamp
• last_seen - Most recent activity

Alerts Table

• id - Primary key
• device_id - Foreign key to devices
• alert_type - Alert category
• message - Alert description
• timestamp - When alert was generated
• resolved - Resolution status

---

🤝 Contributing

This is an educational project. Feel free to fork and modify for your needs.

---

📄 License

This project is for educational purposes. Use responsibly and ethically.

---

⚠️ Troubleshooting

"Permission Denied" Error

• Solution: Run as Administrator (Windows) or use sudo (Linux/Mac)

No Devices Found

• Solution: Ensure you're running with admin privileges and firewall isn't blocking

Dashboard Shows 404

• Solution: Make sure run.py is executed from the project root directory

Module Import Errors

• Solution: Activate virtual environment and reinstall dependencies

---

📞 Support

For issues or questions, please check the troubleshooting section above.

---

Built with 🔒 for network security education