118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
cp config.py.example config.py
|
|
nano config.py
|
|
```
|
|
|
|
```python
|
|
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](#nocodb-requirements) below.
|
|
|
|
### 2. Build and run
|
|
|
|
```bash
|
|
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
|
|
```
|