git/los-vecinos-de-cisco
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7fc616b5c3fea0732622e50d32dbfe8f4af002de
los-vecinos-de-cisco/no/README.md
T
Xavier Rodriguez 7fc616b5c3 first commit
2025-12-09 12:45:15 +01:00

10 KiB
Raw Blame History

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

# Usar Dockerfile específico para versión single
docker build -f Dockerfile -t cisco-mac-monitor .

2. Ejecutar para un dispositivo

# 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

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

# 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

python3 cisco_single_mac_monitor.py [OPTIONS]

Argumentos requeridos:
  --host/-H <IP>        IP o hostname del dispositivo Cisco
  --username/-u <USER>  Usuario SSH
  --password/-p <PASS>  Contraseña SSH

Argumentos opcionales:
  --port/-P <PORT>      Puerto SSH (default: 22)
  --timeout/-t <SEC>    Timeout en segundos (default: 30)
  --hostname/-n <NAME>  Nombre del dispositivo (default: usa --host)
  --debug/-d            Modo debug
  --quiet/-q            Modo silencioso (solo JSON)

Ejemplos de uso

# 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

# 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

# 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

{
  "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:

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

{$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

#!/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

# 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

# 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

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

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

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

# Verificar imagen
docker images | grep cisco-single-mac

# Reconstruir si es necesario
docker build -f Dockerfile.single -t cisco-single-mac-monitor .

Logs útiles

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

Reference in New Issue View Git Blame Copy Permalink