clean_switch

Portfolio Summary

Python automation tool for Cisco switch inventory and topology analysis.

This project collects command outputs from Cisco IOS switches through SSH, parses them into structured data, generates Excel reports with dashboards, stores raw outputs and JSON snapshots, and can crawl neighbouring devices through CDP/LLDP.

It demonstrates practical software engineering in a real infrastructure context: CLI design, network automation, parsing pipelines, fallback handling, report generation, historical comparison, and topology traversal.

Main stack: Python, Netmiko, TextFSM/NTC templates, OpenPyXL, JSON snapshots, CLI tooling.

Coletor modular para switches Cisco (IOS) com:

• SSH via Netmiko, parsing com use_textfsm + CliTable (ntc-templates) e fallbacks internos (nunca ficas só com texto bruto).
• Exportação para Excel com tabelas, CF e Dashboard (KPIs, VLANs, Port-Channels, etc.).
• Geração de .txt brutos (um por comando), com cabeçalho padrão por ficheiro.
• Snapshots JSON por execução (para comparação histórica).
• Modo Crawl: recolha recursiva por vizinhos (CDP/LLDP) com filtros de sub-rede.

Estrutura principal

• clean_switch/network_connector.py — liga por SSH, executa comandos e tenta parse (Netmiko→CliTable→fallbacks). Define a lista COMMANDS_DEFAULT.
• clean_switch/excel_pipeline.py — cria o Excel (tabelas, CF, blocos “Resumo” por comando) e gera a Dashboard.
• clean_switch/excel_dashboard.py — lógica da Dashboard (KPIs, gráficos, PC map, CDP, VLANs).
• clean_switch/excel_utils.py — utilitários (tabelas, CF, gráficos, helpers VLANs/PC/Execução).
• clean_switch/textfsm_utils.py — deteção/uso do NET_TEXTFSM, limpeza de output e CliTable.
• clean_switch/cli.py — CLI: flags, fluxo simples e crawl; integra history_json + ideia6_features.
• clean_switch/__init__.py — torna o pacote importável; define versão e constantes partilhadas (ex.: formato timestamps).
• clean_switch/test_parsers.py — testes unitários simples para os parsers; contém casos de exemplo e asserts para garantir que mudanças nos parsers não quebrem o formato esperado.
• clean_switch/parsers.py - colecção de parsers backup e normalizadores com funções testáveis.
• clean_switch/topology_crawl.py - funções que constroem/percorrer a topologia extraída dos vizinhos.
• clean_switch/logging_config.py — configuração centralizada de logging (formatters, handlers, níveis, ficheiro de logs rotativo). Usado por todo o projecto para logs consistentes.
• clean_switch/raw_outputs.py - utilitários para escrita e rotação dos ficheiros txt; inclui normalização de comandos e limpeza de linhas.
• clean_switch/ideia6_features.py — cria Execucao_, Comparacao, Alterações Detalhadas e Checklist Migração a partir dos snapshots.
• clean_switch/history_json.py — snapshots (_history/host/*.json), diffs simples e retenção.

Requisitos

• Python 3.10+
• netmiko, ntc-templates, openpyxl
• (Opcional p/ --hostmap) PyYAML

O caminho dos templates NTC é detetado automaticamente e NET_TEXTFSM é definido se possível.

Instalação rápida:

pip install netmiko ntc-templates openpyxl pyyaml

Comandos por omissão

Executados se não especificares --commands:

show inventory
show version
show interfaces status
show interfaces trunk
show vlan brief
show cdp neighbors detail
show lldp neighbors detail
show etherchannel summary
show spanning-tree

Utilização (CLI)

Fluxo simples (um único switch “semente”)

Cria Excel, snapshots JSON e .txt brutos:

python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****"

Só snapshots + .txt (sem Excel):

python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****" --no-excel

Geração apenas dos .txt e terminar (não cria Excel):

python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****" --raw-only

Logs:

python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****" --log DEBUG

Flags relevantes:

• --out DIR — força diretório de saída do Excel (por omissão é ./outputs/<hostname>).
• --commands ... — lista personalizada de comandos (senão usa COMMANDS_DEFAULT).
• --raw-dir DIR — base onde gravar os .txt (default outputs).
• --raw-ts-subdir — cria subpasta por timestamp dentro do host para os .txt.

Modo Crawl (vizinhos do switch)

Explora vizinhos por níveis criando excel e .txt para o switch "seed" e para cada vizinho encontrado independentemente da profundidade:

# Seed + vizinhos diretos (depth=1)
python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****"   --crawl-depth 1 --allowed-subnet 192.168.99.0/24

Com profundidade 2 (vizinhos dos vizinhos) e vários filtros de sub-rede:

python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****"   --crawl-depth 2   --allowed-subnet 192.168.99.0/24   --allowed-subnet 10.0.0.0/8

Com --hostmap (fallback DeviceID→IP) e sem tentar DNS:

python -m clean_switch.cli --host 192.168.99.2 --user diogo --password "****"   --crawl-depth 1 --hostmap mapeamento.yml --no-dns-fallback

Opções do crawl (resumo):

• --crawl-depth N — 0=apenas seed; 1=vizinhos; 2=vizinhos dos vizinhos; …
• --allowed-subnet CIDR (repetível) — só segue vizinhos cujos IPs pertençam às sub-redes permitidas.
• --hostmap PATH.yml — YAML com mapa DeviceID: IP para resolver vizinhos sem DNS. (Requer PyYAML.)
• --no-dns-fallback — desativa tentativa de resolução DNS do DeviceID.
• --out DIR — se definido, todos os Excels do crawl são gravados neste diretório.

Exemplo mapeamento.yml:

SW2.domain.local: 192.168.99.3
SW3: 192.168.99.4

Saída do crawl no terminal lista hostname: caminho_do_excel por cada switch recolhido.

Saídas/Artefactos

.txt brutos

• Guardados em outputs/<hostname>/ (ou em --raw-dir).
• Nome: <hostname>_<comando_normalizado>.txt (ex.: SW1_show_vlan_brief.txt).
• Cada ficheiro começa com:

  # Hostname: SW1
  # Comando: show cdp neighbors detail
  # Timestamp: 2025-09-02_17-05-58
  # ---
  

Snapshots (JSON)

• Guardados em outputs/_history/<hostname>/<ts>.json, com itens cmd/raw/headers/rows e meta.
• Retenção automática: mantém os mais recentes (por omissão, 10).

Excel

• Caminho por omissão: outputs/<hostname>/<hostname>_levantamento.xlsx.
• Folhas por comando com tabela formatada e Resumo rápido (ex.: Interfaces, VLANs, Trunks).
• Dashboard com KPIs (Total/Up/Down, IOS/Uptime, VLANs, Port-Channels, CDP) e gráficos.
• Ideia 6: cria Execucao_, Comparacao, Alterações Detalhadas (diffs de VLANs, Interfaces, Port-Channels, Trunks, Neighbors) e Checklist Migração (KPIs “Antes vs Agora”).
• Após correr a Ideia 6, o CLI mantém só a Execução mais recente (limpa as outras folhas de Execução para não acumular).

Notas de parsing

• Pipeline tenta, por ordem: use_textfsm=True (Netmiko) → CliTable (ntc-templates) → fallbacks internos para comandos chave (interfaces status, vlan brief, inventory, CDP detail, version, spanning-tree, etherchannel summary, interfaces trunk).
• O fallback de show interfaces trunk normaliza native VLAN e allowed/allowed_active_vlans.