diff --git a/README.md b/README.md index d1baa01cc5..e975d04cee 100644 --- a/README.md +++ b/README.md @@ -8,53 +8,53 @@ ## What is PhASAR? -PhASAR is a LLVM-based static analysis framework written in C++. It allows users -to specify arbitrary data-flow problems which are then solved in a -fully-automated manner on the specified LLVM IR target code. Computing points-to -information, call-graph(s), etc. is done by the framework, thus you can focus on -what matters. +PhASAR is a LLVM-based static analysis framework written in C++. +It allows users to specify arbitrary data-flow problems which are then solved in a fully-automated manner on the specified LLVM IR target code. +Computing points-to information, call-graph(s), etc. is done by the framework, thus you can focus on what matters. You can find available literature on PhASAR [here](https://github.com/secure-software-engineering/phasar/wiki/Useful-Literature#papers-on-phasar). +### Key Features + +- **IFDS/IDE solver**: Interprocedural data-flow analysis based on the IFDS/IDE algorithm +- **Sparse analysis**: SparseIFDS/SparseIDE for improved performance +- **Call-graph construction**: Several algorithms (CHA, RTA, VTA, alias-based) +- **Type-hierarchy construction**: Extract high-level C*+ type information from LLVM IR +- **Points-to/alias infrastructure**: High-performance alias analyses for LLVM IR. Integration with state-of-the-art alias/points-to information from SVF possible +- **Interprocedural CFG (ICFG)**: Connecting control-flow with call-graph information +- **Path-tracking**: Improve results-reporting by reconstruct concrete data-flow paths from IFDS/IDE results +- **Monotone solver**: Simple intra-procedural analysis engine, based on Monotone Frameworks +- **Taint analysis**: Infrastructure for taint-configuration & IFDS/IDE-based taint analysis +- **Modern C++20 API**: Easy-to use interfaces, also for non C++ experts + ### How do I get started with PhASAR? We have some documentation on PhASAR in our [***Wiki***](https://github.com/secure-software-engineering/phasar/wiki). You probably would like to read this README first. - -Please also have a look on PhASAR's project directory and notice the project directory [examples](./examples/) as well as the custom tool `tools/example-tool/myphasartool.cpp`. - -You can find PhASAR's API reference [here](https://secure-software-engineering.github.io/phasar/). - -## Secure Software Engineering Group - -PhASAR is primarily developed and maintained by the Secure Software Engineering Group at Heinz Nixdorf Institute (University of Paderborn) and Fraunhofer IEM. +Please also have a look at PhASAR's project directory, in particular the +[examples](./examples/) directory and the custom tool +`tools/example-tool/myphasartool.cpp`. -PhASAR was initially developed by Philipp Dominik Schubert (@pdschubert)(). +You can find PhASAR's API reference [here](https://secure-software-engineering.github.io/phasar/). -Currently, PhASAR is maintained by -- Fabian Schiebel (@fabianbs96)() -- Sriteja Kummita (@sritejakv) -- Lucas Briese (@jusito) -- Martin Mory (@MMory)() -- *others* +## Requirements -## Required Version of the C++ Standard +### C++ Standard -**NEW**: PhASAR requires at least C++-20. +PhASAR requires at least C++20. PhASAR supports C++20 modules as an experimental feature. -## Currently Supported Version of LLVM - -**NEW**: PhASAR is currently set up to support LLVM versions **between LLVM-16 and LLVM-22.1**, using LLVM 16 by default. We actively test PHASAR with LLVM-16 and LLVM-22.1, so if something does not work, try these versions instead.
-Specify the `PHASAR_LLVM_VERSION` cmake-variable to change the LLVM version to use. +### LLVM Version +PhASAR supports LLVM versions **between LLVM-16 and LLVM-22.1**, using LLVM-16 by default. +We actively test PhASAR with LLVM-16 and LLVM-22.1, so if something does not work, try these versions instead. +Specify the `PHASAR_LLVM_VERSION` cmake variable to change the LLVM version to use. ## Breaking Changes -To keep PhASAR in a state that it is well suited for state-of-the-art research in static analysis, as well as for productive use, we have to make breaking changes. Please refer to [Breaking Changes](./BreakingChanges.md) for detailed information on what was broken recently and how to migrate. +To keep PhASAR in a state that is well suited for state-of-the-art research in static analysis, as well as for productive use, we have to make breaking changes. Please refer to [Breaking Changes](./BreakingChanges.md) for detailed information on what was broken recently and how to migrate. ## Building PhASAR @@ -62,12 +62,39 @@ Please refer to [BUILD.md](./BUILD.md) for instructions on how to build PhASAR. ## How to use PhASAR? -We recomment using phasar as a library with `cmake` or `conan`. +The following example shows how to use PhASAR's core concepts of IFDS/IDE analysis, alias analysis, type-hierarchy, call-graph, and taint analysis: + +```cpp +#include "phasar.h" + +// Load the target LLVM IR +auto IRDB = psr::LLVMProjectIRDB::loadOrExit("target.ll"); + +// Build alias information, a type-hierarchy, and a taint configuration +// (sources/sinks can come from IR annotations, a JSON file, or callbacks) +psr::LLVMAliasSet AS(&IRDB); +psr::DIBasedTypeHierarchy TH(IRDB); +psr::LLVMTaintConfig TC(IRDB); -If you already have installed phasar, [Use-PhASAR-as-a-library](https://github.com/secure-software-engineering/phasar/wiki/Using-Phasar-as-a-Library) may be a good start. +// Build the interprocedural CFG using VTA call-graph construction +psr::LLVMBasedICFG ICFG(&IRDB, psr::CallGraphAnalysisType::VTA, + {"main"}, &TH, &AS); -Otherwise, we recommend adding PhASAR as a git submodule to your repository. -In this case, just `add_subdirectory` the phasar submodule directory within your `CMakeLists.txt`. +// Instantiate and solve the taint analysis +psr::IFDSTaintAnalysis Problem(&IRDB, &AS, &TC, {"main"}); +psr::solveIFDSProblem(Problem, ICFG); + +// Inspect detected leaks +for (const auto &[Inst, Facts] : Problem.Leaks) { + llvm::outs() << "Leak at: " << psr::llvmIRToString(Inst) << '\n'; +} +``` + +For more examples, including how to write a custom analysis, see [examples/how-to/](./examples/how-to/). + +### Integrating PhASAR into your build + +We recommend using PhASAR as a library with `cmake`, using `FetchContent` or as git submodule. Assuming you have checked out phasar in `external/phasar`, the phasar-related cmake commands may look like this: @@ -84,41 +111,44 @@ target_link_libraries(yourphasartool Depending on your use of PhASAR you also may need to add LLVM to your build. + For more information please consult our [PhASAR wiki pages](https://github.com/secure-software-engineering/phasar/wiki). -## How to use with Conan v2 ? +If you have PhASAR *installed*, [Use-PhASAR-as-a-library](https://github.com/secure-software-engineering/phasar/wiki/Using-Phasar-as-a-Library) may be a good start. + +### Using PhASAR with Conan v2 + +To export the recipe and dependencies, execute from the repo root: -To export the recipe and dependencies execute from repo root: - `conan export utils/conan/llvm-core/ --version 15.0.7 --user secure-software-engineering` - `conan export utils/conan/clang/ --version 15.0.7 --user secure-software-engineering` - `conan export .` -- View exported `conan list "phasar/*"` +- View exported: `conan list "phasar/*"` - [Consume the package](https://docs.conan.io/2/tutorial/consuming_packages.html) If you just want to use phasar-cli: + - `conan install --tool-requires phasar/... --build=missing -of .` - `source conanbuild.sh` - `phasar-cli --help` -## Please help us to improve PhASAR +## Contributing -You are using PhASAR and would like to help us in the future? Then please -support us by filling out this [web form](https://goo.gl/forms/YG6m3M7sxeUJmKyi1). +You are very welcome to contribute to the PhASAR project. +Just raise an issue or a pull request on GitHub. -By giving us feedback you help to decide in what direction PhASAR should stride in -the future and give us clues about our user base. Thank you very much! +For details see [Contributing to PhASAR](https://github.com/secure-software-engineering/phasar/wiki/Contributing-to-PhASAR) and [Coding Conventions](https://github.com/secure-software-engineering/phasar/wiki/Coding-Conventions). -### Installing PhASAR's Git pre-commit hook +## Secure Software Engineering Group -You are very much welcome to contribute to the PhASAR project. -Please make sure that you install our pre-commit hook that ensures your commit adheres to the most important coding rules of the PhASAR project. -For more details please consult [Coding Conventions](https://github.com/secure-software-engineering/phasar/wiki/Coding-Conventions) and [Contributing to PhASAR](https://github.com/secure-software-engineering/phasar/wiki/Contributing-to-PhASAR). +PhASAR is primarily developed and maintained by the Secure Software Engineering Group at Heinz Nixdorf Institute (University of Paderborn) and Fraunhofer IEM. -To install the pre-commit hook, please run the following commands in PhASAR's root directory: +PhASAR was initially developed by Philipp Dominik Schubert (@pdschubert)(). -```bash -pip install pre-commit -pre-commit install -``` +Currently, PhASAR is maintained by -Thanks. And have fun with the project. +- Fabian Schiebel (@fabianbs96)() +- Sriteja Kummita (@sritejakv) +- Lucas Briese (@jusito) +- Martin Mory (@MMory)() +- *others*