{"id":13538929,"url":"https://github.com/trailofbits/deepstate","last_synced_at":"2025-05-15T01:05:40.201Z","repository":{"id":29536037,"uuid":"108593287","full_name":"trailofbits/deepstate","owner":"trailofbits","description":"A unit test-like interface for fuzzing and symbolic execution","archived":false,"fork":false,"pushed_at":"2025-01-23T22:49:30.000Z","size":1515,"stargazers_count":830,"open_issues_count":90,"forks_count":99,"subscribers_count":57,"default_branch":"master","last_synced_at":"2025-04-10T10:04:53.541Z","etag":null,"topics":["fuzzing","property-based-testing","symbolic-execution","testing-framework","testing-tools","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trailofbits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-27T20:35:54.000Z","updated_at":"2025-04-09T21:56:54.000Z","dependencies_parsed_at":"2024-01-16T15:43:14.891Z","dependency_job_id":"728b951c-38e4-4af9-9203-6fb8794ca3b8","html_url":"https://github.com/trailofbits/deepstate","commit_stats":{"total_commits":1030,"total_committers":26,"mean_commits":39.61538461538461,"dds":0.412621359223301,"last_synced_commit":"50c8a14aecb255552f0c22e52610e60d88905b71"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fdeepstate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fdeepstate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fdeepstate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fdeepstate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/deepstate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254039,"owners_count":22039792,"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":["fuzzing","property-based-testing","symbolic-execution","testing-framework","testing-tools","unit-testing"],"created_at":"2024-08-01T09:01:17.808Z","updated_at":"2025-05-15T01:05:40.184Z","avatar_url":"https://github.com/trailofbits.png","language":"Python","readme":"# DeepState\n\n[![Slack Chat](http://slack.empirehacking.nyc/badge.svg)](https://slack.empirehacking.nyc/)\n\nDeepState 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://agroce.github.io/bar18.pdf).\n\nThe\n[2018 IEEE Cybersecurity Development Conference](https://secdev.ieee.org/2018/home)\nincluded a\n[full tutorial](https://github.com/trailofbits/publications/tree/master/workshops/DeepState:%20Bringing%20vulnerability%20detection%20tools%20into%20the%20development%20lifecycle%20-%20SecDev%202018)\non effective use of DeepState.\n\n\nTable of Contents\n=================\n  * [DeepState in a Nutshell](#deepstate-in-a-nutshell)\n  * [Articles describing DeepState](#articles-describing-deepstate)\n  * [Overview of Features](#overview-of-features)\n  * [Build'n'run](#buildnrun)\n     * [Supported Platforms](#supported-platforms)\n     * [Dependencies](#dependencies)\n     * [Building on Ubuntu 18.04 (Bionic)](#building-on-ubuntu-1804-bionic)\n     * [Building on Windows 10](#building-on-windows-10)\n     * [Installing](#installing)\n     * [Installation testing](#installation-testing)\n     * [Docker](#docker)\n  * [Documentation](#documentation)\n  * [Contributing](#contributing)\n  * [Trophy case](#trophy-case)\n  * [License](#license)\n\n\n## DeepState in a Nutshell\n\nIf you want to jump right in, or are having trouble with building DeepState, you can just use a Docker that is pre-built and has compiled versions of several of the easiest examples of DeepState in use:\n\n```shell\ndocker pull agroce/deepstate_examples_aflpp\ndocker run -it agroce/deepstate_examples_aflpp\n```\n\nThen within the DeepState docker container, go to an example:\n```shell\ncd ~/examples/fuzz_tcas\ndeepstate-afl ./TCAS_AFL -o fuzz_afl --fuzzer_out --timeout 120\n./TCAS_cov --input_test_files_dir fuzz_afl/the_fuzzer/queue/\nllvm-cov-9 gcov TCAS_driver.cpp  -b\n```\n\nThis runs the AFL++ fuzzer on the TCAS code (https://en.wikipedia.org/wiki/Traffic_collision_avoidance_system), a long-used example program in software testing.  After two minutes of fuzzing, we run a version of the test driver that collects code coverage, and see how much of the code AFL has managed to cover in two minutes.\n\nNOTE 1: The above docker is built using AFL++ instead of AFL for \"AFL\" fuzzing.  You can use agroce/deepstate_examples instead if for some reason you prefer \"classic\" AFL.\n\nNOTE 2: You may need to modify `/proc/sys/kernel/core_pattern` on your host for AFL to run properly, e.g.:\n\n```shell\necho core | sudo tee /proc/sys/kernel/core_pattern\n```\n\nFinally, we can look at the failing tests AFL produces:\n\n```shell\n./TCAS --input_test_files_dir fuzz_afl/the_fuzzer/crashes/ --min_log_level=0\n```\n\nInspecting `TCAS_driver.cpp` and `Makefile` will give a good idea of how DeepState can be used.  The other examples, including the one in the original DeepState blog post, are similar in structure and usage.\n\n## Articles describing DeepState\n\n* [Fuzzing an API with DeepState (Part 1)](https://blog.trailofbits.com/2019/01/22/fuzzing-an-api-with-deepstate-part-1)\n* [Fuzzing an API with DeepState (Part 2)](https://blog.trailofbits.com/2019/01/23/fuzzing-an-api-with-deepstate-part-2)\n* [Fuzzing Unit Tests with DeepState and Eclipser](https://blog.trailofbits.com/2019/05/31/fuzzing-unit-tests-with-deepstate-and-eclipser)\n* [DeepState Now Supports Ensemble Fuzzing](https://blog.trailofbits.com/2019/09/03/deepstate-now-supports-ensemble-fuzzing/)\n* [Everything You Ever Wanted To Know About Test-Case Reduction, But Didn’t Know to Ask](https://blog.trailofbits.com/2019/11/11/test-case-reduction/)\n\n## Overview of Features\n\n* Tests look like Google Test, but can use symbolic execution/fuzzing to generate data (parameterized unit testing)\n  * Easier to learn than binary analysis tools/fuzzers, but provides similar functionality\n* Already supports Manticore, Angr, libFuzzer, file-based fuzzing with\n  e.g., AFL or Eclipser; more back-ends likely in future\n  * Switch test generation tool without re-writing test harness\n    * Work around show-stopper bugs\n    * Find out which tool works best for your code under test\n    * Different tools find different bugs/vulnerabilities\n    * Fair way to benchmark/bakeoff tools\n* Provides test replay for regression [plus effective automatic test case reduction to aid debugging](https://blog.trailofbits.com/2019/11/11/test-case-reduction/)\n* Supports API-sequence generation with extensions to Google Test interface\n  * Concise readable way (OneOf) to say \"run one of these blocks of code\"\n  * Same construct supports fixed value set non-determinism\n  * E.g., writing a POSIX file system tester is pleasant, not painful as in pure Google Test idioms\n* Provides high-level strategies for improving symbolic execution/fuzzing effectiveness\n  * Pumping (novel to DeepState) to pick concrete values when symbolic execution is too expensive\n  * Automatic decomposition of integer compares to guide coverage-driven fuzzers\n  * Strong support for automated [swarm testing](https://agroce.github.io/issta12.pdf)\n\nTo put it another way, DeepState sits at the intersection of\n*property-based testing*, *traditional unit testing*, *fuzzing*, and\n*symbolic execution*.  It lets you perform property-based unit testing\nusing fuzzing or symbolic execution as a back end to generate data, and saves the\nresults so that what DeepState finds can easily be used in\ndeterministic settings such as regression testing or CI.\n\n## Build'n'run\n\n### Supported Platforms\n\nDeepState currently targets Linux, Windows, with macOS support in progress\n(the fuzzers work fine, but symbolic execution is not well-supported\nyet, without a painful cross-compilation process). No current support for ARM64 architecture,\n this includes Apple Silicon processors, as there is no support for multilib compilers. \n\n### Dependencies\n\nBuild:\n\n- CMake\n- GCC and G++ with multilib support\n- Python 3.6 (or newer)\n- Setuptools\n\nRuntime:\n\n- Python 3.6 (or newer)\n- Z3 (for the Manticore backend)\n\n### Building on Ubuntu 18.04 (Bionic)\n\nFirst make sure you install [Python 3.6 or greater](https://askubuntu.com/a/865569). Then use this command line to install additional requirements and compile DeepState:\n\n**Building Deepstate**\n```shell\nsudo apt update \u0026\u0026 sudo apt-get install build-essential gcc-multilib g++-multilib cmake python3-setuptools python3-dev libffi-dev z3\nsudo apt-add-repository ppa:sri-csl/formal-methods\nsudo apt-get update\nsudo apt-get install yices2\ngit clone https://github.com/trailofbits/deepstate deepstate\nmkdir deepstate/build \u0026\u0026 cd deepstate/build\ncmake ../\nmake\nsudo make install\n```\n\n### Changing file permissions\n```shell\ncd deepstate\nsudo chmod -R 755 .\nsudo chown -R username:groupname .\n```\n\n### Installing Dependencies on Ubuntu if issues arise\n**CMake:**\n```shell\nsudo apt install cmake\n```\n\n**GCC \u0026 G++ with multilib support:**\n```shell\nsudo apt-get install gcc-multilib\nsudo apt-get install g++-multilib\n```\n\n**Installing the latest version of Python via CLI:**\n```shell\nsudo apt-get update \u0026\u0026 sudo apt upgrade\nsudo apt install wget build-essential libncursesw5-dev libssl-dev \\\nlibsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev libffi-dev zlib1g-dev\nsudo add-apt-repository ppa:deadsnakes/ppa\nsudo apt install python3.11\n```\n\n**Setup Tools:**\n\nSkip the first command below if pip is already installed.\n```shell\nsudo apt install python3-pip\npip3 install setuptools\n```\n\n**Z3:**\n```shell\nsudo apt install z3\n```\n\n### Building on Windows 10\nIf you want to compile DeepState on Windows make sure to install MinGW with MSYS2 by following the [installation instructions](https://www.msys2.org/#installation). After the installation is finished, select an environment and launch that version of the environment from the Windows programs menu(if in doubt, choose MINGW64 or UCRT64). Then, use the command below to install all of your environment's dependencies and compile DeepState:\n```shell\npacman -Syyu\npacman -S mingw-w64-x86_64-python3 mingw-w64-x86_64-python-setuptools mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-libffi mingw-w64-x86_64-make\npacman -S make git\n\ngit clone https://github.com/trailofbits/deepstate deepstate\nmkdir deepstate/build \u0026\u0026 cd deepstate/build\ncmake -G \"Unix Makefiles\" ../\nmake\nmake install\n```\n\nNOTE: If you decide to use UCRT64, keep in mind to change `x86_64` to `ucrt-x86_64` in the second pacman command, i.e. `mingw-w64-x86_64-python3` gets replaced with `mingw-w64-ucrt-x86_64-python3`.\n\n### Installing\n\nAssuming the DeepState build resides in `$DEEPSTATE`, run the following commands to install the DeepState python package:\n\n```shell\nvirtualenv venv\n. venv/bin/activate\npython $DEEPSTATE/build/setup.py install\n```\n\nThe `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` or `deepstate-manticore` 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.\n\nIf you try using Manticore, and it doesn't work, but you definitely have the latest Manticore installed, check the `.travis.yml` file.  If that grabs a Manticore other than the master version, you can try using the version of Manticore we use in our CI tests.  Sometimes Manticore makes a breaking change, and we are behind for a short time.\n\n\n### Installation testing\n\nYou 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:\n\n```shell\ndeepstate-angr --num_workers 4 --output_test_dir out $DEEPSTATE/build/examples/IntegerOverflow\n```\n\n The resulting `out` directory should look something like:\n\n ```\n out\n└── IntegerOverflow.cpp\n    ├── SignedInteger_AdditionOverflow\n    │   ├── a512f8ffb2c1bb775a9779ec60b699cb.fail\n    │   └── f1d3ff8443297732862df21dc4e57262.pass\n    └── SignedInteger_MultiplicationOverflow\n        ├── 6a1a90442b4d898cb3fac2800fef5baf.fail\n        └── f1d3ff8443297732862df21dc4e57262.pass\n```\n\nTo run these tests, you can just use the native executable, e.g.:\n\n```shell\n$DEEPSTATE/build/examples/IntegerOverflow --input_test_dir out\n```\n\nto run all the generated tests, or\n\n```shell\n$DEEPSTATE/build/examples/IntegerOverflow --input_test_files_dir out/IntegerOverflow.cpp/SignedInteger_AdditionOverflow --input_which_test SignedInteger_AdditionOverflow\n```\n\nto run the tests in one directory (in this case, you want to specify\nwhich test to run, also).  You can also run a single test, e.g.:\n\n```shell\n$DEEPSTATE/build/examples/IntegerOverflow --input_test_file out/IntegerOverflow.cpp/SignedInteger_AdditionOverflow/a512f8ffb2c1bb775a9779ec60b699cb.fail--input_which_test SignedInteger_AdditionOverflow\n```\n\nIn the absence of an `--input_which_test` argument, DeepState defaults\nto the first-defined test.  Run the native executable with the `--help`\nargument to see all DeepState options.\n\n\n### Docker\n\nYou can also try out Deepstate with Docker, which is the easiest way\nto get all the fuzzers and tools up and running on any system.\n\nThe build may take about 40 minutes, because some fuzzers require us\nbuilding huge projects like QEMU or LLVM.\n\n**Ensure that docker is installed:**\n\n- Check out the docker website [here](https://docs.docker.com/engine/install/) for installation instructions.\n\n**Check if docker is installed correctly:**\n```bash\ndocker run hello-world\n```\n\n**Run these commands to install deepstate via docker:**\n```bash\ngit clone https://github.com/trailofbits/deepstate deepstate\n$ cd deepstate\n$ docker build -t deepstate-base -f docker/base/Dockerfile docker/base\n$ docker build -t deepstate --build-arg make_j=6 -f ./docker/Dockerfile .\n$ docker run -it deepstate bash\nuser@a17bc44fd259:~/deepstate$ cd build/examples\nuser@a17bc44fd259:~/deepstate/build/examples$ deepstate-angr ./Runlen\nuser@a17bc44fd259:~/deepstate/build/examples$ mkdir tmp \u0026\u0026 deepstate-eclipser ./Runlen -o tmp --timeout 30\nuser@a17bc44fd259:~/deepstate/build/examples$ cd ../../build_libfuzzer/examples\nuser@a17bc44fd259:~/deepstate/build_libfuzzer/examples$ ./Runlen_LF -max_total_time=30\nuser@a17bc44fd259:~/deepstate/build_libfuzzer/examples$ cd ../../build_afl/examples\nuser@a17bc44fd259:~/deepstate/build_afl/examples$ mkdir foo \u0026\u0026 echo x \u003e foo/x \u0026\u0026 mkdir afl_Runlen2\nuser@a17bc44fd259:~/deepstate/build_afl/examples$ $AFL_HOME/afl-fuzz -i foo -o afl_Runlen -- ./Runlen_AFL --input_test_file @@ --no_fork --abort_on_fail\nuser@a17bc44fd259:~/deepstate/build_afl/examples$ deepstate-afl -o afl_Runlen2 ./Runlen_AFL --fuzzer_out\n```\n\n**How to use docker without sudo:**\n```bash\nsudo groupadd docker\nsudo gpasswd -a $USER docker\nnewgrp docker\n```\n\n**If this error occurs:**\n```bash\nERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?\n```\n**Run this command:**\n```bash\nsystemctl start docker\n```\n\n## Documentation\n\nCheck out [docs](/docs) folder:\n\n* [Basic usage](/docs/basic_usage.md)\n* [Writing a test harness](/docs/test_harness.md)\n* [Fuzzing](/docs/fuzzing.md)\n* [Swarm testing](/docs/swarm_testing.md)\n\n## External Tools\n\nDeepState can be used to test R packages written using the popular Rcpp package.  The [Rcppdeepstate tool](https://github.com/akhikolla/RcppDeepState) is described in a [paper presented at the 2021 IEEE International Symposium on Software Reliability Engineering](https://agroce.github.io/issre21.pdf).\n\n## Contributing\n\nAll accepted PRs are awarded bounties by Trail of Bits. Join the #deepstate channel on the [Empire Hacking Slack](https://slack.empirehacking.nyc/) 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.\n\n## Trophy case\n\nWe have not yet applied DeepState to many targets, but it was responsible for finding the following confirmed bugs (serious faults are in bold):\n\n- https://github.com/Blosc/c-blosc2/issues/93\n- https://github.com/Blosc/c-blosc2/issues/94\n- **https://github.com/Blosc/c-blosc2/issues/95** (bug causing compression engine to return incorrect uncompressed data) **FIXED**\n- **https://github.com/FooBarWidget/boyer-moore-horspool/issues/4** (implementation of Turbo version of Boyer-Moore string search can fail to find present string)\n\n## License\n\nDeepState is released under [The Apache License 2.0](LICENSE).\n","funding_links":[],"categories":["\u003ca id=\"683b645c2162a1fce5f24ac2abfa1973\"\u003e\u003c/a\u003e漏洞\u0026\u0026漏洞管理\u0026\u0026漏洞发现/挖掘\u0026\u0026漏洞开发\u0026\u0026漏洞利用\u0026\u0026Fuzzing","Python","Emulation and Fuzzing"],"sub_categories":["功能"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fdeepstate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fdeepstate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fdeepstate/lists"}