graphtopo

Build network topology graphs from SNMP/LLDP/CDP discovery data, powered by NetworkX.

The Problem

Network engineers collect discovery data from routers and switches (LLDP neighbors, CDP neighbors, SNMP walks) but lack a clean way to transform that raw text into a structured, analyzable graph. graphtopo bridges this gap — parse discovery output, build a topology graph, analyze it for single points of failure, and export it for visualization or machine learning.

Installation

pip install graphtopo

For PyTorch Geometric export support:

pip install graphtopo[pyg]

For development:

pip install -e ".[dev]"

Quick Start

Build a topology from LLDP data

from graphtopo import LLDPParser, to_json

# Parse 'show lldp neighbors detail' output
with open("lldp-output.txt") as f:
    lldp_text = f.read()

parser = LLDPParser(local_device="core-sw1")
topo = parser.parse(lldp_text)

print(f"Discovered {topo.device_count} devices and {topo.link_count} links")

# Serialize to JSON
print(to_json(topo))

Build a topology programmatically

from graphtopo import TopologyGraph

topo = TopologyGraph()

# Add devices with attributes
topo.add_device("core-sw1", vendor="Cisco", model="C9500", ip="10.0.0.1", type="core")
topo.add_device("dist-sw1", vendor="Cisco", model="C9300", ip="10.0.1.1", type="distribution")
topo.add_device("access-sw1", vendor="Cisco", model="C9200", ip="10.0.2.1", type="access")

# Add links with attributes
topo.add_link("core-sw1", "dist-sw1", speed="10G", protocol="lldp",
              interface_src="Te1/0/1", interface_dst="Te1/0/1")
topo.add_link("dist-sw1", "access-sw1", speed="1G", protocol="lldp",
              interface_src="Gi1/0/1", interface_dst="Gi1/0/48")

# Query the topology
print(topo.neighbors("core-sw1"))       # ['dist-sw1']
print(topo.shortest_path("core-sw1", "access-sw1"))  # ['core-sw1', 'dist-sw1', 'access-sw1']

Analyze topology

from graphtopo import TopologyGraph, critical_nodes, redundancy_score, degree_centrality

topo = TopologyGraph()
# ... build topology ...

# Find single points of failure
spofs = critical_nodes(topo)
print(f"Critical nodes: {spofs}")

# Check redundancy level
score = redundancy_score(topo)
print(f"Redundancy score: {score:.2f}")  # 1.0 = tree, >1.0 = redundant paths

# Identify most connected devices
centrality = degree_centrality(topo)
for device, score in sorted(centrality.items(), key=lambda x: -x[1])[:5]:
    print(f"  {device}: {score:.3f}")

Export formats

from graphtopo import TopologyGraph, to_json, to_graphml
from graphtopo.exporters.networkx_export import to_networkx

topo = TopologyGraph()
# ... build topology ...

# JSON (serialization/API)
json_str = to_json(topo)

# GraphML (Gephi, yEd visualization)
to_graphml(topo, path="topology.graphml")

# Raw NetworkX DiGraph (full NetworkX API)
G = to_networkx(topo)

# PyTorch Geometric (GNN / machine learning)
from graphtopo.exporters.pyg_export import to_pyg
data = to_pyg(topo)  # Returns torch_geometric.data.Data

Supported Discovery Formats

Format	Parser	Input
LLDP	LLDPParser	show lldp neighbors detail
CDP	CDPParser	show cdp neighbors detail
SNMP LLDP-MIB	SNMPDiscovery	snmpwalk of LLDP-MIB
SNMP CDP-MIB	SNMPDiscovery	snmpwalk of CISCO-CDP-MIB

CLI

# Parse LLDP output to JSON
graphtopo parse lldp-output.txt --format lldp --local-device core-sw1

# Parse CDP output
graphtopo parse cdp-output.txt --format cdp -o topology.json

# Analyze a topology
graphtopo analyze topology.json

# Export to GraphML for visualization
graphtopo export topology.json --format graphml -o topology.graphml

Analysis Metrics

• Degree Centrality — How connected each device is
• Betweenness Centrality — Which devices are critical transit points
• Connected Components — Isolated network segments
• Critical Nodes — Articulation points (single points of failure)
• Redundancy Score — Ratio of edges to minimum spanning tree (1.0 = no redundancy)

Development

git clone https://github.com/cwccie/graphtopo.git
cd graphtopo
pip install -e ".[dev]"

# Run tests
pytest --cov=graphtopo

# Lint
ruff check src/ tests/

License

MIT License. Copyright (c) 2026 Corey Wade.