Git/testssl.sh
1
0
Fork 0
mirror of https://github.com/drwetter/testssl.sh.git synced 2024-11-29 22:36:52 +01:00
Code Issues Packages Projects Releases Wiki Activity

further additions 

comply with standard '[]' as optional and '<>' as mandatory parameter

replace double by single backticks
Dirk 2017-06-19 23:20:16 +02:00
parent d4b955e78c
commit 3a922bf381
1 changed files with 53 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
Man-page.md

@ -5,11 +5,11 @@
### SYNOPSIS
``testssl.sh <OPTIONS> [ URI | --file FILE ]``
`testssl.sh [OPTIONS] < URI | --file FILE >`
or
``testssl.sh <BANNER OPTIONS>``
`testssl.sh [BANNER OPTIONS]`
### DESCRIPTION
@ -19,11 +19,11 @@ The output rate findings by color (screen) or severity (file output) so that you
Except DNS lookups it doesn't use any third parties for checks, it's only you who sees the result and you also can use it internally on your LAN.
Portability is another core feature. testssl.sh runs under any Unix-like stack (Linux, *BSD, MacOS X, WSL=bash on Windows, Cygwin and MSYS2). ``bash`` (also version 3) is a prerequisite as well as standard utilities like awk, sed, tr and head. This can be of BSD, System 5 or GNU flavor whereas grep from System V is not yet supported.
Portability is another core feature. testssl.sh runs under any Unix-like stack (Linux, *BSD, MacOS X, WSL=bash on Windows, Cygwin and MSYS2). `bash` (also version 3) is a prerequisite as well as standard utilities like awk, sed, tr and head. This can be of BSD, System 5 or GNU flavor whereas grep from System V is not yet supported.
### GENERAL
``testssl.sh URI`` is the so-called default run which does a number of checks and puts out the results colorized (ANSI and termcap) on the screen. It does every check listed under CHECKS except ``-E``. Following checks are being done (order of appearance) by ``testssl.sh <OPTIONS> URI``
`testssl.sh URI` is the so-called default run which does a number of checks and puts out the results colorized (ANSI and termcap) on the screen. It does every check listed under CHECKS except `-E`. Following checks are being done (order of appearance) by `testssl.sh <OPTIONS> URI`
0) displays a banner (see below), does a DNS lookup also for further IP addresses and does for the returned IP address a reverse lookup. Last but not least a service check is being done.
@ -37,7 +37,7 @@ Portability is another core feature. testssl.sh runs under any Unix-like stack (
5) server defaults (certificate info, TLS extensions, session information)
6) HTTP header (if HTTP detected or being forced via ``--assume-http``)
6) HTTP header (if HTTP detected or being forced via `--assume-http`)
7) vulnerabilities
@ -47,62 +47,62 @@ Portability is another core feature. testssl.sh runs under any Unix-like stack (
### OPTIONS
Options are either short or long options. All options requiring a value can be called with or without '=' e.g. ``testssl.sh -t=smtp --wide --openssl=/usr/bin/openssl <URI>`` is equivalent to ``testssl.sh --starttls smtp --wide --openssl /usr/bin/openssl <URI>``. Some options can also be preset via ENV variables. ``WIDE=true OPENSSL=/usr/bin/openssl testssl.sh --starttls smtp <URI>`` would be the equivalent to the aforementioned examples. Preference has the command line over any enviroment variables.
Options are either short or long options. All options requiring a value can be called with or without '=' e.g. `testssl.sh -t=smtp --wide --openssl=/usr/bin/openssl <URI>` is equivalent to `testssl.sh --starttls smtp --wide --openssl /usr/bin/openssl <URI>`. Some options can also be preset via ENV variables. `WIDE=true OPENSSL=/usr/bin/openssl testssl.sh --starttls smtp <URI>` would be the equivalent to the aforementioned examples. Preference has the command line over any enviroment variables.
``<URI>`` or ``--file <FILE>`` always needs to be the last parameter.
`<URI>` or `--file <FILE>` always needs to be the last parameter.
##### BANNER OPTIONS
``-h, --help`` command line help
``-b, --banner`` displays testssl.sh banner, including license, usage conditions, version of testssl.sh, detected openssl version, its path to it, # of ciphers of openssl, its build date and the architecture
`--help` (or no arg) display command line help
``-v, --version`` same as before
`-b, --banner` displays testssl.sh banner, including license, usage conditions, version of testssl.sh, detected openssl version, its path to it, # of ciphers of openssl, its build date and the architecture
``-V, --local <pattern>`` or ``-V, --local`` pretty print all local ciphers supported by openssl version. If a pattern is supplied it performs a match (ignore case) on any of the strings supplied in the wide output, see below. The pattern will be searched in the any of the columns: hexcode, cipher suite name (OpenSSL or RFC), key exchange, encryption, bits. It does a word pattern match for non-numbers, for number just a normal match applies. Numbers here are defined as [0-9,A-F]. This means (attention: catch) that the pattern CBC is matched as non-word, but AES as word.
`-v, --version` same as before
`-V <pattern> , --local <pattern>` pretty print all local ciphers supported by openssl version. If a pattern is supplied it performs a match (ignore case) on any of the strings supplied in the wide output, see below. The pattern will be searched in the any of the columns: hexcode, cipher suite name (OpenSSL or RFC), key exchange, encryption, bits. It does a word pattern match for non-numbers, for number just a normal match applies. Numbers here are defined as [0-9,A-F]. This means (attention: catch) that the pattern CBC is matched as non-word, but AES as word.
##### INPUT PARAMETERS
``URI`` can be a hostname, an IPv4 or IPv6 address (restriction see below) or an URL. IPv6 addresses need to be in square brackets. For any given parameter port 443 is assumed unless specified by appending a colon and a port number. The only preceding protocol specifier allowed is ``https``. You need to be aware that checks for an IP address might not hit the vhost you want. DNS resolution (A/AAAA record) is being performed unless you have an ``/etc/hosts`` entry for the hostname.
`<URI>` can be a hostname, an IPv4 or IPv6 address (restriction see below) or an URL. IPv6 addresses need to be in square brackets. For any given parameter port 443 is assumed unless specified by appending a colon and a port number. The only preceding protocol specifier allowed is `https`. You need to be aware that checks for an IP address might not hit the vhost you want. DNS resolution (A/AAAA record) is being performed unless you have an `/etc/hosts` entry for the hostname.
``--file <fname>`` is the mass testing option. Per default it implicitly turns on ``--warnings batch``.
In its first incarnation the mass testing option reads command lines from ``<fname>``. ``<fname>`` consists of command lines of testssl, one line per instance. Comments after ``#`` are ignored, ``EOF`` signals the end of <fname> any subsequent lines will be ignored too. You can also supply additional options which will be inherited to each child, e.g. When invoking ``testssl.sh --wide --log --file <fname>`` . Each single line in ``<fname>`` is parsed upon execution. If there's a conflicting option and serial mass testing option is being performed the check will be aborted at the time it occurs and depending on the output option potentially leaving you with an output file without footer. In parallel mode the mileage varies.
`--file <fname>` is the mass testing option. Per default it implicitly turns on `--warnings batch`.
In its first incarnation the mass testing option reads command lines from `<fname>`. `<fname>` consists of command lines of testssl, one line per instance. Comments after `#` are ignored, `EOF` signals the end of <fname> any subsequent lines will be ignored too. You can also supply additional options which will be inherited to each child, e.g. When invoking `testssl.sh --wide --log --file <fname>` . Each single line in `<fname>` is parsed upon execution. If there's a conflicting option and serial mass testing option is being performed the check will be aborted at the time it occurs and depending on the output option potentially leaving you with an output file without footer. In parallel mode the mileage varies.
Alternatively ``<fname>`` can be in ``nmap``'s grep(p)able output format (``-oG``). Only open ports will be considered. Multiple ports per line are allowed. The ports can be different and will be tested by testssl.sh according to common practice in the internet, .i.e. if nmap shows in its output an open port 25, automatically ``-t smtp`` will be added before the URI whereas port 465 will be treated as a plain TLS/SSL port, not requiring an STARTTLS SMTP handshake upfront.
Alternatively `<fname>` can be in `nmap`'s grep(p)able output format (`-oG`). Only open ports will be considered. Multiple ports per line are allowed. The ports can be different and will be tested by testssl.sh according to common practice in the internet, .i.e. if nmap shows in its output an open port 25, automatically `-t smtp` will be added before the URI whereas port 465 will be treated as a plain TLS/SSL port, not requiring an STARTTLS SMTP handshake upfront.
The nmap output always returns IP addresses and -- only if there's a PTR DNS record available -- a hostname. As it is not checked by nmap whether the hostname matches the IP (A or AAAA record), testssl.sh does this for you. If the A record of the hostname matches the IP address, the hostname is used and not the IP address. As stated above, checks against an IP address might not hit the vhost you maybe were aiming at.
``--mode <serial|parallel>``. Mass testing to be done serial (default) or parallel (``--parallel ``is shortcut for the latter, ``--serial`` is the opposite option). Per default mass testing is being run in serial mode, i.e. one line after the other is processed and invoked. The variable ``MASS_TESTING_MODE`` can be defined to be either equal ``serial`` or ``parallel``.
`--mode <serial|parallel>`. Mass testing to be done serial (default) or parallel (`--parallel `is shortcut for the latter, `--serial` is the opposite option). Per default mass testing is being run in serial mode, i.e. one line after the other is processed and invoked. The variable `MASS_TESTING_MODE` can be defined to be either equal `serial` or `parallel`.
##### SPECIAL INVOCATIONS:
``-t, --starttls <protocol>`` does a default run against a STARTTLS enabled ``<protocol>``. ``<protocol>`` is one of ``ftp``, ``smtp``, ``pop3``, ``imap``, ``xmpp``, ``telnet``, ``ldap``, ``postgres`` For the latter three two you need e.g. the supplied openssl.
`-t <protocol>, --starttls <protocol>` does a default run against a STARTTLS enabled `<protocol>`. `<protocol>` is one of `ftp`, `smtp`, `pop3`, `imap`, `xmpp`, `telnet`, `ldap`, `postgres`. For the latter three two you need e.g. the supplied openssl.
``--xmpphost <jabber_domain>`` is an additional option for STARTTLS enabled XMPP: It expects as a parameter the jabber domain. This is only needed if the domain is different from the URI supplied.
`--xmpphost <jabber_domain>` is an additional option for STARTTLS enabled XMPP: It expects as a parameter the jabber domain. This is only needed if the domain is different from the URI supplied.
``--mx <domain/host>`` tests all MX records (STARTTLS, port 25) from high to low priority one after the other.
`--mx <domain|host>` tests all MX records (STARTTLS, port 25) from high to low priority one after the other.
``--ip <ip>`` tests either the supplied IPv4 or IPv6 address instead of resolving host(s) in ``<URI>``. IPv6 addresses needs to be in square brackets.
``--ip=one`` means: just test the first DNS returns (useful for multiple IPs). It's also useful if you want to resolve the supplied hostname to a different IP, similar as if you would edit ``/etc/hosts``. ``--ip=proxy`` tries a DNS resolution via proxy.
`--ip <ip>` tests either the supplied IPv4 or IPv6 address instead of resolving host(s) in `<URI>`. IPv6 addresses needs to be in square brackets.
`--ip=one` means: just test the first DNS returns (useful for multiple IPs). It's also useful if you want to resolve the supplied hostname to a different IP, similar as if you would edit `/etc/hosts` or `/c/Windows/System32/drivers/etc/hosts`. `--ip=proxy` tries a DNS resolution via proxy.
``--proxy <host>:<port>`` does the whole check via the specified HTTP proxy. ``--proxy=auto`` inherits the proxy setting from the environment. Proxying via IPv6 addresses is not possible. The hostname supplied will only be resolved to the first A record. Authentication to the proxy is not supported.
`--proxy <host>:<port>` does the whole check via the specified HTTP proxy. `--proxy=auto` inherits the proxy setting from the environment. Proxying via IPv6 addresses is not possible. The hostname supplied will only be resolved to the first A record. Authentication to the proxy is not supported.
``-6`` does (also) IPv6 checks. This works only with both a supporting openssl binary like 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.
`-6` does (also) IPv6 checks. This works only with both a supporting openssl binary like 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.
``--ssl-native`` instead of using a mixture of bash sockets and openssl s_client connects testssl.sh uses the latter only. This is at the moment faster but provides less accurate results, especially in the client
simulation and if the openssl binary lacks cipher support. For TLS protocol checks and standard cipher lists and certain other checks you will see a warning if testssl.sh internally can tell if one check cannot be performed or will give you inaccurate results. For e.g. single cipher checks (``--each-cipher`` and ``--cipher-per-proto``) you might end up getting false negatives without a warning.
`--ssl-native` instead of using a mixture of bash sockets and openssl s_client connects testssl.sh uses the latter only. This is at the moment faster but provides less accurate results, especially in the client
simulation and if the openssl binary lacks cipher support. For TLS protocol checks and standard cipher lists and certain other checks you will see a warning if testssl.sh internally can tell if one check cannot be performed or will give you inaccurate results. For e.g. single cipher checks (`--each-cipher` and `--cipher-per-proto`) you might end up getting false negatives without a warning.
``--openssl <path_to_openssl>`` testssl.sh tries very hard to find automagically the binary supplied (where the tree of testssl.sh resides, from the directory where testssl.sh has been started from, etc.). If all that doesn't work it falls back to openssl supplied from the OS (``$PATH``). With this option you can point testssl.sh to your binary of choice and override any internal magic to find the openssl binary. (environment preset via `OPENSSL=<path_to_openssl>`)
`--openssl <path_to_openssl>` testssl.sh tries very hard to find automagically the binary supplied (where the tree of testssl.sh resides, from the directory where testssl.sh has been started from, etc.). If all that doesn't work it falls back to openssl supplied from the OS (`$PATH`). With this option you can point testssl.sh to your binary of choice and override any internal magic to find the openssl binary. (environment preset via `OPENSSL=<path_to_openssl>`)
``--bugs`` does some workarounds for buggy servers like padding for old F5 devices. The option is passed as ``-bug`` to openssl when needed, see ``s_client(1)``. For the socket part testssl.sh tries its best also without that option to cope with broken server implementations (environment preset via `BUGS="-bugs"`)
`--bugs` does some workarounds for buggy servers like padding for old F5 devices. The option is passed as `-bug` to openssl when needed, see `s_client(1)`. For the socket part testssl.sh tries its best also without that option to cope with broken server implementations (environment preset via `BUGS="-bugs"`)
``--assuming-http`` testssl.sh does upfront a protocol detection on the application layer. In cases where for some reasons the usage of HTTP cannot be automatically detected you may want to use this option. It helps you to tell testssl.sh not to skip HTTP specific tests and to run the client simulation with browsers. Sometimes also the severity depends on the application protocol, e.g. SHA1 signed certificates, the lack of any SAN matches and some vulnerabilities will be punished harder when checking a web server as opposed to a mail server.
`--assuming-http` testssl.sh does upfront a protocol detection on the application layer. In cases where for some reasons the usage of HTTP cannot be automatically detected you may want to use this option. It helps you to tell testssl.sh not to skip HTTP specific tests and to run the client simulation with browsers. Sometimes also the severity depends on the application protocol, e.g. SHA1 signed certificates, the lack of any SAN matches and some vulnerabilities will be punished harder when checking a web server as opposed to a mail server.
* `-n, --no-dns` instructs testssl.sh to not do any DNS lookups. It's useful if you either can't or are not willing to perform DNS lookups. The latter applies e.g. to some pentests, the former could e.g. help you to avoid timeouts by DNS lookups.
* `--sneaky`
+ as a friendly feature for the server side testssl.sh uses a user agent ``TLS tester from <URL>`` (HTTP). With this option your traces are less verbose and a Firefox user agent is being used. Be aware that it doesn't hide your activities. That is just not possible (environment preset via `SNEAKY=true`).
* `--sneaky` as a friendly feature for the server side testssl.sh uses a user agent `TLS tester from ${URL}` (HTTP). With this option your traces are less verbose and a Firefox user agent is being used. Be aware that it doesn't hide your activities. That is just not possible (environment preset via `SNEAKY=true`).
### SINGLE CHECK OPTIONS
@ -126,28 +126,30 @@ Any single option supplied prevents testssl.sh from doing a default run. It just
* `Strong grade Ciphers` (AEAD): 'AESGCM:CHACHA20:AESGCM:CamelliaGCM:AESCCM8:AESCCM'
`-p, --protocols` checks TLS/SSL protocols
`-p, --protocols` checks TLS/SSL protocols SSLv2, SSLv3, TLS 1.0 - TLS1.2 and for HTTP: SPDY (NPN) and ALPN, a.k.a. HTTP/2
`-S, --server_defaults` displays the servers default picks and certificate info
`-P, --preference` displays the servers preferences: cipher order, with used openssl client: negotiated protocol and cipher. If there's a cipher order enforced by the server it displays it for each protocol (openssl+sockets). If there's not, it displays instead which ciphers from the server were picked with each protocol (by using openssl only)
`-P, --preference` displays the servers picks: protocol+cipher
`-S, --server_defaults` displays information from the server hello(s): available TLS extensions, TLS ticket + session information/capabilities and several certificate info including revocation info (CRL, OCSP, OCSP stapling/must staple), Certification Authority Authorization (CAA) record and: trust (CN, SAN, Chain of trust, expiration of certificate). For trust chain check there are 4 certificate stores provided (see section `FILES` below). If the trust is confirmed or not confirmed and the same in all four vertificate stores there will be only one line of output with the appropriate result. If there are different results, each store is listed and for the one where there's no trust there's an indication what the failure is. Additional certificate stores for e.g. an intranet CA an be put into __etc/__ with the extension __pem__. In that case there will be a complaint about a missing trust with the other stores, in the opposite case -- i.e. if trust will be checked against hosts having a certificate issued by a different CA -- there will be a complaint by a missing trust in this additional store.
If the server provides no matching record in Subject Alternative Name (SAN) but in Common Name (CN), it will be clearly indicated as this is deprecated. Possible fingerprinting is possible by the results in TLS clock skew: Only a few servers nowadays still have and TLS/SSL implementation which returns the local clock `gmt_unix_time` (e.g. IIS, openssl < 1.0.1f). In addition to the HTTP date you could derive that there are different hosts where your TLS and your HTTP request ended -- if the time deltas differ significantly. Also multiple server certificates are being checked for as well as the certificate reply to a non-SNI (Server Name Indication) client hello to the IP address.
`-y, --spdy, --npn` checks for SPDY/NPN
`-x, --single-cipher <pattern>` tests matched <pattern> of ciphers
(if <pattern> not a number: word match)
`-x <pattern>, --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
`-H, --heartbleed` tests for heartbleed vulnerability
`-I, --ccs, --ccs-injection` tests for CCS injection vulnerability
`-T, --ticketbleed` tests for Ticketbleed vulnerability in BigIP loadbalancers
`-R, --renegotiation` tests for renegotiation vulnerabilities
`-C, --compression, --crime` tests for CRIME vulnerability
`-T, --breach` tests for BREACH vulnerability
`-B, --breach` tests for BREACH vulnerability
`-O, --poodle` tests for POODLE (SSL) vulnerability
@ -163,7 +165,7 @@ Any single option supplied prevents testssl.sh from doing a default run. It just
`-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
`-h, --header, --headers` tests HSTS, HPKP, server/app banner, security headers, cookie, reverse proxy, IPv4 address
### OUTPUT OPTIONS
@ -212,11 +214,11 @@ A few file output options can also be preset via environment variables.
### EXAMPLES
testssl.sh testssl.sh
does a default run on https://testssl.sh (protocols, standard cipher lists, PFS, server preferences, server defaults, vulnerabilities, testing all (359 possible) ciphers, client simulation.
does a default run on https://testssl.sh (protocols, standard cipher lists, PFS, server preferences, server defaults, vulnerabilities, testing all (359 possible) ciphers, client simulation.
testssl.sh testssl.net:443
does the same default run as above with the subtle difference that testssl.net has two IPv4 addresses. Both are tested.
does the same default run as above with the subtle difference that testssl.net has two IPv4 addresses. Both are tested.
testssl.sh --ip=one --wide https://testssl.net:443
@ -228,17 +230,17 @@ implicilty does a STARTTLS handshake on the plain text port, then check the IPs
testssl.sh --starttls=imap imap.gmx.net:143
does the same on the plain text IMAP port. Please note that for plain TLS-encrypted ports you must not 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.
does the same on the plain text IMAP port. Please note that for plain TLS-encrypted ports you must not 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.
### Exit status
**0** testssl.sh finished successfully
**245** no bash used or called with sh
**249** temp file generation problem
**251** feature not yet supported
**252** no DNS resolver found or not executable / proxy couldn't be determined from given values / -xmpphost supplied but OPENSSL too old
**253** no SSL/TLS enabled server / OPENSSL too old / couldn't connect to proxy / couldn't connect via STARTTLS
**254** no OPENSSL found or not exexutable / no IPv4 address could be determined / illegal STARTTLS protocol supplied / supplied file name not readable
**0** testssl.sh finished successfully
**245** no bash used or called with sh
**249** temp file generation problem
**251** feature not yet supported
**252** no DNS resolver found or not executable / proxy couldn't be determined from given values / -xmpphost supplied but OPENSSL too old
**253** no SSL/TLS enabled server / OPENSSL too old / couldn\'t connect to proxy / couldn't connect via STARTTLS
**254** no OPENSSL found or not exexutable / no IPv4 address could be determined / illegal STARTTLS protocol supplied / supplied file name not readable
### RFCs
@ -246,10 +248,11 @@ fixme
### FILES
**etc/*pem** Certificate stores from Linux, Mozilla Firefox, Windows 7, JDK 8
**etc/\*pem** certificate stores from Apple, Linux, Mozilla Firefox, Windows
**etc/mapping-rfc.txt** provides a file with mapping from OpenSSL cipher suites names to the ones from IANA / used in the RFCs
**etc/mapping-rfc.txt** provides a mandatory file with mapping from OpenSSL cipher suites names to the ones from IANA / used in the RFCs
**etc/tls_data.txt** provides a mandatory file for ciphers (bash sockets) and key material
### AUTHORS
Developed by Dirk Wetter and others, see https://github.com/drwetter/testssl.sh/blob/master/CREDITS.md