Comprehensive Guide to TLS Scanning Tools: Introducing tls-scan

In today’s digital landscape, ensuring robust security for your online services is paramount. A critical aspect of this security is the implementation and configuration of Transport Layer Security (TLS). To effectively manage and audit your TLS infrastructure, a Tls Scanning Tool is indispensable. This article delves into the world of TLS scanning, introducing you to tls-scan, a powerful and efficient tool designed for in-depth TLS server analysis.

tls-scan is engineered to meticulously scan TLS-based servers, gathering essential information about X.509 certificates, supported ciphers, and other vital TLS configurations. The tool outputs its findings in a structured JSON format, making it ideal for integration with other security analysis and monitoring systems. Built as a single-threaded, asynchronous, and event-driven program powered by libevent, tls-scan boasts impressive speed and the capability to concurrently scan thousands of TLS servers. For even larger deployments and multi-core systems, it can be seamlessly combined with tools like GNU parallel for horizontal scalability.

tls-scan is an invaluable asset for both developers and security engineers. It empowers them to proactively monitor, test, and debug the certificate and TLS configurations of servers within their organizations, ensuring a strong security posture.

Key Features of tls-scan: A Leading TLS Scanning Tool

tls-scan is packed with features that make it a standout tls scanning tool in the security toolkit. Here’s a breakdown of its capabilities:

Full TLS 1.3 Support: Stay ahead of the curve with comprehensive support for the latest TLS protocol, TLSv1.3, ensuring your scans are relevant and future-proof.
Broad Protocol Coverage: Beyond standard TLS, tls-scan extends its reach to StartTLS protocols across various services including SMTP, IMAP, POP3, FTPS, SIEVE, NNTP, XMPP, LDAP, RDP, POSTGRES, and MYSQL. This wide-ranging support makes it a versatile tls scanning tool for diverse environments.
Unparalleled Speed and Scalability: Designed for high-performance scanning, tls-scan can efficiently handle large-scale scans, even for extensive networks like IoT device deployments. Its asynchronous architecture enables rapid concurrent scans, making it a truly efficient tls scanning tool.
Comprehensive Version and Cipher Detection: Identify supported SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 versions, along with their associated ciphers. This detailed enumeration is crucial for identifying and mitigating outdated or weak security configurations.
ALPN Protocol ID Enumeration: Discover the Application-Layer Protocol Negotiation (ALPN) protocol IDs supported by the server. ALPN is vital for optimizing connection performance and protocol selection in modern web applications.
Detailed X.509 Certificate Extraction: Extract and present X.509 certificate fields in JSON format. This includes subject, issuer, validity dates, key usage, and more, providing a complete picture of the server’s certificate setup.
Certificate and Hostname Verification: Perform rigorous certificate and hostname verification checks, ensuring that the server’s identity is properly validated and trusted.
TLS Compression Detection: Identify if TLS compression is enabled. While once used for performance, TLS compression is now often disabled due to security concerns like the CRIME attack.
Session Reuse Testing: Evaluate the server’s session reuse capabilities. Efficient session reuse can improve performance but needs to be securely implemented.
Certificate Revocation Checks with OCSP Stapling: Verify certificate revocation status using stapled OCSP responses. OCSP stapling enhances performance and security by providing real-time revocation information.
Script-Friendly JSON Output: The JSON output format is designed for easy parsing and integration with scripting languages and other security tools. This interoperability makes tls-scan an excellent component in automated security workflows.
Real-time Runtime Statistics: Track scan progress and performance with detailed runtime statistics. This feature is invaluable for monitoring large scans and optimizing scanning parameters.

tls-scan excels as a data collection tool, focusing on gathering TLS cipher and X.509 certificate information. The detailed scan output is readily integrable with other security analysis platforms to pinpoint TLS misconfigurations and vulnerabilities.

Getting Started with tls-scan: Installation Guide

Installing tls-scan, your chosen tls scanning tool, is straightforward. You have the flexibility to choose between using pre-built binaries or compiling from source, depending on your system and preferences.

Pre-built Binary Installation (x86_64)

For convenience, pre-compiled binaries are available for Linux and macOS (x86_64 architectures). You can download the latest release from the GitHub releases page:

https://github.com/prbinu/tls-scan/releases/latest

Simply download the appropriate package for your operating system, extract it, and you’re ready to use tls-scan.

Building from Source: For Customization and Latest Features

If you prefer to build tls-scan from source, perhaps to customize compilation options or ensure you have the very latest version, the process is well-scripted and relatively easy.

The build process relies on shell scripts (build-x86-64.sh for x86_64 Linux/macOS and build-arm64.sh for Linux ARM). These scripts automate the fetching and building of necessary dependencies: Peter Mosmans’ openssl, libevent, and GnuTLS. Notably, tls-scan statically links against a custom-built openssl to avoid conflicts with system libraries. Be aware that the complete build process can take around twenty minutes.

Build Prerequisites:

Before you begin, ensure you have the necessary build tools installed on your system. For Ubuntu/Debian-based Linux distributions, execute the following command:

sudo apt-get update
sudo apt-get install make autoconf automake libtool pkg-config gcc unzip -y

Building on Linux:

Clone the repository:

git clone https://github.com/prbinu/tls-scan.git
cd tls-scan

Run the build script (x86_64):
```
./build-x86-64.sh
```
The build-x86-64.sh script is a wrapper around bootstrap.sh. bootstrap.sh handles dependency builds, including running autoreconf -i to generate the configure script, followed by the standard ./configure, make && make install sequence.
Run the build script (arm64):
```
./build-arm64.sh
```
Locate the built binary: After successful compilation, the tls-scan binary will be located in the ./build-root/bin directory.

Test your build:

cd build-root/bin
./tls-scan --connect=yahoo.com --cacert=../etc/tls-scan/ca-bundle.crt --pretty

Building on macOS:

The process for macOS is similar to Linux. Ensure you have the prerequisite packages. If you are missing tools, consider using package managers like Homebrew to install them easily.

git clone https://github.com/prbinu/tls-scan.git
cd tls-scan
./build-x86-64.sh

The tls-scan binary will be available in ./build-root/bin. Alternatively, for macOS users, especially those on Apple Silicon, Docker offers a convenient build and runtime environment.

Running on Apple Silicon (Arm/M1/M2 Macs):

Currently, native ARM builds are not directly supported. However, you can run the x86_64 binary via Rosetta 2, Apple’s binary translation layer, or leverage Docker for a containerized environment.

Docker Installation: Containerized tls-scan

Docker provides an isolated and reproducible environment for running tls-scan.

Prerequisite: Ensure you have Docker installed on your system (Docker Installation Guide).

Build the Docker image: Navigate to the tls-scan repository directory (after cloning from GitHub) and build the image using the provided Dockerfile:
```
docker build -t tls-scan .
```

Run tls-scan in Docker:

docker run --rm tls-scan --connect=example.com:443 --all --pretty

This Docker approach simplifies deployment and ensures consistent execution across different environments.

Practical Examples: Unleashing the Power of tls-scan

Let’s explore some practical examples of how to use tls-scan as your tls scanning tool to gain valuable insights into server TLS configurations.

Basic Scan:

./tls-scan -c search.yahoo.com --all --pretty

This command performs a comprehensive scan (--all) of search.yahoo.com on the default port 443 and outputs the results in a pretty-printed JSON format (--pretty) for readability. The output provides a wealth of information, including:

{
  "host": "search.yahoo.com",
  "ip": "208.71.45.12",
  "port": 443,
  "elapsedTime": 1600,
  "tlsVersion": "TLSv1.2",
  "cipher": "ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(128) Mac=AEAD",
  "tempPublicKeyAlg": "ECDH prime256v1",
  "tempPublicKeySize": 256,
  "secureRenego": true,
  "compression": "NONE",
  "expansion": "NONE",
  "sessionLifetimeHint": 100800,
  "tlsVersions": [
    "TLSv1",
    "TLSv1_1",
    "TLSv1_2"
  ],
  "x509ChainDepth": 2,
  "verifyCertResult": true,
  "verifyHostResult": true,
  "ocspStapled": true,
  "verifyOcspResult": true,
  "certificateChain": [
      { /* ... Certificate details 1 ... */ },
      { /* ... Certificate details 2 ... */ }
  ]
}

Tip: For scanning multiple targets simultaneously, leverage the --concurrency= option to increase the number of parallel scans.

Advanced Usage: Command-Line Query and Filtering with jq

The JSON output of tls-scan is incredibly versatile, especially when combined with command-line JSON processors like jq (https://stedolan.github.io/jq). jq allows for powerful filtering and querying of JSON data directly from the command line, enabling real-time analysis of scan results.

Examples:

Filter hosts with successful certificate and hostname verification:

cat input.txt | tls-scan --port=443 2>/dev/null | 
jq-linux64 -r 'select(.verifyHostResult == true and .verifyCertResult == true) | [.host, .ip, .verifyHost, .verifyCert] | @tsv'

Identify hosts with expired certificates:

cat input.txt | tls-scan --port=443 --concurrency=500 --timeout=5 2>/dev/null | 
jq-linux64 -r 'select(.certificateChain[].expired == true) | [.host, .ip] | @tsv'

Find servers using weak RSA keys (less than 2048 bits):

cat tlscerts.out | 
jq-linux64 -r 'select(.certificateChain[0].publicKeyAlg == "RSA" and .certificateChain[0].publicKeySize < 2048) | [.host, .ip, .certificateChain[0].publicKeySize] | @tsv'

Detect hosts supporting outdated SSLv2 or SSLv3:

tls-scan --infile=domains.txt --port=443 --version-enum --concurrency=250 --timeout=3 2>/dev/null | 
jq-linux64 -r 'if (.tlsVersions[] | contains("SSL")) == true then [.host, .ip, .tlsVersions[]] else empty end | @tsv'

Important Note: For efficiency, especially with large scans, it’s recommended to save the tls-scan output to a file and then perform filtering and analysis on the saved data, rather than piping directly in frequent scan and filter operations.

Comprehensive Options: Mastering tls-scan Command-Line Flags

To fully utilize tls-scan as your tls scanning tool, understanding its command-line options is crucial. Here’s a detailed table outlining the available options and their descriptions:

Option	Description
`-H --help`	Displays a help message summarizing command-line options.
`-c --connect=<target[:port]>`	Specifies the target to scan (hostname, IPv4, or IPv6). Default port is 443. IPv6 addresses should be enclosed in square brackets, e.g., `[::1]:443`.
`--starttls=<protocol>`	Enables StartTLS for specified protocols: `smtp`, `imap`, `pop3`, `ftp`, `sieve`, `nntp`, `xmpp`, `ldap`, `rdp`, `postgres`, `mysql`, or `tls` (default).
`--cacert=<file>`	Specifies the root CA certificate file for certificate validation. Defaults to `ca-bundle.crt` in the current directory.
`-C --ciphers=<ciphers>`	Defines a custom cipher list to use. Use `openssl ciphers` to see available ciphers. Overridden by `--ssl2`, `--ssl3`, `--tls1`, `--tls1_1`, `--tls1_2` options. Example: `"ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384"`.
`-e --cipher-enum`	Enumerates supported ciphers using `--tls-old` cipher list by default. Use `--meta-info` to see predefined cipher suites.
`--show-unsupported-ciphers`	Includes unsupported ciphers in the cipher list output.
`-V --version-enum`	Enumerates supported TLS versions.
`-v --version`	Prints `tls-scan` version and build information.
`-r --session-reuse`	Enables SSL session reuse testing.
`-u --session-print`	Prints the SSL session in PEM format to stderr (not included in JSON output). Useful for saving sessions for reuse testing with `--session-file`.
`-T --session-file=<file>`	Specifies a file containing an SSL session in PEM format for session reuse testing.
`-a --all`	Shortcut for `--version-enum`, `--cipher-enum`, and `--session-reuse`. May increase scan time and could trigger rate-limiting.
`-s --sni=<servername>`	Sets the TLS Server Name Indication (SNI) extension in ClientHello (TLSv1+ only). Defaults to the input hostname.
`-b --concurrency=<number>`	Sets the number of concurrent requests (worker objects). Default is 1. Adjust based on system resources (memory, CPU, network).
`-t --timeout=<seconds>`	Sets the timeout per connection in seconds. Default is 10 seconds. Note this is per connection, and cipher scans may involve multiple connections.
`-S --sleep=<milliseconds>`	Adds a delay in milliseconds between connections, specifically for `--cipher-enum` and `--version-enum`. Useful for managing server rate limits. Max sleep value is 60000 (1 minute). Default is 0.
`-f --infile=<file>`	Specifies an input file containing a list of domains or IPs to scan (one per line). Defaults to reading from standard input (`stdin`).
`-o --outfile=<file>`	Specifies the output file to store JSON results. Defaults to standard output (`stdout`).
`-n --pretty`	Enables pretty-printed JSON output with newlines for readability.
`-N --nameserver=<ip>`	Specifies DNS resolver IPs to use. Multiple IPs can be provided using `-N <ip1> -N <ip2> ...`. Useful to bypass rate-limited public DNS servers.
`--ssl2`	Uses only SSLv2 ciphers.
`--ssl3`	Uses only SSLv3 ciphers.
`--tls1`	Uses only TLSv1 ciphers.
`--tls1_1`	Uses only TLSv1_1 ciphers.
`--tls1_2`	Uses only TLSv1_2 ciphers.
`--tls-modern`	Uses Mozilla’s modern cipher list (see Mozilla Security Server Side TLS).
`--tls-interm`	Uses Mozilla’s intermediate cipher list.
`--tls-old`	Uses Mozilla’s old (backward compatible) cipher list.
`--no-parallel-enum`	Disables parallel cipher and TLS version enumeration. Parallel scans are enabled by default with `--connect`.
`--meta-info`	Prints program meta-information (including predefined cipher options) and exits.
`--stats-outfile=<file>`	Enables runtime scan statistics and saves them to the specified file.

Important Caveats

Disabled Ciphers: Note that the SRP:PSK ciphers are currently disabled in tls-scan.

TLS 1.3 Support: Bridging Legacy and Modern Security

tls-scan adopts a dual-library approach to ensure comprehensive TLS scanning, including support for both legacy and modern protocols.

To maintain compatibility with older, less secure ciphers (SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2), tls-scan utilizes an older version of OpenSSL. However, to provide robust support for TLS 1.3 and newer protocols, which are not fully supported in older OpenSSL versions, tls-scan integrates the GnuTLS library.

This strategic combination ensures that tls-scan functions as a versatile tls scanning tool, capable of analyzing a wide spectrum of TLS configurations, from outdated setups to the latest, most secure protocols. In essence, OpenSSL handles scans for SSLv2 through TLSv1.2, while GnuTLS takes over for TLSv1.3 and beyond.

Contributing to tls-scan: Join the Community

tls-scan is an open-source project, and contributions are highly encouraged! If you’re interested in improving tls-scan, whether through code contributions, bug reports, feature suggestions, or documentation enhancements, pull requests and collaborative efforts are warmly welcomed. Join the community and help make tls-scan an even more powerful tls scanning tool for everyone.