ripmilla/netwalk/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

Chips turn red past CPU 80%, RAM 85%, storage 85%, 65 °C — so an overloaded box is visible in the picture, not just in a table.

Access points are grouped per switch

A site with a hundred APs draws a hundred boxes and a comb of a hundred lines: accurate, unreadable, and not what anyone opens a diagram for. Every AP whose only uplink is one switch is collapsed into a single node on that switch showing how many APs, the address range they occupy, the model mix, and how many are up versus down. The per-device detail is still in the report's inventory table — only the picture groups them.

An AP with more than one uplink (a mesh AP, or one with a second cable) is never collapsed: its extra link is exactly the thing a diagram exists to show. Pass --no-group-aps to draw every access point separately.

Conventions worth keeping

• One box per internet uplink. Primary and backup are separate boxes with ISP, IP and speed.

Never merge them into a single "INTERNET" cloud — which link is which is the whole point.

• Dashed = inferred. Any edge with discovered_via: "inferred" is drawn dashed, and inferred

devices (a suspected unmanaged switch) get a dashed red outline. Do not promote a guess to a solid line to make the picture tidier.

• Unreachable devices still appear, dashed, with the reason on the box. A device you could not

log into is part of the network and leaving it out makes the map a lie.

• `role` drives the layers, left to right: gateway/router/firewall →

l3-switch/controller → switch → ap/server/nas/nvr → everything else.

• Port names sit above a link, the link's own label below it. A short run between two adjacent

ranks would otherwise print the port name straight through the speed label.

Internet uplinks carry the operator's mark

Each WAN box shows the ISP's own wordmark next to its name, matched from wan_links[].isp against assets/logos/isp-<slug>.svg. Common Thai operators resolve through an alias table, so "AIS Fibre", "True Online" and "3BB Fiber" all find the right mark. An operator with no file gets a lettered chip — never a blank.

python3 {{TOOLKIT}}/scripts/netwalk_logos.py isp                       # the built-in set
python3 {{TOOLKIT}}/scripts/netwalk_logos.py isp "Fibre Co" --colour '#009688'

Get the real operator names from the device rather than guessing: on RouterOS the PPPoE client interfaces usually carry them as comments (/interface pppoe-client print detail), which also gives you the contracted speed. Read that, put it in wan_links[].isp and link_speed, and keep the PPPoE account names out of the record — those are credentials.

Logos

{{TOOLKIT}}/assets/logos/<vendor>.svg, 24×24 viewBox, one path or text element, monochrome so it can inherit the theme colour. Omada devices come back as vendor: "tplink", which the fetched logo set already covers. To add a vendor, drop in <vendor>.svg matching the vendor string in the record (or add an alias in LOGO_ALIAS in netwalk_map.py). No logo is not an error — the device gets a lettered chip.

If it looks wrong

• Boxes overlapping or the picture is enormous — usually many devices in one rank because

role is missing or everything is unknown. Fix the roles.

• Very tall (left to right) or very wide (top down) — one rank holds far more devices than the

others. Check the AP grouping did what you expected, then consider the other orientation.

• A device floating with no links — no topology_edges entry references it. Either you did not

derive the edge, or it genuinely is not connected to anything you scanned; say which.

• Wrong parent — a discovery frame seen on a bridge/VLAN interface was recorded as a direct

link. Prefer the physical port when the neighbour output names one.

• Text clipped — long hostnames are truncated on purpose to keep boxes uniform; the full name is

in the report's inventory table.