Getting Started: Running an Analysis

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

Choosing an existing analysis

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

$ phasar-cli -m module.ll -D ifds-solvertest
$ phasar-cli -m module.ll -D ifds-uninit
# equivalent to
$ phasar-cli -m module.ll -D ifds-solvertest -D ifds-uninit

If no analysis is selected only the call-graph and other supported data structures are created. If a call fails with no -D option provided, 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	CLI Parameter	Description
DataFlowAnalysisType::IFDSConstAnalysis	ifds-const	Determine, which variables are mutated and therefore cannot be considered 'constant'
DataFlowAnalysisType::IFDSUninitializedVariables	ifds-uninit	Find usages of uninitialized variables.
DataFlowAnalysisType::IFDSTaintAnalysis	ifds-taint	Simple, alias-aware taint-analysis. Use with --analysis-config
DataFlowAnalysisType::IDEExtendedTaintAnalysis	ide-xtaint	More advanced alias-aware taint analysis that provides limited field-sensitivity. Use with --analysis-config
DataFlowAnalysisType::IFDSTypeAnalysis	ifds-type	Simple type analysis
DataFlowAnalysisType::IDECSTDIOTypeStateAnalysis	ide-stdio-ts	Find invalid usages of the libc file-io
DataFlowAnalysisType::IDEOpenSSLTypeStateAnalysis	ide-openssl-ts	Find invalid usages of a subset of the OpenSSL EVP library
DataFlowAnalysisType::IFDSSolverTest	ifds-solvertest	Empty analysis. Just to see that the IFDS solver works
DataFlowAnalysisType::IFDSFieldSensTaintAnalysis	ifds-fstaint	Specialized taint analysis for tracing environment variables (deprecated)
DataFlowAnalysisType::IDELinearConstantAnalysis	ide-lca	Simple linear constant propagation
DataFlowAnalysisType::IDESolverTest	ide-solvertest	Empty analysis. Just to see that the IDE solver works
DataFlowAnalysisType::IDEInstInteractionAnalysis	ide-iia	Which instruction has influence on which other instructions?
DataFlowAnalysisType::IntraMonoFullConstantPropagation	intra-mono-fca	Simple constant propagation without the restriction to linear binary operations. Only works inTRA-procedurally
DataFlowAnalysisType::IntraMonoSolverTest	intra-mono-solvertest	Empty analysis. Just to see that the intraprocedural monotone solver works
DataFlowAnalysisType::InterMonoSolverTest	inter-mono-solvertest	Empty analysis. Just to see that the interprocedural monotone solver works
DataFlowAnalysisType::InterMonoTaintAnalysis	inter-mono-taint	Simple taint analysis using the monotone framework with k-limited call-strings. Use ifds-taint or ide-xtaint instead.

Command line interface

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

$ phasar-cli --help
$ phasar-cli --help-hidden

Running an analysis

The analyses of PhASAR run 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 first.

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 from C++ code.

$ clang++ -emit-llvm -S -fno-discard-value-names 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-cli -m path/to/your/main.ll -D ifds-solvertest

In the case of analyzing a complex project you can use the WLLVM compiler wrapper. For details on whole-program analysis, consult Whole-Program-Analysis-(using-WLLVM).

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

A Word on Debug Info

PhASAR typically analyzes any LLVM IR, no matter whether it contains debug-info metadata, or not. Some analyses, however, make use of debug info in order to improve their results representation. So, for example the linear constant analysis (ide-lca) is able to associate constant values to concrete variables present in the source code only if debug info is available.

Hence, to improve your experience with PhASAR's analysis results, it may be useful to analyze LLVM IR with embedded debug info.

EDIT: Once PhASAR has switched fully to opaque pointers, debug information is required for a precise and scalable analysis.