los-vecinos-de-cisco/old

Cisco MAC Monitor para Zabbix LLD

📋 Descripción

Cisco MAC Monitor es una solución completa para monitorizar direcciones MAC conectadas a puertos de switches Cisco. Está diseñado específicamente para integrarse con Zabbix Low Level Discovery (LLD) y detectar cambios en dispositivos conectados a la red.

Características principales:

• ✅ Compatibilidad total con modelos Cisco C2960, C3560, C3560E, C2960X, C3560CX y Catalyst series
• ✅ Conexión SSH segura a dispositivos de red
• ✅ Formato JSON optimizado para Zabbix LLD
• ✅ Monitorización continua configurable por intervalos
• ✅ Contenedor Docker basado en Rocky Linux 8
• ✅ Detección automática de cambios en tabla MAC
• ✅ Filtros avanzados para puertos y VLANs específicas
• ✅ Logging completo y manejo robusto de errores

---

🚀 Inicio Rápido

1. Preparar configuración

# Clonar o descargar los archivos
mkdir cisco-mac-monitor
cd cisco-mac-monitor

# Copiar archivos del proyecto
# - cisco_mac_monitor.py
# - config.yaml
# - Dockerfile
# - docker-compose.yml
# - requirements.txt
# - entrypoint.sh

2. Configurar dispositivos

Edita el archivo config.yaml con tus dispositivos:

devices:
  - hostname: "SW-PRINCIPAL-001"
    ip: "192.168.1.10"
    username: "admin"
    password: "tu_password"
    
  - hostname: "SW-SECUNDARIO-001"
    ip: "192.168.1.11"
    username: "admin"
    password: "tu_password"

3. Construir y ejecutar

# Opción 1: Docker Compose (Recomendado)
docker-compose up --build -d

# Opción 2: Docker tradicional
docker build -t cisco-mac-monitor .
docker run -v $(pwd)/config:/config -v $(pwd)/data:/data cisco-mac-monitor

4. Verificar funcionamiento

# Ver logs en tiempo real
docker-compose logs -f

# Ejecutar una prueba única
docker-compose exec cisco-mac-monitor single-run

# Probar configuración
docker-compose exec cisco-mac-monitor test-config

---

📁 Estructura del Proyecto

cisco-mac-monitor/
├── cisco_mac_monitor.py    # Script principal de Python
├── config.yaml            # Configuración de dispositivos
├── requirements.txt       # Dependencias de Python
├── Dockerfile             # Imagen de contenedor
├── docker-compose.yml     # Orquestación de contenedores
├── entrypoint.sh          # Script de entrada del contenedor
├── example_output.json    # Ejemplo de salida JSON
├── modelos.csv            # Inventario de dispositivos (referencia)
└── README.md              # Esta documentación

---

⚙️ Configuración Detallada

Archivo config.yaml

# Configuración de monitorización
monitoring:
  interval_minutes: 5                    # Intervalo entre monitoreos
  output_file: "/data/cisco_mac_data.json"  # Archivo de salida
  log_level: "INFO"                      # Nivel de logging
  log_file: "/logs/cisco_mac_monitor.log"    # Archivo de log

# Dispositivos de red
devices:
  - hostname: "SW-CORE-001"
    ip: "192.168.1.5"
    username: "admin"
    password: "cisco123"
    port: 22
    timeout: 30
    
  - hostname: "SW-ACCESS-001"
    ip: "192.168.1.10"
    username: "admin"
    password: "cisco123"

# Filtros opcionales
filters:
  exclude_ports:
    - "Gi0/1"    # Uplinks
    - "Gi0/2"
  exclude_vlans:
    - "999"      # VLAN de management
  exclude_macs:
    - "00:1a:2b:3c:4d:5e"  # Servidores conocidos

# Configuración para Zabbix
zabbix:
  custom_macros:
    discovery_rule: "cisco.mac.discovery"
    item_prefix: "cisco.mac"

Variables de entorno del contenedor

Variable	Default	Descripción
CONFIG_FILE	/config/config.yaml	Ruta al archivo de configuración
LOG_LEVEL	INFO	Nivel de logging (DEBUG, INFO, WARNING, ERROR)
MONITORING_INTERVAL	5	Intervalo en minutos (sobrescribe config.yaml)

---

🐳 Uso con Docker

Comandos básicos

# Monitorización continua (por defecto)
docker run -v $(pwd)/config:/config cisco-mac-monitor

# Ejecución única
docker run -v $(pwd)/config:/config cisco-mac-monitor single-run

# Probar configuración
docker run -v $(pwd)/config:/config cisco-mac-monitor test-config

# Probar conexiones SSH
docker run -v $(pwd)/config:/config cisco-mac-monitor test-ssh

# Shell interactivo para debugging
docker run -it -v $(pwd)/config:/config cisco-mac-monitor shell

Volúmenes recomendados

volumes:
  - ./config:/config:ro      # Configuración (solo lectura)
  - ./logs:/logs            # Logs persistentes
  - ./data:/data            # Datos de salida

---

📊 Integración con Zabbix

Formato JSON de salida

El script genera JSON en el formato requerido por Zabbix LLD:

{
  "data": [
    {
      "{#DEVICE_HOSTNAME}": "SW-PB-001",
      "{#PORT_NAME}": "Fa0/1", 
      "{#MAC_COUNT}": 2,
      "{#VLANS}": "10,20",
      "{#MAC_ADDRESSES}": "[{\"mac\": \"aa:bb:cc:dd:ee:01\", \"vlan\": \"10\", \"type\": \"DYNAMIC\"}]",
      "{#LAST_UPDATE}": "2024-10-24T14:30:00.123456"
    }
  ],
  "timestamp": "2024-10-24T14:30:00.123456",
  "total_devices": 3,
  "total_ports": 15
}

Configuración en Zabbix

1. Crear Discovery Rule:

   • Name: Cisco MAC Discovery
   • Type: External check
   • Key: cisco.mac.discovery
   • Update interval: 5m

2. Item prototypes:

   • cisco.mac.count[{#DEVICE_HOSTNAME},{#PORT_NAME}]
   • cisco.mac.list[{#DEVICE_HOSTNAME},{#PORT_NAME}]
   • cisco.mac.vlans[{#DEVICE_HOSTNAME},{#PORT_NAME}]

3. Trigger prototypes:

   • MAC count changes
   • New unauthorized MAC detected
   • MAC disappeared from port

Script de integración para Zabbix

#!/bin/bash
# /usr/lib/zabbix/externalscripts/cisco_mac_discovery.sh

docker exec cisco-mac-monitor single-run > /dev/null 2>&1
cat /data/cisco_mac_data.json

---

🔧 Compatibilidad de Dispositivos

Modelos soportados (basado en modelos.csv):

Modelo	IOS Version	Estado
C2960	12.2(35)SE5+	✅ Soportado
C2960X	15.2(2)E3+	✅ Soportado
C2960S	12.2(55)SE5+	✅ Soportado
C3560	12.2(25)SEB4+	✅ Soportado
C3560E	12.2(55)SE3+	✅ Soportado
C3560CX	15.2(4)E6+	✅ Soportado
Catalyst 3K	16.6.5+	✅ Soportado

Comandos utilizados:

• show mac address-table - Obtener tabla MAC completa
• Compatible con IOS 12.x, 15.x y 16.x

---

🛠️ Desarrollo y Personalización

Ejecutar en modo desarrollo

# Instalar dependencias
pip3 install -r requirements.txt

# Ejecutar directamente
python3 cisco_mac_monitor.py --config config.yaml --single-run

# Debug mode
python3 cisco_mac_monitor.py --config config.yaml --single-run --debug

Estructura del código

# Clases principales:
CiscoSSHConnector      # Manejo de conexiones SSH
CiscoMacTableParser    # Parsing de tabla MAC
ZabbixLLDFormatter     # Formateo para Zabbix
CiscoMacMonitor        # Orquestador principal

Agregar nuevo modelo de dispositivo

1. Editar CiscoMacTableParser._parse_mac_table_output()
2. Agregar nuevo patrón regex para el formato de salida
3. Probar con test-ssh command

---

🔍 Troubleshooting

Problemas comunes

1. Error de conexión SSH:

# Probar conectividad
docker-compose exec cisco-mac-monitor test-ssh

# Verificar credenciales en config.yaml
# Verificar conectividad de red del contenedor

2. Formato JSON incorrecto:

# Verificar salida
docker-compose exec cisco-mac-monitor single-run
cat data/cisco_mac_data.json | jq .

3. No se detectan MACs:

# Verificar comando en dispositivo
ssh admin@192.168.1.10
show mac address-table

# Verificar filtros en config.yaml

4. Container no inicia:

# Verificar logs
docker-compose logs cisco-mac-monitor

# Verificar configuración
docker-compose exec cisco-mac-monitor test-config

Logs útiles

# Logs del contenedor
docker-compose logs -f cisco-mac-monitor

# Logs internos de la aplicación
docker-compose exec cisco-mac-monitor cat /logs/cisco_mac_monitor.log

# Debug completo
docker-compose exec cisco-mac-monitor tail -f /logs/cisco_mac_monitor.log

---

📈 Monitorización y Alertas

Métricas disponibles

• MAC Count por puerto: Número de MACs conectadas
• VLAN Distribution: Distribución de VLANs por puerto
• MAC Changes: Cambios en tabla MAC
• Device Connectivity: Estado de conexión a dispositivos

Alertas recomendadas

1. Nuevo dispositivo conectado (MAC no autorizada)
2. Dispositivo desconectado (MAC desaparecida)
3. Puerto saturado (demasiadas MACs)
4. Error de conectividad con switch
5. Cambio en VLAN de dispositivo conocido

---

🔒 Seguridad

Mejores prácticas

1. Credenciales:

   • Usar variables de entorno para passwords
   • Configurar usuarios SSH específicos para monitorización
   • Rotar credenciales regularmente

2. Red:

   • Usar VLAN de management dedicada
   • Configurar ACLs para acceso SSH
   • Monitorizar accesos SSH en logs de switches

3. Contenedor:

   • Ejecutar como usuario no privilegiado
   • Montar volúmenes como solo lectura cuando sea posible
   • Actualizar imagen base regularmente

Configuración SSH en switches Cisco

! Crear usuario para monitorización
username monitor privilege 1 password cisco123

! Configurar acceso SSH
line vty 0 15
 login local
 transport input ssh

! ACL para acceso (opcional)
access-list 99 permit 192.168.1.100
line vty 0 15
 access-class 99 in

---

🤝 Contribución

Cómo contribuir

1. Fork del repositorio
2. Crear branch para feature: git checkout -b feature/nueva-funcionalidad
3. Commit cambios: git commit -am 'Agregar nueva funcionalidad'
4. Push al branch: git push origin feature/nueva-funcionalidad
5. Crear Pull Request

Reportar bugs

Incluir en el reporte:

• Versión del script
• Modelo y versión IOS del dispositivo
• Logs relevantes
• Configuración utilizada (sin credenciales)

---

📄 Licencia

Este proyecto está bajo licencia MIT. Ver archivo LICENSE para más detalles.

---

👥 Soporte

• Documentación: Este README
• Logs: /logs/cisco_mac_monitor.log
• Ejemplos: example_output.json
• Issues: GitHub Issues

---

🏷️ Versiones

v1.0.0 (Actual)

• ✅ Soporte inicial para switches Cisco
• ✅ Integración con Zabbix LLD
• ✅ Contenedor Docker con Rocky Linux 8
• ✅ Monitorización continua configurable
• ✅ Sistema de filtros avanzado

Roadmap v1.1.0

• 🔄 Soporte para SNMPv3
• 🔄 API REST para consultas
• 🔄 Dashboard web integrado
• 🔄 Soporte para múltiples vendors (HP, Juniper)

---

Desarrollado para entornos de producción con switches Cisco 🚀