tls-scan

  

Table of Contents

• Description
• Installation
  • Dependencies
  • Git
  • Docker
  • tls_scan.json
  • tls_scan.py
• Logging
• Help
• License

  

Description

Automated TLS/SSL server tests for multiple hosts using the SSL Labs REST API.

The code in this repository allows you to scan a list of public TLS/SSL web servers for certificate issues, protocol and cipher suite support, crypto vulnerabilities etc.

Running (up to 10) concurrent assessments is supported (-s), but please keep down the number of concurrent assessments to a minimum. If you're not in a hurry, test only one hostname at a time (default).

The grade report can then be sent to a Slack channel (-k), by mail (-m) or written to stdout:

[A+] artioml.net, 0e411f05, Ready (121 sec.)

Endpoint IP addresses are obfuscated with the first 8 chars of their SHA-256 hash by default (-i to show).

Printing full assessment JSONs is also supported (-j).

  

Installation

Dependencies

Requests HTTP library:

pip install requests

Slack Developer Kit:

pip install slackclient

Or simply:

pip install -r requirements.txt

Git

git clone https://github.com/ArtiomL/tls-scan.git

or download.

Docker

# Shell
docker run -it --rm artioml/tls-scan
# Non-interactive
docker run -it --rm artioml/tls-scan tls_scan.py --help
# Extensibility
docker run -it --rm -e "REPO=drwetter/testssl.sh" artioml/tls-scan

tls_scan.json

To be able to send the report to a Slack channel (-k) or by mail (-m) tls_scan.py must be provided with an API token and/or SMTP credentials. The same config file is used to specify a list of hosts to scan:

{
	"server": "smtp.gmail.com:587",
	"user": "marla@gmail.com",
	"pass": "d293TXVjaEZha2Ux",
	"from": "marla@gmail.com",
	"to": "tyler@gmail.com; chloe@gmail.com",
	"token": "eG94Yi1YWFhYWFhYWFhYWFgtVFRUVFRUVFRUVFRUVFQ=",
	"channel": "#code",
	"hosts": [
		"example.com",
		"example.net",
		"example.org"
	]
}

Schema:

Attribute	Value
server	SMTP server host:port
user	username
pass	password (base64-encoded)
from	from-address string (RFC 822)
to	to-address(es) - delimit with ;
token	Slack bot API token (base64-encoded)
channel	Slack channel ID or name
hosts	list of hosts to scan

  

The config file path is controlled by the -f command line argument or the strCFile global variable (in tls_scan.py):

# Config file
strCFile = 'tls_scan.json'

tls_scan.py

This is the actual scan / report logic.   

Run this program with command-line arguments relevant to your use case. For example:

chmod u+x tls_scan.py
./tls_scan.py -f tls_scan.json -i -k -l2 -m -s3

Using cron (or a similar time-based job scheduler) to perform recurring, periodic scans is recommended.

  

Logging

All logging is disabled by default. Please use the -l {0,1,2,3} argument to set the required verbosity.   

Alternatively, this is controlled by the intLogLevel variable of the log library:

# Log level to /var/log/messages (or stdout)
intLogLevel = 0

If run interactively, stdout is used for log messages (unless -j is set), otherwise /var/log/messages will be used.

  

--help

./tls_scan.py --help
usage: tls_scan.py [-h] [-c] [-f CFILE] [-i] [-j] [-k] [-l {0,1,2,3}] [-m]
                   [-s [2-10]] [-t] [-v]
                   [HOST [HOST ...]]

Automated TLS/SSL Server Tests for Multiple Hosts

positional arguments:
  HOST          list of hosts to scan (overrides config file)

optional arguments:
  -h, --help    show this help message and exit
  -c            deliver cached assessment reports if available
  -f CFILE      config file location
  -i            show IP addresses (default: first 8 chars of their SHA-256)
  -j            return assessment JSONs (default: grades), disables -m and -k
  -k            send report to a Slack channel
  -l {0,1,2,3}  set log level (default: 0)
  -m            send report by mail
  -s [2-10]     number of simultaneous assessments (default: 1)
  -t            ignore server certificate mismatch
  -v            show program's version number and exit

https://github.com/ArtiomL/tls-scan