Catalyst Config Auditor v1.4.0

A standalone, read-only SSH collector and offline file generator for Cisco Catalyst IOS-XE (Catalyst 9300, 9400, 9500). Designed for Windows 10/11 and Python 3.10+. PyPI-ready Python package with a backward-compatible single-file command launcher; no Genie or pyATS, no Linux required.

Safety: This script does not send configuration changes, write erase, reload, or any other device configuration commands. Generated configurations are drafts that must be reviewed before use. Do not upload real running-configs or passwords to public repositories.

Install

Install from the project folder before publishing:

py -m pip install -e .
catalyst-auditor --version
catalyst-auditor --help

After the first release is published to PyPI, users can install it with:

py -m pip install catalyst-config-auditor
catalyst-auditor --help

You can also run python -m catalyst_config_auditor --help, or use the backward-compatible python Catalyst_Config_Auditor.py --help from the repository. The bundled default cmd.txt, variables_selection.yaml, TextFSM and TTP templates are installed as package data; explicit user paths still take precedence.

Before public release: replace LICENSE with the license you choose, confirm you own or may distribute all included code/templates, and verify that the name catalyst-config-auditor is available on PyPI.

Required: Netmiko, PyYAML, Jinja2. Optional parsing engines: TTP, NTC Templates/TextFSM (listed in requirements.txt). If an optional engine cannot parse a command, the workbook uses custom Python parsing or one-column RAW output. No Genie/pyATS.

Independent modes

Mode	SSH?	Inputs	Generated files
--backup-only	Yes	device	<hostname>_running_Config.txt
--commands-only	Yes	device + cmd.txt	Commands_Output.txt
--collect	Yes	device + cmd.txt	Both original TXT files, no Excel
--excel	No	any Commands_Output.txt	<hostname>_Commands.xlsx beside the input TXT (or --output-file)
--extract-vars	No	running-config	var_main.yaml, var_interfaces.yaml only
--generate-templates	No	running-config + existing YAML	template_main.j2, template_interfaces.j2 only
--vars	No	running-config	Both YAML and Jinja2 pairs (legacy combined mode)
--create-main	No	generated main Jinja2 + YAML	<hostname>_main_generated.cfg (without the included physical interfaces)
--create-interfaces	No	generated interfaces Jinja2 + YAML	<hostname>_interfaces_generated.cfg
--create-full	No	main + included interfaces Jinja2 + both YAMLs	<hostname>_full_generated.cfg
--create	No	ANY Jinja2 and YAML	any file via --output-file
-AIO	Yes	device + cmd.txt	Collection + Excel + YAML + Jinja2

The default output path is output/, but it is configurable with -o or --output. All modes protect existing files unless --overwrite is passed.

1. Collect from switches (SSH, read-only)

# Running configuration plus show outputs; does NOT automatically create Excel
catalyst-auditor -ho SW01 --collect --cmd-file cmd.txt

# Only running-config
catalyst-auditor -ho SW01 --backup-only

# Only show commands, no running-config file
catalyst-auditor -ho SW01 --commands-only --cmd-file cmd.txt

# Multiple switches, 20 workers
catalyst-auditor -hf hosts.txt --collect --cmd-file cmd.txt -w 20 -o Cat9k

SSH always collects enough read-only device facts to identify the hostname; the output mode determines which files are saved. Passwords are prompted securely if -p is omitted. --collect no longer generates an Excel in v1.4.0, to honor the independent stages. Use -AIO when you intentionally want everything.

2. Excel from any folder — no SSH

# Excel SAVED TO the SAME folder as Commands_Output.txt
catalyst-auditor --excel --input "C:\Backups\SW01\Commands_Output.txt" --parser auto

# Use a specific workbook filename, anywhere
catalyst-auditor --excel --input "C:\Backups\SW01\Commands_Output.txt" --output-file "C:\Backups\SW01\Audit.xlsx"

# Regenerate an existing workbook
catalyst-auditor --excel --input "C:\Backups\SW01\Commands_Output.txt" --overwrite

# Keep the original automatic directory discovery
catalyst-auditor -ho SW01 --excel -o Cat9k

# External TextFSM and TTP parsers
catalyst-auditor --excel --input "C:\Backups\SW01\Commands_Output.txt" --ntc-dir Custom_Parsers/NTC --parser-dir Custom_Parsers/TTP

--input must contain the original Commands_Output.txt format (show command headings separated by 68 = characters). Workbook has one Summary worksheet and one worksheet for each show command. Successfully parsed commands yield structured columns; unrecognized commands have one column RAW. No Parsing_Summary tab and no Line column. Parsing outcomes go to a timestamped Logs_<hostname> folder beside the external input, or under -o for the original device-folder workflow. If no hostname is detected, the input directory determines the workbook filename; -ho SW01 overrides the inferred label.

3. Extract only YAML, from local backup

catalyst-auditor -ho SW01 --extract-vars -o Cat9k
catalyst-auditor --extract-vars --from-config "C:\Backups\SW01\SW01_running_Config.txt"

Extracted YAMLs:

• var_main.yaml: hostname, serial from saved show inventory/version or license UDI, VLANs, SVI, loopbacks, BGP, etc., subject to variables_selection.yaml.
• var_interfaces.yaml: access port information, routed physical/Port-channel interfaces and only explicitly present DAI trust or rate-limit statements.

When --from-config points to ...\Backups\SW01_running_Config.txt, files go in sibling ...\Variables\; otherwise they go into Variables\ alongside the source directory. To use a specific directory, add --vars-dir "C:\My\Variables".

4. Generate only Jinja2, using existing YAML

catalyst-auditor -ho SW01 --generate-templates -o Cat9k
catalyst-auditor --generate-templates --from-config "C:\Backups\SW01\SW01_running_Config.txt"

Both YAML files must already exist in the corresponding Variables directory. This mode leaves YAML untouched. It regenerates only template_main.j2 and template_interfaces.j2 from the running-config and YAML. If you deliberately need everything together (legacy workflow):

catalyst-auditor -ho SW01 --vars -o Cat9k

5. Create only main, only interfaces or full config (offline)

catalyst-auditor -ho SW01 --create-main -o Cat9k
catalyst-auditor -ho SW01 --create-interfaces -o Cat9k
catalyst-auditor -ho SW01 --create-full -o Cat9k

# No specific standard directory layout required:
catalyst-auditor --create-full --vars-dir "C:\Backups\SW01\Variables"

# Render ANY custom Jinja2 with ANY YAML:
catalyst-auditor --create --template my_config.j2 --variables site.yaml --output-file new_config.cfg

--create-main omits the template_interfaces.j2 include (physical ports and routed Port-channels) but keeps the main config such as VLANs, SVI, loopbacks and routing protocols. --create-interfaces renders interface template only. --create-full includes both. All are file-only operations, never device configuration pushes.

Device-folder layout

Cat9k/
  SW01/
    Backups/
      SW01_running_Config.txt
      Commands_Output.txt
      SW01_Commands.xlsx              # after --excel or -AIO
    Variables/
      var_main.yaml
      var_interfaces.yaml
      template_main.j2
      template_interfaces.j2
      SW01_main_generated.cfg
      SW01_interfaces_generated.cfg
      SW01_full_generated.cfg
  Logs_SW01/
    SW01_COLLECT_<timestamp>.log
    SW01_EXCEL_<timestamp>.log
    SW01_VARS_<timestamp>.log

Parsing, testing and Windows

catalyst-auditor --parser-check
catalyst-auditor --parser-test "show interfaces trunk" --input examples/show_interfaces_trunk.txt --parser auto
python -m unittest discover -s tests -v

--parser {auto,ttp,ntc,custom,raw}: automatic parsing prefers reliable built-in Python parsers for selected commands, then tries TTP, custom NTC, installed NTC, custom Python and RAW. TextFSM/TTP templates and test inputs are samples, not guaranteed to cover every IOS-XE variant. Validate against sanitized outputs of the actual versions you manage. Both real SSH execution and the actual installed TTP/NTC parsers require validation on your Windows environment.

GitHub and security

The ZIP is organized as a GitHub repository. Extract it and commit the contents of the Catalyst_Config_Auditor folder. .gitignore excludes runtime artifacts (Backups, Variables, *.cfg, *.xlsx, logs, generated YAML) except permitted synthetic examples. Git ignores are not security controls; check GitHub Desktop's Changes pane before every commit. Prefer a private repository and never commit live device running-configs, credentials, or BGP secrets.

See PROJECT_CONTEXT.md, CHANGELOG.md, CONTRIBUTING.md, and SECURITY.md for collaboration and release guidance.

Batch Excel from a folder containing multiple switches

# Recursively locate every Commands_Output.txt and write Excel beside each one
catalyst-auditor --excel --input-dir "C:\Backups\Cat9k" --parser auto

Each found input is processed separately, so an error in one switch does not stop the others; failed files are reported at the end. --output-file cannot be combined with batch mode because many workbooks need distinct filenames. Existing workbooks still require --overwrite.

Build and publish to PyPI

py -m pip install --upgrade build twine
py -m build
py -m twine check dist/*
# Optional test publication:
py -m twine upload --repository testpypi dist/*
# Real publication (after reviewing metadata and LICENSE):
py -m twine upload dist/*

For GitHub Actions, PyPI recommends Trusted Publishing (OIDC) instead of storing tokens. Configure the project/publisher in your PyPI account before enabling automatic release.

py -m build generates dist/*.whl and dist/*.tar.gz. Only those two distribution files go to PyPI; the source repository goes to GitHub.