Network Diagram Generator

A Python CLI tool that parses Cisco IOS/IOS-XE running configs and show command outputs, then automatically generates multi-layer network topology diagrams in draw.io format.

Feed it a directory of device configs — get back L1 physical, L2 switching, and L3 routing diagrams with port-channels, VRF isolation, HSRP pairs, and routing protocol adjacencies.

Features

Multi-Layer Diagrams — Generates L1 (physical), L2 (switching), and L3 (routing) topology views
Multi-Source Link Discovery — Correlates CDP/LLDP neighbors, /30-/31 subnet matching, and interface descriptions with confidence scoring
VRF-Aware L3 — Separate routing diagram per VRF with proper IP namespace isolation
Port-Channel Aggregation — Groups physical links into logical bundles with member and speed data
HSRP/VRRP Pairs — Identifies and visualizes first-hop redundancy relationships
Routing Protocol Adjacencies — Color-coded OSPF, EIGRP, BGP, and static route visualization
Multi-Site Support — WAN overview diagram showing inter-site connectivity
Multiple Output Formats — draw.io (default), Graphviz DOT, Mermaid
Config Generation — Template-based site config generation with IP octet swapping

Tech Stack

Component	Technology
CLI	Typer + Rich
Config Parsing	ciscoconfparse2, ntc-templates, TextFSM
Graph Analysis	NetworkX (MultiGraph)
Diagram Output	lxml (draw.io XML), DOT, Mermaid
Testing	pytest, Ruff

Quick Start

# Install
git clone https://github.com/bradmccloskey/network-diagram-generator.git
cd network-diagram-generator
pip install -e .

# Generate diagrams from device configs
netdiag generate input_dir/ output_dir/

# Generate with specific format
netdiag generate input_dir/ output_dir/ --format dot

Input Directory Structure

input_dir/
├── site-01/
│   ├── router-01/
│   │   ├── running-config.txt
│   │   ├── show-cdp-neighbors-detail.txt    # optional enrichment
│   │   ├── show-ip-route.txt                # optional
│   │   └── show-interfaces-status.txt       # optional
│   └── switch-01/
│       ├── running-config.txt
│       └── ...
└── site-02/
    └── ...

Output

Each site gets a single .drawio file with tabbed pages:

L1 Physical — Device icons, physical links, port-channel bundles, speed labels
L2 Switching — Trunk links with VLAN ranges, access port VLANs, HSRP pairs
L3 Routing (per VRF) — IP subnet clouds, routing protocol adjacencies, static routes
WAN Overview — Cross-site connectivity between data center hubs

Architecture

Config Files ──► Parsers ──► Device Models ──► Correlator ──► Diagram Builders
                  │              │                  │               │
          ciscoconfparse2   Dataclasses      NetworkX          draw.io XML
          TextFSM/NTC      (Device,         MultiGraph         DOT / Mermaid
                            Interface,       with confidence
                            PortChannel...)  scoring

Project Structure

src/netdiag/
├── cli.py                    # Typer CLI (generate, config_gen commands)
├── models/
│   ├── device.py             # Device, Interface, PortChannel, RoutingProtocol
│   ├── enums.py              # DeviceType, LinkType, InterfaceMode
│   ├── topology.py           # TopologyLink, EdgeData
│   └── site.py               # SiteSummary for WAN overview
├── parsers/
│   ├── running_config.py     # Cisco running-config parser
│   └── show_commands.py      # TextFSM-based show command parser
├── normalize/
│   ├── interface.py          # Interface name normalization
│   └── hostname.py           # Hostname matching with serial awareness
├── correlator/
│   └── engine.py             # Topology correlation engine (CDP + subnet + description)
├── diagram/
│   ├── generator.py          # draw.io page assembly
│   ├── l1_builder.py         # L1 physical topology
│   ├── l2_builder.py         # L2 switching topology
│   ├── l3_builder.py         # L3 routing topology (per-VRF)
│   ├── wan_builder.py        # WAN overview
│   ├── styles.py             # draw.io style definitions
│   ├── layout.py             # Hierarchical layout engine
│   ├── legend.py             # Diagram legend builder
│   ├── dot_formatter.py      # Graphviz DOT output
│   └── mermaid_formatter.py  # Mermaid output
├── configgen/                # Site config generation tool
│   ├── generator.py
│   ├── ip_swapper.py
│   └── diff_reporter.py
└── io/
    ├── site_reader.py        # Input directory discovery
    ├── site_writer.py        # Diagram file output
    └── report_writer.py      # Topology reports & error logs

Link Discovery Methods

The correlator uses three methods to discover links, ranked by confidence:

Method	Confidence	Source
CDP/LLDP	Highest	Bidirectional neighbor confirmation
Subnet Matching	Medium	/30 and /31 point-to-point links (VRF-aware)
Description Parsing	Lowest	Pattern matching on interface descriptions

Parallel links between the same device pair are detected and optionally aggregated into port-channel bundles.

Diagram Styling

Cisco device type icons (router, switch, firewall, AP, etc.)
Known vs unknown device differentiation
Trunk links show VLAN ranges; access ports show VLAN ID + name
Routing protocol adjacencies color-coded by type (OSPF, EIGRP, BGP)
HSRP/VRRP pairs connected with dashed orange lines
Port-channels rendered with thick lines and member details
Auto-generated legend per diagram

Requirements

Python 3.11+
Cisco IOS/IOS-XE running-config files (required)
Show command outputs (optional, enriches topology data)

bradmccloskey/network-diagram-generator