382 lines
10 KiB
Markdown
382 lines
10 KiB
Markdown
# 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> 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
|
|
|
|
```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** 🎯 |