453 lines
11 KiB
Markdown
453 lines
11 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`
|
|
|
|
```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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
#!/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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```python
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Verificar salida
|
|
docker-compose exec cisco-mac-monitor single-run
|
|
cat data/cisco_mac_data.json | jq .
|
|
```
|
|
|
|
**3. No se detectan MACs:**
|
|
```bash
|
|
# Verificar comando en dispositivo
|
|
ssh admin@192.168.1.10
|
|
show mac address-table
|
|
|
|
# Verificar filtros en config.yaml
|
|
```
|
|
|
|
**4. Container no inicia:**
|
|
```bash
|
|
# Verificar logs
|
|
docker-compose logs cisco-mac-monitor
|
|
|
|
# Verificar configuración
|
|
docker-compose exec cisco-mac-monitor test-config
|
|
```
|
|
|
|
### Logs útiles
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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** 🚀 |