Metadata-Version: 2.4
Name: netdiagrams
Version: 0.2.1
Summary: Generate network diagrams from NetBox: zoned draw.io drawings for audits, segmentation and documentation.
License-Expression: Apache-2.0
Project-URL: Homepage, https://netdiagrams.com
Project-URL: Source, https://github.com/segaudit-hq/netdiagrams-public
Project-URL: Guides, https://netdiagrams.com/tips/
Project-URL: Documentation, https://github.com/segaudit-hq/netdiagrams-public/blob/main/docs/reference.md
Project-URL: Issues, https://github.com/segaudit-hq/netdiagrams-public/issues
Keywords: netbox,netbox diagram,network diagram,network topology,draw.io,drawio,network documentation,network segmentation,purdue model,iec 62443,pci dss
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# 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

```bash
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:

```bash
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:

| Profile | For | Book |
|---|---|---|
| `manufacturing` (default) | Plants, with Purdue levels, an industrial DMZ and production cells | [Book 1](https://netdiagrams.com/books/manufacturing-network-diagrams/) |
| `education` | School districts and campuses | [Book 2](https://netdiagrams.com/books/school-network-diagrams/) |
| `warehouse` | Distribution centers, cross-docks and 3PL sites | [Book 3](https://netdiagrams.com/books/warehouse-network-diagrams/) |
| `retail` | Stores, with the payment zone kept apart | [Book 4](https://netdiagrams.com/books/retail-network-diagrams/) |
| `office` | Offices and branches | [Book 5](https://netdiagrams.com/books/small-office-network-diagrams/) |
| `bank` | Banks and credit unions, with teller, wire and card zones and the core processor's link | [Book 6](https://netdiagrams.com/books/bank-network-diagrams/) |
| `municipal` | Cities, towns and counties, with police (CJIS), public Wi-Fi and the utility boundary kept apart | [Book 7](https://netdiagrams.com/books/local-government-network-diagrams/) |
| `hotel` | Hotels, with payments, guests, guest rooms and building systems kept apart | [Book 8](https://netdiagrams.com/books/hotel-network-diagrams/) |
| `corporate` | Headquarters campuses and multi-site companies, with VRFs, a data center and branch WAN | [Book 9](https://netdiagrams.com/books/corporate-network-diagrams/) |
| `dealership` | Car dealerships, with F&I, the shop and the manufacturer's router kept apart | [Book 10](https://netdiagrams.com/books/car-dealership-network-diagrams/) |

```bash
netdiagrams --profile retail
netdiagrams sample --profile retail
```

## Common commands

| Command | What it does |
|---|---|
| `netdiagrams` | Build drawings for every NetBox site (same as `build`) |
| `netdiagrams doctor` | Check how your NetBox maps onto the template before drawing anything |
| `netdiagrams netbox-setup` | Write NetBox import files for the zones, roles and custom fields the template uses (`--apply` creates them; nothing existing is changed) |
| `netdiagrams gaps` | Write NetBox import files that close the data gaps the drawing lists |
| `netdiagrams share` | Copy a drawing with sensitive details removed |
| `netdiagrams draft` | Lay out a first draft automatically for a site with no drawing yet |
| `netdiagrams blank` / `stencils` | Start by hand without NetBox, using the draw.io shape library |
| `netdiagrams export` / `build --input` | Save NetBox data to JSON and build from it offline |

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](https://github.com/segaudit-hq/netdiagrams-public/blob/main/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](https://netdiagrams.com), one for each profile above, each with a free chapter and worksheets.

Once your zones are drawn, [SegAudit](https://segaudit.com) checks that your firewall configuration actually enforces them.

## How it compares to NetBox topology plugins

NetBox plugins such as [netbox-topology-views](https://github.com/netbox-community/netbox-topology-views) and [netbox_drawio](https://github.com/CESNET/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](https://netdiagrams.com/books/) 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:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

## License

Apache License 2.0. See [LICENSE](https://github.com/segaudit-hq/netdiagrams-public/blob/main/LICENSE) and [NOTICE](https://github.com/segaudit-hq/netdiagrams-public/blob/main/NOTICE). NetDiagrams is a product of SegAudit LLC.
