{"id":13639062,"url":"https://github.com/SoftSec-KAIST/Eclipser","last_synced_at":"2025-04-19T21:35:29.735Z","repository":{"id":48446585,"uuid":"167912156","full_name":"SoftSec-KAIST/Eclipser","owner":"SoftSec-KAIST","description":"Grey-box Concolic Testing on Binary Code (ICSE '19)","archived":false,"fork":false,"pushed_at":"2021-10-04T06:52:39.000Z","size":240,"stargazers_count":148,"open_issues_count":3,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-03T01:13:47.342Z","etag":null,"topics":["concolic-testing","fsharp","fuzzer","fuzzing","testcase-generator"],"latest_commit_sha":null,"homepage":"","language":"F#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SoftSec-KAIST.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-28T06:41:58.000Z","updated_at":"2024-07-24T23:06:24.000Z","dependencies_parsed_at":"2022-09-05T03:41:49.503Z","dependency_job_id":null,"html_url":"https://github.com/SoftSec-KAIST/Eclipser","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftSec-KAIST","download_url":"https://codeload.github.com/SoftSec-KAIST/Eclipser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810255,"owners_count":17206722,"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":["concolic-testing","fsharp","fuzzer","fuzzing","testcase-generator"],"created_at":"2024-08-02T01:00:57.278Z","updated_at":"2024-11-09T09:30:33.266Z","avatar_url":"https://github.com/SoftSec-KAIST.png","language":"F#","readme":"Eclipser\n========\n\nEclipser is a binary-based fuzz testing tool that improves upon classic\ncoverage-based fuzzing by leveraging a novel technique called *grey-box concolic\ntesting*. The details of the technique can be found in our paper \"Grey-box\nConcolic Testing on Binary Code\", which is published in ICSE 2019.\n\n# Installation\n\nEclipser currently supports Linux ELF binaries, and has been tested on Debian\nand Ubuntu. Eclipser is written in F# and runs on .NET Core. Also, Eclipser\nperforms program instrumentation based on QEMU code.\n\n1. Install dependencies\n\n```\n$ sudo vim /etc/apt/sources.list # Uncomment the lines starting with 'deb-src'.\n$ sudo apt-get update\n$ sudo apt-get build-dep qemu\n$ sudo apt-get install libtool libtool-bin wget automake autoconf bison gdb python\n```\n\n2. Install .NET Core\n\nInstallation differs for each Linux distribution, so please refer to this\n[link](https://www.microsoft.com/net/download/linux-package-manager/ubuntu18-04/sdk-current).\nChoose your Linux distribution and version from the tab and follow the\ninstructions.\n\n3. Clone and build Eclipser\n\n```\n$ git clone https://github.com/SoftSec-KAIST/Eclipser\n$ cd Eclipser\n$ make\n```\n\n# Usage\n\n- Running with AFL\n\nStarting from v2.0, Eclipser only performs grey-box concolic testing for test\ncase generation and relies on AFL to perform random-based fuzzing (for the\ncontext of this decision, refer to [Eclipser v2.0](#eclipser-v20) section\nbelow). Therefore, you should first launch AFL instances in parallel mode.\nAlthough it is possible to run Eclipser alone, it is intended only for simple\ntesting and not for realistic fuzzing.\n\n```\n$ AFL_DIR/afl-fuzz -i \u003cseed dir\u003e -o \u003csync dir\u003e -M \u003cID 1\u003e \\\n  -f \u003cinput file to fuzz\u003e -Q -- \u003ctarget program cmdline\u003e\n$ AFL_DIR/afl-fuzz -i \u003cseed dir\u003e -o \u003csync dir\u003e -S \u003cID 2\u003e \\\n  -f \u003cinput file to fuzz\u003e  -Q -- \u003ctarget program cmdline\u003e\n$ dotnet ECLIPSER_DIR/build/Eclipser.dll \\\n  -t \u003ctimeout (sec)\u003e -i \u003cseed dir (optional)\u003e -s \u003csync dir\u003e -o \u003coutput dir\u003e \\\n  -p \u003ctarget program\u003e --arg \u003ctarget program cmdline\u003e -f \u003cinput file to fuzz\u003e\n```\n\nWe note that the output directory for Eclipser should be placed under the\nsynchronization directory (e.g. `-s ../syncdir -o ../syncdir/eclipser-output`).\nAFL will automatically create an output directory under the synchronization\ndirectory, using its specified ID. This way, Eclipser and AFL will share test\ncases with each other. To obtain the final result of the fuzzing, retrieve all\nthe test cases under `\u003csync dir\u003e/*/queue/` and `\u003csync dir\u003e/*/crashes/`.\n\nSimilarly to AFL, Eclipser will fuzz the file input specified by `-f` option, and\nfuzz the standard input when `-f` option is not provided. However, Eclipser does\nnot support `@@` syntax used by AFL.\n\n- Examples\n\nYou can find simple example programs and their fuzzing scripts in\n[examples](./examples) directory. An example script to run Eclipser with AFL can\nbe found [here](examples/test_integerate.sh). Note that we create separate\nworking directories for each AFL instance and Eclipser in this script. This is\nto prevent the instances from using the same input file path for fuzzing.\n\n- Other options for fuzzing\n\nYou can get the full list of Eclipser's options and their descriptions by\nrunning the following command.\n\n```\n$ dotnet build/Eclipser.dll --help\n```\n\n# Eclipser v2.0\n\nOriginally, Eclipser had its own simplified random-based fuzzing module, instead\nof relying on AFL. This was to support fuzzing multiple input sources (e.g.\ncommand-line arguments, standard input, and file input) within a single fuzzer\nrun. We needed this feature for the comparison against KLEE on Coreutils\nbenchmark, which was one of the main experimental targets in our paper.\n\nHowever, as Eclipser is more often compared with other fuzzing tools, we abandon\nthis feature and focus on fuzzing a single input source, as most fuzzers do. We\nalso largely updated the command line interface of Eclipser accordingly. We note\nthat you can still checkout v1.0 code from our repository to reproduce the\nCoreutils experiment result.\n\nBy focusing on fuzzing a single input source, we can now use AFL to perform\nrandom-based fuzzing. For this, from v2.0 Eclipser runs in parallel with AFL, as\ndescribed above. This way, we can benefit from various features offered by AFL,\nsuch as source-based instrumentation, persistent mode, and deterministic mode.\nStill, the core architecture of Eclipser remains the same: it complements\nrandom-based fuzzing with our grey-box concolic testing technique.\n\n# Docker\n\nTo run the latest version of Eclipser, please use the [Dockerfile](./Dockerfile)\nprovided in this repository.\nIf you are interested in reproducing the results of ICSE 2019 paper, you can\nrefer to [Eclipser-Artifact](https://github.com/SoftSec-KAIST/Eclipser-Artifact)\nrepository, which uses Eclipser v0.1.\n\n# Supported Architectures\n\nEclipser currently supports x86 and x64 architecture binaries. We internally\nhave a branch that supports ARM architecture, but do not plan to open source it.\nIn default, Eclipser assumes that the target program is an x64 binary. If you\nwant to fuzz an x86 binary, you should provide `--architecture x86` option to\nEclipser.\n\n# Citation\n\nPlease consider citing our paper (ICSE 2019):\n```bibtex\n@INPROCEEDINGS{choi:icse:2019,\n  author = {Jaeseung Choi and Joonun Jang and Choongwoo Han and Sang Kil Cha},\n  title = {Grey-box Concolic Testing on Binary Code},\n  booktitle = {Proceedings of the International Conference on Software Engineering},\n  pages = {736--747},\n  year = 2019\n}\n```\n","funding_links":[],"categories":["Uncategorized","F# #","Tools"],"sub_categories":["Uncategorized","Binary"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSoftSec-KAIST%2FEclipser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSoftSec-KAIST%2FEclipser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSoftSec-KAIST%2FEclipser/lists"}