TLS MCP Server

Analizar certificados TLS usando OpenSSL y zlint.

GitHub
2
Prueba este MCPPatrocinado

Documentación

Servidor TLS MCP

Un servidor Model Context Protocol (MCP) que proporciona una herramienta unificada y fácil de usar para el análisis de certificados TLS. ¡No más copiar datos PEM entre funciones: todo ocurre en una sola interfaz limpia! Esta herramienta ha sido escrita completamente mediante Claude Code, como un proyecto divertido de aprendizaje.

🚀 Características

  • Interfaz Todo-en-Uno: Herramienta única con opciones flexibles para cualquier necesidad de análisis de certificados
  • Análisis Inteligente: Utiliza automáticamente OpenSSL cuando está disponible, y recurre a la criptografía de Python
  • Monitoreo de Expiración de Certificados: Verificación automática de expiración con avisos amigables para humanos
  • Análisis de Suites de Cifrado: Pruebas exhaustivas de suites de cifrado TLS y soporte de versiones
  • Calificación de Seguridad: Evaluación automática de seguridad con calificaciones de A+ a F
  • Opciones Flexibles: Elija análisis rápido/detallado, incluir/excluir PEM, habilitar/deshabilitar linting
  • Cero Copiado de PEM: El análisis ocurre automáticamente sin manejo manual de certificados
  • Pruebas Exhaustivas: Cobertura completa de pruebas con pruebas unitarias, de integración y del mundo real

🛠️ Herramienta Proporcionada

fetch_certificate - Análisis de Certificados Todo-en-Uno

Obtiene y analiza certificados TLS con opciones flexibles: ¡no necesita copiar datos PEM entre herramientas!

Parámetros:

  • hostname (obligatorio): Nombre de host del sitio web (p. ej., "google.com")
  • port (opcional): Número de puerto (predeterminado: 443)
  • include_pem (opcional): Incluir certificado PEM crudo en la salida (predeterminado: false)
  • analyze (opcional): Nivel de análisis: "none", "quick" o "detailed" (predeterminado: "quick")
  • lint (opcional): Ejecutar verificación de cumplimiento zlint (predeterminado: false)
  • use_openssl (opcional): Usar OpenSSL para el análisis cuando esté disponible (predeterminado: true)
  • analyze_ciphers (opcional): Analizar suites de cifrado y versiones TLS compatibles (predeterminado: false)
  • cipher_scan_type (opcional): Tipo de escaneo de cifrado: "quick" o "full" (predeterminado: "quick")

Opciones de Análisis:

  • Análisis Rápido: Información esencial del certificado (sujeto, emisor, validez, SANs)
  • Análisis Detallado: Detalles completos del certificado, incluidas extensiones e información de claves
  • Monitoreo de Expiración: Verificación automática de expiración con avisos inteligentes:
    • ✅ Los certificados válidos muestran el tiempo hasta la expiración
    • 🟡 Los certificados que expiran dentro de 30 días reciben una advertencia amarilla
    • ⚠️ Los certificados que expiran dentro de 7 días reciben una advertencia urgente
    • 🔴 Los certificados expirados muestran el tiempo desde la expiración
    • ⏳ Los certificados válidos en el futuro muestran el tiempo hasta la validez
  • OpenSSL vs Criptografía: Utiliza automáticamente OpenSSL si está disponible; de lo contrario, recurre a la criptografía de Python

Ejemplos:

  • {"hostname": "google.com"} - Solo análisis rápido
  • {"hostname": "github.com", "analyze": "detailed", "lint": true} - Análisis detallado + zlint
  • {"hostname": "badssl.com", "analyze": "none", "include_pem": true} - Solo obtener PEM

📋 Requisitos Previos

  • Python 3.13+
  • zlint (para linting de certificados)
  • OpenSSL (para operaciones con certificados)

Instalar zlint

# macOS
brew install zlint

# Linux
go install github.com/zmap/zlint/v3/cmd/zlint@latest

# Or download from releases: https://github.com/zmap/zlint/releases

🔧 Instalación

  1. Clonar y configurar el proyecto:
git clone <repository-url>
cd tls-mcp
python3.13 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
  1. Instalar dependencias de desarrollo (opcional):
pip install -e ".[dev]"
  1. Ejecutar pruebas para verificar la instalación:
pytest tests/ -v

⚙️ Configuración

Agregue lo siguiente a su archivo de configuración de Claude Desktop:

Ubicación: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tls-mcp-server": {
      "command": "/path/to/your/tls-mcp/venv/bin/python",
      "args": [
        "/path/to/your/tls-mcp/tls_mcp_server/main.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/tls-mcp"
      }
    }
  }
}

Reemplace /path/to/your/tls-mcp con la ruta real de su proyecto.

🚦 Ejemplos de Uso

Después de la configuración, reinicie Claude Desktop y pruebe estos comandos:

Análisis Rápido de Certificados (Predeterminado)

"Analyze the certificate for github.com"

Análisis Detallado con Verificación de Cumplimiento

"Do a detailed analysis of google.com's certificate and run zlint on it"

Solo Obtener Certificado (Sin Análisis)

"Get me the raw PEM certificate for badssl.com"

Comparar Múltiples Certificados

"Use the TLS certificate tool to analyze both google.com and github.com, then compare their key differences"

Evaluación de Seguridad

"Use the TLS certificate tool to check if example.com uses secure certificate practices with full analysis and linting"

Análisis de Suites de Cifrado

"Use the TLS certificate tool to analyze the cipher suites supported by github.com and give me a security assessment"

Análisis de Seguridad Exhaustivo

"Use the TLS certificate tool to do a full security analysis of google.com including cipher suites, TLS versions, and certificate compliance"

Beneficios Clave:

  • ✅ Sin copiado de PEM - El análisis ocurre automáticamente
  • ✅ Opciones flexibles - Elija qué información necesita
  • ✅ Valores predeterminados inteligentes - Funciona muy bien desde el primer momento
  • ✅ Integración con OpenSSL - Utiliza las mejores herramientas disponibles

🧪 Pruebas

Ejecute el conjunto de pruebas exhaustivo:

# Run all tests (including slow integration tests)
pytest tests/ -v

# Run only fast tests (excludes slow integration tests that require internet)
pytest tests/ -m "not slow" -v

# Run with coverage
pytest tests/ --cov=tls_mcp_server --cov-report=term-missing

# Run only unit tests
pytest tests/test_mcp_server.py -v

# Run only basic integration tests
pytest tests/test_integration.py -v

# Run real-world integration tests (requires internet and zlint)
pytest tests/test_google_integration.py -v

Cobertura de Pruebas

  • Pruebas Unitarias: Prueban la nueva interfaz unificada con dependencias simuladas
  • Pruebas de Análisis de Cifrado: Prueban la categorización de cifrados, la detección de versiones TLS y la calificación de seguridad
  • Pruebas de Verificación de Expiración: Prueban la verificación de validez de certificados, el formato de duración y el manejo de zonas horarias
  • Pruebas de Integración Básicas: Prueban el registro del servidor y las opciones de herramientas
  • Pruebas de Integración del Mundo Real: Prueban el flujo de trabajo completo con el certificado en vivo de Google
  • Manejo de Errores: Prueban varios escenarios de fallo
  • Cobertura Actual: 34 pruebas aprobadas con cobertura exhaustiva

📁 Estructura del Proyecto

tls-mcp/
├── tls_mcp_server/
│   ├── __init__.py          # Package initialization
│   └── main.py              # MCP server implementation
├── tests/
│   ├── __init__.py              # Test package
│   ├── test_mcp_server.py       # Unit tests
│   ├── test_cipher_analysis.py  # Cipher analysis tests
│   ├── test_expiration_check.py # Expiration checking tests
│   └── test_integration.py      # Integration tests
├── pyproject.toml           # Project configuration
├── pytest.ini              # Test configuration
└── README.md               # This file

🔍 Arquitectura

El servidor está construido con el SDK de Python de MCP con un diseño moderno y fácil de usar:

  1. Interfaz de Herramienta Única: Una herramienta fetch_certificate con opciones flexibles
  2. Análisis Inteligente: Elige automáticamente entre OpenSSL o criptografía de Python
  3. Operaciones Asíncronas: Todas las operaciones son asíncronas para un mejor rendimiento
  4. Manejo de Errores: Manejo exhaustivo de errores con respaldos elegantes
  5. Ayudantes Modulares: Funciones auxiliares internas para diferentes métodos de análisis
  6. Sin Manejo Manual de PEM: El análisis ocurre automáticamente sin copiado manual de PEM

🚨 Consideraciones de Seguridad

  • Los certificados se procesan localmente: no se envían datos a servicios externos
  • Las conexiones de red utilizan bibliotecas SSL/TLS estándar
  • Los archivos temporales se limpian después de las operaciones de zlint
  • Los mensajes de error no exponen información sensible del sistema

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Agregue pruebas para la nueva funcionalidad
  4. Asegúrese de que todas las pruebas pasen: pytest tests/ -v
  5. Envíe una solicitud de extracción

📝 Licencia

Licencia MIT: consulte el archivo LICENSE para más detalles.

🆘 Solución de Problemas

Problemas Comunes

"Comando zlint no encontrado"

  • Instale zlint usando las instrucciones anteriores
  • Verifique que esté en su PATH: which zlint

"No se pudo obtener el certificado"

  • Verifique su conexión a internet
  • Verifique que el nombre de host sea correcto
  • Algunos servidores pueden bloquear solicitudes automatizadas

"El servidor MCP no aparece en Claude"

  • Verifique que la ruta del archivo de configuración sea correcta
  • Compruebe que la ruta de Python en la configuración apunte a su entorno virtual
  • Reinicie Claude Desktop después de los cambios de configuración

Modo de Depuración

Habilite el registro de depuración configurando la variable de entorno:

export PYTHONPATH="/path/to/tls-mcp"
python tls_mcp_server/main.py

🏷️ Historial de Versiones

  • v0.2.1: Se agregó monitoreo de expiración de certificados con avisos amigables para humanos y manejo de zonas horarias
  • v0.2.0: Rediseño importante de la interfaz con herramienta unificada fetch_certificate, integración con OpenSSL, análisis de suites de cifrado, calificación de seguridad
  • v0.1.0: Lanzamiento inicial con obtención, análisis y linting básicos de certificados