nettopo

A Python CLI that reads saved Cisco show command outputs (files only — no live device connections in v1) and generates network diagrams in draw.io format with Cisco icons, plus the intermediate data as CSV tables.

Four diagram views are produced from the same parsed data model:

• L2 — physical/link-layer topology from CDP/LLDP, with interface labels and MLAG.
• STP — per-VLAN Rapid-PVST spanning-tree state (root, bridge IDs, priorities, port roles/states).
• HSRP — first-hop redundancy per SVI (virtual IP, priority, active/standby/listen).
• BGP — BGP neighbor (session) graph.

nettopo is a working title — see PROJECT_SPEC.md section 1.

Status

Phase 4 — STP. nettopo stp -i <dir> now renders real per-VLAN spanning-tree draw.io diagrams: the root bridge is highlighted, links are colored by forwarding vs blocking port state and labeled with role/state at each end, and --vlan N or --group-mode per-vlan|strict|topology (with --all to write every resulting diagram) select which VLANs are rendered. stp.csv now includes both base and effective bridge priority. nettopo l2 -i <dir> (Phase 3) renders devices styled with Cisco icons (render/icons.py) by inferred DeviceRole, with per-end interface labels, --endpoints all|network-only filtering and --link-mode physical|port-channel (MLAG links drawn once per bundle). Output is post-processed by lucidify by default (--no-lucidify to skip it), which keeps each end's label attached to its own end of the link rather than merging both into one, and normalizes the geometry flag N2G gets wrong so the labels survive a Lucidchart import. hsrp, bgp, and all still report "not implemented". Both working views are shown end to end under Example diagrams, generated from the capture set in examples/campus/. See the delivery plan in PROJECT_SPEC.md and the open issues for the phased build-out.

Pending manual step: Cisco mxgraph.cisco19.* draw.io icons are a confirmed requirement but may degrade on Lucidchart import (Lucid uses a different shape library, and these icons are drawn by draw.io's own code rather than looked up as named stencils). This still needs a real Lucid import to validate, which requires interactive Lucid access this project's automation doesn't have — see the checklist in docs/architecture.md.

Installation

pip install nettopo

Pre-releases (0.3.0rc1 and the like) are published from the same pipeline but pip skips them unless asked: pip install --pre nettopo, or pin the exact version. Each release is published to PyPI by .github/workflows/publish.yml when a v* tag is pushed. To install from source for development:

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

Requires Python 3.11+.

Example diagrams

examples/campus/ is a complete, self-contained capture set for a six-switch campus: two core switches joined by a port-channel, two distribution switches, two access switches, plus an edge router, two ESXi hosts and a third access switch that no capture covers — ten devices in total. Every image below is nettopo's own output, and the .drawio files behind them are committed in examples/campus/diagrams/. Regenerate them with:

nettopo l2  -i examples/campus -o examples/campus/diagrams
nettopo l2  -i examples/campus -o examples/campus/diagrams --endpoints network-only --link-mode port-channel
nettopo stp -i examples/campus -o examples/campus/diagrams --all

The PNGs are exports of those same files, made with draw.io Desktop's CLI — leaving out -t/--transparent is what gives them a white background:

drawio -x -f png -s 2 -b 20 -o examples/campus/diagrams/l2/l2_full.png examples/campus/diagrams/l2/l2_full.drawio

A PNG is a snapshot. Open the .drawio in draw.io for the editable diagram — draggable nodes, and the hover tooltips that carry a port-channel's member interfaces.

nettopo l2 — physical topology

Ten nodes, thirteen links; each link is labeled with the physical interface at each end, and each node is drawn with the icon for its role. The role comes from the chassis the device reports — cisco C9500-16X for the core pair, cisco WS-C2960X for the access switches, cisco ISR4331/K9 for edge-rtr, VMware ESX for the two ESXi hosts — falling back to the capabilities its neighbors advertised over CDP/LLDP when the platform names nothing recognizable. A legend names every role the diagram actually contains.

Source: l2/l2_full.drawio.

nettopo l2 --endpoints network-only --link-mode port-channel

The same topology with the two flags applied: the ESXi hosts are gone (they advertise neither Router nor Switch), and the two physical core links have collapsed into the single bundle both switches call Po1. Its member interfaces move into the link's draw.io hover tooltip (Gi1/0/1 — Gi1/0/1, Gi1/0/2 — Gi1/0/2), which the PNG below cannot show but the .drawio does. Eight nodes, ten links.

Source: l2/l2_network-only_port-channels.drawio.

nettopo stp --vlan 10 — spanning tree for the user VLAN

Switches only: edge-rtr and the two ESXi hosts are gone. core-sw1 is the root bridge (gold card); every other node carries its bridge MAC and effective priority. acc-sw3 has no capture of its own, so it is drawn faded, in italics, and labeled with its name alone — it is included because the port facing it (dist-sw2 Gi1/0/22) is not an Edge port, the same filter that keeps the ESXi hosts out. Green links forward at both ends; red links have a blocked end. The three blocked ports are what breaks the two loops in the topology. The legend lists only the markings this particular tree uses.

Source: stp/stp_vlan10.drawio.

Note that the core-to-core link is drawn once, labeled Po1: spanning tree treats a bundle as one logical port, and show spanning-tree only ever names Po1 while CDP/LLDP only ever name Gi1/0/1/Gi1/0/2. show etherchannel summary is what joins the two — drop it from core-sw1.txt/core-sw2.txt and this link disappears.

nettopo stp --vlan 30 — the same network, a different tree

VLAN 30 is rooted on core-sw2 (spanning-tree vlan 30 root primary, with core-sw1 as secondary). Same devices, same cabling, different tree: the blocked ports move from Gi1/0/2 to Gi1/0/1 on both distribution switches, and the core port-channel reverses role. This is why the view renders one diagram per VLAN rather than a single "STP diagram".

Source: stp/stp_vlan30.drawio.

What --group-mode does to this capture set

The example has four VLANs, and VLANs 10, 20 and 99 produce the identical picture above — only VLAN 30 differs. VLAN 99 is the interesting case: its tree matches 10 and 20 exactly, but nobody configured core-sw2 as its secondary root, so its priorities differ. That is precisely the line between the two grouping modes:

Usage

nettopo [--version] [--log-level LEVEL] <command> [options]

Every command reads a directory of saved capture files (see Preparing captures below) and writes into an output directory, creating it if needed. parse, l2, and stp are implemented; hsrp, bgp, and all are scaffolded but not yet implemented (running them prints '<command>' is not implemented yet. and exits with status 1 — see Status).

Global options

Options common to every command

nettopo parse

Ingests captures, builds the data model, and writes every CSV table — no diagrams. This is the primary debugging aid: if a diagram looks wrong, inspect the CSVs first to localize the fault to parsing vs. rendering.

nettopo parse -i ./captures -o ./output

Writes output/csv/devices.csv (including each device's serial, from its own show version or from the name a Nexus neighbor advertises; its platform, from its own show version or from the CDP/LLDP report of a neighbor; and its management IP, from CDP's Management address(es) block or LLDP's management TLV), interfaces.csv, neighbors.csv, vlans.csv, stp.csv (base and effective bridge priority — see PROJECT_SPEC.md §6), and header-only hsrp.csv/bgp.csv until Phases 5–6 add those parsers.

One row per device and per adjacency, regardless of how many names its neighbors use for it: CDP and LLDP disagree constantly (nxos-core1 vs nxos-core1(FDO21120U5D) vs nxos-core1.example.com), and those spellings are correlated into one device before the model is built — see PROJECT_SPEC.md §5.2.

nettopo l2

Renders the physical/link-layer topology (from CDP/LLDP) as a draw.io diagram: nodes are devices styled with Cisco icons by inferred role, and links carry per-end interface labels. Needs show cdp neighbors detail and/or show lldp neighbors detail in the captures — see Which commands each subcommand needs.

nettopo l2 -i ./captures --endpoints network-only --link-mode port-channel

Writes output/l2/l2_full.drawio (endpoints all) or output/l2/l2_network-only.drawio (endpoints network-only); under --link-mode port-channel the filename gains a _port-channels suffix (l2_full_port-channels.drawio), so both link modes of the same topology can live side by side in one output directory.

Port-channel mode needs show etherchannel summary (IOS/IOS-XE) or show port-channel summary (NX-OS) in the capture — without it no bundles are known and the diagram is identical to physical. Bundle membership is also exported in interfaces.csv (po_id, po_members), which is the quickest way to check whether that command was captured and parsed. The tooltip is a draw.io feature: hover the link in draw.io to see which physical ports the bundle carries.

nettopo stp

Renders per-VLAN Rapid-PVST spanning-tree diagrams: switches only, root bridge highlighted, links colored by forwarding (green) vs. blocking (red) port state and labeled with role/state at each end. Node labels show the bridge MAC and effective priority (base priority is in stp.csv).

Needs show spanning-tree and a neighbor-discovery command (show cdp neighbors detail / show lldp neighbors detail) in the captures: spanning-tree output alone never says who is on the other end of a port, so without CDP/LLDP the diagram has nodes and no links. If the switches are joined by port-channels, show etherchannel summary (IOS/IOS-XE) or show port-channel summary (NX-OS) is required as well — spanning-tree names the bundle (Po1) while CDP/LLDP name its members (Gi1/0/1), and only the bundle table connects the two. See Which commands each subcommand needs.

Each port-channel is drawn as a single link labeled with the bundle name, with the member interfaces in the link's hover tooltip: spanning-tree treats a bundle as one logical port, so drawing one line per member would misrepresent it.

Switches that appear only in a neighbor's CDP/LLDP output — no capture of their own — are included faded, in italics and labeled with their name alone, since there is no bridge data to show for them. They are reached only through ports that are not Edge/PortFast, which is what keeps phones, access points and servers out of a spanning-tree diagram.

If the root bridge is one of those uncaptured switches, it is highlighted only when an LLDP chassis address matches the root address exactly. Without a match the run logs a warning naming the root's MAC and highlights nothing, rather than guessing.

A diagram with several nodes and no links is always reported as a warning. To see why each individual link was dropped, raise the log level — note that --log-level is a global option, so it goes before the subcommand:

nettopo --log-level DEBUG stp -i ./captures --all

Either --vlan or --all is required — with neither, there's no single sensible default to render out of a potentially many-VLAN model, so the command exits with an error asking you to pick one.

nettopo stp -i ./captures --vlan 10                       # one diagram, VLAN 10 only
nettopo stp -i ./captures --all                            # one diagram per VLAN
nettopo stp -i ./captures --all --group-mode strict         # grouped by exact match
nettopo stp -i ./captures --all --group-mode topology       # grouped by topology only

Filenames: output/stp/stp_vlan10.drawio for a single VLAN; for a group, a sorted, filesystem-safe name listing every VLAN it covers, e.g. output/stp/stp_vlans-10_20_30.drawio.

nettopo hsrp, nettopo bgp, nettopo all — not yet implemented

These subcommands parse their arguments (hsrp already accepts the same --vlan/--group-mode/--all options as stp) but every run currently exits with status 1 and logs '<command>' is not implemented yet.. They land in Phases 5–7 — see PROJECT_SPEC.md §14.

Preparing captures

The -i/--input directory holds one text file per device. Each file concatenates the outputs of several show commands, each preceded by that device's prompt line (hostname#show ...) — this is how nettopo both identifies the device as a source device (as opposed to one only ever mentioned by a neighbor) and splits the file back into per-command sections. tests/fixtures/captures/ has worked examples. Files are read as utf-8-sig, so a leading UTF-8 BOM is handled transparently.

Which commands each subcommand needs

Nothing is mandatory: a missing command means the data it feeds is simply absent (empty CSV columns, missing links, a view with nothing to draw), never an error. The table below is what each subcommand needs to produce a complete result.

stp needs CDP/LLDP too. show spanning-tree reports a device's own bridge and port roles/states, but never says who is on the other end of a port — on its own it yields nodes and no edges. The STP view draws its links from the CDP/LLDP topology and labels each end with the spanning-tree state found there, so without a neighbor discovery command you get a diagram of disconnected boxes.

stp needs the bundle table when links are bundled. The join between the two sources above is the interface name, and for a port-channel the two sources disagree: spanning-tree only ever says Po1, CDP/LLDP only ever say Gi1/0/1. show etherchannel summary (or show port-channel summary) is what maps one to the other. Without it, a fully bundled network produces the same disconnected boxes — every switch drawn, not one line between them.

What each command contributes, whichever subcommand you run:

A capture covering everything implemented today:

sw1-access#show version
...
sw1-access#show cdp neighbors detail
...
sw1-access#show lldp neighbors detail
...
sw1-access#show ip interface brief
...
sw1-access#show interfaces
...
sw1-access#show vlan brief
...
sw1-access#show spanning-tree
...
sw1-access#show etherchannel summary
...

Three things that trip captures up

• Run each command with no arguments. A prompt line has to match the command in full, so show spanning-tree vlan 10 is not recognized as show spanning-tree and that section is skipped silently. Capture the unfiltered output and let nettopo do the per-VLAN split.
• Abbreviations are fine. show ver, show cdp neigh det, show ip int br and show span all match, so a capture taken by typing short forms works as-is.
• One section per command per file. Only the first matching section is read; a command captured twice contributes its first occurrence only.

The prompt line drives all of this, so keep it — the filename is only a fallback for naming a device whose file has no prompt line at all. Both hostname# and hostname> work.

See PROJECT_SPEC.md §9 for the CLI design rationale.

Documentation

• examples/ — runnable capture sets, including the one behind the diagrams above.
• PROJECT_SPEC.md — scope, architecture, data model, CLI, delivery plan.
• docs/architecture.md — components, call flow, design decisions.
• CLAUDE.md — engineering conventions (workflow, coding principles, security review).
• CHANGELOG.md — release history.

Contributing

Work is tracked as GitHub issues, one per delivery-plan phase (see PROJECT_SPEC.md section 14). Each change lands via a pull request from a feat/…/fix/… branch into main; direct pushes to main are disabled. See CLAUDE.md for the full workflow and coding conventions.

Security

This tool makes zero network connections by design — it only reads local capture files. See PROJECT_SPEC.md for the full OWASP-adapted security review.

License

MIT