Labsco
malaya-zemlya logo

TLS MCP Server

★ 2

from malaya-zemlya

Analyze TLS certificates using OpenSSL and zlint.

🔥🔥🔥✓ VerifiedFreeNeeds API keys
#automation#git#maps#finance#security

TLS MCP Server

A Model Context Protocol (MCP) server that provides a unified, user-friendly tool for TLS certificate analysis. No more copying PEM data between functions - everything happens in one clean interface! This tool has been written entirely via Claude Code, as a fun learning project.

🚀 Features

  • All-in-One Interface: Single tool with flexible options for any certificate analysis need
  • Smart Analysis: Automatically uses OpenSSL when available, falls back to Python cryptography
  • Certificate Expiration Monitoring: Automatic expiration checking with human-friendly warnings
  • Cipher Suite Analysis: Comprehensive TLS cipher suite and version support testing
  • Security Grading: Automated security assessment with grades from A+ to F
  • Flexible Options: Choose quick/detailed analysis, include/exclude PEM, enable/disable linting
  • Zero PEM Copying: Analysis happens automatically without manual certificate handling
  • Comprehensive Testing: Full test coverage with unit, integration, and real-world tests

🛠️ Tool Provided

fetch_certificate - All-in-One Certificate Analysis

Fetches and analyzes TLS certificates with flexible options - no need to copy PEM data between tools!

Parameters:

  • hostname (required): Website hostname (e.g., "google.com")
  • port (optional): Port number (default: 443)
  • include_pem (optional): Include raw PEM certificate in output (default: false)
  • analyze (optional): Analysis level - "none", "quick", or "detailed" (default: "quick")
  • lint (optional): Run zlint compliance checking (default: false)
  • use_openssl (optional): Use OpenSSL for analysis when available (default: true)
  • analyze_ciphers (optional): Analyze supported cipher suites and TLS versions (default: false)
  • cipher_scan_type (optional): Type of cipher scan - "quick" or "full" (default: "quick")

Analysis Options:

  • Quick Analysis: Essential certificate info (subject, issuer, validity, SANs)
  • Detailed Analysis: Full certificate details including extensions and key info
  • Expiration Monitoring: Automatic expiration checking with smart warnings:
    • ✅ Valid certificates show time until expiration
    • 🟡 Certificates expiring within 30 days get yellow warning
    • ⚠️ Certificates expiring within 7 days get urgent warning
    • 🔴 Expired certificates show time since expiration
    • ⏳ Future-valid certificates show time until validity
  • OpenSSL vs Cryptography: Automatically uses OpenSSL if available, falls back to Python cryptography

Examples:

  • {"hostname": "google.com"} - Quick analysis only
  • {"hostname": "github.com", "analyze": "detailed", "lint": true} - Detailed analysis + zlint
  • {"hostname": "badssl.com", "analyze": "none", "include_pem": true} - Just fetch PEM

🧪 Testing

Run the comprehensive test suite:

# 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

Test Coverage

  • Unit Tests: Test the new unified interface with mocked dependencies
  • Cipher Analysis Tests: Test cipher categorization, TLS version detection, and security grading
  • Expiration Check Tests: Test certificate validity checking, duration formatting, and timezone handling
  • Basic Integration Tests: Test server registration and tool options
  • Real-World Integration Tests: Test full workflow with live Google certificate
  • Error Handling: Test various failure scenarios
  • Current Coverage: 34 passing tests with comprehensive coverage

📁 Project Structure

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

🔍 Architecture

The server is built using the MCP Python SDK with a modern, user-friendly design:

  1. Single Tool Interface: One fetch_certificate tool with flexible options
  2. Smart Analysis: Automatically chooses OpenSSL or Python cryptography
  3. Async Operations: All operations are asynchronous for better performance
  4. Error Handling: Comprehensive error handling with graceful fallbacks
  5. Modular Helpers: Internal helper functions for different analysis methods
  6. No PEM Juggling: Analysis happens automatically without manual PEM copying

🚨 Security Considerations

  • Certificates are processed locally - no data is sent to external services
  • Network connections use standard SSL/TLS libraries
  • Temporary files are cleaned up after zlint operations
  • Error messages don't expose sensitive system information

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass: pytest tests/ -v
  5. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🏷️ Version History

  • v0.2.1: Added certificate expiration monitoring with human-friendly warnings and timezone handling
  • v0.2.0: Major interface redesign with unified fetch_certificate tool, OpenSSL integration, cipher suite analysis, security grading
  • v0.1.0: Initial release with basic certificate fetching, analysis, and linting