Automated Network Topology Documentation

Problem

Network teams spend hours manually documenting topology diagrams that go stale the moment a config changes. A large enterprise network can have thousands of interfaces, hundreds of VLANs, and dozens of VRFs — and the Visio diagrams are always out of date.

Solution

Built a Python CLI tool that reads a directory of Cisco IOS/IOS-XE running configs and show command outputs, correlates link relationships across devices, and generates multi-layer topology diagrams in draw.io format. Currently supports Cisco IOS and IOS-XE platforms — the most common enterprise switching and routing OS.

Feed it configs, get back accurate L1/L2/L3 diagrams — automatically.

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

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

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

Key Decisions

Multi-source correlation over single-source. Rather than relying solely on CDP (which may be disabled on some links), the tool cross-references three independent data sources and scores confidence. This catches links that any single method would miss.

Per-VRF L3 diagrams. In enterprise networks with VRF-Lite or MPLS, a single L3 diagram becomes unreadable. Each VRF gets its own diagram page with proper IP namespace isolation.

draw.io native format. Rather than generating images, the tool outputs editable .drawio XML files. Engineers can open them in draw.io (free) and adjust layouts, add annotations, or export to any format.

Offline-first design. The tool works entirely from pre-collected config files — no SSH access or live device connectivity required. This makes it safe to run in any environment without network access concerns.

Results

989 passing tests covering parsers, correlators, and diagram builders
Generates accurate topology diagrams from raw configs in seconds
Supports L1 (physical), L2 (switching), L3 (routing per VRF), and WAN overview views
Handles port-channel aggregation, HSRP/VRRP pairs, and routing protocol adjacency visualization
Multiple output formats: draw.io, Graphviz DOT, Mermaid
Includes config generation tool for replicating site configs with IP octet swapping
Demo data covering 7 sites and 29 devices for validation

How This Scales

The current tool is a solid CLI foundation. Planned expansion paths include:

Web interface — Upload configs through a browser, get diagrams back without installing anything. FastAPI backend with drag-and-drop file upload.
Multi-vendor support — Extend parsers to handle NX-OS, Juniper JunOS, and Arista EOS configs alongside IOS/IOS-XE.
Live device collection — SSH into devices via Netmiko/Napalm to pull configs directly, eliminating the manual export step.
SaaS model — Hosted diagram generation with per-site or per-device pricing, API access for CI/CD pipeline integration, and scheduled re-scans.

Tech Stack

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