Skip to content
Grey-box Concolic Testing on Binary Code
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Instrumentor Fix QEMU instrumentor to build on hosts with glibc-2.25 Apr 24, 2019
examples
src Create fsc.props Apr 20, 2019
.gitignore Release the first prototype Jan 28, 2019
Eclipser.sln Release the first prototype Jan 28, 2019
LICENSE.md
Makefile Release the first prototype Jan 28, 2019
README.md Update README Jan 28, 2019

README.md

Eclipser

Eclipser is a binary-based fuzz testing tool that improves upon classic coverage-based fuzzing by leveraging a novel technique called grey-box concolic testing. The details of the technique can be found in our paper "Grey-box Concolic Testing on Binary Code", which will appear in ICSE 2019. This is a prerelease of our tool, and we will release a stable version by the ICSE 2019 conference.

Installation

Eclipser currently supports Linux ELF binaries, and has been tested on Debian and Ubuntu. Eclipser is written in F# and runs on .NET Core. Also, Eclipser performs program instrumentation based on QEMU code.

  1. Install dependencies
$ (First, you should add deb-src entries to /etc/apt/sources.list)
$ sudo apt-get update
$ sudo apt-get build-dep qemu
$ sudo apt-get install libtool libtool-bin wget automake autoconf bison gdb
  1. Install .NET Core

Installation differs for each Linux distribution, so please refer to this link. Choose your Linux distribution and version from the tab and follow the instructions.

  1. Clone and build Eclipser
$ git clone https://github.com/SoftSec-KAIST/Eclipser
$ cd Eclipser
$ make

Usage

  • Basic options

The basic usage of Eclipser is as follow. Note that you should provide fuzz keyword before other options.

$ dotnet build/Eclipser.dll fuzz \
    -p <target program path> -v <verbosity level> -t <timeout second> \
    -o <output directory> --src <'arg'|'file'|'stdin'|'auto'>

This command will fuzz the specified target program for the given amount of time, and store the fuzzing outputs (i.e. test cases and crashes) into the output directory. The last argument --src ... specifies target program's input source to fuzz, and further explanation about this option is given below.

  • Fuzzing command line arguments of a target program

By providing --src arg option to Eclipser, you can fuzz command-line argument input of the target program. You can specify the number of arguments and the maximum length of each argument string with --maxarglen option.

For example, the following command will fuzz target program 'example.bin' by mutating command line argument inputs. A generated test input can have up to three argument strings (i.e. argc <= 3), and the length of the first argument string is limited up to 8 bytes, while the second and third arguments are confined to 4-bytes strings.

$ dotnet build/Eclipser.dll fuzz \
    -p example.bin -v 1 -t 10 -o outdir --src arg --maxarglen 8 4 4
  • Fuzzing a file input of a target program

By providing --src file option to Eclipser, you can fuzz a file input of a target program. You can specify the command line argument of target program with --initarg option, and specify the input file name with --fixfilepath option.

For example, consider a target program that takes in input file via "--input" option. Using the following command, you can fuzz the file input of this program and limit the file input length up to 8 bytes. Currently we support only one file input.

$ dotnet build/Eclipser.dll fuzz \
    -p example.bin -v 1 -t 10 -o outdir \
    --src file --initarg "--input foo" --fixfilepath foo --maxfilelen 8

You may also want to provide initial seed inputs for the fuzzing. You can use -i <seed directory> option to provide initial seed input files for the target program.

  • Fuzzing the standard input of a target program

By providing --src stdin to Eclipser, you can fuzz the standard input of a target program. Currently, we assume a standard input to be a single string, and do not consider cases where a sequence of string is provided as a standard input stream of the target program.

For example, the following command will fuzz target program 'example.bin' by mutating its standard input. The length of standard input is confined up to 8 bytes.

$ dotnet build/Eclipser.dll fuzz \
    -p example.bin -v 1 -t 10 -o outdir --src stdin --maxstdinlen 8
  • Fuzzing multiple input sources.

Eclipser also supports a mode that automatically identifies and fuzz input sources. When you provide --src auto option to Eclipser, it will first start by fuzzing command line argument of the target program. Then, it will trace system call invocations during the program execution, to identify the use of standard input or file input. Once identified, Eclipser will automatically fuzz these input sources as well. As in previous examples, you can specify the maximum lengths with --max* options.

$ dotnet build/Eclipser.dll fuzz \
    -p example.bin -v 1 -t 10 -o outdir \
    --src auto --maxarglen 8 4 4 --maxfilelen 8 --maxstdinlen 8

Note: Eclipser identifies a file input as an input source only if the file name matches one of the argument string. This means if a target program reads in a configuration file from a fixed path, this file will not be considered as a input source to fuzz in --src auto mode.

  • Other options for fuzzing

You can get the full list of Eclipser's options and their detailed descriptions by running the following command.

$ dotnet build/Eclipser.dll fuzz --help

Test case decoding utility

Eclipser internally store test cases in its custom JSON format. For usability, we provide a utility that decodes these JSON format test cases in a specified directory.

For example, suppose that you fuzzed a target program with the following command.

$ dotnet build/Eclipser.dll fuzz -p example.bin -v 1 -t 10 -o outdir --src auto

Then, Eclipser will store generated test cases in outdir/testcase, and store found crash inputs in outdir/crash. Now, to decode the test cases, you can run the following command. Note the decode keyword is used in place of fuzz.

$ dotnet build/Eclipser.dll decode -i outdir/testcase -o decoded_testcase

Then, Eclipser will store the decoded raw string inputs in subdirectories, as shown below.

$ ls decoded_testcase
decoded_args  decoded_files  decoded_paths  decoded_stdins
$ xxd decoded_testcase/decoded_files/tc-0
00000000: 4142 4242 4242 4242 4242 4242 4242 4242  ABBBBBBBBBBBBBBB
$ xxd decoded_testcase/decoded_files/tc-1
00000000: 6142 4242 4242 4242 4242 4242 4242 4242  aBBBBBBBBBBBBBBB
(...)

Examples

You can find simple example programs, along with testing scripts to fuzz these programs, in examples directory.

Docker

We also provide a Docker image to run the experiments in our paper, in Eclipser-Artifact repository.

Supported Architectures

Eclipser currently supports x86 and x64 architecture binaries. We internally have a branch that supports ARM architecture, but do not plan to open source it. In default, Eclipser assumes that the target program is an x64 binary. If you want to fuzz an x86 binary, you should provide --architecture x86 option to Eclipser.

Known issue

Eclipser currently do not strictly comply with the provided time limit, and may run a little bit longer than the specified time limit. We will fix this issue in our stable release.

You can’t perform that action at this time.