NetDiagrams

Network diagrams from your NetBox data, drawn to one consistent standard in draw.io.

NetDiagrams is a free, open-source command-line tool that generates network diagrams from NetBox. You already keep your devices, cables, VLANs and sites in NetBox. NetDiagrams turns that data into a full set of drawings that look like an engineer drew them by hand: overview, logical, physical, hardware, wireless, flows, failover and multi-site sheets, each with registers and title blocks. Run it again whenever NetBox changes, and the drawings follow.

• Works with free, self-hosted NetBox. It needs only a read-only API token.
• Read-only. It sends GET requests to NetBox, never changes it unless you opt in with netbox-setup --apply, and never connects to your network devices.
• No dependencies. Pure Python 3.9+, standard library only.
• Opens anywhere draw.io does: the desktop app, diagrams.net, Confluence, or exported HTML.

How to draw a network diagram from NetBox

pip install netdiagrams
netdiagrams

The first run asks for your NetBox URL and an API token and remembers them. It then writes one drawing per NetBox site, <site>.drawio, plus a <site>.drift.md report of anything the template and NetBox disagree on. Open the drawing in draw.io.

No NetBox handy? See what a finished drawing looks like with a fictional site:

netdiagrams sample -o plant-a.drawio

The sample is only a demo. NetDiagrams never uses it unless you ask for it.

What you get

• A drawing standard, not a random layout. NetDiagrams fills a bundled template, so every site comes out with the same sheets, shapes and colors. Your site's names replace the template's, and NetBox devices take the template slot of the same role.
• Everything typed comes from NetBox. Device fields, management IPs, serials, modules and optics, circuits, VLAN tables per zone, asset and link registers, and title blocks. Every shape links back to its NetBox object.
• Security zones you can see. Zones come from NetBox tags or custom fields, with a flow register of what is allowed between them.
• Any size fits. Repeated cells and closets are drawn once as a TYPICAL with a schedule row per copy, so a 3,000-device site still prints on the same set of sheets.
• Data quality, day to day. A quality sheet scores the site and lists what NetBox is missing. netdiagrams gaps writes the NetBox import files that fill those gaps.
• Audit evidence. An optional sheet shows owners, compliance scope, backups, patching, support contracts and monitoring for every asset.
• Safe to share. netdiagrams share makes a copy without IPs, serials, circuit IDs or NetBox links, ready to send to a vendor.

Industry profiles

Every kind of site groups its zones differently, so each industry has its own template, stencils and example site:

netdiagrams --profile retail
netdiagrams sample --profile retail

Common commands

If your NetBox uses its own role names or custom field names, map them in a small netdiagrams.json file. netdiagrams doctor --save-settings netdiagrams.json proposes one for you.

The full guide to every option, setting and sheet is in docs/reference.md.

Learn the method

The drawings follow a method for documenting segmented networks: what to draw on each sheet, how to name zones, and how to keep drawings current. It is written up as a series of ten industry guides at netdiagrams.com, one for each profile above, each with a free chapter and worksheets.

Once your zones are drawn, SegAudit checks that your firewall configuration actually enforces them.

How it compares to NetBox topology plugins

NetBox plugins such as netbox-topology-views and netbox_drawio are installed on the NetBox server and draw a topology from inside NetBox. NetDiagrams takes a different approach, and you can use it alongside them:

• Nothing to install on NetBox. It runs on your laptop or a CI job and reads the REST API with a read-only token.
• A finished document set, not one graph. Each site gets overview, logical, physical, hardware, wireless, flow, failover and multi-site sheets, with registers and title blocks.
• Security zones first. Sheets are grouped by zone, such as Purdue levels for a plant or the cardholder data environment for a store, with a register of the flows allowed between zones.
• Editable output. The result is an ordinary draw.io file you can annotate, print or attach to an audit.

FAQ

Does NetDiagrams need a NetBox plugin? No. It talks to the NetBox REST API from outside, so it works with NetBox you host yourself and with hosted NetBox, as long as you can create an API token. Both classic tokens and the newer nbt_ tokens work.

Can it draw a Purdue model or IEC 62443 zones and conduits diagram? Yes. The default manufacturing profile draws Purdue levels, the industrial DMZ and production cells, with a flow register for the conduits between zones.

Can it draw a PCI DSS segmentation diagram? Yes. The retail, hotel and bank profiles keep the payment and card zones apart and show what is allowed to cross into them.

Does it change anything in NetBox or on my network? No. It only reads from NetBox and never connects to network devices. The one exception is netbox-setup --apply, which you run on purpose and which only creates missing objects.

Is it free? Yes. NetDiagrams is open source under the Apache License 2.0. The industry guides that explain the method are sold separately, and each one has a free chapter.

Contributing

Bug reports and pull requests are welcome. Run the tests with:

PYTHONPATH=src python3 -m unittest discover -s tests

License

Apache License 2.0. See LICENSE and NOTICE. NetDiagrams is a product of SegAudit LLC.