testssl.sh: Testing TLS/SSL encryption

NameLast ModifiedSizeType
CHANGELOG.txt2015-Sep-15 10:56:4512.27KB TXT Type Document
LICENSE.txt2014-May-03 11:04:2217.59KB TXT Type Document
OPENSSL-LICENSE.txt2015-Oct-13 00:12:2358.08KB TXT Type Document
bash-heartbleed.changelog.txt2014-May-03 17:37:15572.00B TXT Type Document
bash-heartbleed.sh2015-Oct-27 15:11:183.98KB SH File
ccs-injection.sh2014-Jun-14 23:44:423.94KB SH File
mapping-rfc.txt2014-Dec-21 00:52:1315.88KB TXT Type Document
openssl-1.0.2e-chacha.pm.ipv6.Linux.tar.gz2015-Oct-05 13:39:095.58MB GZ Compressed Archive
openssl-1.0.2e-chacha.pm.ipv6.Linux.tar.gz.asc2015-Oct-05 13:39:54811.00B ASC File
openssl-1.0.2e-chacha.pm.tar.gz2015-Sep-15 09:23:0711.65MB GZ Compressed Archive
openssl-1.0.2e-chacha.pm.tar.gz.asc2015-Sep-16 01:17:54828.00B ASC File
openssl-rfc.mappping.html2015-Jul-20 20:49:0533.99KB HTML File
testssl.sh2015-Sep-29 22:00:48169.50KB SH File
testssl.sh.asc2015-Sep-29 22:01:58828.00B ASC File

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.

Key features

Longer read

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

As for security reasons some distributors outphase the dirty stuff you want to check for – it's recommended to compile OpenSSL (best from github.com/PeterMosmans/openssl) by yourself or check out the distributed OpenSSL binaries (Linux) – they come with a whopping 195 ciphers – ~80 more than on an average Linux distro (note: openssl-1.0.2e-chacha.pm.ipv6.Linux.tar.gz is a Linux-only tarball with IPv6 support. openssl-1.0.2e-chacha.pm.tar.gz contains also FreeBSD and Darwin Binaries). In any case: Except the ciphers, you will get a warning if your OpenSSL client cannot perform a specific check, see below. Since 2.4 on some of those checks are done with bash sockets – to be improved gradually. Same applies to LibreSSL: Basically it has lots of flawed features (ciphers, protocols and more) for security reasons disabled – thus for security testing it's not a good choice. Also here testssl.sh will improve over time as more and more checks are done via bash sockets.

Development takes place at github. Here at testssl.sh you find the latest stable version and documentation. As I do releases on github you can as well pull the zip from a stable release there. (Note the feature: curl -L testssl.sh or wget -O - testssl.sh downloads the stable version right away, curl -L testssl.sh/dev/ or wget -O - testssl.sh/dev/ the development version from github. You miss the accompanying files though.)


2.6 Features (Sep 2015)


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
     -S, --server_defaults         displays the servers default picks and certificate info
     -P, --preference              displays the servers picks: protocol+cipher
     -y, --spdy, --npn             checks for SPDY/NPN
     -x, --single-cipher <pattern> tests matched <pattern> of ciphers
                                   (if <pattern> not a number: word match)
     -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
     -s, --pfs, --fs,--nsa         checks (perfect) forward secrecy settings
     -4, --rc4, --appelbaum        which RC4 ciphers are being offered?
     -H, --header, --headers       tests HSTS, HPKP, server/app banner, security headers, cookie, reverse proxy, IPv4 address

  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 <ipv4>                   a) tests the supplied <ipv4> instead of resolving host(s) in URI
                                   b) arg "one" means: just test the first DNS returns (useful for multiple IPs)
     --file <file name>            mass testing option: Just put multiple testssl.sh command lines in <file name>,
                                   one line per instance. Comments via # allowed, EOF signals end of <file name>.

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 ftp,smtp,pop3,imap,xmpp,telnet,ldap (for the latter two you need e.g. the supplied openssl)

tuning options:

     --assuming-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
     --sneaky                      be less verbose wrt referer headers
     --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
     --warnings <batch|off|false>  "batch" doesn't wait for keypress, "off" or "false" skips connection warning
     --color <0|1|2>               0: no escape or other codes,  1: b/w escape codes,  2: color (default)
     --debug <0-6>                 1: screen output normal but debug output in temp files.  2-6: see line ~105

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.

Which OpenSSL binary?

As mentioned above, a prerequisite for thoroughly checking SSL/TLS enabled servers is that all you want to check for has to be available on your client. Transport encryption is not only depending on the server but also on your crypto provider on the client side – especially if you want to use it for testing. So there are drawbacks for openssl binaries distributed with Linux and BSD: One of the worst test scenarios for testssl.sh is using LibreSSL as it has lots of stuff disabled.

Therefore the signed tarball provides specially compiled statically linked (except glibc and the loader) OpenSSL binaries as a courtesy. It has every dirty feature enabled but also has ChaCha+Poly ciphers on board. And as an option there are more Linux binaries having Kerberos ciphers included – the latter ones require a bunch of libraries (no static binaries). In the end those binaries will give you 191 ciphers + four GOST ciphers as opposed to ~110 from standard Linux distros! All binaries are compiled from Peter Mosmans OpenSSL fork. You'll need to unpack the binaries, dump those either in $INSTALLDIR/bin. You can also tell testssl.sh via environment variable where your openssl binary is:
export OPENSSL=<path_to_myopenssl>
before you use testssl or using the option --openssl=<path_to_myopenssl>. Last but not least $PATH is also used to find your OpenSSL binary.

Warning: Don't try outdated OpenSSL versions before 1.0! Those versions are deprecated, you likely will not get very far. testssl.sh is not locking those versions out yet but things might not work as expected. Support will be retired by Jan 2016. If you insist on using crippled – in the sense of this tool – binaries, you'll get a warning in magenta, see e.g. picture on the left hand side (middle of this page).


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 stable version. At github in the master branch is the latest'n'greatest development version.

Bugs (and fixes) 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.