======================================================================= 🌐 UbuntuWebServer - Flask Network Scanner

A modern, lightweight network device scanner built with Flask and Python. Detects all devices on your local network (IP, MAC, hostname, vendor, OS) and provides a clean, auto-refreshing web UI. Optional cron-based deep scans and tagging/notes for known hosts.

✅ PROJECT GOAL

Create a web-based dashboard that:

• Scans LAN for connected devices (IP, MAC, Hostname, Vendor, OS)
• Stores and displays known devices in a SQLite database
• Provides an editable UI for tagging/notes
• Supports automated OS scanning and refresh via cron
• Can run persistently with systemd or a background process

🛠 TOOLS & TECHNOLOGIES

🧱 ARCHITECTURE OVERVIEW

[ Ubuntu Server / Windows / Mac ] | [ Flask App - app.py ] | [ nmap scan → parsed into DB ] | [ SQLite + MAC Vendor DB ] | [ Auto-refresh Web UI /cron ]

🧪 INSTALLATION INSTRUCTIONS

1. Clone and Set Up Environment

git clone https://github.com/tjohnsonII/UbuntuWebServer.git cd UbuntuWebServer python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

2. Install System Dependencies (Linux/macOS)

sudo apt update sudo apt install nmap sqlite3 -y

3. Initialize the Database

bash init_db.sh

4. Run the Web App

bash run_flask.sh

Then open in browser: http://:5000

🔁 GITHUB SYNC & AUTO RESTART

To sync latest updates from GitHub and restart Flask: bash sync_from_github.sh

🔂 AUTOMATE DEEP OS SCANNING

To install cron job that scans every 30 minutes: bash install_cron.sh

This creates: */30 * * * * /usr/bin/python3 /home//UbuntuWebServer/deep_scan.py

🚀 ENABLE ON BOOT (systemd)

sudo cp flaskscanner.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable flaskscanner sudo systemctl start flaskscanner

🧾 ADD / EDIT KNOWN HOSTS

Run this to insert devices with notes: python insert_known_host.py

Prompts for:

• MAC
• IP
• Hostname
• Vendor
• OS
• Notes

📂 PROJECT LAYOUT

🌐 WEB UI FEATURES

• Auto-refresh every 15 seconds
• Search/filter by IP, MAC, hostname, vendor
• Bootstrap responsive design
• Color-coded vendor badges
• OS detection support
• Notes/comments per device

🛠 CROSS-PLATFORM NOTES

✔ Linux - Full support (cron, systemd, bash) ✔ macOS - Supported with brew install nmap sqlite3 ✔ Windows - Use Git Bash or WSL + Python 3.10+ - Adjust paths in bash scripts as needed - Flask auto-refresh supported

🩺 TROUBLESHOOTING

• Port 5000 busy? Run: lsof -i :5000 or sudo fuser -k 5000/tcp
• nmap not found? Run: sudo apt install nmap
• Python error? Verify Python 3.10+ and correct venv
• No output? Check scan logs in flask.log or run scanScript.py

⚠️ SECURITY WARNING

This tool is for private/internal LANs only. Do NOT expose to the public internet. There is no built-in authentication or encryption. Use firewalls, VPN, or nginx basic auth if needed.

📄 LICENSE

MIT License © 2025 Timothy Johnson II

🙋 AUTHOR

Timothy Johnson II Hosted PBX Engineer, 123NET GitHub: https://github.com/tjohnsonII