Network Sketcher Cisco Extension — bridge Cisco platforms to automatic network diagrams

Network Sketcher Cisco Extension is a growing collection of tools that turn
Cisco platform data into
Network Sketcher CLI commands,
so you can rebuild an accurate L1/L2/L3 topology — devices, links, VLANs, SVIs,
sub-interfaces, IP addressing and VRFs — in seconds instead of drawing it by
hand.

Each tool targets a different data source, can be used independently, and the
conversion runs entirely on local files (no live platform connection is
needed at conversion time). aci_converter, catc_converter,
meraki_converter and nd_converter additionally ship a read-only REST API
fetch that pulls the model straight from the platform into that file; the
others read a file you export from the platform.

All tools are standalone Python CLIs. Most run on the Python standard library
alone — cml_converter needs PyYAML and netbox_converter needs networkx;
see each tool's folder README.md for its exact Python version and
dependencies.

Tools in this extension

The extension is a monorepo: each tool lives in its own sub-directory with its
own README.md and requirements.txt. The folder README.md holds the full
details — installation, usage, supported formats, options, and known issues.
The per-tool sections further down are only a short visual preview that links
to each. Tools are listed alphabetically.

Each tool's section below shows a preview and links to its folder README.md
for installation and usage. Every tool produces Network Sketcher CLI
commands, so the
"Running the output in Network Sketcher"
guidance applies to all of them.

Community / third-party converters

Tools that target a data source that is not a Cisco platform live under
3rd_party/ instead of the repository root, so they stay
clearly separated from the Cisco-platform tools above. They follow the same
conventions (own README.md + requirements.txt, local-file conversion,
Network Sketcher CLI command output).

template_converter — scaffold for building new converters

template_converter/ is not a converter itself — it is a copy-paste
starting point for building a new "Platform X → Network Sketcher"
converter (Cisco or third-party) when this repository's toolset needs to be
extended. It documents the architecture every converter here shares (which
files are copy-verbatim vs. platform-specific), the credential/security
conventions, and the README conventions used repo-wide.

It is written primarily for AI coding agents to read and follow
directly — every converter in this repo was itself built by an AI agent —
though it works equally well as a reference for a human contributor. The
command-generation logic it documents (ns_command_builder.py's Phase 1–6
ordering and the numbered RULE N constraints referenced throughout the
shared code) is grounded directly in Network Sketcher's own AI Context
export — the [AI_Context]<master>.txt file produced by the
network-sketcher MCP server (get_ai_context / build_default_outputs),
which documents the full CLI command reference and syntax rules.

See template_converter/GUIDE.md for the full
authoring guide.

Tool 1 — aci_converter

Convert a Cisco ACI fabric into two Network Sketcher diagrams — the physical
underlay (spine/leaf/border-leaf/APIC + observed LLDP cabling) and the
logical overlay (Tenant → VRF → Bridge Domain → EPG, with contracts as a
[Flow_List] traffic matrix) — from a model pulled over the APIC's
read-only REST API (fetch_from_apic).

sample_aci.zip

Full documentation (installation, usage, the underlay/overlay model,
options, colour conventions, accuracy caveats, known issues) is in
aci_converter/README.md.

Tool 2 — catc_converter

Convert a Cisco Catalyst Center (formerly DNA Center) SD-Access campus into two
Network Sketcher diagrams — the physical underlay
(core/distribution/access/WLCs/APs + real observed cabling) and the logical
overlay (Virtual Network → anycast-gateway segments) — from a model pulled
over its read-only Intent REST API (fetch_from_catc).

Full documentation (installation, usage, the underlay/overlay model,
options, colour conventions, accuracy caveats, known issues) is in
catc_converter/README.md.

Tool 3 — cml_converter

Convert a Cisco Modeling Labs lab (topology YAML + any embedded
running-configs) into a ready-to-run Network Sketcher command script,
reconstructing L1/L2/L3 entirely from local files (no CML connectivity at
conversion time).

[L1L2L3_DIAGRAM]AllAreas_no_data_1.html

[DEVICE_TABLE]no_data_1.html

Full documentation (installation, usage, supported CML YAML formats, how
L2/L3 reconstruction works, output file list, known issues) is in
cml_converter/README.md.

Tool 4 — cv_converter

Build an OT network topology from Cisco Cyber Vision asset (networkNodes)
and activities CSV exports, laid out along the Purdue model / IEC 62443 /
CPwE zones (Enterprise → IDMZ → Industrial → Cell/Area) — entirely from local
files.

cv_sample_1.zip

Full documentation (installation, usage, zone classification logic, CPwE
infrastructure synthesis, attribute-sheet colours, the bandwidth caveat,
known issues) is in cv_converter/README.md.

Tool 5 — meraki_converter

Convert a Cisco Meraki organization into a ready-to-run Network Sketcher
command script (L1/L2/L3) — from a model pulled over the read-only Meraki
Dashboard API v1 (fetch_from_meraki), so the conversion is reproducible
offline (e.g. after a DevNet Sandbox reservation expires).

Full documentation (installation, usage, verification status, device
naming/colour conventions, options, known issues) is in
meraki_converter/README.md.

Tool 6 — nd_converter

Convert a Cisco Nexus Dashboard (NDFC / Fabric Controller) NX-OS VXLAN EVPN
fabric into two Network Sketcher diagrams — the physical underlay
(leaf/spine/border/border-gateway + real observed cabling) and the logical
overlay (VRF → Network/L2VNI → anycast gateway) — from a model pulled over
its read-only REST API (fetch_from_nd).

Full documentation (installation, usage, the underlay/overlay model,
options, colour conventions, accuracy caveats, known issues) is in
nd_converter/README.md.

Tool 7 — sna_converter

Reconstruct a multi-site L1/L2/L3 topology plus endpoints from observed
traffic instead of a device inventory: sna_converter reads a Cisco Secure
Network Analytics (SNA / Stealthwatch) NetFlow Flow Search CSV and produces
a Network Sketcher command script plus a [FLOW] traffic matrix — entirely
from a local file.

Full documentation (installation, usage, site inference logic, endpoint
naming conventions, supported CSV formats, the Max. bandwidth(Mbps)
formula, known issues) is in sna_converter/README.md.

3rd Party Tool 1 — netbox_converter

Convert a NetBox DCIM/IPAM instance into a ready-to-run Network Sketcher
command script reconstructing L1/L2/L3 — from a model pulled over its
read-only REST API (fetch_from_netbox).

Full documentation (installation, usage, placement/connection logic,
config keys, data coverage and known limitations) is in
3rd_party/netbox_converter/README.md.

Running the output in Network Sketcher

Every tool in this extension emits a plain-text ns_commands.txt script: one
Network Sketcher CLI command per line (lines starting with # are phase
comments and can be ignored). The commands are already in the correct
Phase 1 → 6 order, so run them top to bottom against a Network Sketcher master
file.

1. Install Network Sketcher by following the instructions in the
   cisco-open/network-sketcher
   repository.
2. Create (or choose) an empty master file, e.g. [MASTER]my_lab.nsm. Starting
   from a freshly created empty master keeps Phase 1 device/area placement on a
   clean canvas.
3. Run the non-comment lines of ns_commands.txt in order against that master.
4. Export the diagram to get the L1/L2/L3 viewer and device table.

Repository structure (monorepo)

network-sketcher-cisco-extension/
├── README.md            ← you are here
├── LICENSE / NOTICE / SECURITY.md / CODE_OF_CONDUCT.md / CONTRIBUTING.md
├── aci_converter/       ← Tool 1: ACI fabric (REST API) → underlay + overlay
├── catc_converter/      ← Tool 2: Catalyst Center (REST API) → underlay + overlay
├── cml_converter/       ← Tool 3: CML YAML → L1/L2/L3
├── cv_converter/        ← Tool 4: Cyber Vision CSV → OT (Purdue / IEC 62443)
├── meraki_converter/    ← Tool 5: Meraki org (Dashboard API) → L1/L2/L3
├── nd_converter/        ← Tool 6: Nexus Dashboard / NDFC (REST API) → underlay + overlay
├── sna_converter/       ← Tool 7: SNA / NetFlow CSV → commands + [FLOW] matrix
├── template_converter/  ← scaffold for building new converters (contributor tooling)
└── 3rd_party/           ← community / third-party converters (non-Cisco platforms)
    └── netbox_converter/  ← NetBox (REST API) → L1/L2/L3

Each converter folder is self-contained — its own README.md,
requirements.txt, a <tool>_to_ns_config.json, and Input_data/ +
Output_data/ directories — so it can be installed and used independently of
the others.

Getting help

• Open an issue on the
  GitHub issues
  page describing the problem, the tool and input format you used, and attach
  the relevant report file (each converter writes one — its name is given in
  the tool's folder README.md).

Credits and references

• Network Sketcher — the
  open-source Cisco network documentation tool these extensions target.
• Cisco Application Centric Infrastructure (ACI) / APIC
  — the SDN data-center platform whose APIC read-only REST API
  feeds aci_converter.
• Cisco Catalyst Center
  — the SD-Access campus controller whose read-only Intent REST API feeds
  catc_converter.
• Cisco Modeling Labs — the
  network simulation platform used as the data source for cml_converter.
• Cisco Cyber Vision
  — the OT/ICS visibility platform whose asset + activity exports feed cv_converter.
• Cisco Meraki — the cloud-managed networking
  platform whose read-only Dashboard API v1 feeds meraki_converter.
• Cisco Nexus Dashboard
  — the NDFC / Fabric Controller platform whose read-only REST API feeds
  nd_converter.
• Cisco Secure Network Analytics (SNA / Stealthwatch)
  — the NetFlow analytics platform whose Flow Search export feeds sna_converter.
• CiscoDevNet/cml-community —
  public CML labs used to validate the converter.
• NetBox — the open-source DCIM/IPAM platform whose
  read-only REST API feeds the community netbox_converter
  (3rd_party/).

Author

Yusuke Ogawa - Architect, Cisco | CCIE#17583

License

This project is licensed under the Apache License 2.0. See the
NOTICE file for copyright and third-party attributions.