# Common testssl.sh Command-Line Options and Flags: A Complete Guide

> Master testssl.sh command-line options and flags. This guide covers essential switches to efficiently scan TLS/SSL configurations and identify vulnerabilities. Optimize your security checks today.

- Repository: [Dirk Wetter/testssl.sh](https://github.com/drwetter/testssl.sh)
- Tags: how-to-guide
- Published: 2026-03-01

---

**testssl.sh processes over 100 command-line switches through its `parse_cmd_line` function around line 9,300, using boolean `do_*` variables to gate specific test blocks executed by `lets_roll` and various `run_*` functions.**

testssl.sh is a single-file Bash utility developed by drwetter/testssl.sh that provides comprehensive SSL/TLS security testing through an extensive command-line interface. Understanding the available **testssl.sh command-line options** allows security professionals to customize scans for specific protocols, output formats, and vulnerability checks while controlling network behavior and performance characteristics.

## Core testssl.sh Command-Line Architecture

The script's argument processing centers on the `parse_cmd_line` function located near line 9,300 in [`testssl.sh`](https://github.com/drwetter/testssl.sh/blob/main/testssl.sh). This function populates boolean variables prefixed with `do_*` that gate individual test blocks through a large `case` statement around line 25,000. The `lets_roll` function subsequently executes enabled tests by calling specific `run_*` functions such as `run_protocols()`, `run_cipherlists()`, and `run_heartbleed()`.

## Target Specification and Network Options

### Basic Invocation Methods

- Single target scan: `testssl.sh <URI>`
- Mass testing from file: `testssl.sh --file <FILE>`

### IP Version and Proxy Configuration

- **Force IPv4 or IPv6**: Use `-4` or `-6` to restrict the connection protocol
- **Custom IP resolution**: `--ip <addr|one|proxy>` resolves a specific IP address or interaction method
- **HTTP proxy routing**: `--proxy <host:port>` routes all checks through the specified proxy
- **Native OpenSSL only**: `--ssl-native` forces OpenSSL client usage and disables socket fallback

## Output Control and Reporting Formats

### Structured Data Export

- **JSON output**: `--json` or `--json-pretty` for machine-readable results
- **CSV export**: `--csv` or `--csvfile <directory>` for spreadsheet compatibility  
- **HTML reports**: `--html` for standalone documentation
- **Combined formats**: `-oA <name>` generates all formats, while `-oa <name>` creates log and CSV only

### Display and Logging Tuning

- **Suppress banner**: `-q` or `--quiet` hides the startup header
- **Wide output**: `--wide` enables full-column display
- **Color schemes**: `--color <0|1|2|3>` controls colorization; `--colorblind` adjusts for accessibility
- **Log files**: `--log` or `--logfile <file>` writes raw output to disk
- **Output prefixing**: `--outprefix <prefix>` prepends a string to all output filenames

## Scanning Scope and Test Categories

### Protocol and Cipher Analysis

- **Protocol versions**: `-p` or `--protocols` tests SSLv2 through TLSv1.3
- **Standard cipher groups**: `-s` or `--std` or `--categories` runs predefined cipher list checks
- **Forward secrecy**: `-f` or `--fs` focuses on PFS-capable cipher suites
- **Server preferences**: `-P` or `--server-preference` evaluates the server's cipher ordering
- **Server defaults**: `-S` or `--server_defaults` analyzes negotiated parameters
- **HTTP headers**: `-h` or `--header` checks security-related HTTP headers
- **Client simulation**: `-c` or `--client-simulation` emulates specific browser SSL/TLS behavior
- **Grease tests**: `-g` or `--grease` sends invalid values to test robustness

### Exhaustive Cipher Testing

- **Individual ciphers**: `-e` or `--each-cipher` tests every cipher separately (computationally expensive)
- **Per-protocol ciphers**: `-E` or `--cipher-per-proto` groups cipher tests by protocol version

### STARTTLS Support

The `-t <protocol>` or `--starttls <protocol>` flag enables testing of protocols that upgrade plain connections to TLS, supporting `smtp`, `ftp`, `pop3`, `imap`, `xmpp`, `ldap`, `nntp`, `mysql`, `postgres`, and `irc`.

## Vulnerability Detection Flags

Individual CVE checks can be run with specific switches:

- **Heartbleed**: `-H` or `--heartbleed`
- **CCS Injection**: `-I` or `--ccs`  
- **Ticketbleed**: `--ticketbleed`
- **ROBOT**: `--robot`
- **Renegotiation**: `--renegotiation`
- **CRIME**: `-C` or `--crime`
- **BREACH**: `-B` or `--breach`
- **POODLE**: `-O` or `--poodle`
- **TLS Fallback**: `-Z` or `--tls-fallback`
- **Sweet32**: `-W` or `--sweet32`
- **FREAK**: `-F` or `--freak`
- **DROWN**: `-D` or `--drown`
- **Logjam**: `-J` or `--logjam`
- **BEAST**: `-A` or `--beast`
- **Lucky13**: `-L` or `--lucky13`
- **RC4**: `--rc4`
- **Winshock**: `--winshock`

Run all vulnerability checks simultaneously with `-U` or `--vulnerable`.

## Advanced Tuning and Debugging

### Performance and Timeout Controls

- **Custom OpenSSL binary**: `--openssl <path>` overrides the bundled or system OpenSSL
- **OpenSSL timeout**: `--openssl-timeout <sec>` sets the OpenSSL connection timeout
- **Socket timeout**: `--socket-timeout <sec>` controls native socket timeouts

### Authentication and Request Modification

- **HTTP Basic Auth**: `--basicauth <user:pass>` supplies credentials for protected endpoints
- **Custom headers**: `--reqheader <Header: value>` injects arbitrary HTTP headers
- **Mutual TLS**: `--mtls <pem>` provides client certificates for authentication
- **Additional CA bundles**: `--add-ca <ca-file>` extends the trusted certificate chain

### Rating and Debugging Options

- **Rating calculation only**: `--rating-only` runs only the grading logic without full tests
- **Disable rating**: `--disable-rating` suppresses the final grade output
- **Severity filtering**: `--severity <LEVEL>` filters findings by severity (low, medium, high, critical)
- **Debug verbosity**: `--debug <0-6>` enables increasing levels of diagnostic output
- **Hints display**: `--hints` shows additional remediation guidance

## Practical testssl.sh Usage Examples

Default comprehensive scan against a single target:

```bash
testssl.sh https://example.com

```

Protocol and cipher order scanning with structured output:

```bash
testssl.sh -p -P --json --html https://example.com

```

STARTTLS SMTP scan with IPv4 forcing and suppressed banner:

```bash
testssl.sh -4 -t smtp --ssl-native --quiet smtp.mail.example.com:25

```

Mass testing with CSV and log output to a directory:

```bash
testssl.sh --file hosts.txt --log --csvfile results/

```

Specific vulnerability check with socket timeout:

```bash
testssl.sh --heartbleed --socket-timeout 5 example.org

```

Custom OpenSSL binary with accessibility features:

```bash
testssl.sh --openssl /opt/openssl-3.2/bin/openssl --wide --colorblind https://secure.example.net

```

## Summary

- **testssl.sh command-line options** are parsed by the `parse_cmd_line` function in [`testssl.sh`](https://github.com/drwetter/testssl.sh/blob/main/testssl.sh), which sets boolean `do_*` variables to enable specific test blocks executed by `lets_roll` and `run_*` functions
- Network configuration includes IPv4/IPv6 forcing (`-4`, `-6`), HTTP proxy support (`--proxy`), and custom IP resolution (`--ip`)
- Output formats encompass JSON (`--json`), CSV (`--csv`), HTML (`--html`), and combined logging (`-oA`) for comprehensive documentation
- Scanning scope is controlled via protocol checks (`-p`), cipher tests (`-s`, `-e`), server preference analysis (`-P`), and STARTTLS support (`-t`)
- Individual vulnerability tests can be targeted with flags like `--heartbleed`, `--robot`, and `--logjam`, or run collectively with `--vulnerable`
- Advanced tuning allows custom OpenSSL binaries (`--openssl`), timeout configuration, HTTP basic authentication, and mutual TLS client certificates

## Frequently Asked Questions

### How does testssl.sh handle command-line parsing internally?

According to the drwetter/testssl.sh source code, the `parse_cmd_line` function around line 9,300 processes arguments using a large `case` statement near line 25,000. It populates boolean variables prefixed with `do_*` that determine which tests execute when `lets_roll` calls the corresponding `run_*` functions such as `run_protocols()` or `run_heartbleed()`.

### What is the difference between the -oA and -oa output options?

The `-oA <name>` switch generates output in all supported formats including JSON, CSV, HTML, and log files, while `-oa <name>` creates only log and CSV files for lighter documentation. Both options automatically handle file naming by appending appropriate extensions to the specified prefix.

### Can I use testssl.sh to test STARTTLS protocols like SMTP and IMAP?

Yes, use the `-t <protocol>` or `--starttls <protocol>` flag followed by the protocol name such as `smtp`, `imap`, `pop3`, `ftp`, `xmpp`, or `ldap`. This instructs testssl.sh to establish a plaintext connection first, then issue the STARTTLS command before beginning the SSL/TLS test sequence against the upgraded connection.

### Where are the OpenSSL binaries stored in the testssl.sh repository?

The repository includes pre-compiled OpenSSL binaries in `bin/openssl.*` for Linux, macOS, and FreeBSD platforms. The script references these when the system OpenSSL lacks required features for specific tests, or you can specify a custom binary path using the `--openssl <path>` option.