DeforaNetworks/deepstate
3
0
Fork 0
Code Releases Activity

Update README.md (#36)

Browse Source 
Clarify the readme:
* incorporated the paper reference into the first paragraph so it gets excerpted together
* removed a lot of extraneous guidance from the building and installing sections
* added a new contributing section that notes the "good first issue" label, bounties, and our Slack
* noted the the best usage guidance is available in the examples and readme for now
This commit is contained in:
Dan Guido
2018-02-18 23:54:35 +01:00
committed by artemdinaburg
parent c9fa425e4b
commit 1294def677
1 changed files with 20 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+20 -35
View File
@@ -1,8 +1,9 @@
# DeepState
DeepState is a framework that provides C and C++ developers with a common interface to various symbolic execution and fuzzing engines. Users can write one test harness using a Google Test-like API, then execute it using multiple backends, without having to learn the complexities of the underlying engines. It supports writing unit tests and API sequence tests, as well as automatic test generation.
[![Slack Chat](http://empireslacking.herokuapp.com/badge.svg)](https://empireslacking.herokuapp.com/)
DeepState is a framework that provides C and C++ developers with a common interface to various symbolic execution and fuzzing engines. Users can write one test harness using a Google Test-like API, then execute it using multiple backends without having to learn the complexities of the underlying engines. It supports writing unit tests and API sequence tests, as well as automatic test generation. Read more about the goals and design of DeepState in our [paper](https://www.cefns.nau.edu/~adg326/bar18.pdf).
More high-level information on DeepState's goals (and design) is available at https://www.cefns.nau.edu/~adg326/bar18.pdf.
## Supported Platforms
DeepState currently targets Linux, with macOS support in progress.
@@ -21,43 +22,19 @@ Runtime:
- Python 2.7
- Z3 (for the Manticore backend)
## Building
DeepState is a static library, used to write test harnesses, accompanied by command-line _executors_ written in Python. Below we describe how to build the library and accompanying Python package.
### Ubuntu 16.04 (Xenial)
Suppose the DeepState project source resides in the directory `$DEEPSTATE`.
First, install the build dependencies:
```shell
$ sudo apt update
$ sudo apt install build-essential gcc-multilib cmake python python-setuptools
```
Set up a build directory and `cd` into it:
```shell
$ mkdir $DEEPSTATE/build
$ cd $DEEPSTATE/build
```
From the build directory, generate Makefiles using CMake:
```shell
$ cmake $DEEPSTATE
```
Finally, build the library and package:
## Building on Ubuntu 16.04 (Xenial)
```shell
$ sudo apt update && sudo apt-get install build-essential gcc-multilib cmake python python-setuptools
$ git clone https://github.com/trailofbits/deepstate deepstate
$ mkdir deepstate/build && cd deepstate/build
$ cmake ../
$ make
```
## Usage
## Installing
After building, you can use DeepState by installing the resulting Python package, e.g. into a virtualenv. For example, from some working directory, with the `virtualenv` tool installed:
Assuming the DeepState build resides in `$DEEPSTATE`, run the following commands to install the DeepState python package:
```shell
$ virtualenv venv
@@ -65,9 +42,9 @@ $ . venv/bin/activate
$ python $DEEPSTATE/build/setup.py install
```
Now your `virtualenv`-enabled `$PATH` should include two executables: `deepstate` and `deepstate-angr`. These are _executors_, which are used to run DeepState test binaries with specific backends (automatically installed as Python dependencies). The `deepstate` executor uses the Manticore backend, and requires the Z3 SMT solver to be installed, while `deepstate-angr` uses angr. They share a common interface, where you may specify a number of workers and an output directory for saving backend-generated test cases.
The `virtualenv`-enabled `$PATH` should now include two executables: `deepstate` and `deepstate-angr`. These are _executors_, which are used to run DeepState test binaries with specific backends (automatically installed as Python dependencies). The `deepstate` executor uses the Manticore backend while `deepstate-angr` uses angr. They share a common interface where you may specify a number of workers and an output directory for saving backend-generated test cases.
You can check your build using the test binaries that were (by default) built and emitted to `$DEEPSTATE/build/examples`. For example, to use angr to symbolically execute the `IntegerOverflow` test harness with 4 workers, saving generated test cases in a directory called `out`, you would invoke:
You can check your build using the test binaries that were (by default) built and emitted to `deepstate/build/examples`. For example, to use angr to symbolically execute the `IntegerOverflow` test harness with 4 workers, saving generated test cases in a directory called `out`, you would invoke:
```shell
$ deepstate-angr --num_workers 4 -output_test_dir out $DEEPSTATE/build/examples/IntegerOverflow
@@ -86,6 +63,14 @@ $ deepstate-angr --num_workers 4 -output_test_dir out $DEEPSTATE/build/examples/
└── f1d3ff8443297732862df21dc4e57262.pass
```
## Usage
DeepState consists of a static library, used to write test harnesses, and command-line _executors_ written in Python. At this time, the best documentation are the [examples](/examples) and our [paper](https://www.cefns.nau.edu/~adg326/bar18.pdf).
## Contributing
All accepted PRs are awarded bounties by Trail of Bits. Join the #deepstate channel on the [Empire Hacking Slack](https://empireslacking.herokuapp.com/) to discuss ongoing development and claim bounties. Check the [good first issue](https://github.com/trailofbits/deepstate/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label for suggested contributions.
## License
DeepState is released under [The Apache License 2.0](LICENSE).