# Cisco Single MAC Monitor para Zabbix LLD ## 📋 Descripción **Cisco Single MAC Monitor** es una versión simplificada del monitor de direcciones MAC que se enfoca en **un dispositivo individual por ejecución**. Recibe los parámetros del dispositivo (IP, credenciales) por línea de comandos y genera salida JSON compatible con **Zabbix Low Level Discovery (LLD)**. ### Características principales: - ✅ **Un dispositivo por ejecución** - Parámetros por línea de comandos - ✅ **Compatible** con modelos Cisco C2960, C3560, C3560E, C2960X, C3560CX y Catalyst - ✅ **Conexión SSH** segura - ✅ **Formato JSON** optimizado para Zabbix LLD - ✅ **Contenedor Docker** ligero basado en Rocky Linux 8 - ✅ **JSON más manejable** - No hay riesgo de JSON gigante - ✅ **Integración sencilla** con Zabbix External Scripts --- ## 🚀 Inicio Rápido ### 1. Construir la imagen Docker ```bash # Usar Dockerfile específico para versión single docker build -f Dockerfile -t cisco-mac-monitor . ``` ### 2. Ejecutar para un dispositivo ```bash # Ejemplo básico curl -k -X POST https://localhost:8443/mac-monitor -H "Content-Type: application/json" -d '{"host": "10.150.226.19", "username": "itops", "password": "Tr4!D0r3s", "use_legacy_ssh": true}' ``` ### ⚠️ **Manejo de Contraseñas con Caracteres Especiales** ```bash # ✅ CORRECTO: Sin escape para caracteres como ! curl -k -X POST https://localhost:8443/mac-monitor -H "Content-Type: application/json" -d '{"host": "10.150.226.19", "username": "itops", "password": "Tr4!D0r3s", "use_legacy_ssh": true}' # ✅ CORRECTO: Para contraseñas con comillas, usar comillas dobles externas curl -k -X POST https://localhost:8443/mac-monitor -H "Content-Type: application/json" -d "{\"host\": \"10.150.226.19\", \"username\": \"itops\", \"password\": \"Pass\\\"word\", \"use_legacy_ssh\": true}" # ✅ CORRECTO: Para contraseñas muy complejas, usar archivo echo '{"host": "10.150.226.19", "username": "itops", "password": "C0mpl3x!P@ss#w0rd$", "use_legacy_ssh": true}' > payload.json curl -k -X POST https://localhost:8443/mac-monitor -H "Content-Type: application/json" -d @payload.json # ❌ INCORRECTO: No usar \ para escapar ! en JSON curl -k -X POST https://localhost:8443/mac-monitor -H "Content-Type: application/json" -d '{"password": "Tr4\!D0r3s"}' # ERROR! ``` ### 3. Integración con Zabbix ```bash # Copiar script de integración sudo cp zabbix_single_integration.sh /usr/lib/zabbix/externalscripts/ sudo chmod +x /usr/lib/zabbix/externalscripts/zabbix_single_integration.sh sudo chown zabbix:zabbix /usr/lib/zabbix/externalscripts/zabbix_single_integration.sh # Probar manualmente /usr/lib/zabbix/externalscripts/zabbix_single_integration.sh 192.168.1.10 admin cisco123 ``` --- ## 📁 Archivos de la Versión Simplificada ``` cisco-mac-monitor/ ├── cisco_single_mac_monitor.py # Script principal simplificado ├── Dockerfile.single # Imagen Docker optimizada ├── docker-compose.single.yml # Compose simplificado ├── zabbix_single_integration.sh # Script para Zabbix External Scripts ├── example_single_output.json # Ejemplo de salida JSON └── README_single.md # Esta documentación ``` --- ## ⚙️ Uso Detallado ### Parámetros de línea de comandos ```bash python3 cisco_single_mac_monitor.py [OPTIONS] Argumentos requeridos: --host/-H IP o hostname del dispositivo Cisco --username/-u Usuario SSH --password/-p Contraseña SSH Argumentos opcionales: --port/-P Puerto SSH (default: 22) --timeout/-t Timeout en segundos (default: 30) --hostname/-n Nombre del dispositivo (default: usa --host) --debug/-d Modo debug --quiet/-q Modo silencioso (solo JSON) ``` ### Ejemplos de uso ```bash # Básico python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 # Puerto SSH personalizado python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 -P 2222 # Con timeout personalizado python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 -t 60 # Modo silencioso (solo JSON por stdout) python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 -q # Con nombre personalizado del dispositivo python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 -n SW-CORE-001 ``` --- ## 🐳 Uso con Docker ### Construir imagen ```bash # Opción 1: Docker directo docker build -f Dockerfile.single -t cisco-single-mac-monitor . # Opción 2: Docker Compose docker-compose -f docker-compose.single.yml build ``` ### Ejecutar contenedor ```bash # Ejecución básica docker run --rm --network host cisco-single-mac-monitor \ --host 192.168.1.10 --username admin --password cisco123 # Con volumen para logs (opcional) docker run --rm --network host -v /tmp:/tmp cisco-single-mac-monitor \ --host 192.168.1.10 --username admin --password cisco123 --debug # Modo interactivo para debugging docker run --rm -it --network host cisco-single-mac-monitor --help ``` --- ## 📊 Integración con Zabbix ### Formato JSON de salida ```json { "data": [ { "{#DEVICE_HOSTNAME}": "SW-CORE-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", "device_hostname": "SW-CORE-001", "total_ports": 3, "total_macs": 6 } ``` ### Configuración en Zabbix **1. Discovery Rule por dispositivo:** ```xml Name: Cisco MAC Discovery for {HOST.NAME} Type: External check Key: cisco_single_mac_discovery.sh[{HOST.IP},{$CISCO_USER},{$CISCO_PASSWORD},{HOST.NAME}] Update interval: 5m ``` **2. Macros requeridas (nivel de host o template):** ```xml {$CISCO_USER} = admin {$CISCO_PASSWORD} = cisco123 ``` **3. Item prototypes:** - `cisco.mac.count[{#DEVICE_HOSTNAME},{#PORT_NAME}]` - `cisco.mac.addresses[{#DEVICE_HOSTNAME},{#PORT_NAME}]` - `cisco.mac.vlans[{#DEVICE_HOSTNAME},{#PORT_NAME}]` **4. Trigger prototypes:** - MAC count changed - Too many MACs on port - New MAC addresses detected ### Script de External Check ```bash #!/bin/bash # /usr/lib/zabbix/externalscripts/cisco_single_mac_discovery.sh HOST="$1" USERNAME="$2" PASSWORD="$3" HOSTNAME="$4" docker run --rm --network host cisco-single-mac-monitor \ --host "$HOST" \ --username "$USERNAME" \ --password "$PASSWORD" \ --hostname "$HOSTNAME" \ --quiet ``` --- ## 🔧 Ventajas de la Versión Simplificada ### ✅ Ventajas 1. **JSON Manejable**: Un dispositivo = Un JSON pequeño 2. **Escalabilidad**: Cada dispositivo se procesa independientemente 3. **Flexibilidad**: Diferentes credenciales por dispositivo 4. **Paralelización**: Zabbix puede ejecutar múltiples checks en paralelo 5. **Debugging Fácil**: Probar un dispositivo específico 6. **Recursos Mínimos**: Contenedor ligero y rápido ### 📊 Comparación con versión completa | Aspecto | Versión Single | Versión Completa | |---------|----------------|------------------| | JSON por ejecución | Pequeño (1 dispositivo) | Grande (N dispositivos) | | Configuración | Línea de comandos | Archivo YAML | | Flexibilidad | Alta (por dispositivo) | Media (global) | | Debugging | Fácil | Complejo | | Recursos | Mínimos | Moderados | | Uso en Zabbix | External check directo | Requires data processing | --- ## 🛠️ Desarrollo y Testing ### Ejecutar sin Docker ```bash # Instalar dependencias pip3 install paramiko PyYAML # Ejecutar directamente python3 cisco_single_mac_monitor.py \ --host 192.168.1.10 \ --username admin \ --password cisco123 \ --debug ``` ### Testing del script de integración ```bash # Test de dependencias ./zabbix_single_integration.sh test # Test manual ./zabbix_single_integration.sh 192.168.1.10 admin cisco123 SW-TEST # Test con hostname personalizado ./zabbix_single_integration.sh 192.168.1.10 admin cisco123 SW-CORE-001 ``` ### Validar JSON ```bash # Ejecutar y validar JSON python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 -q | jq . # Verificar estructura Zabbix LLD python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 -q | jq '.data[0]' ``` --- ## 🔍 Troubleshooting ### Problemas comunes **1. Error de conexión SSH:** ```bash # Probar conexión manual ssh admin@192.168.1.10 # Debug del script python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 --debug ``` **2. JSON vacío:** ```bash # Verificar comando en dispositivo ssh admin@192.168.1.10 show mac address-table # Verificar logs python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 --debug ``` **3. Imagen Docker no encontrada:** ```bash # Verificar imagen docker images | grep cisco-single-mac # Reconstruir si es necesario docker build -f Dockerfile.single -t cisco-single-mac-monitor . ``` ### Logs útiles ```bash # Logs del script (van por stderr) python3 cisco_single_mac_monitor.py -H 192.168.1.10 -u admin -p cisco123 2>debug.log # Logs del contenedor docker run --rm --network host cisco-single-mac-monitor \ --host 192.168.1.10 --username admin --password cisco123 --debug 2>container.log ``` --- ## 📈 Monitorización en Producción ### Configuración recomendada en Zabbix 1. **Por dispositivo de red**: - Crear macro `{$CISCO_USER}` y `{$CISCO_PASSWORD}` - Asignar template "Cisco MAC Monitor" - Discovery rule se ejecuta cada 5 minutos 2. **Alertas importantes**: - Cambio en número de MACs por puerto - Nueva MAC no autorizada - Puerto con demasiadas MACs (>5) 3. **Dashboards**: - Gráfico de MACs por dispositivo - Top 10 puertos con más MACs - Alertas recientes de MACs --- ## 🔒 Seguridad ### Mejores prácticas 1. **Credenciales**: - Usar macros de Zabbix para passwords - Crear usuario específico en switches - Rotar credenciales regularmente 2. **Red**: - Ejecutar en VLAN de management - Configurar ACLs en switches - Monitorizar accesos SSH 3. **Contenedor**: - Usuario no privilegiado - Sin volúmenes innecesarios - Imagen base actualizada --- ## 📄 Licencia Este proyecto está bajo licencia MIT. --- **Versión simplificada optimizada para uso individual por dispositivo** 🎯