testssl.sh MCP Server

A Model Context Protocol (MCP) server that wraps testssl.sh for comprehensive TLS/SSL security analysis. This server provides AI assistants with the ability to analyze TLS configurations, detect vulnerabilities, and assess security posture of HTTPS endpoints.

Overview

This MCP server exposes testssl.sh functionality through structured tools that can be used by AI assistants to perform security assessments. All operations require explicit authorization and include safety controls to prevent misuse.

Features

• Comprehensive TLS Analysis: Full-spectrum scanning of protocols, ciphers, and vulnerabilities
• Protocol Testing: Identify supported SSL/TLS versions
• Cipher Suite Enumeration: Evaluate cryptographic strength
• Vulnerability Detection: Check for Heartbleed, POODLE, BEAST, ROBOT, and more
• Certificate Analysis: Validate chains, expiration, and configuration
• Security Headers: Assess HTTP security headers (HSTS, CSP, etc.)
• Security Rating: Overall security grade assessment
• STARTTLS Support: Test SMTP, IMAP, POP3, FTP, and other protocols

Tools

| Tool | Description | Typical Duration | |------|-------------|------------------| | testssl_full_scan | Comprehensive analysis of all TLS aspects | 2-5 minutes | | testssl_protocols | Test SSL/TLS protocol support | 30-60 seconds | | testssl_ciphers | Enumerate and evaluate cipher suites | 1-2 minutes | | testssl_vulnerabilities | Check for known TLS vulnerabilities | 1-3 minutes | | testssl_certificate | Analyze certificate chain and validity | 30-60 seconds | | testssl_headers | Analyze HTTP security headers | 10-30 seconds | | testssl_rating | Get overall TLS security grade | 2-5 minutes |

Parameters

Common Parameters

All tools share these common parameters:

• host (required): Target hostname or IP with optional port (e.g., example.com, example.com:8443)
• authorized (required): Boolean confirmation that you have permission to test the target
• port (optional): Target port number (1-65535, default: 443)
• timeout (optional): Maximum scan duration in seconds (30-600, default: 300)

Tool-Specific Parameters

testssl_full_scan

• starttls (optional): STARTTLS protocol - one of: smtp, pop3, imap, ftp, xmpp, ldap, postgres, mysql

testssl_ciphers

• cipher_category (optional): Category of ciphers to test
  • strong: Strong cipher suites only
  • weak: Weak cipher suites
  • null: Null encryption ciphers
  • export: Export-grade ciphers
  • obsolete: Obsolete/deprecated ciphers
  • all: All cipher categories (default)

Examples

Full Security Scan

{
  "host": "example.com",
  "authorized": true,
  "timeout": 300
}

Test Specific Port

{
  "host": "example.com",
  "authorized": true,
  "port": 8443
}

STARTTLS for Email Server

{
  "host": "mail.example.com",
  "authorized": true,
  "port": 587,
  "starttls": "smtp"
}

Check Only Vulnerabilities

{
  "host": "example.com",
  "authorized": true,
  "timeout": 180
}

Test Weak Ciphers

{
  "host": "example.com",
  "authorized": true,
  "cipher_category": "weak"
}

Security

Authorization Requirements

All scans require explicit authorization via the authorized parameter. This is a safety mechanism to ensure users consciously acknowledge they have permission to test the target system.

Important: Only scan systems you own or have explicit written permission to test. Unauthorized security scanning may be illegal in your jurisdiction.

Safety Controls

1. Private IP Blocking: Prevents scanning of internal/private IP addresses:

   • 10.0.0.0/8
   • 172.16.0.0/12
   • 192.168.0.0/16
   • 127.0.0.0/8 (localhost)
   • ::1, fe80:: (IPv6 local addresses)

2. File Writing Blocked: Prevents file system operations via blocked flags:

   • --logfile, --csvfile, --jsonfile, --htmlfile
   • --outFile, --outfile, --append

3. Input Validation:

   • Host format validation (alphanumeric, dots, hyphens, colons only)
   • Port range validation (1-65535)
   • Timeout limits (30-600 seconds)

4. Execution Timeouts: All scans are time-limited to prevent infinite runs

Best Practices

• Always obtain written authorization before scanning third-party systems
• Use appropriate timeout values to avoid disrupting target services
• Start with quick scans (protocols, headers) before running full scans
• Review your organization's security testing policies
• Consider rate limiting when scanning multiple targets

Prerequisites

Install testssl.sh

macOS (Homebrew):

brew install testssl

Linux:

git clone --depth 1 https://github.com/drwetter/testssl.sh.git
cd testssl.sh
chmod +x testssl.sh
sudo ln -s $(pwd)/testssl.sh /usr/local/bin/testssl.sh

Environment Variable (optional):

export TESTSSL_PATH=/path/to/testssl.sh

If TESTSSL_PATH is not set, the server assumes testssl.sh is in your PATH.

Installation

1. Install dependencies:

cd /path/to/mi-mcp-servers/packages/testssl
bun install

2. Build the server:

bun run build

3. Configure MCP client (e.g., Claude Desktop):

Edit your MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the testssl server:

{
  "mcpServers": {
    "testssl": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/testssl/src/index.ts"],
      "env": {
        "TESTSSL_PATH": "/usr/local/bin/testssl.sh"
      }
    }
  }
}

4. Restart Claude Desktop

Usage

Once configured, you can ask Claude to perform TLS security assessments:

"Can you scan example.com for TLS vulnerabilities?"

"Check the certificate configuration for mail.example.com on port 587 using STARTTLS SMTP"

"What security headers does example.com send?"

"Give me a full security assessment of api.example.com"

Claude will request authorization confirmation before performing any scans.

Output Format

All tools return structured JSON data with the following common fields:

• target: The scanned target (host:port)
• scan_date: ISO 8601 timestamp of the scan
• [tool-specific fields]: Detailed findings

Example output structure:

{
  "target": "example.com:443",
  "scan_date": "2026-02-09T10:30:00.000Z",
  "protocols": [...],
  "vulnerabilities": [...],
  "certificate": {...},
  "overall_rating": "B"
}

Troubleshooting

testssl.sh not found

Error: testssl.sh: command not found

Solution: Install testssl.sh or set TESTSSL_PATH environment variable

Timeout errors

Error: testssl.sh timed out after N seconds

Solution: Increase the timeout parameter or check network connectivity

Permission errors

Error: You must explicitly authorize scanning

Solution: Set "authorized": true in your request parameters

Private IP blocked

Error: Private IP addresses and localhost are not allowed

Solution: This is a security feature. Use a public IP or hostname for scanning.

Limitations

• Maximum timeout: 600 seconds (10 minutes)
• Output buffer: 10 MB
• Cannot scan private/internal IP addresses
• Cannot write results to files directly
• Requires testssl.sh to be installed on the system

Development

Project Structure

testssl/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts           # Main MCP server
│   ├── schemas.ts         # Zod validation schemas
│   ├── security.ts        # Security validation
│   ├── cli-executor.ts    # testssl.sh execution wrapper
│   └── tools/
│       ├── testssl-full-scan.ts
│       ├── testssl-protocols.ts
│       ├── testssl-ciphers.ts
│       ├── testssl-vulnerabilities.ts
│       ├── testssl-certificate.ts
│       ├── testssl-headers.ts
│       └── testssl-rating.ts

Running in Development

bun run src/index.ts

Building

bun run build

License

MIT

Credits

This MCP server wraps testssl.sh by Dirk Wetter and contributors.

Disclaimer

This tool is provided for authorized security testing only. Users are responsible for ensuring they have permission to scan target systems. Unauthorized security testing may violate laws such as the Computer Fraud and Abuse Act (CFAA) in the United States or similar legislation in other jurisdictions.