TLSAssistant is a modular extensive framework that combines state-of-the-art TLS analyzers with a report system that suggests appropriate mitigations and shows the full set of viable attacks. It is open-source, released under Apache-2.0 license and and you can contribute by visiting the project’s repository.

The tool has been developed within Digimat, a joint lab between Poligrafico e Zecca dello Stato and the Center for Cybersecurity of the Fondazione Bruno Kessler.

Architecture

TLSAssistant v3 is the latest release of our state-of-the-art analyzer able to help system administrators and Android app developers in correctly configuring their TLS deployments. This version expands the software’s capabilities by adding a new analysis module able to assess the compliance level of TLS deployments, comparing them to national agencies-issued guidelines. The new update also comes with an improved output module, which is now able to generate structured PDF reports.

It currently integrates five tools:

• Android analysis
  • mallodroid
  • SUPERAnalyzer
• Server analysis
  • testssl.sh
  • tlsfuzzer
  • TLS-Scanner

To have a deeper understanding of the architecture, we must first grasp how it is organized.

TLSAssistant makes advantage of the idea of a “Module,” which is a collection of objects and classes that are joined in the same file by context (e.g., the type of vulnerability analyzed). Each module adheres to standards that must be followed in order to develop a compliant module.

We have different type of modules

• Analysis Modules: modules that perform the analysis using independent code or external tools. This type of module will employ a submodule called wrapper to interface with external tools. The output module receives the Analysis module’s output.
  • Wrapper Modules: modules that wrap an external software or an API call. Given that output must be refined by the Analysis module, a wrapper should not be directly connected to the output module. Most of the time, the wrapper is an entire API of non-Python software.
• Core Module: the modules’ router. It parses the specified configuration, runs each module, gathers the output and redirects it to the output module.
• Output Module: formats the output properly by according to the mitigation standard and the provided information.

How To Contribute

In order to contribute to the project, allowing the Core module to automatically detect and integrate the new changes, the developer must follow the provided standards:

• Modules Design
• Actionable Mitigations Formatting
• Configuration Files Structuring
• Compliance Analysis

List of modules

Server-related

Wrapper Modules

Analysis Modules

Android-Related

Wrapper Modules

Analysis Modules

Core and Output related

Compliance Modules

Flow

In this architecture, we have two different flow:

• Flow of the developer:

  To add a new Analysis module (see left of Architecture Figure), the developer must follow the provided standard. As a result, the new functionality will be detected and implemented by the Core module. In addition to providing the code for implementing the tests for identifying a vulnerability, if a mitigation is known, the developer should define it by producing a JSON file in accordance with the mitigation standards.

• Flow of the end-user:

  The end-user decides which modules to utilize in the analysis in Step 1 (see right of Architecture Figure) by supplying a configuration file or a command line list. Each configuration file is a context-specific collection of modules that conducts a certain kind of analysis (e.g., checking for vulnerabilities related to weak TLS ciphers). Step 2: The Core loads the configuration (if supplied) and the modules (from the list or configuration), ensuring that they are relevant to the kind of analysis requested.

Type of Analysis

Here a quick overview of the various types of analysis that may be requested:

1. Single Host: Because the testssl.sh program covers the majority of the vulnerabilities assessed by the tool, we decided to make the analysis more efficient by doing a pre-analysis (Step 3a) to create a cache with its results. During current and future analysis, they will be utilized by each of the related testssl.sh modules (Step 3b), such as POODLE (an attack that uses the availability of SSLv3 to weaken the connection).
2. Single APK: Each Android-related module, such as Unsecure TrustManager, performs the analysis (Step 3b) on the given APK.
3. Multiple Hosts: On each of the domains supplied in an input list, we execute a Single Host analysis. Each result is concatenated and delivered as a single output to the Output module. The list can also be generated by subdomain enumeration.
4. TLS Configuration and Fixes: If a configuration file is given, a WhiteBox analysis is conducted by loading the TLS configuration into memory and checking all accessible modules (Step 3b). Otherwise, if a configuration file and a valid hostname are given, a single host analysis is conducted, and the corrections are then merged into the provided TLS configuration. This is referred to as a Hybrid study since we run a BlackBox analysis on the hostname and then apply the changes to the configuration file.

Compliance Analysis

TLSAssistant is able to perform an automated compliance analysis against five agency-issued technical guidelines:

• AgID ver.2020-01
• ANSSI v1.2
• BSI TR-02102-2 and TR-03116-4
• Mozilla v5.7
• NIST SP 800-52 Rev. 2 (and related)

  Comparison Modules

  The compare_one and compare_many modules are used to assess the compliance level of an existing webserver (both deployed and not) against one or multiple guidelines. Its output consists of an actionable report that combines a description of the potential lack of compliance along with an explanation on how improve the security posture of the analyzed server and a set of actionable hints to guide the user in the process of making the webserver compliant.

  Generation Modules

  The generate_one and generate_many modules are used to generate from scratch configuration files that are compliant with one or more guidelines. Its output consists of a configuration file (for Apache or nginx webservers) that can be directly used to deploy a compliant webserver out-of-the-box.

  Custom Guidelines

  The modules can be customized to take into consideration specific requirements of the user, such as structured custom guidelines or single requirements for selected configurable elements.

  Warning

  The compliance module can recieve both a configuration file and a hostname/ip as input. If a configuration file is provided the analysis will not check the Certificates since they depend on external files.

Caching system

Each wrapper module includes a caching mechanism. Because it is unlikely that any value would change dramatically in a single runtime, the caching approach allows the program to be less invasive and more powerful (with a runtime usually less than a minute).

Pre-analysis (testssl.sh)

As stated before, a pre-analysis (step 3a) is required as a compromise between atomicity, efficiency, and execution speed. Because the testssl startup time is roughly 3 seconds, we need to limit the number of times the tool is called. To do this, the core will determine if the module being run is utilizing testssl.sh as a wrapper, and if so, it will get all testssl-related arguments. Following this, the core will fill the testssl wrapper cache, which will be executed once the analysis is complete.

Demo video