Metadata-Version: 2.4
Name: catalyst-config-auditor
Version: 1.4.0
Summary: Read-only Cisco Catalyst IOS-XE collector with offline Excel, YAML and Jinja2 tools
Keywords: cisco,catalyst,ios-xe,network-automation,textfsm,ttp,excel
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: netmiko>=4.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: Jinja2>=3.1
Requires-Dist: ttp>=0.9
Requires-Dist: ntc-templates>=4.0
Requires-Dist: textfsm>=1.1
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

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

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

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

```powershell
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)

```powershell
# 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

```powershell
# 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

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

```powershell
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):

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

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

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

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

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

```powershell
# 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

```powershell
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.
