Getting Started: Running an Analysis

In the following we describe how PhASAR can be used to perform data-flow analyses.

Choosing an existing analysis

PhASAR's built-in analyses can be selected using the -D or --analysis command-line option. Note: more than one analysis can be selected to be executed on the code under analysis. Example:

$ phasar -m module.ll -D IFDS_SolverTest 
$ phasar -m module.ll -D IFDS_UninitializedVariables

If no analysis is selected only the call-graph and other supported data structures are created. If a call using "-D None" fails, there is definitely an error within the code or project under analysis or within the PhASAR framework (which is obviously worse). In either way please report the errors with the target code that triggers those errors.

Currently the following built-in analyses are available in PhASAR:

DataFlowAnalysisType	Parameter
DataFlowAnalysisType::IFDS_ConstAnalysis	"IFDS_ConstAnalysis"
DataFlowAnalysisType::IFDS_LinearConstantAnalysis	"IFDS_LinearConstantAnalysis"
DataFlowAnalysisType::IFDS_SolverTest	"IFDS_SolverTest"
DataFlowAnalysisType::IFDS_TaintAnalysis	"IFDS_TaintAnalysis"
DataFlowAnalysisType::IFDS_TypeAnalysis	"IFDS_TypeAnalysis"
DataFlowAnalysisType::IFDS_UninitializedVariables	"IFDS_UninitializedVariables"
DataFlowAnalysisType::IDE_LinearConstantAnalysis	"IDE_LinearConstantAnalysis"
DataFlowAnalysisType::IDE_SolverTest	"IDE_SolverTest"
DataFlowAnalysisType::IDE_TaintAnalysis	"IDE_TaintAnalysis"
DataFlowAnalysisType::IDE_TypeStateAnalysis	"IDE_TypeStateAnalysis"
DataFlowAnalysisType::Intra_Mono_FullConstantPropagation	"Intra_Mono_FullConstantPropagation"
DataFlowAnalysisType::Intra_Mono_SolverTest	"Intra_Mono_SolverTest"
DataFlowAnalysisType::Inter_Mono_SolverTest	"Inter_Mono_SolverTest"
DataFlowAnalysisType::Inter_Mono_TaintAnalysis	"Inter_Mono_TaintAnalysis"
DataFlowAnalysisType::Plugin	"Plugin"
DataFlowAnalysisType::None	"None"

Command line interface

PhASAR provides a stable command line interface (CLI). The help command displays all the parameters supported by PhASAR.

$ ./phasar --help 

outputs:

Command-line options:
  -h [ --help ]                        Print help message
  --more_help                          Print more help
  --config arg                         Path to the configuration file, options
                                       can be specified as 'parameter = option'
  --silent                             Suppress any non-result output

Configuration file options:
  -f [ --function ] arg                Function under analysis (a mangled
                                       function name)
  -m [ --module ] arg                  Path to the module(s) under analysis
  -p [ --project ] arg                 Path to the project under analysis
  -E [ --entry_points ] arg            Set the entry point(s) to be used
  -O [ --output ] arg (=results.json)  Filename for the results
  -D [ --data_flow_analysis ] arg      Set the analysis to be run
  -P [ --pointer_analysis ] arg        Set the points-to analysis to be used
                                       (CFLSteens, CFLAnders)
  -C [ --callgraph_analysis ] arg      Set the call-graph algorithm to be used
                                       (CHA, RTA, DTA, VTA, OTF)
  -H [ --classhierachy_analysis ] arg  Class-hierarchy analysis
  -V [ --vtable_analysis ] arg         Virtual function table analysis
  -S [ --statistical_analysis ] arg    Statistics
  -W [ --wpa ] arg (=1)                Whole-program analysis mode (1 or 0)
  -M [ --mem2reg ] arg (=1)            Promote memory to register pass (1 or 0)
  -R [ --printedgerec ] arg (=0)       Print exploded-super-graph edge recorder
                                       (1 or 0)
  --analysis_plugin arg                Analysis plugin(s) (absolute path to the
                                       shared object file(s))
  --callgraph_plugin arg               ICFG plugin (absolute path to the shared
                                       object file)
  --project_id arg (=myphasarproject)  Project Id used for the database
  --graph_id arg (=123456)             Graph Id used by the visualization
                                       framework

Running an analysis

The analysis on PhASAR runs on LLVM IR code rather than the source code. In order to run some analysis on your code, you need to translate it into LLVM IR code.

In order to translate a short C/C++ code into the LLVM IR, you can use the LLVM compiler tool chain. The following command calls the clang compiler to emit the LLVM IR code from c++ code.

$ clang++ -emit-llvm -S main.cpp

After running this command a file named main.ll can be found within the current directory.

The file to be analyzed by our framework can be specified using the -m flag. PhASAR starts the analysis at the very first instruction of the main() function by default.

An example call to an analysis is:

$ phasar -m path/to/your/main.ll -D IFDS_SolverTest

In the case of analyzing a complex project you can use WLLVM tool that is explained on the Whole Program Analysis (using WLLVM) page.

You can find some concrete examples of the whole process of running some analysis on some code, in more details, here.