Network documentation generated from the network itself

The problem

Network diagrams are usually drawn by hand, once, and age the first time a port is repatched. Authorization packages, customer questionnaires and zone-and-conduit models all ask for a current, defensible picture of what connects to what.

Scanning alone does not close the gap. A sweep finds addresses that answer; it cannot say which switch port a host sits on, which router owns a subnet, or whether two addresses are one device. Those facts live in the devices’ own routing, forwarding and neighbor tables.

A discovery tool is also a risk: it holds credentials, emits traffic, and can wander outside its intended scope.

What was built

A self-contained local web application that documents an operator’s own network in one pipeline:

1. Discover. An asynchronous TCP-connect and ICMP sweep of declared address blocks, for liveness only. The output is candidate management targets, never topology.
2. Authenticated pull (primary). Read-only SSH and SNMP sessions to routers and switches collect routing, ARP, MAC forwarding and link-layer neighbor tables; where a platform is centrally managed, its controller’s read API is used instead. Each neighbor and next-hop found becomes the next device to poll.
3. Detect (supplement). OS and service detection by nmap when present, otherwise a TTL, banner and OUI heuristic. Never allowed to overwrite device-reported facts.
4. Join. One de-duplicated L2/L3 graph.
5. Lay out and export. A single coordinate table drives PNG, JPG, an interactive browser map and native editable VSDX.

Design decisions

Device-reported facts outrank inference

Every attribute carries its source, confidence, evidence and timestamp. Merging is per attribute, not per host: the higher source tier wins, and lower tiers only record agreement or conflict. A scan-versus-device disagreement resolves to the device and flags the host.

De-duplication that does not fuse distinct devices

Devices are merged by union-find over their identities. The design review found that first-hop redundancy virtual MACs, plus multicast and locally administered addresses, would have collapsed separate routers into one node. Those are barred as identity keys; merges key only on management addresses and a device’s own interface MACs.

Switchports are classified from independent signals:

On the port	Interpretation
Neighbor-protocol sighting	Infrastructure link
One MAC, no neighbor	Edge host
Many MACs, no neighbor	Unmanaged switch, drawn as a placeholder

Unpolled neighbors are drawn and flagged, never dropped.

Safety gates in the structure, not the policy

• One egress point. A single module is the only code allowed to touch network primitives; a source-scanning test enforces it.
• Fail-closed, fixed scope. Scope cannot be widened mid-run. Public address space is refused without a typed override.
• Two-phase confirm. The plan step resolves targets and counts and sends nothing; confirm must present the exact scope hash. A dry run swaps transmission for a recorder.
• Audit before transmit. An append-only log records each probe before it leaves, with no secrets in it.
• Read-only by construction. No SNMP write path exists; an allowlist refuses any non-read SSH command before transmission.
• Credentials in memory by default. Never placed in URLs or process arguments; tests confirm secrets are redacted from logs and object representations. The headless mode reads them from a local file.
• Polite pacing. A global packet-rate ceiling and per-run concurrency limits; an auth-failure circuit breaker against account lockout is designed but not yet built.

Editable output, honestly described

The VSDX writer emits real shapes with glued connectors, not a picture. The first from-scratch package passed every structural check and was still rejected as corrupt; the writer now injects the drawing into a genuine blank Visio scaffold, verified with an independent Visio-file parser. A manual open and re-save in Visio remains the release test; it is not automated.

Evidence and limits

• An adversarial design review before the build found twelve problems, three rated as defects that would corrupt output or silently produce wrong topology, among them the virtual-MAC merge above. All three corrections became binding build rules.
• The offline self-test suite passes 351 checks with no failures, end to end on fixtures.
• The first live discovery and detection run found two faults the offline suite had missed: a call-signature bug in the egress gate and serial per-port timeouts that slowed sweeps. Both are fixed, the first with a regression test.
• Limits. The CLI and SNMP parsers are tested against representative fixtures, not yet against real device output. Some platform collectors are deferred. IP-based merging is not yet partitioned by network, so separately managed networks with overlapping private ranges should be mapped in separate runs. IPv6 is never swept, only read from device tables. Quiet hosts can be absent from forwarding and ARP tables. The tool runs on demand; it is not a monitor.

The open step is confirming the parsers against real output. A container lab rebuilt from versioned topology and configuration files is a reproducible place to do that before any production network.

Where it applies

• Authorization packages. A network diagram and component inventory generated from the devices, with source and timestamp on every attribute and an audit log of exactly what was touched, supports the system description and inventory (CM-8) in a NIST 800-53 or FedRAMP package, and can be regenerated and compared rather than redrawn.
• Manufacturing networks. IEC 62443 zone-and-conduit work and NIST 800-171 baseline and inventory requirements (3.4.1) start from an accurate network picture; equipment delivered to SEMI E187 still has to be placed in a documented network. Near production equipment, active detection can be switched off per run; declared scope, a reviewed plan, rate limits and read-only commands are the floor, not a guarantee of safety for fragile devices. The output also answers the “current network diagram” questionnaire item.
• Fractional security leadership. The first question in an inherited environment is what is actually there. This method answers it from the devices, records how, and stays in bounds.

Independent work by Wade Blackwell. Each write-up is written from scratch for this site, without client, employer or personal data. Names, hostnames, addresses and configuration detail are left out on purpose.