npm package: @modular-intelligence/testssl
Description: MCP server wrapping testssl.sh for TLS/SSL security analysis
Latest version: 1.0.2

# testssl.sh MCP Server

A Model Context Protocol (MCP) server that wraps [testssl.sh](https://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

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

### Test Specific Port

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

### STARTTLS for Email Server

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

### Check Only Vulnerabilities

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

### Test Weak Ciphers

```json
{
  "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)**:
```bash
brew install testssl
```

**Linux**:
```bash
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):
```bash
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**:
```bash
cd /path/to/mi-mcp-servers/packages/testssl
bun install
```

2. **Build the server**:
```bash
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:

```json
{
  "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:

```json
{
  "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

```bash
bun run src/index.ts
```

### Building

```bash
bun run build
```

## License

MIT

## Credits

This MCP server wraps [testssl.sh](https://github.com/drwetter/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.