testssl.sh

https://testssl.sh/doc/
Admin
testssl.sh is a free command line tool that checks servers for TLS/SSL cipher support, protocols,...
Tokens:15,904
Snippets:238
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example testssl.sh input file format

Source: https://testssl.sh/doc/testssl.1

A sample file format for mass testing, showing how to specify hosts, ports, and protocol-specific flags.

```text
  10.10.12.16:443
  10.10.12.16:1443
  -t smtp host.example.com:25
  host.example.com:443
  host.example.com:631
  -t ftp 10.10.12.11:21
  10.10.12.11:8443
```

--------------------------------

### Default Run on Specific Port

Source: https://testssl.sh/doc/testssl.1.md

Executes a default security scan on a specified host and port. This example highlights testing a host with multiple IPv4 addresses, where both are tested.

```bash
testssl.sh testssl.net:443
```

--------------------------------

### Set OpenSSL Connection Timeout

Source: https://testssl.sh/doc/testssl.1

Use `--openssl-timeout` to specify the maximum time in seconds testssl.sh will wait for an OpenSSL connection to establish. This option requires the 'timeout' binary to be installed on your OS. The equivalent environment variable is OPENSSL_TIMEOUT.

```bash
--openssl-timeout <seconds>
```

--------------------------------

### Run Docker Container with Specific Options

Source: https://testssl.sh/Dockerfile.md

Runs testssl.sh with the '-p' option and a header, targeting 'example.com'. This demonstrates passing specific arguments to the tool.

```bash
docker run --rm -t mytestssl -p --header example.com
```

--------------------------------

### Run Docker Container with Help Option

Source: https://testssl.sh/Dockerfile.md

Executes testssl.sh within the Docker container to display its help information. Useful for understanding available command-line options.

```bash
docker run -t mytestssl --help
```

--------------------------------

### Run Docker Container from Docker Hub

Source: https://testssl.sh/Dockerfile.md

Pulls and runs the testssl.sh image from Docker Hub, executing a scan against 'example.com' with the '--fs' option.

```bash
docker run --rm -t drwetter/testssl.sh --fs example.com
```

--------------------------------

### Build and Tag Docker Image

Source: https://testssl.sh/Dockerfile.md

Builds the Docker image and tags it with 'mytestssl' for easier referencing. This is a more convenient way to manage your local image.

```bash
docker build -t mytestssl .
```

--------------------------------

### STARTTLS Protocol Testing

Source: https://testssl.sh/doc/testssl.1.md

Perform a default run against a STARTTLS enabled protocol. The protocol must be one of the supported types.

```APIDOC
## STARTTLS Protocol Testing

### Description
Performs a default run against a STARTTLS enabled protocol. The specified protocol must be one of the supported types.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **-t, --starttls <protocol>** (string) - Required - Specifies the protocol for STARTTLS testing. Supported protocols include `ftp`, `smtp`, `pop3`, `imap`, `xmpp`, `sieve`, `xmpp-server`, `telnet`, `ldap`, `irc`, `lmtp`, `nntp`, `postgres`, `mysql`.

### Notes
- For `postgres`, `mysql`, `ldap`, and `lmtp`, a supplied OpenSSL version 1.1.1 or later is required.
- MongoDB does not support STARTTLS connections.
- `irc` currently only works with `--ssl-native` and is a work in progress (WIP).

### Request Example
```bash
testssl.sh -t smtp example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### Scan services using STARTTLS

Source: https://testssl.sh/doc/testssl.1

Initiates a scan via a STARTTLS handshake on plain text ports.

```bash
testssl.sh -t smtp smtp.gmail.com:25
```

```bash
testssl.sh --starttls=imap imap.gmx.net:143
```

--------------------------------

### Run Docker Container from GHCR

Source: https://testssl.sh/Dockerfile.md

Pulls and runs the testssl.sh image from GHCR, executing a scan against 'example.com' with the '--fs' option.

```bash
docker run --rm -t ghcr.io/testssl/testssl.sh --fs example.com
```

--------------------------------

### Run Docker Container with Tagged Image

Source: https://testssl.sh/Dockerfile.md

Runs a container from the 'mytestssl' image, executing testssl.sh against 'example.com'. The --rm flag ensures the container is removed after execution.

```bash
docker run --rm -t mytestssl example.com
```

--------------------------------

### Mount Volume for Output Files

Source: https://testssl.sh/Dockerfile.md

Runs testssl.sh, mounting the host's '/tmp' directory into the container as '/data'. This allows output files like HTML reports to be saved on the host machine.

```bash
docker run --rm -t -v /tmp:/data drwetter/testssl.sh --htmlfile /data/ example.com
```

--------------------------------

### Provide HTTP Basic Authentication

Source: https://testssl.sh/doc/testssl.1

Use `--basicauth` to supply user and password credentials for HTTP basic authentication. These credentials are used when checking security headers. The equivalent environment variable is BASICAUTH.

```bash
--basicauth <user:pass>
```

--------------------------------

### Build Docker Image from Git Directory

Source: https://testssl.sh/Dockerfile.md

Builds the Docker image from the current directory. When no image tag is specified, the image ID is returned upon successful build.

```bash
docker build .
```

```bash
[..]
---> 889fa2f99933
Successfully built 889fa2f99933
```

--------------------------------

### XMPP Host Override for STARTTLS

Source: https://testssl.sh/doc/testssl.1.md

An additional option for STARTTLS enabled XMPP, used when the Jabber domain differs from the supplied URI.

```APIDOC
## XMPP Host Override for STARTTLS

### Description
Provides an additional option for STARTTLS enabled XMPP connections. This is necessary when the Jabber domain is different from the URI provided in the command.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **--xmpphost <jabber_domain>** (string) - Required - Specifies the Jabber domain to use for the XMPP connection.

### Notes
- This option is only relevant when testing STARTTLS enabled XMPP services.

### Request Example
```bash
testssl.sh --xmpphost myjabber.org -t xmpp example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### testssl.sh Configuration Options

Source: https://testssl.sh/doc/testssl.1

Configuration parameters for controlling connection timeouts, authentication, and request headers in testssl.sh.

```APIDOC
## --openssl-timeout <seconds>

### Description
Sets a timeout for openssl connections to prevent hanging. Requires a timeout binary on the OS.

### Parameters
#### Query Parameters
- **seconds** (integer) - Required - Time in seconds to wait before terminating the connection.

### Environment Variable
- OPENSSL_TIMEOUT

## --basicauth <user:pass>

### Description
Provides HTTP basic authentication credentials for security header checks.

### Parameters
#### Query Parameters
- **user:pass** (string) - Required - Credentials in user:pass format.

### Environment Variable
- BASICAUTH

## --reqheader <header>

### Description
Adds custom HTTP request headers. Can be used multiple times.

### Parameters
#### Query Parameters
- **header** (string) - Required - Header in 'Headername: headercontent' format.

### Environment Variable
- REQHEADER

## --mtls <path_to_client_cert>

### Description
Provides a client certificate and unencrypted private key in PEM format for mutual TLS authentication.

### Parameters
#### Query Parameters
- **path_to_client_cert** (string) - Required - File path to the PEM formatted certificate and key.

### Environment Variable
- MTLS
```

--------------------------------

### CLI Output Configuration Options

Source: https://testssl.sh/doc/testssl.1

Configuration flags for controlling testssl.sh output behavior.

```APIDOC
## CLI Output Options

### Description
Options to customize the display, formatting, and debugging output of testssl.sh.

### Parameters
#### Options
- **-q, --quiet** (flag) - Optional - Suppresses the banner with version info and usage rights.
- **--wide** (flag) - Optional - Enables wide output for BEAST, FS, RC4, and client simulation sections. Can also be set via `WIDE` environment variable.
- **--mapping** (string) - Optional - Sets cipher suite naming convention: `openssl`, `iana`, `no-openssl`, or `no-iana`.
- **--show-each** (flag) - Optional - Displays all tested ciphers in wide mode. Can also be set via `SHOW_EACH_C` environment variable.
- **--color** (integer) - Optional - Sets color/markup level (0-3). Can also be set via `COLOR` environment variable.
- **--colorblind** (flag) - Optional - Swaps green and blue colors for accessibility. Can also be set via `COLORBLIND` environment variable.
- **--debug** (integer) - Optional - Sets debugging level (0-6). Can also be set via `DEBUG` environment variable.
- **--disable-rating** (flag) - Optional - Disables the automatic grading system.
```

--------------------------------

### STARTTLS Scan on SMTP

Source: https://testssl.sh/doc/testssl.1.md

Checks security via a STARTTLS handshake on the plain text port 25 for SMTP. Tests all IPs associated with the specified host.

```bash
testssl.sh -t smtp smtp.gmail.com:25
```

--------------------------------

### STARTTLS Scan on IMAP

Source: https://testssl.sh/doc/testssl.1.md

Performs a security check using STARTTLS on the plain text IMAP port 143.

```bash
testssl.sh --starttls=imap imap.gmx.net:143
```

--------------------------------

### TLS Scan for MongoDB

Source: https://testssl.sh/doc/testssl.1.md

Tests TLS support for MongoDB, which provides TLS without STARTTLS. The command directly checks the encryption.

```bash
testssl.sh <mongodb_host>:<port>
```

--------------------------------

### Specify OpenSSL Binary Path

Source: https://testssl.sh/doc/testssl.1.md

Allows specifying the exact path to the OpenSSL binary to be used by testssl.sh, overriding automatic detection.

```APIDOC
## Specify OpenSSL Binary Path

### Description
Manually specifies the path to the OpenSSL binary that testssl.sh should use. This overrides the tool's automatic detection mechanisms, which normally search in the script's directory, the current working directory, and the system's PATH.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **--openssl <path_to_openssl>** (string) - Required - The full path to the desired OpenSSL binary.

### Notes
- The environment variable `OPENSSL` can also be used to preset the path to the OpenSSL binary.

### Request Example
```bash
testssl.sh --openssl /usr/local/ssl/bin/openssl example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### Scan services with native TLS

Source: https://testssl.sh/doc/testssl.1

Directly tests ports that offer TLS encryption without requiring a STARTTLS handshake.

```bash
testssl.sh smtp.gmail.com:465
```

```bash
testssl.sh imap.gmx.net:993
```

--------------------------------

### Run Docker Container with Stable Tag from GHCR

Source: https://testssl.sh/Dockerfile.md

Runs the testssl.sh container using the 'stable' tag from GHCR. This is an alternative to using Docker Hub for the stable version.

```bash
docker run --rm -t ghcr.io/testssl/testssl.sh:stable example.com
```

--------------------------------

### MX Record Testing

Source: https://testssl.sh/doc/testssl.1.md

Tests all MX records for a given domain, performing STARTTLS checks on port 25 in order of priority.

```APIDOC
## MX Record Testing

### Description
Tests all Mail Exchanger (MX) records for a specified domain. The tests are performed sequentially, starting from the highest priority MX record, and include STARTTLS checks on port 25.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **--mx <domain|host>** (string) - Required - The domain or host for which to test MX records.

### Notes
- This option is useful for verifying TLS support on mail servers associated with a domain.

### Request Example
```bash
testssl.sh --mx example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### Run Docker Container with Stable Tag

Source: https://testssl.sh/Dockerfile.md

Runs the testssl.sh container using the 'stable' tag from Docker Hub. This ensures you are using a specific, tested version.

```bash
docker run --rm -t drwetter/testssl.sh:stable example.com
```

--------------------------------

### SSL/TLS Native Mode

Source: https://testssl.sh/doc/testssl.1.md

Uses OpenSSL's s_client exclusively for checks, which is faster but may yield less accurate results compared to the default mixed approach.

```APIDOC
## SSL/TLS Native Mode

### Description
Forces testssl.sh to use OpenSSL's `s_client` for nearly all checks, instead of a mix of bash sockets and `s_client`. This mode is generally faster but may provide less accurate results, particularly for client simulation and cipher support.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **--ssl-native** (flag) - Optional - Enables the use of OpenSSL's `s_client` for all checks.

### Notes
- This mode is not recommended unless speed is prioritized over accuracy, or if you are certain that your target's protocols and ciphers align well with your OpenSSL binary's capabilities.
- Warnings may be displayed if testssl.sh cannot determine if a check can be performed.
- False negatives might occur without warnings in some cases.

### Request Example
```bash
testssl.sh --ssl-native example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### Output Control Options

Source: https://testssl.sh/doc/testssl.1.md

Options to control the verbosity and format of testssl.sh output.

```APIDOC
## Output Control Options

### Description
Options to control the verbosity and format of testssl.sh output.

### Options

- `-q, --quiet`
  Suppresses the initial banner containing version information, usage rights, and warnings. By using this option, you acknowledge the terms of use and the warning.

- `--wide`
  Enables wide output for sections like BEAST, FS, and RC4, displaying individual cipher names similar to the "each cipher output". Also applies to client simulation with column-aligned output and a proper headline. Can be set using the `WIDE` environment variable.

- `--mapping <openssl|iana|no-openssl|no-iana>`
  Determines the primary naming convention for cipher suites:
  - `openssl`: Uses OpenSSL cipher suite names (default).
  - `iana`: Uses IANA cipher suite names.
  - `no-openssl`: Displays only IANA cipher suite names.
  - `no-iana`: Displays only OpenSSL cipher suite names.
  *Note: `rfc` and `no-rfc` are deprecated aliases for `iana` and `no-iana` respectively, and will be removed after version 3.0.*

- `--show-each`
  (Requires wide modes) Displays all tested ciphers, not just the successful ones. Equivalent to setting the `SHOW_EACH_C` environment variable.

- `--color <0|1|2|3>`
  Controls the use of colors in the output:
  - `0`: No markup or escape codes (suitable for log files).
  - `1`: Non-colored markup (bold, italics, underline, reverse).
  - `2`: Default; uses ANSI and termcap escape codes for terminal output.
  - `3`: Colors ciphers and EC based on an internal rating.
  Can be set using the `COLOR` environment variable.
  *Note: OpenBSD and early FreeBSD may not support italics.*

- `--colorblind`
  Swaps green and blue colors in the output to improve distinguishability for colorblind individuals. Can be set using the `COLORBLIND` environment variable.

- `--debug <0-6>`
  Enables additional debugging output (levels 2-6). Useful for troubleshooting. The `DEBUG` environment variable can be used.
  - `0`: Default; no debug output.
  - `1`: Leaves debug output in `/tmp/testssl.XXXXXX/` without screen display.
  - `2`: Shows high-level status and connection errors.
  - `3`: Includes hexdumps and other information.
  - `4`: Displays bytes sent via sockets.
  - `5`: Displays bytes received via sockets.
  - `6`: Maximum debugging output.

- `--disable-rating`
  Disables the automatic rating of results. This is automatically disabled when not all required functions are executed, to prevent misleading grades (e.g., when checking for a single vulnerability).
```

--------------------------------

### Proxy-Based Testing

Source: https://testssl.sh/doc/testssl.1.md

Performs any check via a specified proxy, with support for environment variable inheritance and IP address resolution through the proxy.

```APIDOC
## Proxy-Based Testing

### Description
Enables performing any test through a specified proxy server. This option supports inheriting proxy settings from the environment and resolving hostnames via the proxy.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **--proxy <host>:<port>** (string) - Required - The host and port of the proxy server (e.g., `proxy.example.com:8080`).
- **--proxy=auto** (flag) - Optional - Inherits proxy settings from the environment (e.g., `HTTP_PROXY`, `HTTPS_PROXY`).

### Notes
- Hostnames provided will be resolved to the first A record, falling back to the AAAA record if necessary. IPv4 and IPv6 addresses can also be used.
- Newer OpenSSL or LibreSSL versions are required for IPv6 proxy functionality.
- To enable DNS lookups via proxy, set `DNS_VIA_PROXY=true` in the environment.
- OCSP revocation checking (`-S --phone-out`) is not supported via proxy with OpenSSL. It will be attempted directly if `IGN_OCSP_PROXY=true` is set.
- Proxy authentication, HTTPS proxies, and SOCKS proxies are not supported.

### Request Example
```bash
testssl.sh --proxy proxy.example.com:8080 example.com
testssl.sh --proxy=auto example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### IPv6 Testing

Source: https://testssl.sh/doc/testssl.1.md

Enables IPv6 checks. Requires specific OpenSSL versions and environment configuration for reliable operation.

```APIDOC
## IPv6 Testing

### Description
Enables performing checks over IPv6. This option assumes that the OpenSSL binary being used has IPv6 support and that connectivity is available.

### Method
CLI Option

### Endpoint
N/A

### Parameters
#### Command Line Options
- **-6** (flag) - Optional - Enables IPv6 checks.

### Notes
- testssl.sh does not automatically perform IPv6 checks due to potential lack of connectivity and uncertainty about the OpenSSL binary's IPv6 capabilities.
- The `-6` flag assumes both connectivity and OpenSSL support are present.
- For consistent IPv6 testing, it is recommended to set the `HAS_IPv6` environment variable.
- IPv6 support is known to work with vanilla OpenSSL versions >= 1.1.0 and older versions >= 1.0.2 on RHEL/CentOS/FC and Gentoo systems.

### Request Example
```bash
testssl.sh -6 example.com
```

### Response
N/A (Output depends on scan results)
```

--------------------------------

### Perform default security scan

Source: https://testssl.sh/doc/testssl.1

Executes a standard suite of tests including protocols, cipher lists, and vulnerabilities.

```bash
testssl.sh testssl.sh
```

```bash
testssl.sh testssl.net:443
```

--------------------------------

### Provide Client Certificate for Mutual TLS

Source: https://testssl.sh/doc/testssl.1

Use `--mtls` to specify the path to a file containing a client certificate and its private key (unencrypted) in PEM format. This is required when the remote server demands mutual TLS authentication. The equivalent environment variable is MTLS.

```bash
--mtls <path_to_client_cert>
```

--------------------------------

### Default Run with testssl.sh

Source: https://testssl.sh/doc/testssl.1.md

Performs a default security scan on a given URL, including protocols, cipher lists, server preferences, forward secrecy, defaults, vulnerabilities, client simulation, and rating.

```bash
testssl.sh testssl.sh
```

--------------------------------

### Implement a new grade warning

Source: https://testssl.sh/doc/testssl.1.md

Use this function to trigger a warning message during the rating process.

```bash
set_grade_warning "Documentation is always right"
```

--------------------------------

### Implement a new grade cap

Source: https://testssl.sh/doc/testssl.1.md

Use this function to restrict the maximum possible grade for a specific vulnerability or condition.

```bash
set_grade_cap "D" "Vulnerable to documentation"
```

--------------------------------

### Plain TLS Scan on IMAPS Port

Source: https://testssl.sh/doc/testssl.1.md

Tests the TLS encryption directly on the IMAPS port (993) without a STARTTLS handshake.

```bash
testssl.sh imap.gmx.net:993
```

--------------------------------

### Plain TLS Scan on SMTPS Port

Source: https://testssl.sh/doc/testssl.1.md

Tests the TLS encryption directly on the SMTPS port (465) without a STARTTLS handshake.

```bash
testssl.sh smtp.gmail.com:465
```

--------------------------------

### Add Custom HTTP Request Headers

Source: https://testssl.sh/doc/testssl.1

Use `--reqheader` to add custom HTTP request headers. The format must be 'Headername: headercontent'. This option can be used multiple times for different headers. The equivalent environment variable is REQHEADER.

```bash
--reqheader <header>
```

```bash
--reqheader 'Proxy-Authorization: Basic dGVzdHNzbDpydWxlcw==' --reqheader 'ClientID: 0xDEADBEAF'
```

--------------------------------

### IPv6 Security Scan

Source: https://testssl.sh/doc/testssl.1.md

Tests the IPv6 connectivity and security of a given URL. Requires the system's OpenSSL to support IPv6.

```bash
testssl.sh -6 https://testssl.net
```
Tokens:
Raw