Spelton

A Static Checker for Memory-Related Bugs Triggered with C++ Smart Pointers

Installation

The Spelton tool is provided as a tarball. The directory tree after extraction is shown below.

spelton/
|-- bin/
|   |-- clang -> clang-9
|   |-- clang++ -> clang
|   |-- clang-9                 Clang executable
|   |-- clang-cl -> clang
|   |-- clang-cpp -> clang
|   |-- clang-extdef-mapping    External definition mapping generator
|   |-- driver                  Built-in scheduler for paralle analysis
|   |-- genidx                  Index generator for the report directory
|   `-- spelton                 Spelton analyzer executable
`-- lib/
    |-- clang/
    `-- genidx/

The Spelton executable is compiled on the top of the Docker image of CentOS 7. It requires the Python interpreter and GNU Make for the execution of the analysis scheduler and the index generator.

Among the files, the executable script driver serves as a parallel execution driver, which is used for analyzing a project in parallel. The executable genidx is used to generate the index file index.html for the report output directory. We also provide the Clang 9.0.0 compiler compiled together with Spelton, in case of necessary.

Build Spelton from source:

# Download LLVM-9.0.0: https://releases.llvm.org/9.0.0/llvm-9.0.0.src.tar.xz
# Extract the source code
$ tar xf llvm-9.0.0.src.tar.xz
# Clone Spelton into subdir /path/to/llvm-9.0.0.src/tools/clang
/path/to/llvm-9.0.0.src/tools$ git clone https://github.com/Snape3058/Spelton.git clang
# Build target "melton"
/path/to/spelton-build$ cmake /path/to/llvm-9.0.0.src -DLLVM_TOOL_CLANG_BUILD=on
/path/to/spelton-build$ make melton

Analyzing Code with the Tool Executable

The command-line arguments that Spelton accepts and their usages are presented as follows.

Command-line format:

$ /path/to/spelton [options] <source0> [... <sourceN>] [-- <compilation arguments>]

The [options] part can specify the following options:

Spelton Options: - --ctu=<string>: Specify the path to the CTU index file (use -ctu=/path/to/externalFnMap.txt to specify the index file, or use -ctu= to disable CTU analysis). - --target=<string>: Analyze only functions with the specified function signatures.

Analyzer Options: - --diag-cli=<value>: Specify the format of output reports. - html (default): HTML report. - plist: PList report. - text: Print report information directly to the console. - --extra-arg=<string>: Additional arguments to append after the arguments provided by the compilation database. - --extra-arg-before=<string>: Arguments to insert before the arguments provided by the compilation database. - -p=<string>: Path to the compilation database.

Other Options: - --help: Display help information. - --version: Display version information.

In addition to adding extra compilation command-line arguments on top of the compilation database using -extra-arg and -extra-arg-before, users can also provide the compiler arguments directly at the end of the command line using the -- delimiter. For more detailed information on Clang Tooling and compilation database, please refer to the Clang documentation.

Concurrent Analysis with the Driver

Command-line format:

$ driver [command] [VAR=value] [-j <nproc>]

The [command] part specifies the following functionalities: - analyze: Perform analysis. - index: Generate only the bug report index index.html. - exfnmap: Generate only the CTU index file. - genifl: Generate the analysis input file list using the compilation database. - archive: Archive the last analysis report and log (rename these two folders with timestamps). - sources: Print the list of input files being analyzed. - logs: Print the list of log files. - dump: View the analysis log using the less command. - help: Display help information (this is the default action when no parameters are provided). - helpexe: Display help information for the Spelton executable program.

The variable definitions [VAR=value] can include the following variables: - IFL: Specify the input file list. - OUT: Specify the output path for log files (default is scan-dir).

Since this script is a makefile, all command-line arguments of GNU Make are also valid, such as -j and -k.

Note: Due to the limitation of the Cross Translation Unit (CTU) analysis in Clang Static Analyzer, the analyze target will execute Spelton twice, one with CTU analysis enabled and another disabled. The report counting in the paper did not deduplicate the reports for the same problem generated by two executions, as the detailed paths of the two versions may be different.

Example Analysis Workflow

This chapter provides a recommended analysis workflow, using the MySQL and Aria2 projects mentioned in the Spelton tool paper as examples.

  1. Obtain the code, preprocess the project, compile, and generate the compilation database.

    For projects configured with the CMake tool, users can generate the compilation database by adding the -DCMAKE_EXPORT_COMPILE_COMMANDS=ON parameter when executing the cmake program. For projects configured with the AutoMake tool, users can capture compilation parameters during the build process using the bear (Build EAR) tool to generate the compilation database. After configuring the project, it is recommended to build the project to ensure that files generated only during compilation are correctly created and to check for any compilation errors.

  2. Generate the input file list.

    $ /path/to/driver genifl

    The generated list will be placed in the input.ifl file in the current directory. The list contains all source files involved in the compilation database. Users can manually edit the list after generation to adjust the files to be analyzed. Lines starting with # in the list are considered comments.

  3. Analyze the code.

    $ /path/to/driver analyze IFL=./input.ifl

    Specify the input file list as the input.ifl file in the current directory, use the clang-extdef-mapping program to generate the CTU index file, and then use the analyzer executable program to analyze all the translation units on the list. After analysis, call the report index generation tool to generate an index for the report folder.

    If an error occurs during the generation of the CTU index file, users can re-execute the last step. In this case, the incomplete CTU index file will continue to be generated, and once it is completed, the code analysis will start. The code analysis process will not fail and will not produce errors, even if crashes occur during analysis. Please be patient during the last few files of the analysis, as it may take a long time to complete. After the analysis is finished, users can check the log to identify files where crashes occurred during analysis.

Usage of Handmade Snippets

In the released packages, a makefile is provided to compile the source files and help to generate the compilation database for the test snippets. After the compilation database is generated, the snippets can be analyzed via the driver scheduler similar to analyze a project repository.

The buggy sites to be reported can be found from the positives.txt files in the root or sub directories of a package. The locations not mentioned in this file or mentioned in negatives.txt file should not be reported and can be considered as bug-free usages.

Trouble Shooting

/root/of/spelton$ ls
bin  lib
/root/of/spelton$ patch -p2 </path/to/python3.patch
patching file lib/genidx/genidx.py
/root/of/spelton$ head -n 1 bin/genidx
#!/usr/bin/python3

Impact