diff --git a/Usage-Documentation.md b/Usage-Documentation.md index a6009fa..1fb5467 100644 --- a/Usage-Documentation.md +++ b/Usage-Documentation.md @@ -2,10 +2,19 @@ ### NAME testssl.sh -- check encryption of SSL/TLS servers +### SYNOPSIS -### SYNTAX +testssl.sh [OPTIONS]... [FILE|URI]... -testssl.sh +### DESCRIPTION + +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 much more. + +All options requiring a value can be called with or without '=' e.g. ``testssl.sh -t=smtp --wide --openssl=/usr/bin/openssl ``. + + or needs always to be the last parameter. + +##### BANNER OPTIONS -h, --help what you're looking at -b, --banner displays banner + version of testssl.sh @@ -13,6 +22,29 @@ testssl.sh -V, --local pretty print all local ciphers -V, --local which local ciphers with are available? (if pattern not a number: word match) +##### INPUT 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) + --file Mass testing option: Reads command lines from in plaintext format, one line per instance. + Comments via # allowed, EOF signals end of . Implicitly turns on "--warnings batch". + Per default mass testing is being run in serial mode, i.e. one line after the other is processed and invoked. + Besides having individual command line options per line in the supplied file you can additionally specify options on the command line. The command line options in the file and on the command line must not conflict. + + Alternatively can be in nmap's greppable output format (-oG). Currently only 1x port per line is allowed. The ports can be different per line, however per mass testing run they can be either STARTTLS enabled ports OR plain TLS/SSL ports. + + --mode Mass testing to be done serial (default) or parallel (--parallel is shortcut for the latter) + +##### SPECIAL INVOCATIONS: + + -t, --starttls does a default run against a STARTTLS enabled + --xmpphost for STARTTLS enabled XMPP it supplies the XML stream to-'' domain -- sometimes needed + --mx tests MX records from high to low priority (STARTTLS, port 25) + --ip a) tests the supplied 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) +##### DEFAULT CHECKS testssl.sh URI (`testssl.sh URI` does everything except `-E`) @@ -40,31 +72,21 @@ testssl.sh URI (`testssl.sh URI` does everything except `-E`) -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: +##### TUNING OPTIONS - -t, --starttls does a default run against a STARTTLS enabled - --xmpphost for STARTTLS enabled XMPP it supplies the XML stream to-'' domain -- sometimes needed - --mx tests MX records from high to low priority (STARTTLS, port 25) - --ip a) tests the supplied 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 mass testing option: Reads command lines from , one line per instance. - Comments via # allowed, EOF signals end of . Implicitly turns on "--warnings batch" -partly mandatory parameters: +Some can also be preset via environment variables. - 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 (can also be preset via environment variables): - - --bugs enables the "-bugs" option of s_client, needed e.g. for some buggy F5s + --bugs enables the "-bugs" option of s_client and some other workarounds. This could be needed e.g. for some buggy F5 loadbalancers --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 use this openssl binary (default: look in $PATH, $RUN_DIR of testssl.sh --proxy : connect via the specified HTTP proxy - -6 use also IPv6 checks, works only with supporting OpenSSL version and IPv6 connectivity -output options (can also be preset via environment variables): + -6 Use also IPv6 checks. This works only with a supporting OpenSSL binary (e.g. the one supplied) and IPv6 connectivity. testssl.sh does no connectivity checks for IPv6, it also cannot determine reliably whether the OpenSSL binary you are using has IPv6 support. + +##### OUTPUT OPTIONS + +All output options can also be preset via environment variables. --warnings "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 @@ -81,7 +103,9 @@ output options (can also be preset via environment variables): 5: display bytes received via sockets 6: whole 9 yards -file output options (can also be preset via environment variables): +##### FILE OUTPUT OPTIONS + +A few file output options can also be preset via environment variables. --log, --logging logs stdout to in current working directory --logfile logs stdout to if file is a dir or to specified log file @@ -89,20 +113,12 @@ file output options (can also be preset via environment variables): --jsonfile additional output to JSON and output JSON to the specified file --csv additional output of findings to CSV file in cwd --csvfile set output to CSV and output CSV to the specified file + --html additional output as HTML to file -p.html + --htmlfile additional output as HTML to the specifed file or directory, similar to --logfile + --append if or 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 . - - -All options requiring a value can also be called with `=` (e.g. `testssl.sh -t=smtp --wide --openssl=/usr/bin/openssl `. - - is always the last parameter. - -Need HTML output? Just pipe through "aha" (Ansi HTML Adapter: github.com/theZiz/aha) like - - `testssl.sh | aha >output.html` - - ### STARTTLS For STARTTLS you need to aim at the text/plain port, provide ``-t/--smtp`` and the port : ``testssl.sh -t smtp smtp.gmail.com:25`` or e.g. ``testssl.sh -t imap imap.gmx.net:143``. Please note that for plain encrypted ports you do not have to specify the protocol option: ``testssl.sh smtp.gmail.com:465`` tests the encryption on the SMTPS port, ``testssl.sh imap.gmx.net:993`` on the IMAPS port. @@ -134,13 +150,13 @@ Developed by Dirk Wetter and others, see https://github.com/drwetter/testssl.sh/ ### COPYRIGHT -Copyright © 2016 Dirk Wetter. License GPLv2: Free Software Foundation, Inc. +Copyright © 2014 Dirk Wetter. License GPLv2: Free Software Foundation, Inc. This is free software: you are free to change and redistribute it under the terms of the license. Usage WITHOUT ANY WARRANTY. USE at your OWN RISK! ### BUGS -Known ones see https://testssl.sh/bugs +Known ones and interface for filing new ones: https://testssl.sh/bugs. ### SEE ALSO