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