switch-collector 2.0.0

Collect data from many Cisco switches and compile to useful CSV's

Switch Collector

This tool collects "show" information from multiple Cisco switches over SSH, parses it nicely, and exports to useful flattened CSV's. This makes it extremely fast to gather holistic networking data for entire enterprises!

Included commands/data are shown below. If there is something you need that's not here, request it! Making more parsers is fairly easy.

Data	Command	Notes
ARP Table	show ip arp
MAC/CAM Table	show mac address-table
CDP Neighbors	show cdp neighbors detail
Hardware Inventory	show inventory OID
Interface Info	show interfaces
Interface Config	show running-config | section ^interface
AAA Servers	show aaa servers
Authenticated Sessions	show authentication sessions	Also collects per-session deep details
CTS SXP Connections	show cts sxp connections
CTS Environment Data	show cts environment-data
CTS PACs	show cts pacs
CTS Credentials	show cts credentials
Device Tracking DB	show device-tracking database	🚧 Coming soon!
IP Routes	show ip route	🚧 Coming soon!

This is validated and hard-coded to work with IOS-XE parsers, but it will likely work (within some reason) with older IOS switches.

Install

This is cross-platform, and should work on Windows, MacOS, and Linux.

You can use pip or pipx if you'd like, but we recommend uv for simplicify.

So first, install uv using the official uv installation instructions:

• https://docs.astral.sh/uv/getting-started/installation/

Then simply install switch-collector as a tool:

uv tool install switch-collector

Init Configure

Create the (sort of optional) starter config files:

switch-collector init

That command writes these files to your system user config directory:

• settings.toml: Optional configuration file
• ssh_config: Optimized SSH settings to allow connections to Cisco switches

When running the script, the input settings are derived in this order of priority:

1. CLI arguments
2. settings.toml (if it exists)
3. Hard-coded defaults (in settings_defaults.py)

Running

A simple example is to run tool as:

switch-collector --ip-file switch-ips.txt

This will open any text file (in any clean or unclean format), search for any IP's, then proceed to collect information (via SSH) from those switches. Generated CSV and JSON reports are written to the current directory.

At least one IP source is required from ip-file or ip-text options. This depends if your input is a file, or a raw string passed to the script. Both can be used at same time.

There are many other options, simply read the help:

switch-collector --help

Additionally, don't forget that you can also see equivalent settings in your settings.toml file. This is likely useful if you want to use the same settings repeatedly.

Keyring

On default, the script will prompt you to enter your SSH password every time.

To use your operating system keyring instead (MacOS Keychain Access, or Windows Credential Manager), set use_keyring = true in settings.toml or pass --use-keyring on the CLI.

You can set the keyring entry from the command line:

uvx keyring set switch-collector myusername-here

Or create it with GUI:

• macOS Keychain Access: create a password item named switch-collector with account myuser.
• Windows Credential Manager: add a generic credential with target switch-collector and username myuser.

Just note that the system/item/target must be called switch-collector exactly.

Parsing Background

Part of the "magic" is relying on Cisco's pyATS/Genie parses which converts the raw SSH data into structured data (dictionaries, lists, JSON, etc). However, Genie is a bloated package that contains many other un-needed (for this script) features that make it non-Windows compatible. So, we created "Yenie-Parser" that extracts the important parsing from Genie, but lightweight and cross-platform compatible. Check out that project as well!

https://github.com/structured-com/yenie-parser