Testing TLS/SSL encryption

testssl.sh

is a free command line tool which checks a server's service on any port for the support of TLS/SSL ciphers, protocols as well as recent cryptographic flaws and more.

Name	Last Modified	Size	Type
2.6/	2018-Nov-15 22:02:23	--	Directory
2.8/	2018-Nov-15 22:46:12	--	Directory
2.9.5/	2018-Nov-15 22:24:07	--	Directory
bleichenbacher/	2018-Feb-23 18:00:33	--	Directory
openssl-1.0.2i-chacha.pm.ipv6.contributed/	2016-Sep-26 23:15:22	--	Directory
utils/	2018-Nov-15 22:47:49	--	Directory

CHANGELOG.txt	2015-Sep-15 10:56:45	12.27KB	TXT Type Document
CREDITS.md	2018-Oct-09 12:36:15	2.65KB	MD File
Dockerfile	2018-Oct-09 12:36:15	412.00B	Unknown File
LICENSE.txt	2014-May-03 11:04:22	17.59KB	TXT Type Document
OPENSSL-LICENSE.txt	2017-May-09 13:14:16	6.13KB	TXT Type Document
etc+doc.tar.gz	2018-Nov-15 22:32:16	889.75KB	GZ Compressed Archive
etc+doc.tar.gz.asc	2018-Nov-15 22:32:39	833.00B	ASC File
openssl-1.0.2k-chacha.pm.ipv6.Linux+FreeBSD.201705.tar.gz	2017-May-12 18:11:02	9.51MB	GZ Compressed Archive
openssl-1.0.2k-chacha.pm.ipv6.Linux+FreeBSD.201705.tar.gz.asc	2017-May-12 18:11:04	811.00B	ASC File
openssl-1.0.2k-dev-chacha.pm.ipv6.Linux+FreeBSD.tar.gz	2017-Jul-19 09:28:30	9.51MB	GZ Compressed Archive
openssl-1.0.2k-dev-chacha.pm.ipv6.Linux+FreeBSD.tar.gz.asc	2017-Jul-19 09:28:38	811.00B	ASC File
openssl-iana.mapping.html	2018-Nov-08 20:40:06	59.51KB	HTML File
openssl-ms14-066.Linux.x86_64	2016-Apr-15 12:36:23	4.24MB	X86_64 File
testssl.1.html	2018-Dec-17 21:11:03	55.38KB	HTML File
testssl.sh	2018-Dec-06 11:25:32	879.78KB	SH File
testssl.sh.asc	2018-Dec-06 11:25:32	811.00B	ASC File
testssl_german_owasp_day.pdf	2018-Nov-18 13:53:38	1.11MB	PDF Type Document

Key features

Clear output: you can tell easily whether anything is good or bad
Ease of installation: It works for Linux, Mac OSX, FreeBSD and WSL/MSYS2/Cygwin out of the box: no need to install or configure something, no gems, CPAN, pip or the like.
Flexibility: You can test any SSL/TLS enabled and STARTTLS service, not only webservers at port 443
Toolbox: Several command line options help you to run YOUR test and configure YOUR output
Reliability: features are tested thoroughly
Verbosity: If a particular check cannot be performed because of a missing capability on your client side, you'll get a warning
Privacy: It's only you who sees the result, not a third party
Freedom: It's 100% open source. You can look at the code, see what's going on and you can change it. Heck, even the development is open (github)
Documentation: Yes!

License

testssl.sh is free and open source software. You can use it under the terms of GPLv2, please review the License before using it. In addition starting from version 3.0rc1 if you're offering it as a public and / or paid service you need to mention to your audience that you're using this program and where to get this program from.

Donations

If you like this software, you or your company use it a lot or even your company makes money from any service around testssl.sh, why not support the project with a donation? It helps keeping the project alive and kicking.

Dirk setup a paypal account for it, keeps track of the money and makes sure it is spend on project related activities.

If you want a commercial invoice in return please get in touch with me before using paypal.

Development

github

Development takes place at github. This website is referring to the latest stable version only 2.9.5 and provides code, binaries and documention for the stable version. (The pictures are from oder releases.) In the development version @ github things might have changed. As I do releases on github too you can as well pull the zip for a stable release from there. There will be "soon" a 3.0 release.

Nov 11,2018: Release Candidate 3 of version 3.0 has been made public, see 3.0rc3 @ github

Oct 9,2018: Release Candidate 2 of version 3.0 has been made public, see 3.0rc2 @ github

Dec 12, 2017: ROBOT / Bleichenbacher check has been implemented. . Read more about this old+new attack @ robotattack.org. Please checkout 2.9dev @ github. I compiled also some info here, including an Alexa Top 10k scan and some background information.

Sep 19,2017: Version 2.9.5 has been released. Please checkout 2.9.5 @ github or download it from here, you need the etc tar ball as well.

Screenshots /Pictures here

The pictures and also the help are still from an older version of testssl.sh. This will be updated later. It should suffice to ge a picture though.

Longer read

testssl.sh is pretty much portable/compatible. It is working on every Linux, Mac OS X, FreeBSD distribution, on MSYS2/Cygwin (slow). It is supposed also to work on any other unixoid systems. A newer OpenSSL version (1.0) is recommended though. /bin/bash is a prerequisite – otherwise there would be no sockets.

Speaking of it: Since 2.4 some of the checks were done with bash sockets. This improved gradually and from 2.9.5 on almost every check is done with bash sockets. Still OpenSSL is needed for some core functions like openssl <verify|ocsp|pkey> . In principle any OpenSSL or even LibreSSL can be used as a helper. It's recommended to use the one supplied as it makes sure special tests or features like IPv6, proxy support, STARTTLS MySQL or PostgreSQL are supported. (The one supplied stems originally from github.com/PeterMosmans/openssl. openssl-1.0.2k-chacha.pm.ipv6.Linux+FreeBSD.tar.gz is a Linux- and FreeBSD-only tarball. The directory openssl-1.0.2i-chacha.pm.ipv6.contributed/ contains contributed builds for ARM7l and Darwin binaries).

Download shortcuts

Note the following features are supported by the webserver configuration:

curl -L https://testssl.sh or wget -O - https://testssl.sh pulls the current stable code from here
curl -L https://testssl.sh/dev/ or wget -O - https://testssl.sh/dev/ pulls the current development code from github

– each to standard output. Please note however that for 2.9dev you need the mandatory files in etc/ though.

Usage

The normal use case is probably just testssl.sh <hostname>, see first picture right hand above (a deliberately bad configuration).

Starting testssl.sh with no params will give you a general idea how to use it:

userid@somehost:~ % testssl.sh

testssl.sh <options>

     -h, --help                    what you're looking at
     -b, --banner                  displays banner + version of testssl.sh
     -v, --version                 same as previous
     -V, --local                   pretty print all local ciphers
     -V, --local <pattern>         which local ciphers with <pattern> are available?
                                   (if pattern not a number: word match)

testssl.sh <options> URI    ("testssl.sh URI" does everything except -E)

     -e, --each-cipher             checks each local cipher remotely
     -E, --cipher-per-proto        checks those per protocol
     -f, --ciphers                 checks common cipher suites
     -p, --protocols               checks TLS/SSL protocols (including SPDY/HTTP2)
     -y, --spdy, --npn             checks for SPDY/NPN
     -Y, --http2, --alpn           checks for HTTP2/ALPN
     -S, --server-defaults         displays the server's default picks and certificate info
     -P, --server-preference       displays the server's picks: protocol+cipher
     -x, --single-cipher <pattern> tests matched <pattern> of ciphers
                                   (if <pattern> not a number: word match)
     -c, --client-simulation       test client simulations, see which client negotiates with cipher and protocol
     -H, --header, --headers       tests HSTS, HPKP, server/app banner, security headers, cookie, reverse proxy, IPv4 address

     -U, --vulnerable              tests all vulnerabilities
     -B, --heartbleed              tests for heartbleed vulnerability
     -I, --ccs, --ccs-injection    tests for CCS injection vulnerability
     -R, --renegotiation           tests for renegotiation vulnerabilities
     -C, --compression, --crime    tests for CRIME vulnerability
     -T, --breach                  tests for BREACH vulnerability
     -O, --poodle                  tests for POODLE (SSL) vulnerability
     -Z, --tls-fallback            checks TLS_FALLBACK_SCSV mitigation
     -F, --freak                   tests for FREAK vulnerability
     -A, --beast                   tests for BEAST vulnerability
     -J, --logjam                  tests for LOGJAM vulnerability
     -D, --drown                   tests for DROWN vulnerability
     -s, --pfs, --fs, --nsa        checks (perfect) forward secrecy settings
     -4, --rc4, --appelbaum        which RC4 ciphers are being offered?

special invocations:
     -t, --starttls <protocol>     does a default run against a STARTTLS enabled <protocol>
     --xmpphost <to_domain>        for STARTTLS enabled XMPP it supplies the XML stream to-'' domain -- sometimes needed
     --mx <domain/host>            tests MX records from high to low priority (STARTTLS, port 25)
     --ip <ip>                     a) tests the supplied <ip> v4 or v6 address instead of resolving host(s) in URI
                                   b) arg "one" means: just test the first DNS returns (useful for multiple IPs)
     --file <fname>                mass testing option: Reads command lines from <fname>, one line per instance.
                                   Comments via # allowed, EOF signals end of <fname>. Implicitly turns on "--warnings batch"

partly mandatory parameters:
     URI                           host|host:port|URL|URL:port   (port 443 is assumed unless otherwise specified)
     pattern                       an ignore case word pattern of cipher hexcode or any other string in the name, kx or bits
     protocol                      is one of the STARTTLS protocols ftp,smtp,pop3,imap,xmpp,telnet,ldap 
                                   (for the latter two you need e.g. the supplied openssl)

tuning options (can also be preset via environment variables):
     --bugs                        enables the "-bugs" option of s_client, needed e.g. for some buggy F5s
     --assume-http                 if protocol check fails it assumes HTTP protocol and enforces HTTP checks
     --ssl-native                  fallback to checks with OpenSSL where sockets are normally used
     --openssl <PATH>              use this openssl binary (default: look in $PATH, $RUN_DIR of testssl.sh)
     --proxy <host>:<port>         connect via the specified HTTP proxy
     -6                            use also IPv6. Works only with supporting OpenSSL version and IPv6 connectivity
     --sneaky                      leave less traces in target logs: user agent, referer

output options (can also be preset via environment variables):
     --warnings <batch|off|false>  "batch" doesn't wait for keypress, "off" or "false" skips connection warning
     --quiet                       don't output the banner. By doing this you acknowledge usage terms normally appearing in the banner
     --wide                        wide output for tests like RC4, BEAST. PFS also with hexcode, kx, strength, RFC name
     --show-each                   for wide outputs: display all ciphers tested -- not only succeeded ones
     --mapping <no-rfc>            don't display the RFC Cipher Suite Name
     --color <0|1|2>               0: no escape or other codes,  1: b/w escape codes,  2: color (default)
     --colorblind                  swap green and blue in the output
     --debug <0-6>                 1: screen output normal but keeps debug output in /tmp/.  2-6: see "grep -A 5 '^DEBUG=' testssl.sh"

file output options (can also be preset via environment variables):
     --log, --logging              logs stdout to <NODE-YYYYMMDD-HHMM.log> in current working directory
     --logfile <logfile>           logs stdout to <file/NODE-YYYYMMDD-HHMM.log> if file is a dir or to specified log file
     --json                        additional output of findings to JSON file <NODE-YYYYMMDD-HHMM.json> in cwd
     --jsonfile <jsonfile>         additional output to JSON and output JSON to the specified file
     --csv                         additional output of findings to CSV file  <NODE-YYYYMMDD-HHMM.csv> in cwd
     --csvfile <csvfile>           set output to CSV and output CSV to the specified file
     --append                      if <csvfile> or <jsonfile> exists rather append then overwrite

All options requiring a value can also be called with '=' e.g. testssl.sh -t=smtp --wide --openssl=/usr/bin/openssl <URI>.

<URI> is always the last parameter.

Need HTML output? Just pipe through "aha" (ANSI HTML Adapter: github.com/theZiz/aha) like

   "testssl.sh <options> <URI> | aha >output.html"

userid@somehost:~ %

You are free to check any port – supposed there's any SSL enabled service (TCP) listening. For the service HTTPS you can also supply a full URL. A STARTTLS check would be invoked with testssl.sh -t pop3 pop.o2online.de:110. Other examples:

testssl.sh --starttls smtp <smtphost>.<tld>:587 
testssl.sh --starttls ftp <ftphost>.<tld>:21
testssl.sh -t xmpp <jabberhost>.<tld>:5222 
testssl.sh -t xmpp --xmpphost <XMPP domain> <jabberhost>.<tld>:5222 
testssl.sh --starttls imap <imaphost>.<tld>:143

The ports in those examples above are just the standard ports. Also here you're free to check any port.
If you just want to check the mail exchangers of a domain, do it like this: testssl.sh --mx google.com (make sure port 25 outbound is not blocked by your firewall) – see left hand side picture.

With the output option --wide you get where possible a wide output with hexcode of the cipher, OpenSSL cipher suite name, key exchange (with DH size), encryption algorithm, encryption bits size and maybe the RFC cipher suite name.

If you have the file mapping-rfc.txt in the same directory as testssl.sh it displays in the wide outputs also the corresponding RFC style cipher name. If you don't want this, you need to move mapping-rfc.txt away. Another thing: If you want to find out what local ciphers you have and print them pretty, use testssl.sh -V. Ever wondered what hexcode a cipher is? testssl.sh -V x14 lets you search for the hexcode x14. For hexcodes: If you just specify 14 instead of x14 you will get all ciphers returned which have 14 as a low, middle or high byte. For ciphers: You can also supply a word case pattern, e.g. testssl.sh -V CBC puts out every locally available cipher having the Cipher Block Chaining mode in its name.

testssl.sh -x <pattern> <URI> does the same as testssl.sh -V, it only checks the matched pattern at the server, so e.g. testssl.sh -x ECDH google.com checks google.com for ECDH ciphers (and lists also not available ones at the target), testssl.sh -x DHE smtp.posteo.de:465 does a similar thing for the TLS enabled SMTP service.

testssl.sh --file <myfile> let you do mass testing. The syntax of the file is very easy: one cmdline per line. Use comment signs # as you like, blank lines will be skipped, EOF signals the end of the file – what else? ;-).

You can also specify a proxy since version 2.6: testssl.sh --proxy=<proxyhost>:<proxyport> <your_other_cmds_here> will sneak the openssl and bash sockets requests e.g. out of our corporate environment. Proxy authentication is not supported and the port and protocol has to be allowed in the proxy.

Another neat feature: testssl.sh -H <URI> gives you some information on the HTTP header and marks security features in green (see upper black picture on the right hand side), not so good headers range from yellow over brown to red. It also allows you to fingerprint proxies, see lower black picture.

Changes

2.9.5

See Readme

2.8

► Trust chain check against certificate stores from Apple (OS), Linux (OS), Microsoft (OS), Mozilla (Firefox Browser)
► Works now on servers requiring a x509 certificate for authentication
► Extensive CN+SAN <--> hostname check
► SSL Session ID check
► Avahi/mDNS based name resolution
► HTTP2/ALPN protocol check
► IPv6 support via '-6' argument (except IPv6 proxy)
► Logging to a file / dir
► Logging to (flat) JSON + CSV
► HPKP checks now also for Root and intermediate SPKIs
► Check for multiple server certificates
► Browser cipher simulation: what client will connect with which cipher + protocol
► GOST cipher+certificate improvements
► Assistance for color-blind users
► Even more compatibility improvements for FreeBSD, NetBSD, Gentoo, RH-ish, F5 and Cisco systems
► Considerable speed improvements for each cipher runs (-e/-E)
► More robust SSLv2 + TLS socket interface
► separate check for curves
► OpenSSL 1.1.0 compliant
► Check for DROWN
► Whole number of bugs squashed

2.6 Features (Sep 2015)

► LOGJAM: check of DHE_EXPORT ciphers, displays DH(/ECDH) bits in wide mode on negotiated ciphers
► (HTTP) proxy support! Via sockets and openssl -- Thx @jnewbigin
► TLS_FALLBACK_SCSV check – Thx @JonnyHightower
► TLS 1.0-1.1 as socket checks per default in production
► TLS time and HTTP time stamps for architecture fiingerprinting
► support of sockets also for STARTTLS protocol checks
► TLS time displayed also for STARTTLS
► binary directory provides out of the box better suited binaries (with up to 195 ciphers), besides Linux static binaries
(OS X binaries (new builds from @jpluimers), FreeBSD binary, ARM binary (@f-s)
► Extended validation certificate detection
► "wide mode" option for checks like RC4, BEAST. PFS: Displays hexcode, kx, strength, DH bits, RFC cipher name
► will test multiple IP adresses in one shot, --ip= restricts it accordingly
► runs in default mode through all ciphers at the end of a default run
► new mass testing file option --file option where testssl.sh commands are being read from, see here
► displays matching host key (HPKP)
► further detection of security relevant headers (reverse proxy, IPv4 addresses) as well as proprietary banners (OWA, Liferay etc.)
► can scan STARTTLS+XMPP by also supplying the XMPP domain (to-option in XML streams).
► quite some fixes when using LibreSSL, still not recommended to use though (see above)
► lots of fixes, code improvements, even more robust

2.4 Features (May, 2015)

► "only one cmd line option at a time" is completely gone
► several tuning parameters on the cmd line (only available through environment variables b4): --assuming-http,
--ssl-native, --sneaky, --warnings, --color, -- debug, --long
► certificate information
► more HTTP header infos (cookies+security headers)
► protocol check via bash sockets for SSLv2+v3
► debug handling significantly improved (verbosity/each function leaves files in $TEMPDIR)
► BEAST check
► FREAK check
► HeartBleed check
► check for Secure Client-Initiated Renegotiation
► lots of cosmetic and maintainability code cleanups
► bugfixing

2.0 Features (June 2014)

► SNI
► STARTTLS
► server preferences for protocols and ciphers
► checks for: RC4, PFS, SPDY
► web and app server banner, HSTS
► server key size
► TLS session tickets
► TLS server extensions
► heartbleed check from bash-heartbleed.sh with shell only SSL handshake!
► CCS check from ccs-injection.sh with shell only SSL handshake!
► somewhat smart check for BREACH vulnerability
► check for CRIME
► tests now for renegotiation vulnerabity
► prelease of cipher suites name space mapping OpenSSL ↔ RFC
► aaand: neat output
► supplying URL, hostname, port with hostname is fine
► sanity check for servce and SSL enabled service is listening at all
► major code cleanups
[..]
More see CHANGELOG.

Misc

Feedback, bugs and contributions are welcome! Currently there's one git repo at https://github.com/drwetter/testssl.sh. Here @ https://testssl.sh you will always find the latest stable version. At github in the 2.9dev branch is the latest'n'greatest development version.

Bugs (and fixes) as well as other PRs can by filed at the git repo or send me a mail to dirk aet testssl dot sh.

I post all significant updates on Twitter (@drwetter).

Services: If you need a scanning service or consulting get in touch with me.