How to Customize testssl.sh Behavior Using Environment Variables: A Complete Guide

testssl.sh reads environment variables at startup to establish default values for command-line options, allowing you to permanently configure the SSL/TLS scanner without modifying each invocation command.

The drwetter/testssl.sh repository provides a comprehensive SSL/TLS testing tool that supports extensive customization through shell environment variables. As implemented in the main script, these variables declared at lines 150-199 serve as fallback defaults that the parse_cmdline() function can later override. This design enables stateless configuration for CI pipelines, constrained containers, and specialized testing environments.

How Environment Variables Work in testssl.sh

The script initializes tunable parameters using Bash parameter expansion syntax ${VAR:-default} within the Defining (and presetting) variables which can be changed block. When the script starts, it checks for exported environment variables and applies their values; if none exist, it falls back to built-in defaults.

Precedence rules determine final behavior:

1. Environment default – Variables set in the shell (e.g., export WIDE=true) propagate automatically because declarations use declare -x
2. Command-line override – Explicit flags in parse_cmdline() overwrite environment values (e.g., --wide overrides WIDE=false)
3. Inline assignment – You can set variables ad-hoc without exporting: COLOR=0 ./testssl.sh target.com

This architecture ensures that environment variables provide persistent defaults while preserving flexibility for one-off overrides.

Key Environment Variables by Category

OpenSSL Binary Configuration

Control which OpenSSL binaries perform cryptographic operations:

• OPENSSL – Path to primary OpenSSL binary (auto-detected by default). Use this to point to a custom build with TLS 1.3 support: OPENSSL=/opt/openssl/bin/openssl
• OPENSSL2 – Secondary OpenSSL binary for specific cipher checks

Connection Timeouts

Prevent hangs on slow or unresponsive targets:

• OPENSSL_TIMEOUT – Timeout for OpenSSL s_client connections (empty by default)
• SOCKET_TIMEOUT – Timeout for pure socket-based checks. Example: SOCKET_TIMEOUT=10 waits 10 seconds before abandoning socket connections

Output Formatting

Customize visual presentation and data density:

• COLOR – Color depth level (2 for full color, 1 for 256-color, 0 for monochrome). Set COLOR=0 for log files
• COLORBLIND – Boolean to enable color-blind friendly palettes (false by default)
• WIDE – Enable wide table output for better readability in CI logs (false by default)
• SHOW_EACH_C – Display every cipher tested instead of summaries (false by default)
• SHOW_SIGALGO – Show signature algorithms in output (false by default)

Performance and Acceleration

Enable experimental optimizations for large-scale scanning:

• FAST_SOCKET – Switch to experimental socket acceleration (false by default)
• FAST – Short-circuit cipher list testing for quicker results (false by default)
• FAST_STARTTLS – Speed up STARTTLS handshakes (true by default)

Network Behavior

Adjust protocol detection and proxy handling:

• ASSUME_HTTP – Force HTTP detection regardless of port (false by default)
• PROXY_WAIT – Seconds to wait for proxy responses (10 by default)
• DNS_VIA_PROXY – Route DNS lookups through proxy (false by default)
• HEADER_MAXSLEEP – Maximum seconds to wait for HTTP headers (5 by default). Increase to 15 for slow web servers
• MAX_WAITSOCK – Socket wait time上限 (5 by default)

File Output Destinations

Direct reports to specific locations without command-line flags:

• LOGFILE – Destination for plain text logs
• JSONFILE – JSON report path
• CSVFILE – CSV report path
• HTMLFILE – HTML report path
• FNAME_PREFIX – Prefix for auto-generated filenames
• APPEND – Append to existing files instead of overwriting
• OVERWRITE – Force overwrite existing output files

Authentication and Headers

Configure access credentials for protected endpoints:

• BASICAUTH – HTTP basic authentication credentials in user:password format
• REQHEADER – Arbitrary additional HTTP request headers

Certificate Authority Configuration

Specify alternative trust stores:

• CA_BUNDLES_PATH – Directory containing alternative CA certificate bundles (defaults to built-in)
• ADDTL_CA_FILES – Single additional PEM file for trust chain validation

Debugging and Development

Control verbosity and diagnostic output:

• DEBUG – Verbosity level (0 silent through 6 maximum debug output)
• DEBUGTIME – Enable timing/profiling information (false by default)
• DEBUG_ALLINONE – Force specific debug mode (false by default)
• GIVE_HINTS – Generate remediation hints in output (false by default)
• EXPERIMENTAL – Enable internal test switches (false by default)

Practical Configuration Examples

Use a custom OpenSSL binary with TLS 1.3 support:

export OPENSSL=/opt/openssl-1.1.1/bin/openssl
testssl.sh --fast example.com

Force monochrome output and wide tables for automated log parsing:

COLOR=0 WIDE=true ./testssl.sh https://api.example.org

Increase timeouts for extremely slow servers:

SOCKET_TIMEOUT=20 HEADER_MAXSLEEP=15 ./testssl.sh slow.example.net

Direct all output formats to a dedicated directory:

export LOGFILE=reports/log.txt
export JSONFILE=reports/scan.json
export CSVFILE=reports/scan.csv
export HTMLFILE=reports/scan.html
testssl.sh -oA reports/prefix example.com

Test a password-protected endpoint:

BASICAUTH=admin:secret123 ./testssl.sh https://protected.example.com

Combine multiple variables inline for containerized deployments:

OPENSSL=/usr/local/bin/openssl \
FAST_SOCKET=true \
WIDE=true \
./testssl.sh smtp.gmail.com:25

Summary

• testssl.sh evaluates environment variables at startup using ${VAR:-default} syntax in testssl.sh lines 150-199, treating them as default values for command-line options.
• Command-line flags always win: The parse_cmdline() function overrides environment variables when explicit flags are provided.
• You can export variables persistently in your shell or set them inline without export using VAR=value ./testssl.sh syntax.
• Key tunable categories include OpenSSL binary paths, connection timeouts, output formatting, performance acceleration, network behavior, file destinations, authentication, CA trust stores, and debug levels.
• The manual page at doc/testssl.1.md lines 376-383 documents these variables for special scenarios, though most installations use defaults.

Frequently Asked Questions

Do environment variables override command-line flags in testssl.sh?

No. According to the source code in testssl.sh, the parse_cmdline() function processes command-line arguments after environment variables are initialized, meaning explicit flags (--wide, --openssl, etc.) always take precedence over environment defaults.

Where are the environment variables defined in the testssl.sh source code?

The variables are defined in the Defining (and presetting) variables which can be changed block in testssl.sh at lines 150-199, where each variable uses Bash parameter expansion (${VAR:-default}) to establish fallback values while supporting declare -x for automatic export propagation.

Can I use environment variables to set default output files for testssl.sh?

Yes. Set LOGFILE, JSONFILE, CSVFILE, and HTMLFILE to specify destination paths, or use FNAME_PREFIX to auto-generate filenames with specific prefixes. These settings persist across invocations until unset, eliminating the need to type --logfile or --jsonfile repeatedly.

How do I point testssl.sh to a custom OpenSSL binary using environment variables?

Set the OPENSSL environment variable to the full path of your OpenSSL binary before invoking the script: OPENSSL=/usr/local/openssl/bin/openssl ./testssl.sh target.com. This is essential when testing TLS 1.3 features requiring newer OpenSSL versions than the system default.

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