TLS MCP Server

Analise certificados TLS usando OpenSSL e zlint.

Documentação

TLS MCP Server

Um servidor Model Context Protocol (MCP) que fornece uma ferramenta unificada e amigável para análise de certificados TLS. Chega de copiar dados PEM entre funções — tudo acontece em uma interface limpa! Esta ferramenta foi escrita inteiramente via Claude Code, como um projeto divertido de aprendizado.

🚀 Recursos

Interface Tudo-em-Um: Ferramenta única com opções flexíveis para qualquer necessidade de análise de certificados
Análise Inteligente: Usa automaticamente OpenSSL quando disponível, com fallback para Python cryptography
Monitoramento de Expiração de Certificados: Verificação automática de expiração com avisos amigáveis
Análise de Suites de Cifras: Teste abrangente de suites de cifras TLS e suporte a versões
Classificação de Segurança: Avaliação de segurança automatizada com notas de A+ a F
Opções Flexíveis: Escolha análise rápida/detalhada, incluir/excluir PEM, ativar/desativar linting
Zero Cópia de PEM: A análise acontece automaticamente sem manipulação manual de certificados
Testes Abrangentes: Cobertura completa de testes com testes unitários, de integração e de mundo real

🛠️ Ferramenta Fornecida

`fetch_certificate` - Análise de Certificados Tudo-em-Um

Busca e analisa certificados TLS com opções flexíveis — sem necessidade de copiar dados PEM entre ferramentas!

Parâmetros:

hostname (obrigatório): Hostname do site (ex.: "google.com")
port (opcional): Número da porta (padrão: 443)
include_pem (opcional): Incluir certificado PEM bruto na saída (padrão: false)
analyze (opcional): Nível de análise - "none", "quick" ou "detailed" (padrão: "quick")
lint (opcional): Executar verificação de conformidade zlint (padrão: false)
use_openssl (opcional): Usar OpenSSL para análise quando disponível (padrão: true)
analyze_ciphers (opcional): Analisar suites de cifras suportadas e versões TLS (padrão: false)
cipher_scan_type (opcional): Tipo de varredura de cifras - "quick" ou "full" (padrão: "quick")

Opções de Análise:

Análise Rápida: Informações essenciais do certificado (assunto, emissor, validade, SANs)
Análise Detalhada: Detalhes completos do certificado, incluindo extensões e informações de chave
Monitoramento de Expiração: Verificação automática de expiração com avisos inteligentes:
- ✅ Certificados válidos mostram o tempo até a expiração
- 🟡 Certificados que expiram em até 30 dias recebem aviso amarelo
- ⚠️ Certificados que expiram em até 7 dias recebem aviso urgente
- 🔴 Certificados expirados mostram o tempo desde a expiração
- ⏳ Certificados válidos no futuro mostram o tempo até a validade
OpenSSL vs Cryptography: Usa automaticamente OpenSSL se disponível, com fallback para Python cryptography

Exemplos:

{"hostname": "google.com"} - Apenas análise rápida
{"hostname": "github.com", "analyze": "detailed", "lint": true} - Análise detalhada + zlint
{"hostname": "badssl.com", "analyze": "none", "include_pem": true} - Apenas buscar PEM

📋 Pré-requisitos

Python 3.13+
zlint (para linting de certificados)
OpenSSL (para operações com 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

🔧 Instalação

Clone e configure o projeto:

git clone <repository-url>
cd tls-mcp
python3.13 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Instale dependências de desenvolvimento (opcional):

pip install -e ".[dev]"

Execute os testes para verificar a instalação:

pytest tests/ -v

⚙️ Configuração

Adicione o seguinte ao arquivo de configuração do Claude Desktop:

Localização: ~/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"
      }
    }
  }
}

Substitua /path/to/your/tls-mcp pelo caminho real do seu projeto.

🚦 Exemplos de Uso

Após a configuração, reinicie o Claude Desktop e tente estes comandos:

Análise Rápida de Certificado (Padrão)

"Analyze the certificate for github.com"

Análise Detalhada com Verificação de Conformidade

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

Apenas Buscar Certificado (Sem Análise)

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

Comparar Múltiplos Certificados

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

Avaliação de Segurança

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

Análise de Suites de Cifras

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

Análise de Segurança Abrangente

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

Principais Benefícios:

✅ Sem cópia de PEM - A análise acontece automaticamente
✅ Opções flexíveis - Escolha quais informações você precisa
✅ Padrões inteligentes - Funciona muito bem imediatamente
✅ Integração com OpenSSL - Usa as melhores ferramentas disponíveis

🧪 Testes

Execute a suíte de testes abrangente:

# 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 Testes

Testes Unitários: Testam a nova interface unificada com dependências simuladas
Testes de Análise de Cifras: Testam categorização de cifras, detecção de versões TLS e classificação de segurança
Testes de Verificação de Expiração: Testam verificação de validade de certificados, formatação de duração e tratamento de fuso horário
Testes de Integração Básicos: Testam registro do servidor e opções de ferramentas
Testes de Integração com Mundo Real: Testam o fluxo completo com certificado ao vivo do Google
Tratamento de Erros: Testam vários cenários de falha
Cobertura Atual: 34 testes passando com cobertura abrangente

📁 Estrutura do Projeto

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

🔍 Arquitetura

O servidor é construído usando o MCP Python SDK com um design moderno e amigável:

Interface de Ferramenta Única: Uma ferramenta fetch_certificate com opções flexíveis
Análise Inteligente: Escolhe automaticamente entre OpenSSL e Python cryptography
Operações Assíncronas: Todas as operações são assíncronas para melhor desempenho
Tratamento de Erros: Tratamento abrangente de erros com fallbacks graciosos
Helpers Modulares: Funções auxiliares internas para diferentes métodos de análise
Sem Manipulação de PEM: A análise acontece automaticamente sem cópia manual de PEM

🚨 Considerações de Segurança

Os certificados são processados localmente - nenhum dado é enviado a serviços externos
Conexões de rede usam bibliotecas SSL/TLS padrão
Arquivos temporários são limpos após operações zlint
Mensagens de erro não expõem informações sensíveis do sistema

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Adicione testes para novas funcionalidades
Garanta que todos os testes passem: pytest tests/ -v
Envie um pull request

📝 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🆘 Solução de Problemas

Problemas Comuns

"comando zlint não encontrado"

Instale o zlint usando as instruções acima
Verifique se ele está no seu PATH: which zlint

"Falha ao buscar certificado"

Verifique sua conexão com a internet
Confirme se o hostname está correto
Alguns servidores podem bloquear solicitações automatizadas

"Servidor MCP não aparece no Claude"

Verifique se o caminho do arquivo de configuração está correto
Confirme se o caminho do Python no config aponta para seu ambiente virtual
Reinicie o Claude Desktop após alterações na configuração

Modo de Depuração

Ative o registro de depuração definindo a variável de ambiente:

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

🏷️ Histórico de Versões

v0.2.1: Adicionado monitoramento de expiração de certificados com avisos amigáveis e tratamento de fuso horário
v0.2.0: Redesenho importante da interface com ferramenta unificada fetch_certificate, integração com OpenSSL, análise de suites de cifras, classificação de segurança
v0.1.0: Lançamento inicial com busca básica de certificados, análise e linting

TLS MCP Server

Documentação

TLS MCP Server

🚀 Recursos

🛠️ Ferramenta Fornecida

fetch_certificate - Análise de Certificados Tudo-em-Um

📋 Pré-requisitos

Instalar zlint

🔧 Instalação

⚙️ Configuração

🚦 Exemplos de Uso

Análise Rápida de Certificado (Padrão)

Análise Detalhada com Verificação de Conformidade

Apenas Buscar Certificado (Sem Análise)

Comparar Múltiplos Certificados

Avaliação de Segurança

Análise de Suites de Cifras

Análise de Segurança Abrangente

🧪 Testes

Cobertura de Testes

📁 Estrutura do Projeto

🔍 Arquitetura

🚨 Considerações de Segurança

🤝 Contribuindo

📝 Licença

🆘 Solução de Problemas

Problemas Comuns

Modo de Depuração

🏷️ Histórico de Versões

`fetch_certificate` - Análise de Certificados Tudo-em-Um