Command Line

An advanced method to directly run Clearblue.

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


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:





Get the bc File

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


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.


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 You could learn how to develop a custom checker from Develop Examples.

cb-check -custom-options input.bc

Example 4

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

cb-check -query input.bc


Was this page helpful?

Last modified June 26, 2024: Update Command (d8dfe86)