diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b79171a..e8c72cb 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,22 +1,36 @@ + ## What is your pull request about? - [ ] Bug fix - [ ] Improvement - [ ] New feature (adds functionality) -- [ ] Breaking change (bug fix, feature or improvement that would cause existing functionality to not work as expected) -- [ ] Typo fix +- [ ] Breaking change: bug fix, feature or improvement that would cause existing output (especially JSON, CSV) to not work as expected before +- [ ] Typo / spelling fix - [ ] Documentation update - [ ] Update of other files ## If it's a code change please check the boxes which are applicable - [ ] For the main program: My edits contain no tabs, indentation is five spaces and any line endings do not contain any blank chars -- [ ] I've read CONTRIBUTING.md and Coding_Convention.md +- [ ] I've read [CONTRIBUTING.md](https://github.com/testssl/testssl.sh/blob/3.3dev/CONTRIBUTING.md) +- [ ] My code follows [Coding_Convention.md](https://github.com/testssl/testssl.sh/blob/3.3dev/Coding_Convention.md) - [ ] I have tested this __fix__ or __improvement__ against >=2 hosts and I couldn't spot a problem - [ ] I have tested this __new feature__ against >=2 hosts which show this feature and >=2 host which does not (in order to avoid side effects) . I couldn't spot a problem - [ ] For the __new feature__ I have made corresponding changes to the documentation and / or to ``help()`` -- [ ] If it's a bigger change: I added myself to CREDITS.md (alphabetical order) and the change to CHANGELOG.md +- [ ] If it's a bigger change: I added myself to [CREDITS.md](https://github.com/testssl/testssl.sh/blob/3.3dev/CREDITS.md) (alphabetical order) and the change to [CHANGELOG.md](https://github.com/testssl/testssl.sh/blob/3.3dev/CHANGELOG.md) + +## AI section +- [ ] My contribution does not include any AI-generated content +- [ ] My contribution includes AI-generated content, as disclosed below: + - AI Tools: `[e.g. GitHub CoPilot, JetBrains Junie, VS Code plugin etc.]` + - LLMs and versions: `[e.g. GPT-A.B, Claude A.B, Gemini A.B , Qwen-Coder, DeepSeek- etc.]` + diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 0000000..cfa708f --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,43 @@ +name: Build Documentation + +on: + pull_request: + paths: + - "doc/testssl.1.md" + +jobs: + build-docs: + runs-on: ubuntu-26.04 + # Skip fork PRs: GITHUB_TOKEN can't push to a fork's branch + if: github.event.pull_request.head.repo.full_name == github.repository + + steps: + - name: Checkout repository + uses: actions/checkout@v7 + with: + ref: ${{ github.head_ref }} + fetch-depth: 0 + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y pandoc make + + - name: Build documentation + working-directory: doc + run: make -B + # -B ensures build when doc/testssl.1.md changes. When checking out the md file + # it probably might have a time stamp which indicates nothing has changed + + - name: Commit and push generated doc files + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add -A + if git diff --staged --quiet; then + echo "No generated changes to commit" + else + git commit -m "Auto-generate docs from testssl.1.md [skip ci]" + git push + fi + diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index c0177b5..36b1948 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -9,7 +9,7 @@ jobs: name: Check for spelling errors runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: codespell-project/actions-codespell@master with: skip: ca_hashes.txt,tls_data.txt,*.pem,OPENSSL-LICENSE.txt,CREDITS.md,openssl.cnf,testssl.1 diff --git a/.github/workflows/docker-3.3dev.yml b/.github/workflows/docker-3.3dev.yml index 18b080d..f7adff2 100644 --- a/.github/workflows/docker-3.3dev.yml +++ b/.github/workflows/docker-3.3dev.yml @@ -22,7 +22,7 @@ jobs: run: echo "REPO=${GITHUB_REPOSITORY@L}" >> "${GITHUB_ENV}" - name: Source checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Setup QEMU id: qemu diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml index ec3f8a1..f7339e8 100644 --- a/.github/workflows/shellcheck.yml +++ b/.github/workflows/shellcheck.yml @@ -30,7 +30,7 @@ jobs: env: LANG: C.UTF-8 steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - name: Install shellcheck run: sudo apt update && sudo apt install -y shellcheck && shellcheck --version diff --git a/.github/workflows/unit_tests_macos.yml b/.github/workflows/unit_tests_macos.yml index ace1cc9..a5814ea 100644 --- a/.github/workflows/unit_tests_macos.yml +++ b/.github/workflows/unit_tests_macos.yml @@ -29,7 +29,7 @@ jobs: name: PoC unit test on MacOS steps: - name: checkout - uses: actions/checkout@v6 + uses: actions/checkout@v7 - name: Set up system (perl, curl is installed already) run: | @@ -54,6 +54,7 @@ jobs: cpanm --notest Data::Dumper cpanm --notest JSON cpanm --notest Text::Diff + cpanm --notest IPC::Run3 - name: run it run: | diff --git a/.github/workflows/unit_tests_ubuntu.yml b/.github/workflows/unit_tests_ubuntu.yml index 771cc10..ef08ae6 100644 --- a/.github/workflows/unit_tests_ubuntu.yml +++ b/.github/workflows/unit_tests_ubuntu.yml @@ -32,7 +32,7 @@ jobs: perl: ['5.38'] name: Unit test on ${{ matrix.os }} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - name: Set up perl uses: shogo82148/actions-setup-perl@v1 @@ -51,6 +51,8 @@ jobs: printf "%s\n" "----------" bash --version printf "%s\n" "----------" + echo $PATH + printf "%s\n" "----------" - name: Install perl modules run: | @@ -58,6 +60,7 @@ jobs: cpanm --notest Data::Dumper cpanm --notest JSON cpanm --notest Text::Diff + cpanm --notest IPC::Run3 - name: run it run: | diff --git a/CHANGELOG.md b/CHANGELOG.md index d98a7b5..5fd2c92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,10 +5,11 @@ * QUIC protocol check * TLS 1.3 early data (0-RTT) -* Support for RFC 8998 and draft-yang-tls-hybrid-sm2-mlkem (TLS_SM4_GCM_SM3, TLS_SM4_CCM_SM3 ciphers, kx groups curveSM2, curveSM2MLKEM768; SM2 pub keys + signatures) +* Support for RFC 8998, draft-yang-tls-hybrid-sm2-mlkem (TLS_SM4_GCM_SM3, TLS_SM4_CCM_SM3 ciphers, kx groups curveSM2, curveSM2MLKEM768; SM2 pub keys + signatures) * Adds a check for mandatory extended master secret TLS extension * Bump SSLlabs rating guide to 2009r * Check for Opossum vulnerability +* `--phone-out` checks the HSTS preload list on https://hstspreload.org/ * Enable IPv6 automagically, i.e. if target via IPv6 is reachable just (also) scan it * Detect and show DNS HTTPS RR (RFC 9460) * Provide an FAQ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1cf7006..cc04c05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,11 +8,11 @@ Please note the following: * Please read the [coding convention](https://github.com/testssl/testssl.sh/blob/3.3dev/Coding_Convention.md). * If you have something new and/or bigger which you like to contribute, better open an issue first before you get frustrated. * Please one pull request per feature or bug fix or improvement. Please do not mix issues. -* Documentation pays off in the long run. So please your document your code and the pull request and/or commit message. -* Please test your changes thoroughly as reliability is important for this project. You may want to check different servers with different settings. -* GitHub actions are running automatically when anything is committed. You should see any complaints. Beforehand you can check with `prove -v` from the "root dir" of this project. +* Please test your changes thoroughly as reliability is important for this project. You may want to check different servers with different settings. Also a run with a different client might help. +* GitHub actions are running automatically when anything is committed. You should see any complaints. Beforehand you can check with `prove -v` from the "root dir" of this project for the whole run, a single (perl) script with `./t/NR_NAME.t`. * If it's a new feature, please consider writing a unit test for it. You can use e.g. `t/10_baseline_ipv4_http.t` or `t/61_diff_testsslsh.t` as a template. The general documentation for [Test::More](https://perldoc.perl.org/Test/More.html) is a good start. * If it's a new feature, it would need to be documented in the appropriate section in `help()` and in `~/doc/testssl.1.md` +* Documentation pays off in the long run. So please your document your code and the pull request and/or commit message. You only have to change `~/doc/testssl.1.md` . The HTML and roff file should be autogenerated by github (see if you PR adds those files). If you're interested in contributing and wonder how you can help, you can search for different tags in the issues (somewhat increasing degree of difficulty): * [documentation](https://github.com/testssl/testssl.sh/issues?q=is:issue%20state:open%20label:documentation) diff --git a/CREDITS.md b/CREDITS.md index b901810..f4ca94b 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -11,7 +11,7 @@ Full contribution, see git log. - extended parsing of TLS ServerHello messages - TLS 1.3 support (final and pre-final) with needed en/decryption - add several TLS extensions - - Several ciphers and curves added + - Several ciphers and curves added - Detection + output of multiple certificates - several cleanups of server certificate related stuff - testssl.sh -e/-E: testing with a mixture of openssl + sockets @@ -55,6 +55,7 @@ Full contribution, see git log. - maximum certificate lifespan of 398 days - ssl renegotiation amount variable - custom http request headers + - HSTS preload list lookup (finalized: Mayank) * Frank Breedijk - Detection of insecure redirects diff --git a/Readme.md b/Readme.md index 6ee366c..6ece533 100644 --- a/Readme.md +++ b/Readme.md @@ -5,22 +5,26 @@ This would display the latest tag which is from the 3.2 branch. Here we don't have tags yet --> ![GitHub forks](https://img.shields.io/github/forks/testssl/testssl.sh) -![GitHub Repo stars](https://img.shields.io/github/stars/testssl/testssl.sh) +![GitHub Repo stars](https://img.shields.io/github/stars/testssl/testssl.sh?style=flat) ![GitHub Created At](https://img.shields.io/github/created-at/testssl/testssl.sh) ![GitHub last commit](https://img.shields.io/github/last-commit/testssl/testssl.sh) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/testssl/testssl.sh) [![Docker](https://img.shields.io/docker/pulls/drwetter/testssl.sh)](https://github.com/testssl/testssl.sh/blob/3.3dev/Dockerfile.md) - [![License](https://img.shields.io/github/license/testssl/testssl.sh)](https://github.com/testssl/testssl.sh/LICENSE) ![Static Badge](https://img.shields.io/badge/version-3.3dev-blue) ![Static Badge](https://img.shields.io/badge/%2Fbin%2Fbash_-blue) ![Static Badge](https://img.shields.io/badge/Libre+OpenSSL_-blue) [![Vim](https://img.shields.io/badge/Vim-%2311AB00.svg?logo=vim&logoColor=white)](#) [![Visual Studio Code](https://custom-icon-badges.demolab.com/badge/Visual%20Studio%20Code-0078d7.svg?logo=vsc&logoColor=white)](#) -[![CI test Ubuntu](https://github.com/testssl/testssl.sh/actions/workflows/unit_tests_ubuntu.yml/badge.svg)](https://github.com/testssl/testssl.sh/actions/workflows/unit_tests_ubuntu.yml?branch=3.3dev) -[![CI test MacOS](https://github.com/testssl/testssl.sh/actions/workflows/unit_tests_macos.yml/badge.svg)](https://github.com/testssl/testssl.sh/actions/workflows/unit_tests_macos.yml?branch=3.3dev) + ![Mastodon Follow](https://img.shields.io/mastodon/follow/109319848143024146?domain=infosec.exchange) -[![Bluesky](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%2F%3Factor%3Dtestssl.bsky.social&query=%24.followersCount&style=social&logo=bluesky&label=Follow%20%40testssl.sh) +![Bluesky](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%2F%3Factor%3Dtestssl.bsky.social&query=%24.followersCount&style=social&logo=bluesky&label=Follow%20%40testssl.sh) `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 some diff --git a/doc/testssl.1 b/doc/testssl.1 index a30d23e..f0a0a58 100644 --- a/doc/testssl.1 +++ b/doc/testssl.1 @@ -1,8 +1,8 @@ -.\" Automatically generated by Pandoc 3.1.11.1 +.\" Automatically generated by Pandoc 3.7.0.2 .\" -.TH "" "" "" "" "" +.TH "" "" "" "" .SS NAME -testssl.sh \[en] check encryption of SSL/TLS servers +testssl.sh \(en check TLS/SSL encryption of servers .SS SYNOPSIS \f[CR]testssl.sh [OPTIONS] \f[R], \f[CR]testssl.sh [OPTIONS] \-\-file \f[R] @@ -11,7 +11,7 @@ or .PP \f[CR]testssl.sh [BANNER OPTIONS]\f[R] .SS DESCRIPTION -testssl.sh is a free command line tool which checks a server\[cq]s +testssl.sh is a free command line tool which checks a server\(cqs service on any port for the support of TLS/SSL ciphers, protocols as well as cryptographic flaws and much more. .PP @@ -25,7 +25,7 @@ properly. Only you see the result. You also can use it internally on your LAN. Except DNS lookups or unless you instruct testssl.sh to check for -revocation of certificates it doesn\[cq]t use any other hosts or even +revocation of certificates it doesn\(cqt use any other hosts or even third parties for any test. .SS REQUIREMENTS Testssl.sh is out of the box portable: it runs under any Unix\-like @@ -56,7 +56,7 @@ SSL/TLS protocol check .IP " 2)" 4 standard cipher categories .IP " 3)" 4 -server\[cq]s cipher preferences (server order?) +server\(cqs cipher preferences (server order?) .IP " 4)" 4 forward secrecy: ciphers and elliptical curves .IP " 5)" 4 @@ -78,7 +78,7 @@ scans all IPs with the specified options or using the default run \- unless specified otherwise, see \f[CR]\-\-ip\f[R], \f[CR]\-4\f[R] and \f[CR]\-6\f[R]. IPv6 connectivity is automagically checked. -If there\[cq]s noch such thing you will see a banner \f[I]Testing all +If there\(cqs noch such thing you will see a banner \f[I]Testing all \f[BI]IPv4\f[I] addresses\f[R] and all IPv6 addresses will appear in round brackets. .SS OPTIONS AND PARAMETERS @@ -145,13 +145,13 @@ You can also supply additional options which will be inherited to each child, e.g.\ When invoking \f[CR]testssl.sh \-\-wide \-\-log \-\-file \f[R] . Each single line in \f[CR]fname\f[R] is parsed upon execution. -If there\[cq]s a conflicting option and serial mass testing option is +If there\(cqs 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, likely a line won\[cq]t be scanned. +In parallel mode the mileage varies, likely a line won\(cqt be scanned. .PP -Alternatively \f[CR]fname\f[R] can be in \f[CR]nmap\f[R]\[cq]s +Alternatively \f[CR]fname\f[R] can be in \f[CR]nmap\f[R]\(cqs grep(p)able output format (\f[CR]\-oG\f[R]). Only open ports will be considered. Multiple ports per line are allowed. @@ -160,10 +160,10 @@ common practice in the internet, i.e.\ if nmap shows in its output an open port 25, automatically \f[CR]\-t smtp\f[R] 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. -This is done by an internal table which correlates nmap\[cq]s open port +This is done by an internal table which correlates nmap\(cqs open port detected to the STARTTLS/plain text decision from testssl.sh. .PP -Nmap\[cq]s output always returns IP addresses and only if there\[cq]s a +Nmap\(cqs output always returns IP addresses and only if there\(cqs 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 automatically for you. @@ -173,7 +173,7 @@ Please keep in mind that checks against an IP address might not hit the vhost you maybe were aiming at and thus it may lead to different results. .PP -A typical internal conversion to testssl.sh file format from nmap\[cq]s +A typical internal conversion to testssl.sh file format from nmap\(cqs grep(p)able format could look like: .IP .EX @@ -187,7 +187,7 @@ grep(p)able format could look like: .EE .PP Please note that \f[CR]fname\f[R] has to be in Unix format. -DOS carriage returns won\[cq]t be accepted. +DOS carriage returns won\(cqt be accepted. Instead of the command line switch the environment variable FNAME will be honored too. .PP @@ -204,7 +204,7 @@ equal \f[CR]serial\f[R] or \f[CR]parallel\f[R]. The warnings parameter determines how testssl.sh will deal with situations where user input normally will be necessary. There are two options. -\f[CR]batch\f[R] doesn\[cq]t wait for a confirming keypress when a +\f[CR]batch\f[R] doesn\(cqt wait for a confirming keypress when a client\- or server\-side problem is encountered. As of 3.0 it just then terminates the particular scan. This is automatically chosen for mass testing (\f[CR]\-\-file\f[R]). @@ -221,24 +221,24 @@ The same can be achieved by setting the environment variable \f[CR]\-\-socket\-timeout \f[R] This is useful for socket TCP connections to a node. If the node does not complete a TCP handshake (e.g.\ because it is down -or behind a firewall or there\[cq]s an IDS or a tarpit) testssl.sh may +or behind a firewall or there\(cqs an IDS or a tarpit) testssl.sh may usually hang for around 2 minutes or even much more. This parameter instructs testssl.sh to wait at most \f[CR]seconds\f[R] for the handshake to complete before giving up. This option only works if your OS has a timeout binary installed. SOCKET_TIMEOUT is the corresponding environment variable. -This doesn\[cq]t work on Macs out of the box. +This doesn\(cqt work on Macs out of the box. .PP \f[CR]\-\-openssl\-timeout \f[R] This is especially useful for all connects using openssl and practically useful for mass testing. -It avoids the openssl connect to hang for \[ti]2 minutes. +It avoids the openssl connect to hang for \(ti2 minutes. The expected parameter \f[CR]seconds\f[R] instructs testssl.sh to wait before the openssl connect will be terminated. The option is only available if your OS has a timeout binary installed. As there are different implementations of \f[CR]timeout\f[R]: It automatically calls the binary with the right parameters. OPENSSL_TIMEOUT is the equivalent environment variable. -This doesn\[cq]t work on Macs out of the box. +This doesn\(cqt work on Macs out of the box. .PP \f[CR]\-\-basicauth \f[R] This can be set to provide HTTP basic auth credentials which are used during checks for security @@ -250,7 +250,7 @@ HTTP request headers in the correct format \f[CR]Headername: headercontent\f[R]. This parameter can be called multiple times if required. For example: -\f[CR]\-\-reqheader \[aq]Proxy\-Authorization: Basic dGVzdHNzbDpydWxlcw==\[aq] \-\-reqheader \[aq]ClientID: 0xDEADBEAF\[aq]\f[R]. +\f[CR]\-\-reqheader \(aqProxy\-Authorization: Basic dGVzdHNzbDpydWxlcw==\(aq \-\-reqheader \(aqClientID: 0xDEADBEAF\(aq\f[R]. REQHEADER is the corresponding environment variable. .PP \f[CR]\-\-mtls \f[R] This can be set to provide a @@ -268,7 +268,7 @@ against a STARTTLS enabled \f[CR]protocol\f[R]. \f[CR]mysql\f[R]. For the latter four you need e.g.\ the supplied OpenSSL or OpenSSL version 1.1.1. -Please note: MongoDB doesn\[cq]t offer a STARTTLS connection, IRC +Please note: MongoDB doesn\(cqt offer a STARTTLS connection, IRC currently only works with \f[CR]\-\-ssl\-native\f[R]. \f[CR]irc\f[R] is WIP. .PP @@ -292,7 +292,7 @@ the supplied hostname to a different IP, similar as if you would edit \f[CR]/c/Windows/System32/drivers/etc/hosts\f[R]. \f[CR]\-\-ip=proxy\f[R] tries a DNS resolution via proxy. \f[CR]\-\-ip=proxy\f[R] plus \f[CR]\-\-nodns=min\f[R] is useful for -situations with no local DNS as there\[cq]ll be no DNS timeouts when +situations with no local DNS as there\(cqll be no DNS timeouts when trying to resolve CAA, TXT and MX records. .PP \f[CR]\-\-proxy :\f[R] does ANY check via the specified @@ -310,7 +310,7 @@ In addition if you want lookups via proxy you can specify OCSP revocation checking (\f[CR]\-S \-\-phone\-out\f[R]) is not supported by OpenSSL via proxy. As supplying a proxy is an indicator for port 80 and 443 outgoing being -blocked in your network an OCSP revocation check won\[cq]t be performed. +blocked in your network an OCSP revocation check won\(cqt be performed. However if \f[CR]IGN_OCSP_PROXY=true\f[R] has been supplied it will be tried directly. Authentication to the proxy is not supported, also no HTTPS or SOCKS @@ -321,12 +321,12 @@ Besides the OpenSSL binary supplied IPv6 is known to work with vanilla OpenSSL >= 1.1.0 and older versions >=1.0.2 in RHEL/CentOS/FC and Gentoo. Scans are somewhat in line with tools like curl or wget, i.e.\ if -there\[cq]s an IPv6 address of the target which can be reached, it just +there\(cqs an IPv6 address of the target which can be reached, it just uses them. -If you don\[cq]t want this behavior, you need to supply \f[CR]\-4.\f[R] +If you don\(cqt want this behavior, you need to supply \f[CR]\-4.\f[R] .PP \f[CR]\-4\f[R] scans only IPv4 addresses of the target, IPv6 addresses -of the target won\[cq]t be scanned. +of the target won\(cqt be scanned. .PP \f[CR]\-\-ssl\-native\f[R] Instead of using a mixture of bash sockets and a few openssl s_client connects, testssl.sh uses the latter (almost) @@ -345,7 +345,7 @@ provided by your openssl binary. \f[CR]\-\-openssl \f[R] testssl.sh tries first very hard to find 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\[cq]t work it falls back to openssl supplied from the +If all that doesn\(cqt work it falls back to openssl supplied from the OS (\f[CR]$PATH\f[R]). With this option you can point testssl.sh to your binary of choice and override any internal magic to find the openssl binary. @@ -361,7 +361,7 @@ version. for old F5 devices. The option is passed as \f[CR]\-bug\f[R] to openssl when needed, see \f[CR]s_client(1)\f[R], environment preset via -\f[CR]BUGS=\[dq]\-bugs\[dq]\f[R] (1x dash). +\f[CR]BUGS=\(dq\-bugs\(dq\f[R] (1x dash). For the socket part testssl.sh has always workarounds in place to cope with broken server implementations. .PP @@ -384,21 +384,21 @@ to a DNS name. \f[CR]none\f[R] performs no DNS lookups at all. For the latter you either have to supply the IP address as a target, to use \f[CR]\-\-ip\f[R] or have the IP address in \f[CR]/etc/hosts\f[R]. -The use of the switch is only useful if you either can\[cq]t or are not +The use of the switch is only useful if you either can\(cqt or are not willing to perform DNS lookups. The latter can apply e.g.\ to some pentests. In general this option could e.g.\ help you to avoid timeouts by DNS lookups. \f[CR]NODNS\f[R] is the environment variable for this. \f[CR]\-\-nodns=min\f[R] plus \f[CR]\-\-ip=proxy\f[R] is useful for -situations with no local DNS as there\[cq]ll be no DNS timeouts when +situations with no local DNS as there\(cqll be no DNS timeouts when trying to resolve CAA, TXT and MX records. .PP \f[CR]\-\-sneaky\f[R] For HTTP header checks testssl.sh uses normally the server friendly HTTP user agent \f[CR]TLS tester from ${URL}\f[R]. With this option your traces are less verbose and a Firefox user agent is being used. -Be aware that it doesn\[cq]t hide your activities. +Be aware that it doesn\(cqt hide your activities. That is just not possible (environment preset via \f[CR]SNEAKY=true\f[R]). .PP @@ -417,13 +417,14 @@ can try to apply evasion techniques by changing the variables USLEEP_SND and / or USLEEP_REC and maybe MAX_WAITSOCK. .PP \f[CR]\-\-phone\-out\f[R] Checking for revoked certificates via CRL and -OCSP is not done per default. -This switch instructs testssl.sh to query external \[en] in a sense of -the current run \[en] URIs. +OCSP, as well as the HSTS preload list status via hstspreload.org, is +not done per default. +This switch instructs testssl.sh to query external \(en in a sense of +the current run \(en URIs. By using this switch you acknowledge that the check might have privacy issues, a download of several megabytes (CRL file) may happen and there may be network connectivity problems while contacting the endpoint which -testssl.sh doesn\[cq]t handle. +testssl.sh doesn\(cqt handle. PHONE_OUT is the environment variable for this which needs to be set to true if you want this. .PP @@ -457,7 +458,7 @@ Per default it lists the following parameters: \f[CR]hexcode\f[R], Please note the \f[CR]\-\-mapping\f[R] parameter changes what cipher suite names you will see here and at which position. Also please note that the \f[B]bit\f[R] length for the encryption is -shown and not the \f[B]security\f[R] length, albeit it\[cq]ll be sorted +shown and not the \f[B]security\f[R] length, albeit it\(cqll be sorted by the latter. For 3DES due to the Meet\-in\-the\-Middle problem the bit size of 168 bits is equivalent to the security size of 112 bits. @@ -474,33 +475,33 @@ though. suites / cipher categories by strength. (\f[CR]\-\-standard\f[R] is deprecated.) Those lists are (\f[CR]openssl ciphers $LIST\f[R], $LIST from below:) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]NULL encryption ciphers\f[R]: `NULL:eNULL' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]Anonymous NULL ciphers\f[R]: `aNULL:ADH' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]Export ciphers\f[R] (w/o the preceding ones): `EXPORT:!ADH:!NULL' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]LOW\f[R] (64 Bit + DES ciphers, without EXPORT ciphers): `LOW:DES:RC2:RC4:MD5:!ADH:!EXP:!NULL:!eNULL:!AECDH' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]3DES + IDEA ciphers\f[R]: `3DES:IDEA:!aNULL:!ADH:!MD5' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]Obsoleted CBC ciphers\f[R]: `HIGH:MEDIUM:AES:CAMELLIA:ARIA:!IDEA:!CHACHA20:!3DES:!RC2:!RC4:!AESCCM8:!AESCCM:!AESGCM:!ARIAGCM:!aNULL:!MD5' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]Strong ciphers with no FS\f[R] (AEAD): `AESGCM:CHACHA20:CamelliaGCM:AESCCM:ARIAGCM:!kEECDH:!kEDH:!kDHE:!kDHEPSK:!kECDHEPSK:!aNULL' -.IP \[bu] 2 +.IP \(bu 2 \f[CR]Forward Secrecy strong ciphers\f[R] (AEAD): `AESGCM:CHACHA20:CamelliaGCM:AESCCM:ARIAGCM:!kPSK:!kRSAPSK:!kRSA:!kDH:!kECDH:!aNULL' .PP \f[CR]\-f, \-\-fs, \-\-nsa, \-\-forward\-secrecy\f[R] Checks robust forward secrecy key exchange. -\[lq]Robust\[rq] means that ciphers having intrinsic severe weaknesses -like Null Authentication or Encryption, 3DES and RC4 won\[cq]t be +\(lqRobust\(rq means that ciphers having intrinsic severe weaknesses +like Null Authentication or Encryption, 3DES and RC4 won\(cqt be considered here. -There shouldn\[cq]t be the wrong impression that a secure key exchange +There shouldn\(cqt be the wrong impression that a secure key exchange has been taking place and everything is fine when in reality the encryption sucks. Also this section lists the available elliptical curves and Diffie @@ -522,54 +523,54 @@ Also this will be tried for the QUIC check. \f[CR]\-P, \-\-server\-preference, \-\-preference\f[R] displays the servers preferences: cipher order, with used openssl client: negotiated protocol and cipher. -If there\[cq]s a cipher order enforced by the server it displays it for +If there\(cqs a cipher order enforced by the server it displays it for each protocol (openssl+sockets). -If there\[cq]s not, it displays instead which ciphers from the server +If there\(cqs not, it displays instead which ciphers from the server were picked with each protocol. .PP \f[CR]\-S, \-\-server_defaults\f[R] displays information from the server hello(s): -.IP \[bu] 2 +.IP \(bu 2 Available TLS extensions, -.IP \[bu] 2 +.IP \(bu 2 TLS ticket + session ID information/capabilities, -.IP \[bu] 2 +.IP \(bu 2 session resumption capabilities, -.IP \[bu] 2 +.IP \(bu 2 TLS 1.3 early data, a.k.a 0\-RTT -.IP \[bu] 2 +.IP \(bu 2 Time skew relative to localhost (most server implementations return random values). -.IP \[bu] 2 +.IP \(bu 2 Several certificate information .RS 2 -.IP \[bu] 2 +.IP \(bu 2 signature algorithm, -.IP \[bu] 2 +.IP \(bu 2 key size, -.IP \[bu] 2 +.IP \(bu 2 key usage and extended key usage, -.IP \[bu] 2 +.IP \(bu 2 fingerprints and serial -.IP \[bu] 2 +.IP \(bu 2 Common Name (CN), Subject Alternative Name (SAN), Issuer, -.IP \[bu] 2 +.IP \(bu 2 Trust via hostname + chain of trust against supplied certificates -.IP \[bu] 2 +.IP \(bu 2 EV certificate detection -.IP \[bu] 2 -experimental \[lq]eTLS\[rq] detection -.IP \[bu] 2 +.IP \(bu 2 +experimental \(lqeTLS\(rq detection +.IP \(bu 2 validity: start + end time, how many days to go (warning for certificate lifetime >=5 years) -.IP \[bu] 2 +.IP \(bu 2 revocation info (CRL, OCSP, OCSP stapling + must staple). When \f[CR]\-\-phone\-out\f[R] supplied it checks against the certificate issuer whether the host certificate has been revoked (plain OCSP, CRL). -.IP \[bu] 2 +.IP \(bu 2 displaying DNS Certification Authority Authorization resource record -.IP \[bu] 2 +.IP \(bu 2 Certificate Transparency info (if provided by server). .RE .PP @@ -590,7 +591,7 @@ client. Only a few TLS stacks nowadays still support this and return the local clock \f[CR]gmt_unix_time\f[R], e.g.\ IIS, openssl < 1.0.1f. In addition to the HTTP date you could e.g.\ derive that there are -different hosts where your TLS and your HTTP request ended \[en] if the +different hosts where your TLS and your HTTP request ended \(en if the time deltas differ significantly. .PP \f[CR]\-x , \-\-single\-cipher \f[R] tests matched @@ -601,29 +602,33 @@ above about matching. \f[CR]\-h, \-\-header, \-\-headers\f[R] if the service is HTTP (either by detection or by enforcing via \f[CR]\-\-assume\-http\f[R]. It tests several HTTP headers like -.IP \[bu] 2 +.IP \(bu 2 HTTP Strict Transport Security (HSTS) -.IP \[bu] 2 +.RS 2 +.IP \(bu 2 +HSTS preload list status (when \f[CR]\-\-phone\-out\f[R] supplied) +.RE +.IP \(bu 2 HTTP Public Key Pinning (HPKP) -.IP \[bu] 2 +.IP \(bu 2 Server banner -.IP \[bu] 2 +.IP \(bu 2 HTTP date+time -.IP \[bu] 2 +.IP \(bu 2 Server banner like Linux or other Unix vendor headers -.IP \[bu] 2 +.IP \(bu 2 Application banner (PHP, RoR, OWA, SharePoint, Wordpress, etc) -.IP \[bu] 2 +.IP \(bu 2 Reverse proxy headers -.IP \[bu] 2 +.IP \(bu 2 Web server modules -.IP \[bu] 2 +.IP \(bu 2 IPv4 address in header -.IP \[bu] 2 +.IP \(bu 2 Cookie (including Secure/HTTPOnly flags) -.IP \[bu] 2 +.IP \(bu 2 Decodes BIG IP F5 non\-encrypted cookies -.IP \[bu] 2 +.IP \(bu 2 Security headers (X\-Frame\-Options, X\-XSS\-Protection, Expect\-CT,\&... , CSP headers). @@ -633,7 +638,7 @@ Nonsense is not yet detected here. number of standard clients so that you can figure out which client cannot or can connect to your site. For the latter case the protocol, cipher and curve is displayed, also if -there\[cq]s Forward Secrecy. +there\(cqs Forward Secrecy. testssl.sh uses a handselected set of clients which are retrieved by the SSLlabs API. The output is aligned in columns when combined with the @@ -643,14 +648,14 @@ variable ALL_CLIENTS. .PP \f[CR]\-g, \-\-grease\f[R] checks several server implementation bugs like tolerance to size limitations and GREASE, see RFC 8701. -This check doesn\[cq]t run per default. +This check doesn\(cqt run per default. .SS VULNERABILITIES \f[CR]\-U, \-\-vulnerable, \-\-vulnerabilities\f[R] Just tests all (of the following) vulnerabilities. .PP \f[CR]\-H, \-\-heartbleed\f[R] Checks for Heartbleed, a memory leakage in openssl. -Unless the server side doesn\[cq]t support the heartbeat extension it is +Unless the server side doesn\(cqt support the heartbeat extension it is likely that this check runs into a timeout. The seconds to wait for a reply can be adjusted with \f[CR]HEARTBLEED_MAX_WAITSOCK\f[R]. @@ -669,7 +674,7 @@ BigIP loadbalancers. vulnerability named Opossum. .PP \f[CR]\-\-BB, \-\-robot\f[R] Checks for vulnerability to ROBOT / -(\f[I]Return Of Bleichenbacher\[cq]s Oracle Threat\f[R]) attack. +(\f[I]Return Of Bleichenbacher\(cqs Oracle Threat\f[R]) attack. The predefined timeout of 5 seconds can be changed with the environment variable \f[CR]ROBOT_TIMEOUT\f[R]. .PP @@ -678,7 +683,7 @@ vulnerabilities (SMTP, IMAP, POP3 only). \f[CR]socat\f[R] and OpenSSL >=1.1.0 is needed. .PP \f[CR]\-R, \-\-renegotiation\f[R] Tests renegotiation vulnerabilities. -Currently there\[cq]s a check for \f[I]Secure Renegotiation\f[R] and for +Currently there\(cqs a check for \f[I]Secure Renegotiation\f[R] and for \f[I]Secure Client\-Initiated Renegotiation\f[R]. Please be aware that vulnerable servers to the latter can likely be DoSed very easily (HTTP). @@ -693,9 +698,9 @@ CRIME in SPDY is not yet being checked for. Reconnaissance and Exfiltration via Adaptive Compression of Hypertext\f[R]) vulnerability. As for this vulnerability HTTP level compression is a prerequisite -it\[cq]ll be not tested if HTTP cannot be detected or the detection is +it\(cqll be not tested if HTTP cannot be detected or the detection is not enforced via \f[CR]\-\-assume\-http\f[R]. -Please note that only the URL supplied (normally \[lq]/\[rq] ) is being +Please note that only the URL supplied (normally \(lq/\(rq ) is being tested. .PP \f[CR]\-O, \-\-poodle\f[R] Tests for SSL POODLE (\f[I]Padding Oracle On @@ -718,12 +723,12 @@ RSA Export Keys\f[R]) by testing for EXPORT RSA ciphers checking whether the SSL 2 protocol is available at the target. Please note that if you use the same RSA certificate elsewhere you might be vulnerable too. -testssl.sh doesn\[cq]t check for this but provides a helpful link \[at] +testssl.sh doesn\(cqt check for this but provides a helpful link \(at censys.io which provides this service. .PP \f[CR]\-J, \-\-logjam\f[R] Checks for LOGJAM vulnerability by checking for DH EXPORT ciphers. -It also checks for \[lq]common primes\[rq] which are preconfigured DH +It also checks for \(lqcommon primes\(rq which are preconfigured DH keys. DH keys =< 1024 Bit will be penalized. Also FFDHE groups (TLS 1.2) will be displayed here. @@ -748,7 +753,7 @@ This option suppresses it. Please note that by choosing this option you acknowledge usage terms and the warning normally appearing in the banner. .PP -\f[CR]\-\-wide\f[R] Except the \[lq]each cipher output\[rq] all tests +\f[CR]\-\-wide\f[R] Except the \(lqeach cipher output\(rq all tests displays the single cipher name (scheme see below). This option enables testssl.sh to display also for the following sections the same output as for testing each ciphers: BEAST, FS, RC4. @@ -758,25 +763,25 @@ proper headline. The environment variable \f[CR]WIDE\f[R] can be used instead. .PP \f[CR]\-\-mapping \f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]openssl\f[R]: use the OpenSSL cipher suite name as the primary name cipher suite name form (default), -.IP \[bu] 2 +.IP \(bu 2 \f[CR]iana\f[R]: use the IANA cipher suite name as the primary name cipher suite name form. -.IP \[bu] 2 -\f[CR]no\-openssl\f[R]: don\[cq]t display the OpenSSL cipher suite name, +.IP \(bu 2 +\f[CR]no\-openssl\f[R]: don\(cqt display the OpenSSL cipher suite name, display IANA names only. -.IP \[bu] 2 -\f[CR]no\-iana\f[R]: don\[cq]t display the IANA cipher suite name, +.IP \(bu 2 +\f[CR]no\-iana\f[R]: don\(cqt display the IANA cipher suite name, display OpenSSL names only. .PP Please note that in testssl.sh 3.0 you can still use \f[CR]rfc\f[R] instead of \f[CR]iana\f[R] and \f[CR]no\-rfc\f[R] instead of -\f[CR]no\-iana\f[R] but it\[cq]ll disappear after 3.0. +\f[CR]no\-iana\f[R] but it\(cqll disappear after 3.0. .PP \f[CR]\-\-show\-each\f[R] This is an option for all wide modes only: it -displays all ciphers tested \[en] not only succeeded ones. +displays all ciphers tested \(en not only succeeded ones. \f[CR]SHOW_EACH_C\f[R] is your friend if you prefer to set this via the shell environment. .PP @@ -812,7 +817,7 @@ screen output normal but leaves useful debug output in The info about the exact directory is included in the screen output in the end of the run. .IP "2." 3 -lists more what\[cq]s going on, status (high level) and connection +lists more what\(cqs going on, status (high level) and connection errors, a few general debug output .IP "3." 3 even slightly more info: hexdumps + other info @@ -834,8 +839,8 @@ directory of the shell. Depending on the color output option (see above) the output file will contain color and other markup escape codes, unless you specify \f[CR]\-\-color 0\f[R] too. -\f[CR]cat\f[R] and \[en] if properly configured \f[CR]less\f[R] \[en] -will show the output properly formatted on your terminal. +\f[CR]cat\f[R] and \(en if properly configured \f[CR]less\f[R] \(en will +show the output properly formatted on your terminal. The output shows a banner with the almost the same information as on the screen. In addition it shows the command line of the testssl.sh instance. @@ -860,11 +865,11 @@ You can override the width with the environment variable TERM_WIDTH. \f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.json\f[R] in the current working directory of the shell. The resulting JSON file is opposed to \f[CR]\-\-json\-pretty\f[R] flat -\[en] which means each section is self contained and has an identifier +\(en which means each section is self contained and has an identifier for each single check, the hostname/IP address, the port, severity and the finding. For vulnerabilities it may contain a CVE and CWE entry too. -The output doesn\[cq]t contain a banner or a footer. +The output doesn\(cqt contain a banner or a footer. .PP \f[CR]\-\-jsonfile \f[R] or \f[CR]\-oj \f[R] Instead of the previous option you may want to use this one if you want to log @@ -878,8 +883,8 @@ path is also permitted here. \f[CR]\-\-json\-pretty\f[R] Logs additionally to JSON file \f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.json\f[R] in the current working directory of the shell. -The resulting JSON file is opposed to \f[CR]\-\-json\f[R] non\-flat -\[en] which means it is structured. +The resulting JSON file is opposed to \f[CR]\-\-json\f[R] non\-flat \(en +which means it is structured. The structure contains a header similar to the banner on the screen, including the command line, scan host, openssl binary used, testssl version and epoch of the start time. @@ -916,7 +921,7 @@ For further explanation see \f[CR]\-\-jsonfile\f[R] or \f[CR]${NODE}\-p${port}${YYYYMMDD\-HHMM}.html\f[R] in the current working directory of the shell. It contains a 1:1 output of the console. -In former versions there was a non\-native option to use \[lq]aha\[rq] +In former versions there was a non\-native option to use \(lqaha\(rq (Ansi HTML Adapter: github.com/theZiz/aha) like \f[CR]testssl.sh [options] | aha >output.html\f[R]. This is not necessary anymore. @@ -961,7 +966,7 @@ remove the file and exit with an error. header. The environment variable APPEND does the same. Be careful using this switch/variable. -A complementary option which overwrites an existing file doesn\[cq]t +A complementary option which overwrites an existing file doesn\(cqt exist per design. .PP \f[CR]\-\-overwrite\f[R] Normally, if an output file already exists and @@ -978,7 +983,7 @@ Using this any output files will be named \f[CR]\-${NODE}\-p${port}${YYYYMMDD\-HHMM}.\f[R] when no file name of the respective output option was specified. If you do not like the separator `\-' you can as well supply a -\f[CR]\f[R] ending in `.', \[cq]_\[cq] or `,'. +\f[CR]\f[R] ending in `.', \(cq_\(cq or `,'. In this case or if you already supplied `\-' no additional `\-' will be appended to \f[CR]\f[R]. .PP @@ -986,49 +991,49 @@ A few file output options can also be preset via environment variables. .SS COLOR RATINGS Testssl.sh makes use of (the eight) standard terminal colors. The color scheme is as follows: -.IP \[bu] 2 +.IP \(bu 2 light red: a critical finding -.IP \[bu] 2 +.IP \(bu 2 red: a high finding -.IP \[bu] 2 +.IP \(bu 2 brown: a medium finding -.IP \[bu] 2 +.IP \(bu 2 yellow: a low finding -.IP \[bu] 2 +.IP \(bu 2 green (blue if COLORBLIND is set): something which is either in general a good thing or a negative result of a check which otherwise results in a high finding -.IP \[bu] 2 +.IP \(bu 2 light green (light blue if COLORBLIND is set) : something which is either in general a very good thing or a negative result of a check which otherwise results in a critical finding -.IP \[bu] 2 +.IP \(bu 2 no color at places where also a finding can be expected: a finding on an info level -.IP \[bu] 2 +.IP \(bu 2 cyan: currently only used for \f[CR]\-\-show\-each\f[R] or an additional hint -.IP \[bu] 2 +.IP \(bu 2 magenta: signals a warning condition, e.g.\ either a local lack of capabilities on the client side or another problem -.IP \[bu] 2 +.IP \(bu 2 light magenta: a fatal error which either requires strict consent from the user to continue or a condition which leaves no other choice for testssl.sh to quit .PP -What is labeled as \[lq]light\[rq] above appears as such on the screen -but is technically speaking \[lq]bold\[rq]. +What is labeled as \(lqlight\(rq above appears as such on the screen but +is technically speaking \(lqbold\(rq. Besides \f[CR]\-\-color=3\f[R] will color ciphers according to an internal and rough rating. .PP Markup (without any color) is used in the following manner: -.IP \[bu] 2 +.IP \(bu 2 bold: for the name of the test -.IP \[bu] 2 +.IP \(bu 2 underline + bold: for the headline of each test section -.IP \[bu] 2 +.IP \(bu 2 underline: for a sub\-headline -.IP \[bu] 2 +.IP \(bu 2 italics: for strings just reflecting a value read from the server .SS TUNING via ENV variables and more options Except the environment variables mentioned above which can replace @@ -1036,138 +1041,149 @@ command line options here a some which cannot be set otherwise. Variables used for tuning are preset with reasonable values. \f[I]There should be no reason to change them\f[R] unless you use testssl.sh under special conditions. -.IP \[bu] 2 +.IP \(bu 2 TERM_WIDTH is a variable which overrides the auto\-determined terminal width size. Setting this variable normally only makes sense if you log the output to a file using the \f[CR]\-\-log\f[R], \f[CR]\-\-logfile\f[R] or \f[CR]\-oL\f[R] option. -.IP \[bu] 2 +.IP \(bu 2 DEBUG_ALLINONE / SETX: when setting one of those to true testssl.sh falls back to the standard bash behavior, i.e.\ calling \f[CR]bash \-x testssl.sh\f[R] it displays the bash debugging output not in an external file \f[CR]/tmp/testssl\-.log\f[R] -.IP \[bu] 2 +.IP \(bu 2 DEBUGTIME: Profiling option. -When using bash\[cq]s debug mode and when this is set to true, it +When using bash\(cqs debug mode and when this is set to true, it generates a separate text file with epoch times in \f[CR]/tmp/testssl\-.time\f[R]. They need to be concatenated by -\f[CR]paste /tmp/testssl\-.{time,log}\f[R] -.IP \[bu] 2 +\f[CR]paste /tmp/testssl\-.{time,log}\f[R] +.IP \(bu 2 EXPERIMENTAL=true is an option which is sometimes used in the development process to make testing easier. In released versions this has no effect. -.IP \[bu] 2 +.IP \(bu 2 ALL_CLIENTS=true runs a client simulation with \f[I]all\f[R] (currently 126) clients when testing HTTP. -.IP \[bu] 2 +.IP \(bu 2 UNBRACKTD_IPV6: needs to be set to true for some old versions of OpenSSL -(like from Gentoo) which don\[cq]t support [bracketed] IPv6 addresses -.IP \[bu] 2 +(like from Gentoo) which don\(cqt support [bracketed] IPv6 addresses +.IP \(bu 2 NO_ENGINE: if you have problems with garbled output containing the word `engine' you might want to set this to true. -It forces testssl.sh not try to configure openssl\[cq]s engine or a non +It forces testssl.sh not try to configure openssl\(cqs engine or a non existing one from libressl -.IP \[bu] 2 +.IP \(bu 2 HEADER_MAXSLEEP: To wait how long before killing the process to retrieve a service banner / HTTP header -.IP \[bu] 2 +.IP \(bu 2 MAX_WAITSOCK: It instructs testssl.sh to wait until the specified time before declaring a socket connection dead. -Don\[cq]t change this unless you\[cq]re absolutely sure what you\[cq]re +Don\(cqt change this unless you\(cqre absolutely sure what you\(cqre doing. Value is in seconds. -.IP \[bu] 2 +.IP \(bu 2 CCS_MAX_WAITSOCK Is the similar to above but applies only to the CCS handshakes, for both of the two the two CCS payload. -Don\[cq]t change this unless you\[cq]re absolutely sure what you\[cq]re +Don\(cqt change this unless you\(cqre absolutely sure what you\(cqre doing. Value is in seconds. -.IP \[bu] 2 +.IP \(bu 2 HEARTBLEED_MAX_WAITSOCK Is the similar to MAX_WAITSOCK but applies only to the ServerHello after sending the Heartbleed payload. -Don\[cq]t change this unless you\[cq]re absolutely sure what you\[cq]re +Don\(cqt change this unless you\(cqre absolutely sure what you\(cqre doing. Value is in seconds. -.IP \[bu] 2 +.IP \(bu 2 ROBOT_TIMEOUT is similar to above and applies to the ROBOT check. -.IP \[bu] 2 -MEASURE_TIME_FILE For seldom cases when you don\[cq]t want the scan time +.IP \(bu 2 +MEASURE_TIME_FILE For seldom cases when you don\(cqt want the scan time to be included in the output you can set this to false. -.IP \[bu] 2 +.IP \(bu 2 STARTTLS_SLEEP is per default set to 10 (seconds). -That\[cq]s the value testssl.sh waits for a string in the STARTTLS +That\(cqs the value testssl.sh waits for a string in the STARTTLS handshake before giving up. -.IP \[bu] 2 +.IP \(bu 2 MAX_PARALLEL is the maximum number of tests to run in parallel in parallel mass testing mode. The default value of 20 may be made larger on systems with faster processors. -.IP \[bu] 2 +.IP \(bu 2 MAX_WAIT_TEST is the maximum time (in seconds) to wait for a single test in parallel mass testing mode to complete. The default is 1200. -.IP \[bu] 2 + +.IP \(bu 2 HSTS_MIN is preset to 179 (days). If you want warnings sooner or later for HTTP Strict Transport Security you can change this. -.IP \[bu] 2 +.IP \(bu 2 HPKP_MIN is preset to 30 (days). If you want warnings sooner or later for HTTP Public Key Pinning you can change this -.IP \[bu] 2 -DAYS2WARN1 is the first threshold when you\[cq]ll be warning of a +.IP \(bu 2 +DAYS2WARN1 is the first threshold when you\(cqll be warning of a certificate expiration of a host, preset to 60 (days). -For Let\[cq]s Encrypt this value will be divided internally by 2. -.IP \[bu] 2 -DAYS2WARN2 is the second threshold when you\[cq]ll be warning of a +For Let\(cqs Encrypt this value will be divided internally by 2. +.IP \(bu 2 +DAYS2WARN2 is the second threshold when you\(cqll be warning of a certificate expiration of a host, preset to 30 (days). -For Let\[cq]s Encrypt this value will be divided internally by 2. -.IP \[bu] 2 +For Let\(cqs Encrypt this value will be divided internally by 2. +.IP \(bu 2 TESTSSL_INSTALL_DIR is the derived installation directory of testssl.sh. Relatively to that the \f[CR]bin\f[R] and mandatory \f[CR]etc\f[R] directory will be looked for. -.IP \[bu] 2 +.IP \(bu 2 CA_BUNDLES_PATH: If you have an own set of CA bundles or you want to point testssl.sh to a specific location of a CA bundle, you can use this variable to set the directory which testssl.sh will use. Please note that it overrides completely the builtin path of testssl.sh which means that you will only test against the bundles you point to. -Also you might want to use \f[CR]\[ti]/utils/create_ca_hashes.sh\f[R] to +Also you might want to use \f[CR]\(ti/utils/create_ca_hashes.sh\f[R] to create the hashes for HPKP. -.IP \[bu] 2 +.IP \(bu 2 MAX_SOCKET_FAIL: A number which tells testssl.sh how often a TCP socket connection may fail before the program gives up and terminates. The default is 2. You can increase it to a higher value if you frequently see a message like \f[I]Fatal error: repeated TCP connect problems, giving up\f[R]. -.IP \[bu] 2 +.IP \(bu 2 MAX_OSSL_FAIL: A number which tells testssl.sh how often an OpenSSL s_client connect may fail before the program gives up and terminates. The default is 2. You can increase it to a higher value if you frequently see a message like \f[I]Fatal error: repeated openssl s_client connect problem, -doesn\[cq]t make sense to continue\f[R]. -.IP \[bu] 2 +doesn\(cqt make sense to continue\f[R]. +.IP \(bu 2 MAX_HEADER_FAIL: A number which tells testssl.sh how often a HTTP GET request over OpenSSL may return an empty file before the program gives up and terminates. The default is 3. Also here you can increase the threshold when you spot messages like -\f[I]Fatal error: repeated HTTP header connect problems, doesn\[cq]t -make sense to continue\f[R]. -.IP \[bu] 2 +\f[I]Fatal error: repeated HTTP header connect problems, doesn\(cqt make +sense to continue\f[R]. +.IP \(bu 2 OPENSSL2 can be used to supply an alternative openssl version. This only makes sense if you want to amend the supplied version in \f[CR]bin/\f[R] which lacks TLS 1.3 support with a version which doesn not and is not in \f[CR]/usr/bin/openssl\f[R]. -.IP \[bu] 2 +.IP \(bu 2 OSSL_SHORTCUT should be set to false when you run interactively and -don\[cq]t want to switch automatically to \f[CR]/usr/bin/openssl\f[R] +don\(cqt want to switch automatically to \f[CR]/usr/bin/openssl\f[R] (\f[CR]OPENSSL2\f[R]) if you encounter a TLS 1.3\-only host. .SS RATING -This program has a near\-complete implementation of SSL Labs\[cq]s `\c +This program has a near\-complete implementation of SSL Labs\(cqs `\c .UR https://github.com/ssllabs/research/wiki/SSL-Server-Rating-Guide SSL Server Rating Guide .UE \c @@ -1175,7 +1191,7 @@ SSL Server Rating Guide .PP This is \f[I]not\f[R] a 100% reimplementation of the \c .UR https://www.ssllabs.com/ssltest/analyze.html -SSL Lab\[cq]s SSL Server Test +SSL Lab\(cqs SSL Server Test .UE \c , but an implementation of the above rating specification, slight discrepancies may occur. @@ -1186,7 +1202,7 @@ Before filing issues please inspect their Rating Guide. .PP Disclaimer: Having a good grade is \f[B]NOT\f[R] necessarily equal to having good security! -Don\[cq]t start a competition for the best grade, at least not without +Don\(cqt start a competition for the best grade, at least not without monitoring the client handshakes and not without adding a portion of good sense to it. Please note STARTTLS always results in a grade cap to T. Anything else @@ -1198,33 +1214,33 @@ Also with DANE or MTA\-STS no one can test on the server side whether a client makes use if it. .PP As of writing, these checks are missing: -.IP \[bu] 2 +.IP \(bu 2 GOLDENDOODLE \- should be graded \f[B]F\f[R] if vulnerable -.IP \[bu] 2 +.IP \(bu 2 Insecure renegotiation \- should be graded \f[B]F\f[R] if vulnerable -.IP \[bu] 2 +.IP \(bu 2 Padding oracle in AES\-NI CBC MAC check (CVE\-2016\-2107) \- should be graded \f[B]F\f[R] if vulnerable -.IP \[bu] 2 +.IP \(bu 2 Sleeping POODLE \- should be graded \f[B]F\f[R] if vulnerable -.IP \[bu] 2 +.IP \(bu 2 Zero Length Padding Oracle (CVE\-2019\-1559) \- should be graded \f[B]F\f[R] if vulnerable -.IP \[bu] 2 +.IP \(bu 2 Zombie POODLE \- should be graded \f[B]F\f[R] if vulnerable -.IP \[bu] 2 +.IP \(bu 2 All remaining old Symantec PKI certificates are distrusted \- should be graded \f[B]T\f[R] -.IP \[bu] 2 +.IP \(bu 2 Symantec certificates issued before June 2016 are distrusted \- should be graded \f[B]T\f[R] -.IP \[bu] 2 +.IP \(bu 2 Anonymous key exchange \- should give \f[B]0\f[R] points in \f[CR]set_key_str_score()\f[R] -.IP \[bu] 2 +.IP \(bu 2 Exportable key exchange \- should give \f[B]40\f[R] points in \f[CR]set_key_str_score()\f[R] -.IP \[bu] 2 +.IP \(bu 2 Weak key (Debian OpenSSL Flaw) \- should give \f[B]0\f[R] points in \f[CR]set_key_str_score()\f[R] .SS Implementing new grades caps or \-warnings @@ -1232,14 +1248,14 @@ To implement a new grading cap, simply call the \f[CR]set_grade_cap()\f[R] function, with the grade and a reason: .IP .EX -set_grade_cap \[dq]D\[dq] \[dq]Vulnerable to documentation\[dq] +set_grade_cap \(dqD\(dq \(dqVulnerable to documentation\(dq .EE .PP To implement a new grade warning, simply call the \f[CR]set_grade_warning()\f[R] function, with a message: .IP .EX -set_grade_warning \[dq]Documentation is always right\[dq] +set_grade_warning \(dqDocumentation is always right\(dq .EE .SS Implementing a new check which contains grade caps When implementing a new check (be it vulnerability or not) that sets @@ -1255,7 +1271,7 @@ This is to prevent giving out a misleading or wrong grade. .SS Implementing a new revision When a new revision of the rating specification comes around, the following has to be done: -.IP \[bu] 2 +.IP \(bu 2 New grade caps has to be either: .RS 2 .IP "1." 3 @@ -1263,9 +1279,9 @@ Added to the script wherever relevant, or .IP "2." 3 Added to the above list of missing checks (if above is not possible) .RE -.IP \[bu] 2 +.IP \(bu 2 New grade warnings has to be added wherever relevant -.IP \[bu] 2 +.IP \(bu 2 The revision output in \f[CR]run_rating()\f[R] function has to updated .SS EXAMPLES .IP @@ -1274,8 +1290,8 @@ The revision output in \f[CR]run_rating()\f[R] function has to updated .EE .PP does a default run on https://testssl.sh (protocols, standard cipher -lists, server\[cq]s cipher preferences, forward secrecy, server -defaults, vulnerabilities, client simulation, and rating. +lists, server\(cqs cipher preferences, forward secrecy, server defaults, +vulnerabilities, client simulation, and rating. .IP .EX testssl.sh testssl.net:443 @@ -1297,7 +1313,7 @@ Displayed is everything where possible in wide format. testssl.sh \-6 https://testssl.net .EE .PP -As opposed to the first example it also tests the IPv6 part \[en] +As opposed to the first example it also tests the IPv6 part \(en supposed you have an IPv6 network and your openssl supports IPv6 (see above). .IP @@ -1322,135 +1338,135 @@ port. Also MongoDB which provides TLS support without STARTTLS can be tested directly. .SS RFCs and other standards -.IP \[bu] 2 +.IP \(bu 2 RFC 2246: The TLS Protocol Version 1.0 -.IP \[bu] 2 +.IP \(bu 2 RFC 2595: Using TLS with IMAP, POP3 and ACAP -.IP \[bu] 2 +.IP \(bu 2 RFC 2817: Upgrading to TLS Within HTTP/1.1 -.IP \[bu] 2 +.IP \(bu 2 RFC 2818: HTTP Over TLS -.IP \[bu] 2 +.IP \(bu 2 RFC 2830: Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security -.IP \[bu] 2 +.IP \(bu 2 RFC 3207: SMTP Service Extension for Secure SMTP over Transport Layer Security -.IP \[bu] 2 +.IP \(bu 2 RFC 3501: INTERNET MESSAGE ACCESS PROTOCOL \- VERSION 4rev1 -.IP \[bu] 2 +.IP \(bu 2 RFC 4346: The Transport Layer Security (TLS) Protocol Version 1.1 -.IP \[bu] 2 +.IP \(bu 2 RFC 4366: Transport Layer Security (TLS) Extensions -.IP \[bu] 2 +.IP \(bu 2 RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS) -.IP \[bu] 2 +.IP \(bu 2 RFC 5077: Transport Layer Security (TLS) Session Resumption -.IP \[bu] 2 +.IP \(bu 2 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 -.IP \[bu] 2 +.IP \(bu 2 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile -.IP \[bu] 2 +.IP \(bu 2 RFC 5321: Simple Mail Transfer Protocol -.IP \[bu] 2 +.IP \(bu 2 RFC 5746: Transport Layer Security (TLS) Renegotiation Indication Extension -.IP \[bu] 2 +.IP \(bu 2 RFC 5804: A Protocol for Remotely Managing Sieve Scripts -.IP \[bu] 2 +.IP \(bu 2 RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions -.IP \[bu] 2 +.IP \(bu 2 RFC 6101: The Secure Sockets Layer (SSL) Protocol Version 3.0 -.IP \[bu] 2 +.IP \(bu 2 RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core -.IP \[bu] 2 +.IP \(bu 2 RFC 6125: Domain\-Based Application Service Identity [..] -.IP \[bu] 2 +.IP \(bu 2 RFC 6797: HTTP Strict Transport Security (HSTS) -.IP \[bu] 2 +.IP \(bu 2 RFC 6961: The Transport Layer Security (TLS) Multiple Certificate Status Request Extension -.IP \[bu] 2 +.IP \(bu 2 RFC 7469: Public Key Pinning Extension for HTTP (HPKP) -.IP \[bu] 2 +.IP \(bu 2 RFC 7507: TLS Fallback Signaling Cipher Suite Value (SCSV) for Preventing Protocol Downgrade Attacks -.IP \[bu] 2 +.IP \(bu 2 RFC 7627: Transport Layer Security (TLS) Session Hash and Extended Master Secret Extension -.IP \[bu] 2 +.IP \(bu 2 RFC 7633: X.509v3 Transport Layer Security (TLS) Feature Extension -.IP \[bu] 2 +.IP \(bu 2 RFC 7465: Prohibiting RC4 Cipher Suites -.IP \[bu] 2 +.IP \(bu 2 RFC 7685: A Transport Layer Security (TLS) ClientHello Padding Extension -.IP \[bu] 2 +.IP \(bu 2 RFC 7905: ChaCha20\-Poly1305 Cipher Suites for Transport Layer Security (TLS) -.IP \[bu] 2 +.IP \(bu 2 RFC 7919: Negotiated Finite Field Diffie\-Hellman Ephemeral Parameters for Transport Layer Security -.IP \[bu] 2 +.IP \(bu 2 RFC 8143: Using Transport Layer Security (TLS) with Network News Transfer Protocol (NNTP) -.IP \[bu] 2 +.IP \(bu 2 RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3 -.IP \[bu] 2 +.IP \(bu 2 RFC 8470: Using Early Data in HTTP -.IP \[bu] 2 +.IP \(bu 2 RFC 8701: Applying Generate Random Extensions And Sustain Extensibility (GREASE) to TLS Extensibility -.IP \[bu] 2 +.IP \(bu 2 RFC 9000: QUIC: A UDP\-Based Multiplexed and Secure Transport -.IP \[bu] 2 +.IP \(bu 2 W3C CSP: Content Security Policy Level 1\-3 -.IP \[bu] 2 +.IP \(bu 2 TLSWG Draft: The Transport Layer Security (TLS) Protocol Version 1.3 -.IP \[bu] 2 +.IP \(bu 2 FIPS 203: Module\-Lattice\-Based Key\-Encapsulation Mechanism Standard .PP More RFCs might be applicable. .SS EXIT STATUS -.IP \[bu] 2 +.IP \(bu 2 0 testssl.sh finished successfully without errors and without ambiguous results -.IP \[bu] 2 +.IP \(bu 2 1 testssl.sh has encountered exactly one ambiguous situation or an error during run -.IP \[bu] 2 +.IP \(bu 2 1+n same as previous. The errors or ambiguous results are added, also per IP. -.IP \[bu] 2 +.IP \(bu 2 50\-200 reserved for returning a vulnerability scoring for system monitoring or a CI tools -.IP \[bu] 2 +.IP \(bu 2 242 (ERR_CHILD) Child received a signal from master -.IP \[bu] 2 -244 (ERR_RESOURCE) Resources testssl.sh needs couldn\[cq]t be read -.IP \[bu] 2 +.IP \(bu 2 +244 (ERR_RESOURCE) Resources testssl.sh needs couldn\(cqt be read +.IP \(bu 2 245 (ERR_CLUELESS) Weird state, either though user options or testssl.sh -.IP \[bu] 2 +.IP \(bu 2 246 (ERR_CONNECT) Connectivity problem -.IP \[bu] 2 +.IP \(bu 2 247 (ERR_DNSLOOKUP) Problem with resolving IP addresses or names -.IP \[bu] 2 +.IP \(bu 2 248 (ERR_OTHERCLIENT) Other client problem -.IP \[bu] 2 +.IP \(bu 2 249 (ERR_DNSBIN) Problem with DNS lookup binaries -.IP \[bu] 2 +.IP \(bu 2 250 (ERR_OSSLBIN) Problem with OpenSSL binary -.IP \[bu] 2 +.IP \(bu 2 251 (ERR_NOSUPPORT) Feature requested is not supported -.IP \[bu] 2 -252 (ERR_FNAMEPARSE) Input file couldn\[cq]t be parsed -.IP \[bu] 2 -253 (ERR_FCREATE) Output file couldn\[cq]t be created -.IP \[bu] 2 -254 (ERR_CMDLINE) Cmd line couldn\[cq]t be parsed -.IP \[bu] 2 +.IP \(bu 2 +252 (ERR_FNAMEPARSE) Input file couldn\(cqt be parsed +.IP \(bu 2 +253 (ERR_FCREATE) Output file couldn\(cqt be created +.IP \(bu 2 +254 (ERR_CMDLINE) Cmd line couldn\(cqt be parsed +.IP \(bu 2 255 (ERR_BASH) Bash version incorrect .SS FILES \f[B]etc/*pem\f[R] are the certificate stores from Apple, Linux, Mozilla @@ -1474,9 +1490,9 @@ the terms of the license, see LICENSE. .PP Attribution is important for the future of this project \- also in the internet. -Thus if you\[cq]re offering a scanner based on testssl.sh as a public +Thus if you\(cqre offering a scanner based on testssl.sh as a public and/or paid service in the internet you are strongly encouraged to -mention to your audience that you\[cq]re using this program and where to +mention to your audience that you\(cqre using this program and where to get this program from. That helps us to get bugfixes, other feedback and more contributions. .PP diff --git a/doc/testssl.1.html b/doc/testssl.1.html index 741e576..347a120 100644 --- a/doc/testssl.1.html +++ b/doc/testssl.1.html @@ -43,7 +43,7 @@

NAME

-

testssl.sh – check encryption of SSL/TLS servers

+

testssl.sh – check TLS/SSL encryption of servers

SYNOPSIS

testssl.sh [OPTIONS] <URI>, testssl.sh [OPTIONS] --file <FILE>

@@ -396,7 +396,8 @@ evasion techniques by changing the variables USLEEP_SND and / or USLEEP_REC and maybe MAX_WAITSOCK.

--phone-out Checking for revoked certificates - via CRL and OCSP is not done per default. This switch instructs + via CRL and OCSP, as well as the HSTS preload list status via + hstspreload.org, is not done per default. This switch instructs testssl.sh to query external – in a sense of the current run – URIs. By using this switch you acknowledge that the check might have privacy issues, a download of several megabytes (CRL file) @@ -548,7 +549,11 @@ --assume-http. It tests several HTTP headers like

    -
  • HTTP Strict Transport Security (HSTS)
    • +
  • HTTP Strict Transport Security (HSTS) +
      +
    • HSTS preload list status (when --phone-out + supplied)
      • +
  • HTTP Public Key Pinning (HPKP)
  • Server banner
  • HTTP date+time
    • @@ -921,11 +926,11 @@ and when this is set to true, it generates a separate text file with epoch times in /tmp/testssl-<XX>.time. They need to be concatenated by - paste /tmp/testssl-<XX>.{time,log} + paste /tmp/testssl-<XX>.{time,log} + <!— +
  • FAST_SOCKET
    • +
  • SHOW_SIGALGO
    • +
  • FAST –>
  • EXPERIMENTAL=true is an option which is sometimes used in the development process to make testing easier. In released versions this has no effect.
    • @@ -965,10 +970,9 @@ may be made larger on systems with faster processors.
  • MAX_WAIT_TEST is the maximum time (in seconds) to wait for a single test in parallel mass testing mode to complete. The - default is 1200.
    • + default is 1200. <!— +
  • USLEEP_SND
    • +
  • USLEEP_REC –>
  • HSTS_MIN is preset to 179 (days). If you want warnings sooner or later for HTTP Strict Transport Security you can change this.
    • diff --git a/doc/testssl.1.md b/doc/testssl.1.md index 0f0ddeb..db58e8e 100644 --- a/doc/testssl.1.md +++ b/doc/testssl.1.md @@ -1,6 +1,6 @@ ## NAME - testssl.sh -- check encryption of SSL/TLS servers + testssl.sh -- check TLS/SSL encryption of servers ## SYNOPSIS @@ -36,7 +36,7 @@ linked OpenSSL binaries for major operating systems are supplied in `./bin/`. `testssl.sh URI` as the default invocation does 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 below except `-E` which are (order of appearance): -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. +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. 1) SSL/TLS protocol check @@ -152,7 +152,7 @@ The same can be achieved by setting the environment variable `WARNINGS`. `--ids-friendly` is a switch which may help to get a scan finished which otherwise would be blocked by a server side IDS. This switch skips tests for the following vulnerabilities: Heartbleed, CCS Injection, Ticketbleed and ROBOT. The environment variable OFFENSIVE set to false will achieve the same result. Please be advised that as an alternative or as a general approach you can try to apply evasion techniques by changing the variables USLEEP_SND and / or USLEEP_REC and maybe MAX_WAITSOCK. -`--phone-out` Checking for revoked certificates via CRL and OCSP is not done per default. This switch instructs testssl.sh to query external -- in a sense of the current run -- URIs. By using this switch you acknowledge that the check might have privacy issues, a download of several megabytes (CRL file) may happen and there may be network connectivity problems while contacting the endpoint which testssl.sh doesn't handle. PHONE_OUT is the environment variable for this which needs to be set to true if you want this. +`--phone-out` Checking for revoked certificates via CRL and OCSP, as well as the HSTS preload list status via hstspreload.org, is not done per default. This switch instructs testssl.sh to query external -- in a sense of the current run -- URIs. By using this switch you acknowledge that the check might have privacy issues, a download of several megabytes (CRL file) may happen and there may be network connectivity problems while contacting the endpoint which testssl.sh doesn't handle. PHONE_OUT is the environment variable for this which needs to be set to true if you want this. `--add-ca ` enables you to add your own CA(s) in PEM format for trust chain checks. `CAfile` can be a directory containing files with a \.pem extension, a single file or multiple files as a comma separated list of root CAs. Internally they will be added during runtime to all CA stores. This is (only) useful for internal hosts whose certificates are issued by internal CAs. Alternatively ADDTL_CA_FILES is the environment variable for this. @@ -213,6 +213,7 @@ Also for multiple server certificates are being checked for as well as for the c `-h, --header, --headers` if the service is HTTP (either by detection or by enforcing via `--assume-http`. It tests several HTTP headers like * HTTP Strict Transport Security (HSTS) + - HSTS preload list status (when `--phone-out` supplied) * HTTP Public Key Pinning (HPKP) * Server banner * HTTP date+time diff --git a/t/03_debug.t.DISABLED b/t/03_debug.t.DISABLED new file mode 100755 index 0000000..4fc5214 --- /dev/null +++ b/t/03_debug.t.DISABLED @@ -0,0 +1,39 @@ +#!/usr/bin/env perl + +# Example for debugging what the runners do, here MacOS only +# (we used that before), To get output on the screen it's +# needed to encapsulate the functions you want to debug with +# set -x/+x and comment the last function @ 00_testssl_help.t + +use strict; +use Test::More; +use IPC::Run3; + +my $os="$^O"; +my $prg="./testssl.sh"; +my $check2run ="-p"; +my $uri="testssl.sh"; +my $stdout = ''; +my $stderr = ''; + +# if ( $os eq "darwin" ){ + printf "%s\n", "testing MacOS "; + run3(["/bin/bash", $prg, $check2run, $uri], \undef, \$stdout, \$stderr); + print STDERR $stderr; + print STDOUT $stdout; +# } elsif ( $os eq "linux" ){ +# printf "skipped check on Linux\n\n"; +#} + + +# Use the following when you want to run everything below ~/t +# done_testing(); + + +# This stops, no further checks within ~/t will run: +BAIL_OUT("Fundamental check done, aborting"); + + + +# vim:ts=5:sw=5:expandtab + diff --git a/t/12_diff_opensslversions.t b/t/12_diff_opensslversions.t index 9735d8e..8464133 100755 --- a/t/12_diff_opensslversions.t +++ b/t/12_diff_opensslversions.t @@ -98,6 +98,11 @@ $cat_csvfile2 =~ s/.nonce-.* //g; $cat_csvfile =~ s/","google.com\/.*","443/","google.com","443/g; $cat_csvfile2 =~ s/","google.com\/.*","443/","google.com","443/g; +# Address differences in QUIC: Ubuntu 24.04's openssl still doesn't support QUIC, MacOS 26 does +# (Status 06/2026, should be checked later) +$cat_csvfile =~ s/"QUIC".*\n//g; +$cat_csvfile2 =~ s/"QUIC".*\n//g; + if ( $os eq "darwin" ){ # Now address the differences for LibreSSL, see t/61_diff_testsslsh.t diff --git a/t/53_hsts_preload.t b/t/53_hsts_preload.t new file mode 100755 index 0000000..66a5552 --- /dev/null +++ b/t/53_hsts_preload.t @@ -0,0 +1,52 @@ +#!/usr/bin/env perl + +# Check the HSTS preload list status against the hstspreload.org API (needs --phone-out). +# github.com is on the preload list, example.com is not. +# +# We don't use a full run, only the HTTP header section. + +use strict; +use Test::More; + +my $tests = 0; +my $prg="./testssl.sh"; +my $csv="tmp.csv"; +my $cat_csv=""; +my $check2run="-q --color 0 --phone-out --ip=one --headers --csvfile $csv"; +my $uri="github.com"; +my @args=""; + +die "Unable to open $prg" unless -f $prg; + +# Provide proper start conditions +unlink $csv; + +#1 run -- a domain which is on the HSTS preload list +printf "\n%s\n", "Unit test for HSTS preload list status against \"$uri\""; +@args="$prg $check2run $uri >/dev/null"; +system("@args") == 0 + or die ("FAILED: \"@args\" "); +$cat_csv=`cat $csv`; + +# github.com is on the preload list +like($cat_csv, qr/"HSTS_preloadAPI".*"preloaded"/,"\"$uri\" should be on the HSTS preload list"); +$tests++; +unlink $csv; + +#2 run -- a domain which is NOT on the HSTS preload list +$uri="example.com"; +@args="$prg $check2run $uri >/dev/null"; +system("@args") == 0 + or die ("FAILED: \"@args\" "); +$cat_csv=`cat $csv`; + +# example.com is not on the preload list +like($cat_csv, qr/"HSTS_preloadAPI".*"no entry"/,"\"$uri\" should not be on the HSTS preload list"); +$tests++; +unlink $csv; + +done_testing($tests); +printf "\n"; + + +# vim:ts=5:sw=5:expandtab diff --git a/t/Readme.md b/t/Readme.md index bfdeac0..d517fd4 100644 --- a/t/Readme.md +++ b/t/Readme.md @@ -8,3 +8,7 @@ Please help to write CI tests! Documentation can be found [here](https://perldoc.perl.org/Test/More.html). You can consult the existing code here. Feel free to use `10_baseline_ipv4_http.t` or `12_diff_opensslversions.t` as a template. The latter is newer and code is cleaner. + + +* `03_debug.t.DISABLED` is a handy tool when the runner is not in line with checks outside github. It provides debugging means +* IPv6 was (status 2025) not allowed, thus the file `11_baseline_ipv6_http.t.DISABLED` which can be renamed if that will change. diff --git a/testssl.sh b/testssl.sh index 48b3c6a..354417c 100755 --- a/testssl.sh +++ b/testssl.sh @@ -2268,6 +2268,76 @@ check_revocation_ocsp() { fi } +# Checks a domain against the hstspreload.org HSTS preload list API (requires --phone-out). +# arg1: domain to check +# arg2: JSON key to check (e.g. status, bulk, preloadedDomain). Empty: only (re)fetch the response. +# arg3: value the key is expected to have (without surrounding quotes; quoting is handled here) +# Return values: +# 0 - request made, nothing compared (no key supplied) +# 1 - API request failed (connection error) +# 10 - key matched the expected value +# 20 - key present but value did not match +# 21 - key not found in the response +# +check_hsts_preloadlist_match() { + local domain="$1" + local key="$2" + local value="$3" + local response="" + local tmpfile="$TEMPDIR/$NODE.hsts-preloadlist.txt" + local uri_api_status="https://hstspreload.org/api/v2/status?domain=$domain" + + "$PHONE_OUT" || return 0 + + # Only query the API once per host, then reuse the cached response + if [[ ! -f "$tmpfile" ]]; then + http_get "$uri_api_status" "$tmpfile" || return 1 + fi + response="$(<"$tmpfile")" + + # Without a key we only (re)fetched the response + [[ -z "$key" ]] && return 0 + + # The key must be present, otherwise the API may have changed + [[ "$response" == *"\"$key\""* ]] || { debugme echo "HSTS preloadlist key unrecognized: $key"; return 21; } + + # String values are quoted in the JSON, booleans are not, so accept either form + [[ "$response" == *"\"$key\": \"$value\""* || "$response" == *"\"$key\": $value"* ]] && return 10 + return 20 +} + +# Returns the value of a known key from the hstspreload.org preload list API. +# Depends on check_hsts_preloadlist_match(). +# arg1: domain to check +# arg2: key to resolve (status or bulk) +# Echoes the matched value and returns 0, or returns 1 if no known value matched. +# +check_hsts_preloadlist_value() { + local domain="$1" + local key="$2" + local -a values=() + local value + local value_ret="" + + [[ -z "$key" ]] && return 1 + + # Only test against known values instead of echoing the API response back, + # so no untrusted input is reflected. + case "$key" in + status) values=("unknown" "pending" "rejected" "preloaded") ;; + bulk) values=("true" "false") ;; + *) return 1 ;; + esac + + for value in "${values[@]}"; do + check_hsts_preloadlist_match "$domain" "$key" "$value" + [[ $? -eq 10 ]] && value_ret="$value" && break + done + + [[ -n "$value_ret" ]] && safe_echo "$value_ret" && return 0 + return 1 +} + # waits maxsleep 1/10 seconds (arg2) until process with arg1 (pid) will be killed # # return values @@ -2932,6 +3002,8 @@ run_hsts() { local hsts_age_days local spaces=" " local jsonID="HSTS" + local json_postfix="" + local preloadmarked preloadsame preloadbulk preloadcombined="" if [[ ! -s $HEADERFILE ]]; then run_http_header "$1" || return 1 @@ -2985,18 +3057,105 @@ run_hsts() { fi if preload "$TMPFILE"; then fileout "${jsonID}_preload" "OK" "domain IS marked for preloading" + preloadmarked=true else fileout "${jsonID}_preload" "INFO" "domain is NOT marked for preloading" - #FIXME: To be checked against preloading lists, - # e.g. https://dxr.mozilla.org/mozilla-central/source/security/manager/boot/src/nsSTSPreloadList.inc - # https://chromium.googlesource.com/chromium/src/+/master/net/http/transport_security_state_static.json + preloadmarked=false fi else pr_svrty_low "not offered" fileout "$jsonID" "LOW" "not offered" + preloadmarked=false fi outln + # Check the domain against the hstspreload.org HSTS preload list (requires --phone-out). + # Run this regardless of the served header: a domain may still be listed after the header + # was removed, or be rejected because the served header does not meet the requirements. + if "$PHONE_OUT"; then + json_postfix="_preloadAPI" + pr_bold " HSTS preload API " + + # If the domain itself is the preloaded entry, it may be fine that the header omits 'preload' + check_hsts_preloadlist_match "$NODE" "preloadedDomain" "$NODE" + [[ $? -eq 10 ]] && preloadsame=true || preloadsame=false + + # bulk=true: added via the submission form; false: manual addition or a subdomain + check_hsts_preloadlist_match "$NODE" "bulk" "true" + [[ $? -eq 10 ]] && preloadbulk=true || preloadbulk=false + + # Combine the three booleans for a compact lookup, e.g. marked+same+bulk -> "111" + [[ $preloadmarked == true ]] && preloadcombined="${preloadcombined}1" || preloadcombined="${preloadcombined}0" + [[ $preloadsame == true ]] && preloadcombined="${preloadcombined}1" || preloadcombined="${preloadcombined}0" + [[ $preloadbulk == true ]] && preloadcombined="${preloadcombined}1" || preloadcombined="${preloadcombined}0" + debugme echo "Temporary lookupvariable: $preloadcombined" + + # Determine and show the outcome + case "$(check_hsts_preloadlist_value "$NODE" "status")" in + "unknown") # Not found in the HSTS preload list + case "$preloadcombined" in + "000"|"001"|"010"|"011") + outln "no entry" + fileout "${jsonID}${json_postfix}" "INFO" "no entry" + ;; + "100"|"101"|"110"|"111") + pr_svrty_low "no entry" + outln " -- submit to HSTS preload list"; fileout "${jsonID}${json_postfix}" "LOW" "no entry" + ;; + esac + ;; + "pending") # Currently in the HSTS pending list + case "$preloadcombined" in + "000"|"001"|"010"|"100"|"101"|"110"|"111") + outln "pending" + fileout "${jsonID}${json_postfix}" "INFO" "pending" + ;; + "011") pr_svrty_medium "pending" + outln " -- addition going to fail, add header" + fileout "${jsonID}${json_postfix}" "MEDIUM" "pending" + ;; + esac + ;; + "rejected") # Entry is considered rejected by the HSTS list + case "$preloadcombined" in + "000"|"001"|"010"|"011") + outln "rejected" + fileout "${jsonID}${json_postfix}" "INFO" "rejected" + ;; + "100"|"101"|"110"|"111") + pr_svrty_medium "rejected" ; outln " -- check other requirements" + fileout "${jsonID}${json_postfix}" "MEDIUM" "rejected" + ;; + esac + ;; + "preloaded") # Marked as 'preload' in the HSTS preload list + case "$preloadcombined" in + "000"|"001") + prln_svrty_good "preloaded" + fileout "${jsonID}${json_postfix}" "OK" "preloaded" + ;; + "010") + outln "preloaded -- manual addition detected" + fileout "${jsonID}${json_postfix}" "INFO" "preloaded" + ;; + "011") + pr_svrty_medium "preloaded" + outln " -- list may remove entry, add header" + fileout "${jsonID}${json_postfix}" "MEDIUM" "preloaded" + ;; + "100"|"101"|"110"|"111") + prln_svrty_best "preloaded" + fileout "${jsonID}${json_postfix}" "OK" "preloaded" + ;; + esac + ;; + *) # Empty: the hstspreload.org API was unreachable or returned an unexpected response + prln_warning "not checked (HSTS preload list lookup failed)" + fileout "${jsonID}${json_postfix}" "WARN" "HSTS preload list could not be checked" + ;; + esac + fi + tmpfile_handle ${FUNCNAME[0]}.txt return 0 } @@ -3623,7 +3782,14 @@ run_security_headers() { "Referrer-Policy INFO" \ "X-UA-Compatible INFO" \ "Cache-Control INFO" \ - "Pragma INFO"; do + "Pragma INFO" \ + "X-Permitted-Cross-Domain-Policies INFO" \ + "Origin-Agent-Cluster INFO" \ + "Document-Policy INFO" \ + "Clear-Site-Data INFO" \ + "Reporting-Endpoints INFO" \ + "Report-To INFO" \ + "NEL INFO"; do read header svrty <<< "${header_and_svrty}" [[ "$DEBUG" -ge 5 ]] && echo "testing \"$header\" (severity \"$svrty\")" match_httpheader_key "$header" "$header" "$spaces" "$first" @@ -10468,7 +10634,7 @@ certificate_info() { out " ($enddate). " # Match Subject/Issuer on next 5 lines, where the CN is (4 lines is fine in most cases, 5 should suffice for all certs) cn="$(awk '/Subject:/{stop=NR+5}; NR<=stop' <<< "${intermediate_certs_txt[i]}" | awk -F= '/CN/ { print $NF }')" - issuer_CN="$(awk '/Issuer:/{stop=NR+5}; NR<=stop' <<< "${intermediate_certs_txt[i]}" | awk -F= '/CN/ { print $NF }')" + issuer_CN="$(awk '/Issuer:/{stop=NR+7}; NR<=stop' <<< "${intermediate_certs_txt[i]}" | awk -F= '/CN/ { print $NF }')" # to catch errors like #2789 during unit test: [[ -z "$cn" ]] && cn="FIXME: cn error" [[ -z "$issuer_CN" ]] && issuer_CN="FIXME: issuer_CN error" @@ -21744,7 +21910,7 @@ tuning / connect options (most also can be preset via environment variables): --sneaky leave less traces in target logs: user agent, referer --user-agent set a custom user agent instead of the standard user agent --ids-friendly skips a few vulnerability checks which may cause IDSs to block the scanning IP - --phone-out allow to contact external servers for CRL download and querying OCSP responder + --phone-out allow to contact external servers for CRL download, querying OCSP responder and the HSTS preload API --add-ca path to with *.pem or a comma separated list of CA files to include in trust check --mtls path to file in PEM format containing unencrypted certificate key (beta) --basicauth provide HTTP basic auth information @@ -24106,21 +24272,27 @@ draw_line() { run_mx_all_ips() { local fname_date="$1" + local domain="$2" local mxs mx - local mxport + local mxport=${3:-25} local -i ret=0 local word="" STARTTLS_PROTOCOL="smtp" + # A port may be appended to the domain, e.g. "--mx example.com:587" (#2986). + # Strip it off before the MX DNS lookup and use it as the port to test. + if [[ "$domain" =~ :[0-9]+$ ]]; then + mxport="${domain##*:}" + domain="${domain%:*}" + fi # test first higher priority servers - mxs=$(get_mx_record "$2" | sort -n | sed -e 's/^.* //' -e 's/\.$//' | tr '\n' ' ') + mxs=$(get_mx_record "$domain" | sort -n | sed -e 's/^.* //' -e 's/\.$//' | tr '\n' ' ') if [[ $CMDLINE_IP == one ]]; then word="as instructed one" # with highest priority mxs=${mxs%% *} else word="the only" fi - mxport=${3:-25} if [[ -n "$LOGFILE" ]] || [[ -n "$PARENT_LOGFILE" ]]; then prepare_logging "${fname_date}" else @@ -24161,7 +24333,7 @@ run_mx_all_ips() { outln pr_bold "Done testing all MX records (on port $mxport): "; outln "$mxs" else - prln_bold " $1 has no MX records(s)" + prln_bold " $domain has no MX record(s)" fi return $ret }