{"id":14991161,"url":"https://github.com/csl-ugent/esss","last_synced_at":"2025-04-12T03:30:40.807Z","repository":{"id":230249015,"uuid":"763980219","full_name":"csl-ugent/ESSS","owner":"csl-ugent","description":"Static analysis tool to detect missing and incorrect error checks in C and C++ codebases without using a priori knowledge.","archived":false,"fork":false,"pushed_at":"2024-10-07T11:36:37.000Z","size":825,"stargazers_count":13,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T23:06:43.258Z","etag":null,"topics":["error-checks","llvm","static-analysis"],"latest_commit_sha":null,"homepage":"https://www.usenix.org/conference/usenixsecurity24/presentation/dossche","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csl-ugent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-27T09:08:10.000Z","updated_at":"2025-02-28T02:55:50.000Z","dependencies_parsed_at":"2024-03-28T17:03:58.529Z","dependency_job_id":"3cdc4e2b-5a46-418d-bede-c1afe6fc4fb4","html_url":"https://github.com/csl-ugent/ESSS","commit_stats":{"total_commits":35,"total_committers":1,"mean_commits":35.0,"dds":0.0,"last_synced_commit":"1c9615154cc190dcebcfc886ffacea68e7085213"},"previous_names":["csl-ugent/esss"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csl-ugent%2FESSS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csl-ugent%2FESSS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csl-ugent%2FESSS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csl-ugent%2FESSS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csl-ugent","download_url":"https://codeload.github.com/csl-ugent/ESSS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248512454,"owners_count":21116602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-checks","llvm","static-analysis"],"created_at":"2024-09-24T14:21:36.819Z","updated_at":"2025-04-12T03:30:40.784Z","avatar_url":"https://github.com/csl-ugent.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESSS\n\nESSS is a static analysis tool to detect missing and incorrect error checks in C and C++ codebases.\nThe tool automatically deduces error specifications for functions, without needing a priori knowledge, and then it finds code locations where error checks are either missing or inconsistent with those specifications. \n\nThis repository contains the ESSS source code, as well as the scripts and data to run the tool and EESI on the benchmarks used in the paper.\n\nThe artifact evaluation VM already contains the ESSS tool and the LLVM toolchain pre-built.\nThe LLVM version used is 14.0.6.\nThe reason we perform the build ourselves rather than a distro-provided version is to ensure reproducibility of the exact results without having potentially-interfering distro-specific patches.\n\nThe tool is supported on any recent Linux distribution. We confirmed that it works for sure on Ubuntu 22.04.\nNo special hardware requirements are necessary to run ESSS, although we do recommend at least 8 GiB of RAM. Even though the tool can run with less, it may take up to 2 GiB of RAM for the largest benchmark, leaving fewer memory for other processes.\n\n## Tool build instructions\n\nIf you wish to manually build the ESSS tool and/or the LLVM toolchain, follow these instructions.\n\n### Dependencies\n\nThe following dependencies are required to build the ESSS tool:\n  * CMake\n  * A C and C++ compiler to build the LLVM dependency\n\n### Build LLVM\n```sh\n$ cd /home/evaluation/ESSS/llvm\n$ mkdir llvm-project\n$ cd llvm-project\n$ wget https://github.com/llvm/llvm-project/releases/download/llvmorg-14.0.6/clang-14.0.6.src.tar.xz\n$ wget https://github.com/llvm/llvm-project/releases/download/llvmorg-14.0.6/llvm-14.0.6.src.tar.xz\n$ tar xf llvm-14.0.6.src.tar.xz \n$ tar xf clang-14.0.6.src.tar.xz \n$ mv clang-14.0.6.src clang\n$ mv llvm-14.0.6.src llvm\n$ cd ..\n$ ./build-llvm.sh\n```\n\n### Build the analyzer\n```sh\n$ cd /home/evaluation/ESSS/analyzer\n$ make\n```\n\nThis will build the analyzer tool and place the binary in the `/home/evaluation/ESSS/analyzer/build/lib` directory.\n\n## Tool usage instructions\n\n### Prerequisites\n\nWhen applying the tool to your own benchmarks, you'll need to generate the bitcode files first.\nTo do so, you should use [wllvm](https://github.com/travitch/whole-program-llvm). Follow the installation instructions on the wllvm README page.\n\nFurthermore, we also rely on [musl](https://musl.libc.org/) to infer specifications from libc.\nWhile not strictly necessary for the tool to work, this will increase the precision of the inferred specifications.\nThe version used in the paper was musl 1.2.3, but any version should work.\nThese are the steps to build musl into a bitcode file:\n```sh\ncd musl\nmkdir prefix\nexport CC=wllvm\n./configure --prefix=\"$(realpath prefix)\"\nmake -j4\nmake install\nextract-bc prefix/lib/libc.so\n```\n\n### Compiling a program\n\nTo compile a program for use with our tool, you should follow the build instructions of said program, but use the wllvm wrapper as a compiler. This will result in bitcode files that can be analyzed by our tool. Ideally, you pass all bitcode files separately to our tool, as giving the entire program at once (which is what happens by default by extract-bc) will be slower to process than separate files.\n\n### Running the tool\n\nThe tool can be executed directly by executing `./kanalyzer` inside `/home/evaluation/ESSS/analyzer/build/lib`.\nThe arguments are the paths to the bitcode files. The output is written to stdout.\nThe tool also contains some optional arguments that can be listed using the `--help` option.\n\nTo run the tool for inferring specifications and detecting bugs in a program, you can use the following command:\n```sh\n./kanalyzer /path/to/mysl/libc.so.bc /path/to/bitcode1.bc /path/to/bitcode2.bc ...\n```\n\nThe output will be written to stdout, this includes the inferred specifications and the bugs.\n\n### Options\n\nThe tool supports configuration options that can be set using command line arguments.\n\nThe most important configuration options are:\n  * `--missing-ct`: The threshold for missing checks. Only reports with a score that is at least this value will be reported. The default value is 0.725.\n  * `--incorrect-ct`: The threshold for incorrect specifications. Only reports with a score that is at least this value will be reported. The default value is 0.725.\n\nOther useful options include:\n  * `--refine-vsa`: This enables taking the intersection between the error value set and the possible constant return values of the function to increase the precision of the error specifications. Defaults to true.\n  * `--st`: Association analysis confidence between [0, 1]. The higher the more confident the association must be. Defaults to 0.925.\n  * `--interval-ct`: Confidence threshold between [0, 1]. The higher the more similar the error intervals should be.\n  * `-c \u003cnumber\u003e`: Sets the number of threads to `\u003cnumber\u003e`. Not thoroughly tested for values other than 1.\n\nThere are a few debugging options as well:\n  * `--print-random-non-void-function-samples \u003cnumber\u003e`: How many random non-void function names to print, useful for sampling functions to compute a recall. Defaults to 0.\n  * `--ssc`: Prints the detected error checks out separately. Defaults to false.\n\n### Minimal example\n\nWe provide a minimal example in the `example` directory. There is some simple toy code in `example/example.c` that you can run through the analyzer using the `example/build_and_run.sh` script. Upon running you should get the following output:\n\n```\nFunction error return intervals (3, pre-libc-pruning 3):\nFunction: func {return index 0}\n  [0, 0]\nFunction: generate_error {return index 0}\n  [-2147483648, -1] U [1, 2147483647]\nFunction: malloc {return index 0}\n  [0, 0]\n```\n\n## Repository structure\n\nThe repository is structured as follows. Files adapted from [Crix](https://github.com/umnsec/crix) are marked as such.\n\n```\n📁 ESSS\n│ ├── 📁 analyzer [the ESSS tool source code]\n│ │   │ ├── 📃 Makefile [adapted from Crix]\n│ │   │ └── 📁 src\n│ │   │     │ ├── 📃 ...\n│ │   │     │ └── 📁 src\n│ │   │     │     │ ├── 📃 Analyzer.{cc, h} [Entry point of the application, adapted from Crix]\n│ │   │     │     │ ├── 📃 CallGraph.{cc, h} [MLTA component from Crix]\n│ │   │     │     │ ├── 📃 ClOptForward.h [Forward declarations of command line options]\n│ │   │     │     │ ├── 📃 Common.{cc, h} [Common utility functions, adapted from Crix]\n│ │   │     │     │ ├── 📃 DataFlowAnalysis.{cc, h} [Dataflow analysis helpers]\n│ │   │     │     │ ├── 📃 DebugHelpers.{cc, h} [Debugging helpers]\n│ │   │     │     │ ├── 📃 EHBlockDetector.{cc, h} [Specification inference component]\n│ │   │     │     │ ├── 📃 ErrorCheckViolationFinder.{cc, h} [Bug detection component]\n│ │   │     │     │ ├── 📃 FunctionErrorReturnIntervals.{cc, h} [Data structure file]\n│ │   │     │     │ ├── 📃 FunctionVSA.{cc, h} [Value set analysis of return values component]\n│ │   │     │     │ ├── 📃 Helpers.{cc, h} [Common utility functions]\n│ │   │     │     │ ├── 📃 Interval.{cc, h} [Interval data structure]\n│ │   │     │     │ ├── 📃 Lazy.h [Lazy execution utility class]\n│ │   │     │     │ ├── 📃 MLTA.{cc, h} [MLTA component from Crix]\n│ │   │     │     │ └── 📃 PathSpan.h [Data structure to store (parts of) paths]\n│ └── 📁 evaluation [Scripts and data to run the tool on the benchmarks]\n│     │ ├── 📁 benchmark-instructions [Instructions to compile each benchmark into bitcode files]\n│     │ ├── 📃 ...\n│     │ ├── 📃 eesi-\u003cprogram\u003e-output [Our EESI output for \u003cprogram\u003e]\n│     │ ├── 📃 eesi-\u003cprogram\u003e-precision [Random sample from EESI's output for \u003cprogram\u003e for precision calculation]\n│     │ ├── 📃 run-eesi-\u003cprogram\u003e.sh [Runs EESI for \u003cprogram\u003e (e.g. openssl)]\n│     │ ├── 📃 my-\u003cprogram\u003e-output [Our ESSS output for \u003cprogram\u003e]\n│     │ ├── 📃 run-my-\u003cprogram\u003e.sh [Runs ESSS for \u003cprogram\u003e (e.g. openssl)]\n│     │ ├── 📃 \u003cprogram\u003e-bugs [Bug categorisations for \u003cprogram\u003e (e.g. openssl)]\n│     │ ├── 📃 \u003cprogram\u003e-recall-sample [Random sample from error-returning functions in \u003cprogram\u003e for recall calculation]\n│     │ ├── 📃 \u003cprogram\u003e-precision-ground-truth [Ground truth for precision evaluation for ESSS]\n│     │ ├── 📃 \u003cprogram\u003e-random-functions-for-precision-my-tool [Random sample from ESSS's output for \u003cprogram\u003e for precision calculation]\n│     │ ├── 📃 compute_my_stats.py [Computes stats for ESSS for a program]\n│     │ └── 📃 compute_eesi_stats.py [Computes stats for EESI for a program]\n```\n\nIn particular, the specification inference is implemented in EHBlockDetector.cc and the bug detection in ErrorCheckViolationFinder.cc.\n\n## Evaluation scripts\n\nThe instructions for running each benchmark are provided in the `evaluation/benchmark-instructions` directory.\nTo run one of the benchmarks, execute the corresponding script in the `evaluation` directory (as described in the above repository structure overview).\n\n* `compute_my_stats.py`: This script computes the precision, recall, and F1 score of the ESSS tool for a given benchmark.\n* `compute_eesi_stats.py`: This script computes the precision, recall, and F1 score of the EESI tool for a given benchmark.\n* `run-eesi-\u003cprogram\u003e.sh`: This script runs the EESI tool on the given benchmark.\n* `run-my-\u003cprogram\u003e.sh`: This script runs the ESSS tool on the given benchmark.\n\n## Tool evaluation\n\nTo ease the evaluation, we provided for each benchmark a run script to run the tool.\nThese can be found in `/home/evaluation/ESSS/evaluation`:\n  * `run-my-openssl.sh`\n  * `run-my-openssh.sh`\n  * `run-my-php.sh`\n  * `run-my-zlib.sh`\n  * `run-my-libpng.sh`\n  * `run-my-freetype.sh`\n  * `run-my-libwebp.sh`\n\n## Virtual Machine\n\nThe evaluation artifact is provided as a [VirtualBox VM image](https://zenodo.org/doi/10.5281/zenodo.10843435) on Zenodo.\nTo build the VM image, we started from a Ubuntu 22.04 LTS (x86-64) installation.\nWe can then use the script provided in `vm/build-vm.sh` to install and setup everything needed for the evaluation.\n\n## License\n\nThis tool is based on the [Crix](https://github.com/umnsec/crix) tool from the University of Minnesota.\nIn particular, we reuse the MLTA component of Crix.\nESSS is distributed under the same license.\n\n## More details\n\nLink to the Usenix paper publication page: https://www.usenix.org/conference/usenixsecurity24/presentation/dossche\n\nLink to the final publication PDF: https://www.usenix.org/system/files/usenixsecurity24-dossche.pdf\n\nLink to the final artifact appendix PDF (Available, Functional, Reproduced badges): https://www.usenix.org/system/files/usenixsecurity24-appendix-dossche.pdf\n\n```\n@inproceedings {dossche2024inferenceoferrorspecifications,\n  author = {Niels Dossche and Bart Coppens},\n  title = {Inference of Error Specifications and Bug Detection Using Structural Similarities},\n  booktitle = {33rd USENIX Security Symposium (USENIX Security 24)},\n  year = {2024},\n  isbn = {978-1-939133-44-1},\n  address = {Philadelphia, PA},\n  pages = {1885--1902},\n  url = {https://www.usenix.org/conference/usenixsecurity24/presentation/dossche},\n  publisher = {USENIX Association},\n  month = aug\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsl-ugent%2Fesss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsl-ugent%2Fesss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsl-ugent%2Fesss/lists"}