netscantools

A local-first control panel for discovering, understanding, and organizing your LAN.

netscantools (eG::39 / netPad) brings network discovery, device identity, manual inventory, security hygiene, presence tracking, and address planning into one private web interface. It is designed for home labs and small local networks, with SQLite storage and no required cloud service.

• Windows
• Python 3.12 or newer
• Node.js with npm
• Access to the local network you want to scan

git clone https://github.com/erop39/netscantools.git
cd netscantools
.\start.bat

You can also launch directly:

python run.py

The launcher creates the backend virtual environment, installs missing backend and frontend dependencies, starts both development servers, and opens the browser.

Initial local login:

Username: admin
Password: admin

Useful options:

python run.py --no-browser
python run.py --api-port 8001 --ui-port 5174
python run.py --skip-install

If a requested port is already busy, the launcher selects the next available port and prints the resulting URL.

1. Sign in and change the default password.
2. Open Settings and set your network in CIDR notation, for example 192.168.1.0/24.
3. Choose the quick/full scan port sets and, if wanted, a scan interval.
4. Run a scan from Scans.
5. Add names, icons, locations, ownership flags, and notes as devices are identified.

The initial scan subnet is 192.168.1.0/24. Automatic scanning is disabled until a non-zero interval is configured.

Backend process settings are loaded from backend/.env. Start from the supplied template:

Copy-Item backend\.env.example backend\.env

Set credentials and the JWT secret before the first launch when possible. Existing account passwords are managed from the application, not overwritten on every restart by .env.

Runtime data is stored locally. With the default configuration, the primary database is backend/data/netpad.db; scheduled and manual copies are placed under backend/data/backups/.

flowchart LR
    Browser[React web UI] -->|/api| API[FastAPI]
    API --> DB[(SQLite)]
    API --> Scheduler[APScheduler]
    Scheduler --> Scanner[Discovery and diagnostics]
    API --> Scanner
    Scanner --> LAN[Local network]

The launcher binds the API and UI to 127.0.0.1 by default. Vite proxies /api calls to FastAPI, including when the launcher moves the API to another local port.

cd backend
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

In a second terminal:

cd frontend
npm install
$env:NETPAD_API_URL = "http://127.0.0.1:8000"
npm run dev -- --host 127.0.0.1 --port 5173

cd backend
.\.venv\Scripts\python.exe -m pytest -q

cd ..\frontend
npm run lint
npm run build

• Keep the default loopback binding unless you intentionally configure protected remote access.
• Do not forward the development UI or API directly to the public internet.
• Prefer a trusted VPN such as WireGuard or Tailscale for remote LAN access.
• Use a strong account password and a unique, long JWT_SECRET.
• Restrict CORS_ORIGINS to the exact origins that serve the UI.
• Treat scan results, device names, MAC addresses, notes, and backups as private network data.

The app performs active network checks. Only scan networks and devices you own or are authorized to administer.

Current release: v0.9.0-beta.2.

• Changelog
• Design specifications
• GitHub releases
• Issue tracker

Docker deployment, VPN deployment guidance, Home Assistant integration, and multi-VLAN support remain roadmap work; see the changelog for current details.

This repository currently does not include an open-source license file. No permission is granted beyond rights provided by applicable law unless the project owner states otherwise.