{"id":13641879,"url":"https://github.com/PKU-ASAL/WASEM","last_synced_at":"2025-04-20T12:30:50.967Z","repository":{"id":192852419,"uuid":"687562427","full_name":"PKU-ASAL/WASEM","owner":"PKU-ASAL","description":"WASEM - a general symbolic execution framework for WebAssembly (WASM) binaries","archived":false,"fork":false,"pushed_at":"2024-09-30T12:00:08.000Z","size":2458,"stargazers_count":12,"open_issues_count":1,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-09T12:39:33.476Z","etag":null,"topics":["program-analysis","symbolic-execution","vulnerability-detection","webassembly"],"latest_commit_sha":null,"homepage":"","language":"WebAssembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PKU-ASAL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-09-05T15:55:56.000Z","updated_at":"2024-09-30T12:00:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"b6a65132-a585-4168-81d7-8562ab455c0d","html_url":"https://github.com/PKU-ASAL/WASEM","commit_stats":null,"previous_names":["pku-asal/wasem"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKU-ASAL%2FWASEM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKU-ASAL%2FWASEM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKU-ASAL%2FWASEM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PKU-ASAL%2FWASEM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PKU-ASAL","download_url":"https://codeload.github.com/PKU-ASAL/WASEM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249893348,"owners_count":21341434,"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":["program-analysis","symbolic-execution","vulnerability-detection","webassembly"],"created_at":"2024-08-02T01:01:25.302Z","updated_at":"2025-04-20T12:30:50.956Z","avatar_url":"https://github.com/PKU-ASAL.png","language":"WebAssembly","funding_links":[],"categories":["Defenses"],"sub_categories":["Library OSes and SDKs"],"readme":"\u003cdiv style=\"text-align: center;\"\u003e\n  \u003cimg src=\"pic/logo.png\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n[![test](https://github.com/PKU-ASAL/WASEM/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/PKU-ASAL/WASEM)\n\n**WASEM is a general symbolic execution framework for WebAssembly (WASM) binaries.** It serves as the **core engine** for multiple **WASM binary analysis** tools and can be used to analyse both normal WASM programs and WASM files compiled from SGX programs *(see our ISSTA and CCS paper in the Citations section)*. Our framework processes the WASM file compiled from the source code of C/C++/Rust/Go, performs symbolic execution, and generates detailed vulnerability reports. These reports include the vulnerability type, location, and the corresponding constraints.\n\n##  Prerequisites \n\nTo run WASEM, ensure you have Python 3.7 or a later version installed. Then, install the required Python libraries by executing the following command:\n\n```shell\npython3 -m pip install -r requirements.txt\n```\n\nIf you encounter issues building the wheel for leb128, update pip and wheel, then reinstall leb128:\n\n```shell\npip install --upgrade pip wheel\npip install --force-reinstall leb128\n```\n\nTo verify everything is set up correctly, run the following command:\n\n```shell\npython3 -m pytest test.py -vv\n```\n\nThis command traverses the `./test` folder and performs symbolic execution on all Wasm binaries.\nIf successful, a success message will be displayed, typically **after several seconds**.\n\nSample Wasm binaries, including \"Hello World\" in C, Go, and Rust, are provided in the folder. \nThese can be compiled from their respective source languages; the compilation processes are detailed in [WASI tutorial](https://github.com/bytecodealliance/wasmtime/blob/main/docs/WASI-tutorial.md#compiling-to-wasi) (C and Rust), and [WASI \"Hello World\" example](https://wasmbyexample.dev/examples/wasi-hello-world/wasi-hello-world.go.en-us.html) (Go).\n\nFor Rust and C++ project, you can use `wasm-tools` to demangle symbol names in the `name` section. Install with `cargo install wasm-tools`. Confirm by `wasm-tools --version`. Details can be found at [Wasm Tools](https://github.com/bytecodealliance/wasm-tools).\n\n## Normal Mode\n\nThis section demonstrates how to use WASEM to analyze normal Wasm file.\n\n### Options\nAll valid options are shown in below:\n\n```shell\nWASEM, a general symbolic execution framework for WebAssembly (WASM) binaries\n\noptional arguments:\n  -h, --help            show this help message and exit\n\nInput arguments:\n  -f WASMMODULE, --file WASMMODULE\n                        binary file (.wasm)\n  --stdin STDIN         stream of stdin\n  --sym_stdin SYM_STDIN\n                        stream of stdin in N bytes symbols\n  --args ARGS           command line\n  --sym_args SYM_ARGS [SYM_ARGS ...]\n                        command line in symbols, each of them is N bytes at most\n  --sym_files SYM_FILES SYM_FILES\n                        Create N symbolic files, each of them has M symbolic bytes\n  --source_type [{c,go,rust}]\n                        type of source file\n\nFeatures:\n  --entry ENTRY         set entry point as the specilized function\n  --visualize           visualize the ICFG on basic blocks level\n  --incremental         enable incremental solving\n  -v [{warning,info,debug}], --verbose [{warning,info,debug}]\n                        set the logging level\n\nAnalyze:\n  -s, --symbolic        perform the symbolic execution\n  --search [{dfs,bfs,random,interval}]\n                        set the search algorithm\n```\n\nWe will detail these options according to their functionalities.\n\n### Input Arguments\nWASEM can deassemble the target binary and construct valid inputs based on the values of the input arguments.\n\nSpecifically, `-f` option is mandatory, and it must be followed by the path of the Wasm binary to be analyzed. The `--stdin STRING` and `--sym_stdin N` options allow users to pass concrete and symbolic bytes through the stdin stream, respectively. A concrete string must be passed using `--stdin`, while a string consisting of `N` symbolic characters must be passed using `--sym_stdin`. For example, `--sym_stdin 5` inputs 5 symbolic bytes for functions that read from stdin.\n\nSimilarly, `--args STRING1, STRING2, ...` and `--sym_args N1, N2, ...` options pass concrete and symbolic arguments to the Wasm binary. For instance, if `main` requires three arguments, each two bytes long, `--sym_args 2 2 2` is enough.\n\nSome programs interact with files. WASEM simulates this using a *symbolic file system*. Users can create `N` symbolic files, each with up to `M` bytes, using the `--sym_files N M` option.\n\nAs multiple high-level programming languages can be compiled to Wasm binaries, we have implemented specific optimizations. To take advantage of these optimizations, users must indicate the source language using the `--source_type` option.\n\n### Features\n`--entry` specifies the entry function from which symbolic execution begins. By default, the entry function is `__original_main`. Users must specify a proper entry function to ensure the symbolic execution is performed correctly.\n\nThe input Wasm is parsed into an Interprocedural Control Flow Graph (ICFG), which can be visualized for debugging purposes using the `--visualize` option (requires `graphviz`, installable via `sudo apt install graphviz` on Ubuntu).\n\nThe constraint solving process is a bottleneck for symbolic execution performance; however, we have implemented some optimizations to mitigate this issue. The `--incremental` flag enables *incremental solving*. Note that it may not always yield positive results during analysis, and is therefore optional.\n\nThe `-v` option controls the logging level, allowing users to adjust the verbosity of logging output to aid in debugging.\n\n### Analyze\nThe `-s` is a mandatory option. It enables symbolic execution analysis on the given Wasm binary.\n\nThe `--search` option specifies the search algorithm used during symbolic execution. The default algorithm is Depth-First Search (DFS), but users can choose from the following options: `bfs`, `random`, and `interval`.\n\n### Output\nThe output of WASEM, including logs and results, is stored in the `output` folder, with each file named according to the pattern `NAME_TIMESTAMP`.\n\nThe log file follows a specific format, which illustrates the call trace of the anaylzed program:\n\n```log\n2024-07-01 07:50:36,191 | WARNING | Totally remove 27 unrelated functions, around 50.000% of all functions\n2024-07-01 07:50:36,205 | INFO | Call: __original_main -\u003e __main_void\n2024-07-01 07:50:36,218 | INFO | Call: __main_void -\u003e __wasi_args_sizes_get\n2024-07-01 07:50:36,219 | INFO | Call: args_sizes_get (import)\n2024-07-01 07:50:36,219 | INFO | \targs_sizes_get, argc_addr: 70792, arg_buf_size_addr: 70796\n2024-07-01 07:50:36,219 | INFO | Return: args_sizes_get (import)\n2024-07-01 07:50:36,219 | INFO | Return: __wasi_args_sizes_get\n...\n```\n\nThe result is a JSON file containing feasible paths with their solutions, formatted as follows:\n\n```json\n{\n    \"Status\": \"xxx\",\n    \"Solution\": {\"xxx\"},\n    \"Output\": [\n        {\n            \"name\": \"stdout\",\n            \"output\": \"xxx\"\n        },\n        {\n            \"name\": \"stderr\",\n            \"output\": \"xxx\"\n        }\n    ]\n}\n```\n\nYou can use `./clean.sh -f` to remove all files in the `output` folder.\n\n### Example\nTo execute a program that takes no extra arguments or input, use the following command:\n\n```shell\npython3 launcher.py -f PATH_TO_WASM_BINARY -s\n```\n\nIf compilicated arguments are required, for example, a `base64` program with a `main` function like:\n\n```c\n// main of base64\nint main(int argc, char **argv)\n{\n  // environment setting\n  ...\n\n  while ((opt = getopt_long(argc, argv, \"diw:\", long_options, NULL)) != -1)\n    switch (opt) {\n      // call functions according to passed arguments\n      ...\n    }\n\n  // encode or decode\n}\n```\n\nThe `base64` program expects two-byte arguments and a string input to encode or decode, producing output that is written to a file.\nThus, the command to analyze `base64` is like:\n\n```shell\npython3 launcher.py -f PATH_TO_BASE64 -s --sym_args 2 --sym_stdin 5 --sym_files 1 10\n```\n\n## SGX Mode\n\n### Compilation\n\nWe compile the C/C++ SGX programs into WASM files using [wllvm](https://github.com/travitch/whole-program-llvm) and [wabt](https://github.com/WebAssembly/wabt). Initially, we replace the compiler used in the makefile of SGX programs with the compilers of wllvm and compile them with the -g compile flag.\n\n```shell\n# Install prerequisites\nsudo apt update\nsudo apt-get install cmake libstdc++6-7-dbg libssl-dev\n# Download wabt\ngit clone --recursive https://github.com/WebAssembly/wabt\ncd wabt\ngit submodule update --init\n# Build wabt\nmkdir build\ncd build\ncmake ..\ncmake --build .\nexport PATH=$(pwd):$PATH\n\n# OR: for Ubuntu 22.04, you can directly use wabt pre-built releases\ncurl -JLO \"https://github.com/WebAssembly/wabt/releases/download/1.0.32/wabt-1.0.32-ubuntu.tar.gz\"\ntar xzf wabt-1.0.32-ubuntu.tar.gz\nexport PATH=$(pwd)/wabt-1.0.32/bin:$PATH\n\n# Compile\nCC=wllvm CXX=wllvm++ make SGX_MODE=SIM \nextract-bc xxx.so\nllvm-dis xxx.bc\nllc -march=wasm32 -filetype=obj xxx.ll\nwasm-ld  --no-entry --export-all xxx.o --allow-undefined\nwasm2wat xxx.wasm -o xxx.wat\n```\n\nWe have successfully compiled several benchmarks, which can be found in the `benchmarks/` directory.\n\n\n### Input Arguments\n\nOur tool can be used by executing the `main.py` with the appropriate parameters. Four arguments are required. The first argument is the name of the wasm file to analyze. The second argument is the ECall list of the program, separated by commas (`,`). The third argument, which is optional, is the function list of the wasm file. If a corresponding wat file exists in the same path as the wasm file, the third argument can be omitted. The fourth argument is the mode to run WASEM. If `--symgx` is set, it will be run in SGX mode, or it will be run in normal mode. For instance, to analyze the `sgx-dent` program in SGX mode for 12 hours, execute the following command:\n\n```shell\npython3 main.py -f benchmarks/dnet.wasm --ecall-list sgx_empty_ecall,sgx_ecall_trainer,sgx_ecall_tester,sgx_ecall_classify --symgx --max-time 43200\n```\n\nIt is worth noting that although we set the `--ecall-list` and `--func-list` manually, they can be automatically obtained using automated tools. However, as this is not the primary focus of this project, we leave it for future work.\n\nTo facilitate a more convenient analysis of the samples in the `benchmarks/` directory, we have provided a script. You can analyze benchmarks by executing the script with the name of the program you wish to analyze. For instance, to analyze the `sgx-dent` program, use the following command:\n\n```shell\n./run.sh sgx-dnet --max-time 43200\n```\n\nOther available programs include `sgxwallet`, `SGXCryptoFile`, `verifiable-election`, `sgx-log`, `sgx-kmeans`, `sgx-reencrypt`, `CryptoEnclave`, `sgx-pwenclave`, `sgx-deep-learning`, `sgx-biniax2`, `sgx-rsa`, `sgx_protect_file` and `SGXSSE`.\n\n### Output Report\n\nThe vulnerability reports will be generated in the directory `output/result/PROGRAM_NAME`. The format of a vulnerability report is as follows:\n\n```shell\n{\n    \"Status\": xxx,\n    \"Solution\": {xxx},\n    \"Basic_Blocks\": [xxx],\n    \"vulnerability\": xxx,\n    \"iteration round\": xxx,\n}\n```\n\nThe `Solution` field represents a set of values that can lead to the vulnerability instruction. `Basic_Blocks` records all the basic blocks encountered during the execution process, which can be used to restore the execution path and the ECall sequence. `Vulnerability` indicates the type of the vulnerability. `iteration round` is the round number of the vulnerability state.\n\n## Citations\n\nIf you use any of our tools or datasets in your research for publication, please kindly cite the following paper:\n\n```\n@inproceedings{he2023eunomia,\n  author = {He, Ningyu and Zhao, Zhehao and Wang, Jikai and Hu, Yubin and Guo, Shengjian and Wang, Haoyu and Liang, Guangtai and Li, Ding and Chen, Xiangqun and Guo, Yao},\n  title = {Eunomia: Enabling User-Specified Fine-Grained Search in Symbolically Executing WebAssembly Binaries},\n  year = {2023},\n  isbn = {9798400702211},\n  publisher = {Association for Computing Machinery},\n  address = {New York, NY, USA},\n  url = {https://doi.org/10.1145/3597926.3598064},\n  doi = {10.1145/3597926.3598064},\n  booktitle = {Proceedings of the 32nd ACM SIGSOFT International Symposium on Software Testing and Analysis},\n  pages = {385–397},\n  numpages = {13},\n  keywords = {WebAssembly, Symbolic Execution, Domain Specific Language, Path Explosion},\n  location = {Seattle, WA, USA},\n  series = {ISSTA 2023}\n}\n\n```\n\n```\n@inproceedings{wang2023symgx,\n  title={SymGX: Detecting Cross-boundary Pointer Vulnerabilities of SGX Applications via Static Symbolic Execution},\n  author={Wang, Yuanpeng and Zhang, Ziqi and He, Ningyu and Zhong, Zhineng and Guo, Shengjian and Bao, Qinkun and Li, Ding and Guo, Yao and Chen, Xiangqun},\n  booktitle={Proceedings of the 2023 ACM SIGSAC Conference on Computer and Communications Security},\n  pages={2710--2724},\n  year={2023}\n}\n```\n\n## Feedback\n\nIf you have any questions or need further clarification, please post on the [Issues](https://github.com/PKU-ASAL/WASEM/issues) page, or you can directly email Yuanpeng Wang at [yuanpeng_wang@pku.edu.cn](yuanpeng_wang@pku.edu.cn).\n\n## Acknowledgements\n\nWe would like to thank the anonymous reviewers for their valuable feedback and suggestions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPKU-ASAL%2FWASEM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPKU-ASAL%2FWASEM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPKU-ASAL%2FWASEM/lists"}