# MCP Cybersecurity Server

**Servidor MCP para análisis de vulnerabilidades CVE, integrado con la API de CIRCL Vulnerability Lookup**

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.23.1-green.svg)](https://github.com/anthropics/mcp)
[![License](https://img.shields.io/badge/License-Academic-yellow.svg)]()

---

## Descripción

Este proyecto implementa un servidor MCP (Model Context Protocol) especializado en análisis de vulnerabilidades de ciberseguridad. Permite a modelos de lenguaje (LLMs) consultar información de CVEs, analizar riesgos y proporcionar recomendaciones de seguridad basadas en playbooks profesionales y matrices de riesgo.

**Desarrollado para**: Máster en IA Aplicada a Ciberseguridad - Módulo 8 - Tarea 2
**Autor**: José Miguel Teba Luque
**Fecha**: Diciembre 2025

---

## Características Principales

### 🔧 3 Herramientas (Tools)

1. **`search_cve_by_id`**
   - Busca información detallada de un CVE específico
   - Retorna: descripción, CVSS, severidad, referencias, fechas, CWEs

2. **`search_cves_by_keyword`**
   - Busca CVEs por producto, vendor o palabra clave
   - Ideal para descubrir vulnerabilidades de tecnologías específicas

3. **`summarize_cve_risk`**
   - Análisis de riesgo orientado a equipos SOC/Blue Team
   - Incluye EPSS score, nivel de urgencia, SLAs y recomendaciones

### 📚 2 Recursos (Resources)

1. **`playbook_high_risk.md`**
   - Playbook operativo para gestión de vulnerabilidades críticas
   - 4 fases: Detección, Mitigación, Parcheo, Cierre
   - SLA de 4 horas, procedimientos de escalación

2. **`risk_matrix.json`**
   - Matriz de priorización de riesgos
   - 5 niveles: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL
   - Criterios basados en CVSS, EPSS y contexto del activo

### 🤖 1 Prompt Preconfigurado

- **`analyze_asset_vulnerabilities`**
  - Análisis completo de un activo con múltiples CVEs
  - Genera reporte ejecutivo con timeline de remediación
  - Combina tools + resources para análisis integral

---

## Requisitos Previos

- **Python**: 3.10 o superior (recomendado 3.12+)
- **Sistema Operativo**: macOS, Linux, o Windows
- **MCP Host**: Claude Desktop, VS Code con extensión MCP, o cliente MCP compatible
- **Conexión a Internet**: Para consultas a la API de CIRCL

---

## Instalación

### 1. Clonar o Descargar el Proyecto

```bash
# Navegar al directorio del proyecto
cd "/path/to/mcp-cybersecurity-server"
```

### 2. Crear Entorno Virtual

```bash
# Crear entorno virtual con Python 3.12+
python3.12 -m venv venv

# Activar entorno virtual
# En macOS/Linux:
source venv/bin/activate

# En Windows:
venv\Scripts\activate
```

### 3. Instalar Dependencias

```bash
# Actualizar pip
pip install --upgrade pip

# Instalar dependencias del proyecto
pip install -r requirements.txt
```

**Dependencias principales**:
- `mcp>=1.0.0` - Framework MCP oficial de Anthropic
- `httpx>=0.24.0` - Cliente HTTP async
- `pydantic>=2.0.0` - Validación de datos
- `python-dotenv>=1.0.0` - Gestión de variables de entorno

### 4. Verificar Instalación

```bash
# Verificar que MCP se instaló correctamente
python -c "import mcp; print(f'MCP version: {mcp.__version__}')"
```

---

## Configuración

### Configurar Variables de Entorno (Opcional)

```bash
# Copiar archivo de ejemplo
cp .env.example .env

# Editar .env si necesitas personalizar:
# CIRCL_API_BASE_URL=https://vulnerability.circl.lu/api
# LOG_LEVEL=INFO
```

### Configurar Claude Desktop

1. **Ubicar archivo de configuración**:
   ```bash
   # En macOS:
   ~/Library/Application Support/Claude/claude_desktop_config.json

   # En Windows:
   %APPDATA%\Claude\claude_desktop_config.json

   # En Linux:
   ~/.config/Claude/claude_desktop_config.json
   ```

2. **Editar el archivo** y añadir la configuración del servidor:

   ```json
   {
     "mcpServers": {
       "cybersecurity-server": {
         "command": "/RUTA_COMPLETA/mcp-cybersecurity-server/venv/bin/python",
         "args": [
           "-m",
           "src.server"
         ],
         "cwd": "/RUTA_COMPLETA/mcp-cybersecurity-server",
         "env": {
           "CIRCL_API_BASE_URL": "https://vulnerability.circl.lu/api"
         }
       }
     }
   }
   ```

   **IMPORTANTE**: Reemplaza `/RUTA_COMPLETA/` con la ruta absoluta al directorio del proyecto.

   **Ejemplo para macOS**:
   ```json
   {
     "mcpServers": {
       "cybersecurity-server": {
         "command": "/Users/jmteba/Library/Mobile Documents/com~apple~CloudDocs/Máster IA Ciberseguridad /Módulo 8/TAREA 2/mcp-cybersecurity-server/venv/bin/python",
         "args": ["-m", "src.server"],
         "cwd": "/Users/jmteba/Library/Mobile Documents/com~apple~CloudDocs/Máster IA Ciberseguridad /Módulo 8/TAREA 2/mcp-cybersecurity-server"
       }
     }
   }
   ```

3. **Reiniciar Claude Desktop**

4. **Verificar**: En Claude Desktop, deberías ver el servidor "cybersecurity-server" en la lista de servidores MCP disponibles.

---

## Uso

### Test 1: Búsqueda de CVE por ID

**Prompt en Claude Desktop**:
```
Busca información detallada del CVE-2024-3094
```

**Resultado Esperado**:
- Claude invoca la tool `search_cve_by_id`
- Retorna información completa: descripción, CVSS, severidad, referencias
- Para CVE-2024-3094 (XZ backdoor): CVSS 10.0, CRITICAL

---

### Test 2: Búsqueda por Producto/Keyword

**Prompt en Claude Desktop**:
```
Busca las 5 vulnerabilidades más recientes de Apache HTTP Server
```

**Resultado Esperado**:
- Claude invoca `search_cves_by_keyword` con keyword="apache" y limit=5
- Retorna tabla con CVE IDs, severidad, CVSS, fechas y resúmenes

---

### Test 3: Análisis de Riesgo

**Prompt en Claude Desktop**:
```
Analiza el riesgo del CVE-2024-3094 para un servidor web público de producción
```

**Resultado Esperado**:
- Claude invoca `summarize_cve_risk` con contexto="servidor web público"
- Retorna análisis detallado con:
  - Nivel de urgencia (CRÍTICA)
  - EPSS score y probabilidad de explotación
  - SLA de respuesta (4 horas)
  - Recomendaciones de mitigación

---

### Test 4: Consultar Resource

**Prompt en Claude Desktop**:
```
Muéstrame el playbook de respuesta para vulnerabilidades críticas
```

**Resultado Esperado**:
- Claude lee el resource `playbook://high_risk`
- Presenta el contenido del playbook con las 4 fases

---

### Test 5: Usar Prompt Preconfigurado

**Prompt en Claude Desktop**:
```
Analiza las vulnerabilidades del servidor web de producción con estos CVEs:
CVE-2024-3094, CVE-2023-44487, CVE-2023-38545

El servidor está expuesto a Internet y es de criticidad alta.
```

**Resultado Esperado**:
- Claude ejecuta el prompt `analyze_asset_vulnerabilities`
- Invoca múltiples tools:
  - `search_cve_by_id` para cada CVE
  - `summarize_cve_risk` para análisis de riesgo
- Lee resources:
  - `risk_matrix.json` para clasificación
  - `playbook_high_risk.md` si hay CVEs críticos
- Genera reporte completo con:
  - Resumen ejecutivo
  - Tabla priorizada de vulnerabilidades
  - Timeline de remediación
  - Recomendaciones específicas

---

## Estructura del Proyecto

```
mcp-cybersecurity-server/
├── src/
│   ├── __init__.py
│   ├── server.py                 # Servidor MCP principal
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── cve_search.py         # Tool: search_cve_by_id
│   │   ├── cve_keyword.py        # Tool: search_cves_by_keyword
│   │   └── cve_risk.py           # Tool: summarize_cve_risk
│   ├── api/
│   │   ├── __init__.py
│   │   └── circl_client.py       # Cliente para API CIRCL
│   └── utils/
│       ├── __init__.py
│       └── formatters.py         # Utilidades de formato
├── resources/
│   ├── playbook_high_risk.md     # Resource: Playbook crítico
│   └── risk_matrix.json          # Resource: Matriz de riesgos
├── tests/                        # Tests unitarios (opcional)
│   ├── test_tools.py
│   └── test_api.py
├── config/
│   └── mcp_config.json           # Configuración del servidor
├── docs/
│   └── memoria.md                # Documentación de la práctica
├── venv/                         # Entorno virtual (no incluir en git)
├── pyproject.toml                # Metadata y dependencias
├── requirements.txt              # Dependencias pip
├── README.md                     # Este archivo
├── .gitignore
└── .env.example
```

---

## Testing

### Tests Unitarios (Opcional)

```bash
# Activar entorno virtual
source venv/bin/activate

# Ejecutar tests
pytest tests/ -v

# Con cobertura
pytest tests/ --cov=src --cov-report=html
```

### Tests de Integración

1. **Verificar servidor se inicia correctamente**:
   ```bash
   python -m src.server
   # Debe mostrar logs sin errores
   # Ctrl+C para detener
   ```

2. **Test desde Claude Desktop**:
   - Reiniciar Claude Desktop
   - Verificar que "cybersecurity-server" aparece en la lista de servidores
   - Ejecutar los 5 tests de uso descritos arriba

---

## Solución de Problemas

### Error: "CVE not found"
- **Causa**: El CVE no existe en la base de datos de CIRCL
- **Solución**: Verificar el formato (CVE-YYYY-NNNN) y que el CVE está publicado

### Error: "Timeout al consultar API"
- **Causa**: La API de CIRCL está lenta o no responde
- **Solución**: Reintentar después de unos segundos, verificar conexión a Internet

### Error: "Tool not found" en Claude Desktop
- **Causa**: El servidor no está correctamente registrado
- **Solución**:
  1. Verificar `claude_desktop_config.json`
  2. Asegurar que las rutas son absolutas
  3. Reiniciar Claude Desktop

### Error: "Module not found: mcp"
- **Causa**: Dependencias no instaladas o entorno virtual no activado
- **Solución**:
  ```bash
  source venv/bin/activate
  pip install -r requirements.txt
  ```

### El servidor no aparece en Claude Desktop
- **Solución**:
  1. Verificar que el archivo de configuración está en la ubicación correcta
  2. Verificar sintaxis JSON (usar validador online)
  3. Verificar permisos de ejecución: `chmod +x venv/bin/python`
  4. Revisar logs de Claude Desktop (Menu > View > Toggle Developer Tools > Console)

---

## Funcionalidades Avanzadas (Opcionales)

### Caché de Respuestas

Para mejorar el rendimiento, puedes implementar un caché local:

```python
# En src/api/circl_client.py
from functools import lru_cache

@lru_cache(maxsize=100)
async def cached_get_cve(cve_id: str):
    # Implementación con caché
    pass
```

### Logging Personalizado

```bash
# En .env
LOG_LEVEL=DEBUG
LOG_FORMAT=json
```

### Integración con SIEM

El servidor puede integrarse con sistemas SIEM para análisis automatizado de vulnerabilidades.

---

## Contribuciones y Mejoras Futuras

Este proyecto es parte de un trabajo académico, pero las siguientes mejoras podrían implementarse:

- [ ] Integración con NVD (National Vulnerability Database) de NIST
- [ ] Exportación de reportes a PDF
- [ ] Tool adicional para comparar múltiples CVEs
- [ ] Resource adicional con CWEs comunes y recomendaciones
- [ ] Soporte para múltiples idiomas
- [ ] Dashboard web para visualización
- [ ] Integración con Slack/Teams para notificaciones

---

## Referencias y Recursos

### API Utilizada
- **CIRCL Vulnerability Lookup**: https://vulnerability.circl.lu/api/
- **Documentación de la API**: https://vulnerability.circl.lu/

### Estándares de Seguridad
- **CVSS v3.1**: https://www.first.org/cvss/
- **EPSS**: https://www.first.org/epss/
- **CWE Top 25**: https://cwe.mitre.org/top25/
- **OWASP Top 10**: https://owasp.org/www-project-top-ten/

### Documentación Técnica
- **MCP SDK**: https://github.com/anthropics/mcp
- **Claude Desktop**: https://claude.ai/download
- **Model Context Protocol**: https://modelcontextprotocol.io/

---

## Licencia

Este proyecto es un trabajo académico desarrollado para el Máster en IA Aplicada a Ciberseguridad de la Universidad Católica de Murcia (UCAM) en colaboración con ENIIT y Campus Internacional de Ciberseguridad.

**Uso Académico y Educativo**.

---

## Autor

**José Miguel Teba Luque**
- Máster en IA Aplicada a Ciberseguridad
- Módulo 8: Diseño y Publicación de Interfaces para Herramientas IA
- Fecha de entrega: Diciembre 2025

---