netwalk-map

netwalk-map

Part of the netwalk read-only network survey toolkit. Toolkit lives at {{TOOLKIT}}.

Run it

python3 {{TOOLKIT}}/scripts/netwalk_map.py ~/.netwalk/sites/acme-hq/scan-2026-08-22.json \
  -o ~/.netwalk/sites/acme-hq/map.svg \
  [--public] [--title "Acme HQ — after the switch swap"] [--top-down] [--no-group-aps]

Output is one self-contained SVG: no external fonts, no scripts, no network requests. It opens in a browser, drops into a document, and follows the reader's light/dark setting. netwalk-fullreport embeds the same renderer, so the diagram in the report and the standalone file never drift apart.

--public drops the scan date and the unreachable-device count from the caption.

The record is the source of truth

The renderer draws only what the record says. Never hand-edit the SVG — fix the record and re-render, or the diagram and the report start telling different stories and the next scan silently reverts your edit.

Layout is deterministic and reads left to right, the way a packet travels: internet uplinks in a column on the left, then the gateway, then each layer of switching, then the edge. Devices are ranked by BFS depth from the gateway and ordered inside each rank to minimise crossings. A rank with more devices than fit in one column wraps into another column rather than running off the page. Same record in, same SVG out — so two scans of one site diff cleanly and a changed diagram means a changed network.

--top-down stacks it vertically instead, which suits a shallow network or a portrait page.

What the record needs for a good diagram

Field	Effect if missing
devices[].vendor	falls back to a lettered chip instead of a logo
devices[].hostname, mgmt_ip	the box is hard to identify
devices[].model, os_version	the version line is empty — and version is what people read a diagram for at upgrade time
devices[].role	everything lands in one flat rank and the layout stops meaning anything
devices[].health	no CPU/RAM/storage/temperature chips
topology_edges[].a_port / b_port	links have no port labels, so nobody can trace a cable from the picture
wan_links[]	no uplink boxes at all