# 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** 🚀