Command Line

As an advanced user, you can run Clearblue directly via the command line.

Prerequisites

Before you start running Clearblue, make sure your system meets the following requirements:

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

Get Necessary Artifacts

Clearblue provides two tools to perform the analysis process: 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.

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

plankton-dasm

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

cb-check

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

Get the bc File

plankton-dasm is a binary to LLVM IR translator, which could transform binary to .bc file.

Usage:

plankton-dasm -b <binary> -o <filename>

Here are some parameters you can use with plankton-dasm:

-b=<binary>										- Path to the binary file.
-o=<filename>									- Output filename.
-bc-only										- Flags to only output .bc file.
-debug-file=<debugFile>                         - User provided debug information file.
-dsm-only                                       - Flags to only perform disassembly without other recovery.
-global-only                                    - Flags to recover global variable.
-lti=<ltiFile>                                  - User provided modeling for external functions.
-no-debug                                       - Disable parsing debug information.
-param-only                                     - Flags to recover parameters.
-select-func=<selected>                         - Specify a comma separated list of target functions to decode (example: funcA,funcB,funcC)
-stack-only                                     - Flags to recover stack variable.
-strict-dsm                                     - Flags to only perform disassembly on known functions from debug information.

For file formats that use separate debug information files, such as Mach-O and PE, you can use the -debug-file option to specify the path to the debug file.

For example, Mach-O creates a .dSYM directory to store the debug information. You can use any of the following commands to make plankton-dasm parse the debug information:

plankton-dasm -b <path_to_binary> -o <filename>  # require that <path_to_binary>.dSYM exists
plankton-dasm -b <path_to_binary> -o <filename> -debug-file <path_to_binary>.dSYM
plankton-dasm -b <path_to_binary> -o <filename> -debug-file <path_to_dSYM>
plankton-dasm -b <path_to_binary> -o <filename> -debug-file <path_to_dSYM>/Contents/Resources/DWARF/<binary_name>

Analyze the bc File

cb-check is a tool to perform bug detection and generate the corresponding bug report.

Usage:

cb-check [options] <input bitcode>

For more information on different parameters, execute the following command:

cb-check -h

Example 0: Run the null pointer dereference checker for a quick test.

cb-check -ps-npd input.bc

The found bugs are written into bug_report.txt (you can specify -report=res.txt to write the reports in res.txt).

Example 1: Run all checkers belonging to the group with -ps-stable.

cb-check -ps-stable input.bc

Example 2: Get useful in-process messages with the -verbose option.

cb-check -verbose input.bc

Example 3: Load checkers in different ways.

The first is by using a checker provided by Clearblue, such as -ps-npd, which is a path-sensitive null-pointer-dereference checker.

The second is by using the -load option to load a custom checker, such as -load=myChecker.so. You could learn how to develop a custom checker from Develop Examples.

cb-check -custom-options -load=myChecker.so input.bc

Example 4

You could load queries in the same way you load checkers. After building your queries into a dynamic library myChecker.so, you could execute them in Clearblue using the command:

cb-check -query -load=myChekcer.so input.bc