netwalk

Three promises enforced in code

Netwalk is a read only network survey toolkit for Claude Code, though it also works with other agents and with no agent at all. You point it at one device you can log into, and it crawls the network hop by hop, reads the health of everything it finds, draws the topology, and produces a report you can hand to the site owner. The project makes three promises and backs each one with code rather than by asking the model nicely. The first promise is that it never changes anything. Every command is checked against a per vendor read only allowlist before it is sent. Config writes, clear counters, dmesg with clear, systemctl restart, reload, configure terminal, and shell metacharacters are all refused by the tool. Configuration is exported for reading and nothing is ever imported. The allowlist lives in scripts/netwalk_policy.py and is covered by tests/test_policy.py with 397 cases. The second promise is that credentials never touch the conversation. The login skill serves a one shot page on your own machine, you type the password into your browser, and it is written to a private file with mode 0600 on POSIX. The third promise is that it never sweeps a range nobody authorized, and a range outside the approved scope is refused with no override flag.

How a survey actually runs

A survey is one loop, not three separate phases. The login, scan, and diag steps repeat together until the frontier is empty. Netwalk crawls outward from one device you name, one hop at a time, using LLDP, CDP, MNDP, ARP, DHCP leases, routing tables, and per port MAC tables. A port that learned several MAC addresses but reports no LLDP neighbor is flagged as a suspected unmanaged switch. Then it sweeps the authorized address ranges with a TCP connect scan to find static servers, forgotten printers, and second firewalls that never announce themselves. About 68 well known TCP ports are checked by default, and risky services such as telnet, SMB, RDP, VNC, Redis, Winbox, and a database on a user VLAN are flagged. The sweep is blind to UDP and to hosts that drop rather than reject, and that limitation is written into the report coverage section automatically instead of being left implied. The config is then checked against a vendor best practice list held as data in netwalk_audit.py, so the same checks run on every site. Health is read from CPU, memory, storage, temperature, PoE budget, interface errors, link down counts, throughput, and logs, and every finding carries the command output that produced it. Findings from either default to public_safe false, because a hardening list is effectively a route map. At the end you get a deterministic SVG topology and a self contained HTML report that opens offline and follows the reader light or dark setting.

Installing and keeping credentials private

Installation is a clone followed by python3 install.py, which copies the runtime to the Claude skills directory and writes the six skill folders with real absolute paths baked in. The six skills are netwalk for the whole survey, netwalk login to collect credentials through a local browser form, netwalk scan to crawl the topology, netwalk diag to export config and find faults, netwalk map to draw the diagram, and netwalk fullreport to produce the HTML report. For agents other than Claude Code you pass an --agent flag such as cursor, codex, gemini, cline, copilot, windsurf, continue, aider, or generic, and the installer writes the matching rules file. The toolkit itself is plain Python that needs no agent. Requirements are Python 3.9 or newer with only the standard library, plus an OpenSSH client, and optionally paramiko, sshpass, or plink for password auth. Credentials live in a file at ~/.netwalk/creds/<site>.json with mode 0600, outside the repository. When the job is done you stop the credential form and run forget with --with-configs to overwrite and delete both credentials and the read only config exports. The README is blunt that deleting is not rotating, so you should rotate any real passwords rather than assume the delete was enough.

Editorial conclusion

Netwalk is a read only network survey toolkit for Claude Code and other agents, licensed under MIT. It installs with python3 install.py and crawls from one device while a per vendor allowlist refuses any command that would change the network.