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

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. 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:

testssl.sh https://example.com

Protocol and cipher order scanning with structured output:

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

STARTTLS SMTP scan with IPv4 forcing and suppressed banner:

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

Mass testing with CSV and log output to a directory:

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

Specific vulnerability check with socket timeout:

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

Custom OpenSSL binary with accessibility features:

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}