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

> Learn how to customize testssl.sh behavior using environment variables to set default options. Configure the SSL/TLS scanner permanently without altering command lines. Get the complete guide.

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

---

**[`testssl.sh`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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:

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

```

Force monochrome output and wide tables for automated log parsing:

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

```

Increase timeouts for extremely slow servers:

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

```

Direct all output formats to a dedicated directory:

```bash
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:

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

```

Combine multiple variables inline for containerized deployments:

```bash
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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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`](https://github.com/drwetter/testssl.sh/blob/main/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.