LLDP Network Mapper

SSH-based network topology mapper for FS switches (and IOS-like CLIs). Discovers switch topology via LLDP, stores in SQLite, and visualises with Cytoscape.js.

Quick Start

1. Configure

Copy config.py.example to config.py and fill in your values:

cp config.py.example config.py
nano config.py

NOCODB_URL   = "http://your-nocodb-host:8080"
NOCODB_TOKEN = "your-api-token"

SSH_USERNAME = "admin"
SSH_PASSWORD = "your-ssh-password"
SSH_PORT     = 22
SSH_TIMEOUT  = 30
DEVICE_TYPE  = "cisco_ios"

Switch IPs are pulled automatically from NocoDB — no manual list needed. See NocoDB Requirements below.

2. Build and run

docker compose up -d --build

3. Open the UI

Navigate to: http://your-host-ip:5000

Click Scan Now to start discovery.

What it does

SSHs into each switch in parallel (up to 10 at once)
Runs show lldp neighbors and show ip interface brief
Parses neighbors, hostnames, management IPs, chassis IDs
Stores everything in SQLite (data/network.db)
De-duplicates bidirectional links automatically
Renders an interactive Cytoscape.js topology diagram
Exports to CSV, Mermaid (.md), and Graphviz PNG

Outputs

All files written to data/exports/:

File	Purpose
`topology.csv`	Switch links with hostnames and IPs
`topology.md`	Mermaid diagram (paste into any markdown viewer)
`topology.dot`	Graphviz source
`topology.png`	Rendered network diagram

Auto-scan

Toggle auto-scan on/off from the UI. Set interval (15 min to 6 hours). State persists across container restarts.

NocoDB Requirements

Switch inventory is loaded from NocoDB automatically. The table must have:

Column	Description
`IP`	Switch management IP — required
`Hostname`	Switch hostname
`Active`	Must be `YES` to be included in scans
`Dept`	Department code (e.g. `ELEC`, `GW`) — used for filtering
`Location`	Physical location label
`Model`	Switch model
`Manufacturer`	Switch manufacturer
`Asset Tag`	Asset tag

The NocoDB base ID and table ID are hardcoded in nocodb_client.py — update them there if you point this at a different NocoDB instance.

Troubleshooting

No switches loaded: Check NOCODB_URL and NOCODB_TOKEN in config.py. NocoDB must return at least one row with Active=YES and a non-empty IP.

Auth errors: Check SSH_USERNAME / SSH_PASSWORD in config.py.

Timeout errors: Increase SSH_TIMEOUT in config.py (default: 30s).

Wrong device type: If your switch uses a non-IOS CLI, try changing DEVICE_TYPE to "linux" or "generic" in config.py.

No management IP found: The script looks for Vlan interfaces in show ip interface brief. If your switch uses a different command, edit parser.py → parse_mgmt_ip_from_interfaces().

Project Structure

lldp-mapper/
├── app.py              # Flask API + scheduler
├── db.py               # SQLite operations
├── parser.py           # LLDP output parser
├── ssh_client.py       # Netmiko SSH + parallel scan
├── scanner.py          # Orchestrator
├── exports.py          # CSV / Mermaid / Graphviz
├── config.py           # Switch IPs + credentials (not committed)
├── config.py.example   # Config template
├── index.html          # Cytoscape.js frontend
├── data/               # SQLite DB + exports (created at runtime)
├── Dockerfile
├── docker-compose.yml
└── README.md

3.5 KiB Raw Blame History