first commit
This commit is contained in:
Xavier Rodriguez
+382
@@ -0,0 +1,382 @@
|
||||
# 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** 🎯
|
||||
Reference in New Issue
Block a user