Welcome to pySSLScan’s documentation!¶
Installation¶
You can install pySSLScan with pip:
$ pip install sslscan
See Introduction for more information.
Contents:
Introduction¶
Installation¶
From a tarball release¶
Download the most recent tarball from github, unpack it and run the following command on the command-line.
$ python setup.py install
Install the development version¶
Install git and run the following commands on the command-line.
$ git clone https://github.com/DinoTools/pysslscan.git
$ cd pysslscan
$ python setup.py install
How to use¶
The pySSLScan framework provides an API to write tests for SSL enabled services. But it also includes a command-line interface to get you started in a few steps.
Command-line¶
Use the --help parameter to display the main help. This will give a short overview about all global options available and list all subcommands.
$ pysslscan --help
Subcommands are very helpful and extend the command-line interface. To get help for a subcommand just specify the command and append the --help option. The result of the following example command will be the help for the scan command.
$ pysslscan scan --help
Performe a basic scan¶
First of all get a list of all available scan modules.
$ pysslscan scan.list
client.ciphers - List all client ciphers.
server.preferred_ciphers - Detect preferred server ciphers.
server.certificate - Extract certificate information.
...
After that determine what reporting modules are available.
$ pysslscan report.list
term - Print results to the terminal.
...
Choose some of the modules and perform a target scan. In the example below two scan modules are used. The first one is server.ciphers to detect all supported ciphers available on the server and the second one is vuln.heartbleed to run test to detect if the server is vulnerable by the heartbleed bug. To display the scan results on the command-line the reporting module term is used. The --tls10 option enables all TLSv1.0 ciphers.
$ pysslscan scan --scan=server.ciphers --scan=vuln.heartbleed --report=term --tls10 127.0.0.1
Highlight the result¶
pySSLScan provides also some rating modules to highlight important facts in the result.
First of all have a look at the list of available rating modules.
$ pysslscan rating.list
ssllabs.2009c - Rating used by SSL Labs 2009c
ssllabs.2009d - Rating used by SSL Labs 2009d
...
Perform the scan from an earlier example but specify a rating module.
$ pysslscan scan --scan=server.ciphers --scan=vuln.heartbleed --report=term:rating=ssllabs.2009e --tls10 127.0.0.1
Use a protocol handler¶
pySSLScan has support for different protocols which are handled by a special handler module. By default pySSLScan will perform a basic TCP connect to scan a target but it supports also protocols like HTTP or SMTP.
The example below will print a list of all available handler modules.
$ sslscan.py handler.list
tcp - Handle raw TCP-connections.
smtp - Handle SMTP-connections.
http - Handle HTTP-connections.
...
To use a handler module it has to be specified as shown in the next example.
$ pysslscan scan --scan=server.ciphers --report=term:rating=rbsec --tls10 'smtp://127.0.0.1:25?starttls=true'
Python API¶
ToDo
API Reference¶
Scanner¶
- class sslscan.Scanner(module_manager=None)[source]¶
The main scanner object.
- append(module)[source]¶
Append a scan or report module.
Parameters: module – Instance of a scan or report module
- append_load(name, config, base_class=None)[source]¶
Append a module but load it first by using the module manager.
Parameters: - name (String) – Name of the module to load
- config (Mixed) – Config of the module
- base_class (class) – Module lookup filter
Returns: False if module not found
- get_enabled_methods()[source]¶
Uses the scanner config to create and return a list of all enabled SSL methods.
Returns: List of methods Return type: List
- load_handler_from_uri(host_uri)[source]¶
Load a handler from a given uri.
Parameters: host_uri (String) – The URI Returns: The handler
Config¶
A collection of classes to handle the configuration of a scanner or a module.
- class sslscan.config.BaseConfig(options=None, parent=None)[source]¶
The base config. All other configuration classes use it as base class.
- add_option(name, **kwargs)[source]¶
Add an option.
Parameters: - name (String) – Name of the config option
- kwargs – Additional params are used for a new sslscan.config.Option instance
- add_option_group(group)[source]¶
Add grouped options.
Parameters: group (sslscan.config.OptionGroup) – Instance of sslscan.config.OptionGroup
- get_option(name)[source]¶
Return an option.
Parameters: name (String) – The name of the option Returns: The option or None if not found
- get_parent()[source]¶
Return the parent config object or None if no parent is set.
Returns: Object or None
- get_value(name, default=None)[source]¶
Get the value of an option.
Parameters: - name (String) – Name of the option
- default (Mixed) – Default value
Returns: If found the value of the option or the default value
- set_parent(parent)[source]¶
Set the current parent config object.
Parameters: parent (Object|None) – Set or reset parent config object
- class sslscan.config.ModuleConfig(module=None, **kwargs)[source]¶
Holds the config of a module
Parameters: module – The module this config is for
- class sslscan.config.Option(name, action='store', default=None, help='', metavar='', type='string', values=None, negation=None, parent=None)[source]¶
- convert_value_type(value)[source]¶
Tries to convert the value into the right type
Parameters: value (Mixed) – Value to convert Returns: The value Return type: Mixed
- get_parent()[source]¶
Return the parent config object or None if no parent is set.
Returns: Object or None
Knowledge base¶
The knowledge base is used to store and access all collected information.
Example 1:
>>> kb = KnowledgeBase()
>>> kb.set("test.foo", 1234)
>>> kb.get("test.foo")
Example 2:
>>> kb = KnowledgeBase()
>>> cipher = Cipher()
>>> kb.append("client.ciphers", cipher)
>>> kb.get("client.ciphers")
Example 3:
>>> group = ResultGroup(label="My Results")
>>> value = ResultValue(label="Yes/No", True)
>>> group.append(value)
- class sslscan.kb.Cipher(method=None, name=None, bits=None, status=None)[source]¶
This class is used to store all information for a cipher.
- class sslscan.kb.KnowledgeBase[source]¶
The knowledge base is used to store and access all collected information.
- append(kb_id, value)[source]¶
Append a new value to the knowledge base.
Parameters: - kb_id (String) – The ID of the value
- value (Mixed) – The value
- get(kb_id)[source]¶
Fetch a value by its ID
Parameters: kb_id (String) – The ID Todo: Add default value
- get_group_ids(kb_id)[source]¶
Collect and return all values that are result groups.
The given kb_id is used as filter.
Parameters: kb_id (String) – The ID