A portable, self-contained Python 3 CLI tool that performs network discovery, logs into Cisco switches (supporting IOS / IOS-XE, NX-OS, and IOS-XR), runs safe read-only commands, and compiles authoritative network inventory, configuration diffs, and migration documentation reports.
- Nmap & Socket Scanner Fallback: Uses
nmapvia subprocess for scanning. Ifnmapis not installed, it falls back to a built-in multi-threaded Python TCP port scanner. - Auto-OS Detection: Connects initially, detects the Cisco OS (IOS, NX-OS, IOS-XR) via system strings, and dynamically loads the correct Netmiko driver.
- Safe, Read-Only CLI Commands: Executes safe status commands (e.g.,
show version,show running-config,show ip interface brief,show interfaces,show arp,show cdp/lldp neighbors,show spanning-tree,show ip route). - Switch Configuration Benchmarking: Saves running configurations as standard baselines and provides comparison diffs to track configuration drift over time.
- Offline OUI Lookup: Resolves manufacturer MAC addresses using a built-in common vendor database, with automatic fallback to loading or downloading the official IEEE OUI registry.
- Failure Management / Retry: Logs failed or partial hosts to
failed_hosts.json. You can resume/retry scanning just those hosts using new credentials or network configurations. - Cross-Platform Operator Shells: Automated interactive menu wrappers (
run.shfor Linux/macOS andrun.ps1/run.batfor Windows) streamline setup, prerequisites installation, baseline comparison, and retries. - Advanced Options & Security Controls: Hides advanced operational settings (thread pool scale, timeouts, baseline comparison, retry modes, telnet disabling) in an
Advanced Options Menuto protect production switches from junior engineers. - EOF-Safe Menus & Pipes: Shell menus support non-interactive pipelines (e.g., piping configuration scripts via stdin) and terminate immediately upon receiving EOF.
- Accurate Layer 3 Subnet Analysis: Diagnostics accurately identify overlapping nested IP subnets versus exact IP address conflicts, using standard CIDR boundary parsing.
- Standard Python Packaging: Supports PEP 517 structures. Run
pip install .to install the crawler as a system-wide CLI utility.
After a successful scan, the crawler compiles and generates the following reports in the current directory:
asset_inventory.csv: The authoritative inventory database including Hostname, IP, MAC Address, Device Type, Model, Firmware, Serial Number, Role, and Management Protocol.migration_cabling_matrix.csv: A port-by-port cabling patching matrix mapping Cisco interfaces, connected MACs, resolved vendors (OUI), descriptions, link speeds, VLAN numbers, names, and target destination switch ports.cisco_to_target_translation.md: A detailed command-by-command and feature-by-feature translation map bridging Cisco CLI syntax (IOS/NX-OS/XR) with standard modern target switches.migration_config_variables.json: An extracted variables database containing hostname, domain name, VLAN names, IP interfaces, routing configurations, NTP, SNMP, AAA, and DNS details.L2_network_diagrams.md: Physical topologies, switch-to-switch uplinks, switch stacks, wireless AP connections, and STP blocking/forwarding links documented in standard Mermaid.js diagrams.L3_network_diagrams.md: Logical routing boundaries, Switch Virtual Interfaces (SVIs), VLAN mapping tables, and VRF instances mapped out via Mermaid.js.network_analysis_report.md: Detailed Layer 1-7 behavior analysis highlighting cabling errors, port utilization percentages, loop/STP risks, overlapping subnets, dynamic routing configurations, AAA/RADIUS setups, and security gaps.failed_hosts.json: List of hosts that failed scanning for follow-up runs.
The easiest way to initialize the environment, install requirements, and run the crawler is using the interactive menu shell:
- Linux/macOS:
chmod +x run.sh ./run.sh
- Windows (PowerShell):
Double click on
run.bator run:PowerShell.exe -ExecutionPolicy Bypass -File .\run.ps1
This shell will guide you through checking requirements, installing dependencies, executing discovery, comparing baselines, retrying failed hosts, and listing backups.
A pre-built container package is compiled and hosted on GitHub Container Registry (GHCR). It contains Python, all packages, and system-level nmap pre-configured.
To pull and run the crawler image in a container, mounting a local volume to collect the deliverables:
docker run --rm -it -v "$(pwd)/deliverables:/app/deliverables" ghcr.io/leifdavisson/cisco-docu-crawler --subnets 192.168.1.0/24(Optionally define CRAWLER_USER, CRAWLER_PASSWORD, and CRAWLER_SECRET environment variables using -e flags to skip the credential prompt).
You can install the crawler directly on your host machine as a standard, system-wide command-line utility:
pip install .Once installed, you can invoke the crawler from any directory simply by typing:
cisco-crawlerDetailed guides and manuals are available in the docs/ directory:
- Junior Network Engineer Quick-Start Guide: Walks through basic menu operations, using the simulated demo scan mode, and reading generated topology diagrams and reports.
- Advanced Scripting & Automation Guide: Outlines command-line flags, environment variable parameterization, and integration scripts to run the crawler programmatically in cron jobs or CI/CD pipelines.
If you prefer to run the scripts manually, follow these steps:
Install the light dependencies:
pip install -r requirements.txtchmod +x cisco_crawler.py./cisco_crawler.pyIf no subnets are passed, the script automatically detects your machine's local IP and suggests your local /24 subnet as the default.
To specify target subnets directly via CLI:
./cisco_crawler.py --subnets 192.168.1.0/24,10.0.5.0/24To save a snapshot of the current configurations:
./cisco_crawler.py --baselineTo run the crawler and check for changes against the saved baseline:
./cisco_crawler.py --compareIf any switches fail (due to network timeout, bad credentials, or AAA/enable issues), their details are logged in failed_hosts.json.
You can rerun the crawler to target only the failed devices:
./cisco_crawler.py --retry failed_hosts.json(The script will scan only those hosts and prompt for credentials again, making it easy to try alternate passwords or troubleshoot connectivity)
This crawler normalizes command inputs across Cisco platforms based on the following differences:
| Function | IOS / IOS-XE | NX-OS | IOS-XR |
|---|---|---|---|
| Interfaces Summary | show ip interface brief |
show ip interface brief |
show ipv4 interface brief |
| MAC Address Table | show mac address-table |
show mac address-table |
Parsed from show interfaces / show arp |
| ARP Table | show arp |
show ip arp |
show arp |
| Topology Discovery | CDP + LLDP detail | CDP + LLDP detail | LLDP only |
| Spanning Tree | show spanning-tree |
show spanning-tree |
Disabled (Routing platforms) |
| Routing Table | show ip route |
show ip route |
show route |
| Paging Control | terminal length 0 |
terminal length 0 |
terminal length 0 |
The generated reports are written in Markdown (.md) format, which is a clean, readable text format. The physical and logical network diagrams are created using Mermaid.js, a text-to-diagram standard.
To view the reports with rich formatting and render the diagrams automatically, we recommend using one of the following tools:
Obsidian is a free, highly-rated note-taking app available for Windows, macOS, and Linux.
- Why it's best: It natively supports Markdown and renders Mermaid diagrams instantly out-of-the-box without needing any plugins or setup.
- How to use: Install Obsidian, click "Open folder as vault", and select the folder where the crawler generated your reports.
If you push these files to a GitHub repository:
- Why it's best: GitHub natively parses Markdown and renders Mermaid diagrams directly inside the web browser.
- How to use: Simply click on any
.mdfile on your GitHub project page to read it.
For developers and IT administrators already using VS Code:
- How to use: Open any
.mdfile and open the preview tab (Ctrl+Shift+Von Windows/Linux orCmd+Shift+Von macOS). - Render Diagrams: Install the Markdown Preview Mermaid Support extension from the Marketplace to render the topologies inside the preview pane.
If you just want to export the diagrams:
- How to use: Copy the text block starting with ````mermaid` from your diagram reports and paste it into the Mermaid Live Editor. From there, you can customize the layout or export it as a high-resolution PNG, SVG, or PDF.
This script uses read-only status commands and does not make configuration changes. All username/password prompting is done securely using Python's standard getpass module so that passwords never leak to the terminal logs or bash history.
This project is licensed under the GNU Affero General Public License Version 3.0 (AGPL-3.0). See the LICENSE file for the full license text.