{"id":28633593,"url":"https://github.com/softsec-kaist/suri","last_synced_at":"2025-06-12T15:09:16.677Z","repository":{"id":275248245,"uuid":"924975340","full_name":"SoftSec-KAIST/SURI","owner":"SoftSec-KAIST","description":"Towards Sound Reassembly of Modern x86-64 Binaries (ASPLOS'25)","archived":false,"fork":false,"pushed_at":"2025-03-28T06:51:22.000Z","size":17394,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T07:22:20.305Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"F#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SoftSec-KAIST.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-01-31T01:17:59.000Z","updated_at":"2025-03-26T03:43:49.000Z","dependencies_parsed_at":"2025-03-28T07:31:37.083Z","dependency_job_id":null,"html_url":"https://github.com/SoftSec-KAIST/SURI","commit_stats":null,"previous_names":["softsec-kaist/suri"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SoftSec-KAIST/SURI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FSURI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FSURI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FSURI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FSURI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftSec-KAIST","download_url":"https://codeload.github.com/SoftSec-KAIST/SURI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FSURI/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259490550,"owners_count":22865769,"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":[],"created_at":"2025-06-12T15:09:15.214Z","updated_at":"2025-06-12T15:09:16.657Z","avatar_url":"https://github.com/SoftSec-KAIST.png","language":"F#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SURI: Towards Sound Reassembly of Modern x86-64 Binaries\n\nSURI is a binary reassembler for CET- and PIE-enabled x86-64 binaries. For a\ndetailed technical description, please refer to our paper \"Towards Sound\nReassembly of Modern x86-64 Binaries\", which will be published in the ACM\nInternational Conference on Architectural Support for Programming Languages and\nOperating Systems (ASPLOS) 2025.\n\nIf you are interested in our artifact, visit [here](artifact/README.md)\n\n## Dependencies\n\nSURI requires the following software dependencies:\n\n- .NET 9.0\n- Python 3 (with pip)\n- gcc-11\n\n.NET is necessary for our Superset CFG Builder, which is based on\n[B2R2](https://github.com/B2R2-org/B2R2). All other components of SURI are\nwritten in Python 3. Lastly, our reassembler internally uses `gcc-11` for the\nreassembly process.\n\nIf you have installed Python 3, you need to install\n[pyelftools](https://github.com/eliben/pyelftools) using the following command:\n```\n$ pip install pyelftools\n```\n\n\n## Install SURI\n\nYou need to build our Superset CFG Builder and install SURI Python project in order to use SURI.\nTry:\n```\n$ python3 setup.py install --user # install SURI Python project\n$ cd superCFGBuilder\n$ dotnet build # build Superset CFG Builder\n```\n\n### Docker environment\n\nWe also provide Docker environment in case you don't want to struggle to set up\nthe software dependencies. You still need to install SURI python project though.\nType this on your shell:\n```\n$ python3 setup.py install --user # install SURI Python project\n$ docker build --tag suri:v1.0 . # build Docker image for .NET and gcc-11\n```\n\nNote that you still need Python 3 because the top-level SURI script runs on\noutside of the Docker image.\n\n\n## Usage\n\nIf you want to reassemble a target binary, use following command;\n```\n$ python3 suri.py [target_binary_path]\n```\n\nFor example, to rewrite the 7zip binary located at artifact/realworld/phoronix/7zip, run SURI as follows:\n```\n$ python3 suri.py artifact/realworld/phoronix/7zip\n[+] Generate assembly file: 7zip.s\n[+] Generate rewritten binary: /test/SURI/my_7zip\n```\n\nSURI generates a reassembled binary.\n```\n$ ls -al my_7zip\n-rw-rw-r-- 1 test  test 7428218  Jan  1 00:00 my_7zip\n```\n\n#### Running SURI in a Docker environment\n\nIf you want to use the Docker environment, you need to pass the `--usedocker` flag to SURI.\n```\npython3 suri.py [target binary path] --usedocker\n```\n\nThis will make that Superset CFG Builder and compiler for reassembly run inside the provided Docker image.\n\n### Two-step SURI execution\n\nIf you want to manually instrument the assembly file from the target binary, follow the steps below.\n\n#### 1. Generating assembly code using SURI\n\nIf you want to generate the assembly file without compiling it, use the `--without-compile` option:\n```\npython3 suri.py [target binary path] [--without-compile]\n```\n\nFor example,\n```\n$ python3 suri.py artifact/realworld/phoronix/7zip --without-compile\n[+] Generate assembly file: 7zip.s\n```\n\nSURI will generate an assembly file with the `.s` extension:\n```\n$ ls -al 7zip.s\n-rw-rw-r-- 1 test  test 43578474 Jan  1 00:00 7zip.s\n```\nYou can modify the assembly code for instrumentation if necessary.\n\n#### 2. Compiling the assembly file\n\nAfter editing the assembly file, you can compile the assembly file using `emitter.py` script:\n```\n$ python3 emitter.py artifact/realworld/phoronix/7zip 7zip.s\n[+] Generate rewritten binary: /test/SURI/my_7zip\n```\n\n## Application\n\n### Binary Only Address Sanitizer\nIf you want to enable the AddressSanitizer feature in the target binary,\nuse the `--asan` option. This will generate a binary with memory sanitizing\ncode inserted.\n```\npython3 suri.py [target_binary_path] --asan\n```\n\nFor example,\n```\n$ python3 suri.py artifact/realworld/phoronix/7zip --asan\n[+] Generate assembly file: 7zip.s\n[+] Generate rewritten binary: /test/SURI/my_7zip\n```\n\n## Directory Structure\n\nThis tree shows some important files and directories only.\n\n```\n.\n├── artifact/                   : contains files related to the artifact evaluation\n├── superCFGBuilder/            : contains our Superset CFG Builder module\n├── superSymbolizer/\n│   ├── lib/\n│   │   └── CFGSerializer.py    : contains our CFG Serializer module\n│   ├── CustomCompiler.py.py    : contains our Emitter module\n│   └── SuperSymbolizer.py      : contains our Pointer Repairer and Superset Symbolizer modules\n├── README.md                   : this document\n└── suri.py                     : the main entry point of SURI\n└── emitter.py                  : a script for compiling assembly file\n```\n\n## Citation\n\nIf you want to cite SURI:\n```\n@inproceedings{kim:asplos:2025,\n  author = {Kim, Hyungseok and Kim, Soomin and Cha, Sang Kil},\n  title = {Towards Sound Reassembly of Modern x86-64 Binaries},\n  year = {2025},\n  url = {https://doi.org/10.1145/3676641.3716026},\n  doi = {10.1145/3676641.3716026},\n  booktitle = {Proceedings of the 30th ACM International Conference on Architectural Support for Programming Languages and Operating Systems, Volume 2},\n  pages = {1317–1333},\n  numpages = {17},\n  series = {ASPLOS '25}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Fsuri","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftsec-kaist%2Fsuri","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Fsuri/lists"}