Cross-module Analysis

As an advanced user, you can analyze not only individual executable files using ClearBlue but also the libraries on which they dynamically depend. By extracting more comprehensive information, you can achieve cross-module analysis and obtain more comprehensive and detailed analysis results.

Prerequisites

Before you start running clearblue-cli, make sure your system meets the following requirements:

• Operating System: Linux
• Memory: 16GB or more

Get Necessary Artifacts

Clearblue-cli provides three tools to perform the cross-module analysis process: clearblue-cli, plankton-dasm, and cb-check.

plankton-dasm is used to convert the binary file into a .bc file. The .bc file will then be used as the input of the tool cb-check, which will finally output the bug report. clearblue-cli is a tool to unify the entire analysis process, and to store and manage necessary data. Both Plankton and ClearBlue will be invoked through it.

You can download these tools in one package by wget using the links below:

clearblue-cli

wget https://gitlab.com/api/v4/projects/45263341/packages/generic/cbvis-artifacts/dev/clearblue-cli.tar.xz

The structure of the tools package is here:

build/
|-- clearblue
|   |-- cb-check
|  
|-- clearblue-cli
|-- plankton
    |-- plankton-dasm

What is Cross-module Analysis

Cross-module analysis refers to the process of analyzing a binary executable that includes a significant number of dynamic link libraries (DLLs). When an executable file is running, dynamic link libraries work by allowing code to load libraries in a run-time way.

If we only analyze the binary itself, the calls to functions in other modules cannot be fully analyzed, leading to less precise results. This limitation often necessitates approximations or modeling.

However, by parsing the binary’s dependency relationships and analyzing all libraries from the bottom-up, we can extract and store information such as SEG and PSA data. This approach enables us to construct a complete information graph during the analysis of the binary, ensuring a more comprehensive understanding of the system’s architecture and behavior.

A dependency graph of a binary is like:

Start Cross-module Analysis

To complete cross-library analysis, three steps are required:

• The first step involves parsing the dynamic library dependencies of the binary.
• The second step is to translate both the binary and libraries into bc files using lifting.
• The third step is to analyze and store analysis information bottom-up based on the dependency graph.

clearblue-cli is a tool that integrates Plankton and ClearBlue, capable of parsing third-party dependencies of binaries, translating them into LLVM bitcode, and conducting sequential analysis.

Usage:

To simplify the process of completing the three steps mentioned above with a single operation, we can use the following command to directly analyze the entire process:

./clearblue-cli -workspace <workspace_path> -create <binary> -run

Besides, the three steps mentioned above can be carried out separately into stages:

• parsing and storing only the dependencies of the binary:

./clearblue-cli -workspace <workspace_path> -create <binary>  

• Lifting executable files of binaries and dependent libraries into BC files:

./clearblue-cli -workspace <workspace_path> -create <binary> -lift

• Analyzing the corresponding BC files sequentially:

./clearblue-cli -workspace <workspace_path> -create <binary> -analysis

Here are some parameters you can use with clearblue-cli:

-workspace <workspace_path>						- Path to store the analysis data. All analysis data will be stored into workspace.
-create <binary>								- Path to the binary file.
-run										    - To run the entire process.
-lift                                           - Select to perform the lifting operation separately.
-plankton <plankton_path>                       - Specify the Plankton path. If not provided, search in the default path.
-plParams <params_string>                       - Provide non-default parameters for Plankton.
-analysis                                       - Select to perform the analyzing operation separately.
-clearblue <clearblue_path>                     - Specify the Clearblue path. If not provided, search in the default path.
-cbParams <params_string>                       - Provide non-default parameters for Clearblue.

Example of cross-module analysis

Example 1: Run the NPD analysis on real-world project openssl:

./clearblue-cli -workspace test/ -create /usr/bin/openssl -run

Getting the library dependency-graph for openssl:

digraph usr-bin-openssl{
"/usr/bin/openssl" -> "/lib/x86_64-linux-gnu/libssl.so.1.1";
"/usr/bin/openssl" -> "/lib/x86_64-linux-gnu/libcrypto.so.1.1";
"/usr/bin/openssl" -> "/lib/x86_64-linux-gnu/libpthread.so.0";
"/usr/bin/openssl" -> "/lib/x86_64-linux-gnu/libc.so.6";
"/lib/x86_64-linux-gnu/libssl.so.1.1" -> "/lib/x86_64-linux-gnu/libcrypto.so.1.1";
"/lib/x86_64-linux-gnu/libssl.so.1.1" -> "/lib/x86_64-linux-gnu/libpthread.so.0";
"/lib/x86_64-linux-gnu/libssl.so.1.1" -> "/lib/x86_64-linux-gnu/libc.so.6";
"/lib/x86_64-linux-gnu/libcrypto.so.1.1" -> "/lib/x86_64-linux-gnu/libdl.so.2";
"/lib/x86_64-linux-gnu/libcrypto.so.1.1" -> "/lib/x86_64-linux-gnu/libpthread.so.0";
"/lib/x86_64-linux-gnu/libcrypto.so.1.1" -> "/lib/x86_64-linux-gnu/libc.so.6";
"/lib/x86_64-linux-gnu/libpthread.so.0" -> "/lib/x86_64-linux-gnu/libc.so.6";
"/lib/x86_64-linux-gnu/libdl.so.2" -> "/lib/x86_64-linux-gnu/libc.so.6";
}

This dependency graph will be stored in:

<workspace_path>/<binary_name>.dep.dot

After the analysis, we can obtain relevant data, where we can see that through cross-module analysis, more NPD issues can be discovered.

The analysis report will be stored in:

<workspace_path>/<binary_name>-report.json