Metadata-Version: 2.4
Name: switch-collector
Version: 2.0.0
Summary: Collect data from many Cisco switches and compile to useful CSV's
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Dist: yenie-parser>=0.5.3
Requires-Dist: click>=8
Requires-Dist: flatdict>=4.1.0,<5
Requires-Dist: keyring>=25.7,<26
Requires-Dist: pandas>=3.0.1,<4
Requires-Dist: netmiko>=4.6.0,<5
Requires-Dist: platformdirs>=4,<5
Requires-Dist: rich>=14.3.3
Requires-Python: >=3.12, <3.15
Project-URL: Homepage, https://github.com/structured-com/switch-collector
Project-URL: Issues, https://github.com/structured-com/switch-collector/issues
Description-Content-Type: text/markdown

# 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:

```bash
uv tool install switch-collector
```


## Init Configure

Create the (sort of optional) starter config files:

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


