{"id":20275636,"url":"https://github.com/softsec-kaist/eclipser-artifact","last_synced_at":"2025-09-13T07:39:29.868Z","repository":{"id":89248936,"uuid":"167931146","full_name":"SoftSec-KAIST/Eclipser-Artifact","owner":"SoftSec-KAIST","description":"Docker image for Eclipser","archived":false,"fork":false,"pushed_at":"2019-01-28T10:36:38.000Z","size":85673,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-11T05:35:35.295Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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":"2019-01-28T09:04:23.000Z","updated_at":"2020-02-22T15:33:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"fe2e2ae0-b99b-4df7-8745-1314fc541d18","html_url":"https://github.com/SoftSec-KAIST/Eclipser-Artifact","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SoftSec-KAIST/Eclipser-Artifact","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser-Artifact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser-Artifact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser-Artifact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser-Artifact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftSec-KAIST","download_url":"https://codeload.github.com/SoftSec-KAIST/Eclipser-Artifact/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FEclipser-Artifact/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274935937,"owners_count":25376831,"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","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2024-11-14T13:10:23.555Z","updated_at":"2025-09-13T07:39:29.808Z","avatar_url":"https://github.com/SoftSec-KAIST.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"Eclipser Artifact\n========\n\n[Eclipser](https://github.com/SoftSec-KAIST/Eclipser) is a binary-based fuzz\ntesting tool, which will be presented in ICSE 2019 conference. This repository\nmaintains a Docker image to run the experiments in our paper. The Docker image\nand running scripts were tested on Ubuntu 18.04 host machine.\n\n# Installation\n\n1. Install Docker\n\nTo install Docker CE, please follow the instructions in this\n[link](https://docs.docker.com/install/linux/docker-ce/ubuntu/).\n\n2. Prepare to run Docker without root privilege (i.e. sudo)\n\nSince we wanted our scripts not to ask you for sudo password, we assumed that\nyou run Docker commands as a non-root user. Please follow the instructions in\nthis [link](https://docs.docker.com/install/linux/linux-postinstall/) for the\nconfiguration.\n\n3. Prepare Docker image for experiment\n\nYou may choose either (1) to build a Docker image from the scratch by running\n[build.sh](build.sh), or (2) to download an already-built image from Docker\nHub by running [pull.sh](pull.sh). Since building an image from the scratch\ntakes a long time, we recommend the latter choice if you want to save your time.\n\nIf you want to investigate the image setup process in detail, please refer to\n[Dockerfile](Dockerfile) and [setup scripts](docker-scripts/setup-scripts).\n\nNote: If you chose to run `build.sh` script, you would want to fix the first\ncommand in [Dockerfile](Dockerfile) and replace the apt-get repository to the\nfastest one from your region.\n\nNote: When you run `pull.sh`, it will first pull the image from Docker Hub, and\nthen build an image on top of that, by running a command to adjust UID within\nthe container. This is to avoid creating files on your system with root\nprivilege.\n\n4. Testing the image\n\nOnce the Docker image is prepared, you can run [launch.sh](launch.sh) to run a\nDocker container. Also, you can use the following commands to run Eclipser on\nsome simple example programs. Each testing script in `Eclipser/examples`\ndirectory contains a comment about the test cases expected to be found by\nEclipser.\n\n```\n$ ./launch.sh\nartifact@fb7350adf920:~$ cd Eclipser/examples/\nartifact@fb7350adf920:~/Eclipser/examples$ ./test_cmp_gcc.sh\nFuzz target: /home/artifact/Eclipser/examples/cmp.bin\n...\n```\n\nNote: In `launch.sh`, resource limitations of Docker container is specified with\n`--cpuset-cpus` and `--memory` options. Memory resource limitation may print the\nfollowing warning message, depending on the kernel environment. We believe this\nwarning can be ignored.\n\n```\nWARNING: Your kernel does not support swap limit capabilities or the cgroup is not mounted. Memory limited without swap.\n```\n\n# Running experiments\n\n## Pre-requisites\n\nAlthough we provide a Docker image to minimize the effect on your system,\nrunning AFLFast and LAF-intel requires to change some of your system\nconfiguration.\n\n- Configuring core dump file pattern\n\nAFL-based fuzzers request to disable the use of external crash report utilities\nlike 'apport', by running the following command.\n```\necho core | sudo tee /proc/sys/kernel/core_pattern'\"\n```\n\n- Configuring CPU governor\n\nAFL-based fuzzers request to configure your CPU scaling algorithm, by running\nthe following command.\n```\n[ -f /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor ] \u0026\u0026 \\\necho performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor\n```\n\n## Top-level script\n\nWe provide a single top-level script\n[scripts/run_experiment.py](scripts/run_experiment.py) to run our experiments.\nYou can specify which experiment to run, by providing proper arguments to this\nscript. Its basic usage is as follow, and more detailed usage for each\nexperiment is described below.\n\n```\nrun_experiment.py \u003ctestset\u003e \u003ctool\u003e \u003ctimelimit\u003e \u003c# proc\u003e \u003c# iteration (optional)\u003e\n```\n\nNote: You can adjust the memory resource limitation for each Docker container,\nby fixing `MEM_PER_CONTAINER` variable at the top of `run_experiment.py` file.\n\n## Running coreutils experiment\n\nTo run coreutils experiment with Eclipser and KLEE, you can use the following\ncommands respectively.\n\n```\n$ ./scripts/run_experiment.py coreutils eclipser 3600 4\n$ ./scripts/run_experiment.py coreutils klee 3600 4\n```\n\nThis command will run each program in coreutils for one hour, as in our\nexperiment setting in the paper. The last argument specifies to run four worker\nprocesses in parallel. You should modify these parameters considering your\nmachine spec and available resource. When deciding the number of worker\nprocesses, please take a look at [threats](#threats-to-reproducing-experiments)\nsection, too.\n\nAlso, you can run each program in the test set iteratively. For this, you simply\nhave to append an optional argument (N) at the end of the command. If no\noptional argument is provided, each program in the test set will be ran only\nonce.\n\nWhen `run_experiment.py` script finishes, the testing outputs will be stored in\n`output-*` directory. The directory name is automatically suffixed with a unique\nnumber, starting from zero. You can parse the coverage result of the experiment\nwith [scripts/parse_coreutils_coverage.py](scripts/parse_coreutils_coverage.py)\nas below. The last argument specifies how many time each program was ran\niteratively.\n\n```\n$./scripts/parse_coreutils_coverage.py ./output-0 1\n```\n\nNote : FYI, coreutils test set is composed of 95 programs.\n\n## Running LAVA experiment\n\nTo run LAVA experiment with Eclipser, AFLFast, and LAF-intel, you can use the\nfollowing commands respectively. Each program in LAVA test set will be ran for 5\nhours, as in our experiment setting in the paper. You should modify these\nparameters considering your machine spec and available resource.\n\n\n```\n$ ./scripts/run_experiment.py lava eclipser 18000 4\n$ ./scripts/run_experiment.py lava aflfast 18000 4\n$ ./scripts/run_experiment.py lava lafintel 18000 4\n```\n\nWe recommend you to carefully choose the number of worker process to spawn,\nbecause if you run too many Docker containers simultaneously, AFLFast may fail\nto initialize its 'fork server' for fuzzing, and exit immediately.\n\nYou can count the number of bugs found from the experiment with\n[scripts/count_lava_crash.py](scripts/count_lava_crash.py) as below.\n\n```\n$./scripts/count_lava_crash.py ./output-0\n```\n\nNote : FYI, LAVA test set is composed of 4 programs.\n\n## Running Debian package experiment\n\nTo run Debian package experiment with Eclipser, AFLFast, and LAF-intel, you can\nuse the following commands respectively. Each program in Debian package test set\nwill be ran for 24 hours, as in our experiment setting in the paper. You should\nmodify these parameters considering your machine spec and available resource.\n\n```\n$ ./scripts/run_experiment.py package eclipser 86400 4\n$ ./scripts/run_experiment.py package aflfast 86400 4\n$ ./scripts/run_experiment.py package lafintel 86400 4\n```\n\nYou can parse the coverage result of the experiment with\n[scripts/parse_package_coverage.py](scripts/parse_package_coverage.py), and\ntriage found crashes with\n[scripts/triage_package_crash.py](scripts/triage_package_crash.py) as below.\nHowever, note that `triage_package_crash.py` conservatively de-duplicates\ncrashes, so its result should be further investigated manually, in order to\ncorrectly identify unique bugs.\n\n```\n$./scripts/parse_package_coverage.py ./output-0 1\n$./scripts/triage_package_crash.py ./output-0 1\n```\n\nNote : FYI, Debian package test set is composed of 20 programs.\n\n# Threats to reproducing experiments\n\nThere are several obstacles to precisely reproduce the experiment results of the\npaper. First, the difference between Docker and KVM (which was used in our paper\nexperiment) seems to substantially affect the experiment result.\n\nEspecially, running AFLFast and LAF-intel within Docker seems not to scale up\nwell as we increase the number of worker processes (i.e. Docker container) that\nruns in parallel. Therefore, we recommend to avoid choosing a large number as\nthe number of worker process to spawn, when running `run_experiment.py` script.\n\nAlso, even if we give each experiment the same amount of time as in the paper,\nexperiment results can vary according to machine specs.\n\nDespite such threats, in our several testing environments we could consistently\nconfirm the overall tendency that Eclipser outperforms other tools as in the\npaper.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Feclipser-artifact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftsec-kaist%2Feclipser-artifact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Feclipser-artifact/lists"}