{"id":13787391,"url":"https://github.com/aflgo/aflgo","last_synced_at":"2025-05-12T00:31:00.216Z","repository":{"id":23997182,"uuid":"100235805","full_name":"aflgo/aflgo","owner":"aflgo","description":"Directed Greybox Fuzzing with AFL","archived":false,"fork":true,"pushed_at":"2024-03-13T14:14:57.000Z","size":2071,"stargazers_count":530,"open_issues_count":21,"forks_count":139,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-08T18:13:49.654Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://mboehme.github.io/paper/CCS17.pdf","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mirrorer/afl","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aflgo.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":null,"security":null,"support":null,"governance":null}},"created_at":"2017-08-14T06:33:10.000Z","updated_at":"2025-05-05T00:47:05.000Z","dependencies_parsed_at":"2023-01-16T22:02:02.545Z","dependency_job_id":"8cd38214-ac76-4a48-94f4-4d9fa85aaa3f","html_url":"https://github.com/aflgo/aflgo","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aflgo%2Faflgo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aflgo%2Faflgo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aflgo%2Faflgo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aflgo%2Faflgo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aflgo","download_url":"https://codeload.github.com/aflgo/aflgo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655801,"owners_count":21943068,"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":[],"created_at":"2024-08-03T20:00:33.656Z","updated_at":"2025-05-12T00:30:57.542Z","avatar_url":"https://github.com/aflgo.png","language":"C","funding_links":[],"categories":["Tools","C","Resources","Uncategorized"],"sub_categories":["File Format Fuzzers","By Purpose","Uncategorized"],"readme":"# AFLGo: Directed Greybox Fuzzing\n\u003ca href=\"https://mboehme.github.io/paper/CCS17.pdf\" target=\"_blank\"\u003e\u003cimg src=\"https://github.com/mboehme/mboehme.github.io/blob/master/paper/CCS17.png\" align=\"right\" width=\"250\"\u003e\u003c/a\u003e\nAFLGo is an extension of \u003ca href=\"https://lcamtuf.coredump.cx/afl/\" target=\"_blank\"\u003eAmerican Fuzzy Lop (AFL)\u003c/a\u003e.\nGiven a set of target locations (e.g., `folder/file.c:582`), AFLGo generates inputs specifically with the objective to exercise these target locations.\n\nUnlike AFL, AFLGo spends most of its time budget on reaching specific target locations without wasting resources stressing unrelated program components. This is particularly interesting in the context of\n* **patch testing** by setting changed statements as targets. When a critical component is changed, we would like to check whether this introduced any vulnerabilities. AFLGo, a fuzzer that can focus on those changes, has a higher chance of exposing the regression.\n* **static analysis report verification** by setting statements as targets that a static analysis reports as potentially dangerous or vulnerability-inducing. When assessing the security of a program, static analysis tools might identify dangerous locations, such as critical system calls. AFLGo can generate inputs that actually show that this is indeed no false positive.\n* **information flow detection** by setting sensitive sources and sinks as targets. To expose data leakage vulnerabilities, a security researcher would like to generate executions that exercise sensitive sources containing private information and sensitive sinks where data becomes visible to the outside world. A directed fuzzer can be used to generate such executions efficiently.\n* **crash reproduction**  by setting method calls in the stack-trace as targets. When in-field crashes are reported, only the stack-trace and some environmental parameters are sent to the in-house development team. To preserve the user's privacy, the specific crashing input is often not available. AFLGo could help the in-house team to swiftly reproduce these crashes.\n\nAFLGo is based on \u003ca href=\"http://lcamtuf.coredump.cx/afl/\" target=\"_blank\"\u003eAFL\u003c/a\u003e from Michał Zaleski \\\u003clcamtuf@coredump.cx\\\u003e. Checkout the project [awesome-directed-fuzzing](https://github.com/strongcourage/awesome-directed-fuzzing) for related work on directed greybox/whitebox fuzzing.\n\n# Getting Started\nLet's get started with building AFLGo (on Ubuntu 20.04) and fuzz the target libxml2:\n```bash\ngit clone https://github.com/aflgo/aflgo.git\ncd aflgo\nexport AFLGO=$PWD\n\n# Build AFLGo\nsudo ./build.sh\n\n# When you fuzz for the very first time...\nsudo sh -c 'echo core \u003e /proc/sys/kernel/core_pattern'\n\n# Fuzz the target libxml2\ncd examples\n./libxml2-ef709ce2.sh\n```\nSee the detailed steps discussed below.\n\n# Integration into OSS-Fuzz\nThe easiest way to use AFLGo is as patch testing tool in OSS-Fuzz. Here is our integration:\n* https://github.com/aflgo/oss-fuzz\n\n# Environment Variables\n* **AFLGO_INST_RATIO** -- The proportion of basic blocks instrumented with distance values (default: 100).\n* **AFLGO_SELECTIVE** -- Add AFL-trampoline only to basic blocks with distance values? (default: off).\n* **AFLGO_PROFILER_FILE** -- When CFG-tracing is enabled, the data will be stored here. (See `instrument/README.md`)\n\n# How to instrument a Binary with AFLGo\n\nYou can run [AFLGo building script](./build.sh) to do everything for you instead of manually go through **step 1** to **step 3**. Be careful in these steps we would download, build and install LLVM 11.0.0 from source, which may have unexpected impacts on compiler toolchain in current system.\n\nFor **step 4** to **step 8**, we are going to take \u003ca href=\"http://xmlsoft.org/\" target=\"_blank\"\u003elibxml2\u003c/a\u003e as an example. You can also equivalently run [libxml2 fuzzing script](./examples/libxml2-ef709ce2.sh) instead.\n\nBefore we start, make sure that source code tree of AFLGo is ready and we are in its root. Then set the environment variable `AFLGO` to it, which will be used in later steps. For example,\n```bash\ngit clone https://github.com/aflgo/aflgo.git\ncd aflgo\nexport AFLGO=$PWD\n```\n\n1) Install \u003ca href=\"https://releases.llvm.org/11.0.0/docs/CMake.html\" target=\"_blank\"\u003eLLVM\u003c/a\u003e **11.0.0** with \u003ca href=\"http://llvm.org/docs/GoldPlugin.html\" target=\"_blank\"\u003eGold\u003c/a\u003e-plugin. Then make sure that the following commands successfully executed:\n   ```bash\n   # Install LLVMgold into bfd-plugins\n   mkdir /usr/lib/bfd-plugins\n   cp /usr/local/lib/libLTO.so /usr/lib/bfd-plugins\n   cp /usr/local/lib/LLVMgold.so /usr/lib/bfd-plugins\n   ```\n\n2) Install other prerequisite\n   ```bash\n   sudo apt-get update\n   sudo apt-get install python3\n   sudo apt-get install python3-dev\n   sudo apt-get install python3-pip\n   sudo apt-get install pkg-config\n   sudo apt-get install autoconf\n   sudo apt-get install automake\n   sudo apt-get install libtool-bin\n   sudo apt-get install gawk\n   sudo apt-get install libboost-all-dev  # boost is not required if you use gen_distance_orig.sh in step 7\n   python3 -m pip install networkx  # May vary by different python versions, see the case statement in build.sh\n   python3 -m pip install pydot\n   python3 -m pip install pydotplus\n   ```\n\n3) Compile AFLGo fuzzer, LLVM-instrumentation pass and the distance calculator\n   ```bash\n   export CXX=`which clang++`\n   export CC=`which clang`\n   export LLVM_CONFIG=`which llvm-config`\n\n   pushd afl-2.57b; make clean all; popd;\n   pushd instrument; make clean all; popd;\n   pushd distance/distance_calculator; cmake ./; cmake --build ./; popd;\n   ```\n\n4) Download subject \u003ca href=\"http://xmlsoft.org/\" target=\"_blank\"\u003elibxml2\u003c/a\u003e.\n   ```bash\n   # Clone subject repository\n   git clone https://gitlab.gnome.org/GNOME/libxml2\n   export SUBJECT=$PWD/libxml2\n   ```\n\n5) Set targets (e.g., changed statements in commit \u003ca href=\"https://git.gnome.org/browse/libxml2/commit/?id=ef709ce2\" target=\"_blank\"\u003eef709ce2\u003c/a\u003e). Writes `BBtargets.txt`.\n   ```bash\n   # Setup directory containing all temporary files\n   mkdir temp\n   export TMP_DIR=$PWD/temp\n\n   # Download commit-analysis tool\n   wget https://raw.githubusercontent.com/jay/showlinenum/develop/showlinenum.awk\n   chmod +x showlinenum.awk\n   mv showlinenum.awk $TMP_DIR\n\n   # Generate BBtargets from commit ef709ce2\n   pushd $SUBJECT\n     git checkout ef709ce2\n     git diff -U0 HEAD^ HEAD \u003e $TMP_DIR/commit.diff\n   popd\n   cat $TMP_DIR/commit.diff |  $TMP_DIR/showlinenum.awk show_header=0 path=1 | grep -e \"\\.[ch]:[0-9]*:+\" -e \"\\.cpp:[0-9]*:+\" -e \"\\.cc:[0-9]*:+\" | cut -d+ -f1 | rev | cut -c2- | rev \u003e $TMP_DIR/BBtargets.txt\n\n   # Print extracted targets. \n   echo \"Targets:\"\n   cat $TMP_DIR/BBtargets.txt\n   ```\n   **Note**: If there are no targets, there is nothing to instrument!\n\n6) Generate CG and intra-procedural CFGs from the subject.\n   ```bash\n   # Set aflgo-instrumenter\n   export CC=$AFLGO/instrument/aflgo-clang\n   export CXX=$AFLGO/instrument/aflgo-clang++\n   \n   # Set aflgo-instrumentation flags\n   export COPY_CFLAGS=$CFLAGS\n   export COPY_CXXFLAGS=$CXXFLAGS\n   export ADDITIONAL=\"-targets=$TMP_DIR/BBtargets.txt -outdir=$TMP_DIR -flto -fuse-ld=gold -Wl,-plugin-opt=save-temps\"\n   export CFLAGS=\"$CFLAGS $ADDITIONAL\"\n   export CXXFLAGS=\"$CXXFLAGS $ADDITIONAL\"\n   \n   # Build libxml2 (in order to generate CG and CFGs).\n   # Meanwhile go have a coffee ☕️\n   export LDFLAGS=-lpthread\n   pushd $SUBJECT\n     ./autogen.sh\n     ./configure --disable-shared\n     make clean\n     make xmllint\n   popd\n   ```\n   You can test whether CG/CFG extraction was successful with\n   ```bash\n   $SUBJECT/xmllint --valid --recover $SUBJECT/test/dtd3\n   ls $TMP_DIR/dot-files\n   echo \"Function targets\"\n   cat $TMP_DIR/Ftargets.txt\n   ```\n   **Note**:\n    - If the linker (CCLD) complains that you should run `ranlib`, make sure that `libLTO.so` and `LLVMgold.so` (from \u003cu\u003eInstall LLVM 11.0.0 with Gold-plugin\u003c/u\u003e in step 1) can be found in `/usr/lib/bfd-plugins`.\n    - If the compiler crashes, there is some problem with LLVM not supporting our instrumentation (*afl-llvm-pass.so.cc:540-577*). LLVM has changed the instrumentation-API very often :( You can check LLVM-version, fix problem, and prepare pull request.\n    - You can speed up the compilation with a parallel build. However, this may impact which BBs are identified as targets. See https://github.com/aflgo/aflgo/issues/41.\n\n7) Generate distance file.\n   Firstly we need to clean up `BBnames.txt` and `BBcalls.txt`, otherwise `distance_calculator` may fail. This is necessary for any subjects, not only for *libxml2*.\n   ```bash\n   # Clean up\n   cat $TMP_DIR/BBnames.txt | grep -v \"^$\"| rev | cut -d: -f2- | rev | sort | uniq \u003e $TMP_DIR/BBnames2.txt \u0026\u0026 mv $TMP_DIR/BBnames2.txt $TMP_DIR/BBnames.txt\n   \n   cat $TMP_DIR/BBcalls.txt | grep -Ev \"^[^,]*$|^([^,]*,){2,}[^,]*$\"| sort | uniq \u003e $TMP_DIR/BBcalls2.txt \u0026\u0026 mv $TMP_DIR/BBcalls2.txt $TMP_DIR/BBcalls.txt\n   ```\n   Then start to generate (this may take a while):\n   ```bash\n   # Generate distance ☕️\n   # $AFLGO/distance/gen_distance_orig.sh is the original, but significantly slower, version\n   \n   $AFLGO/distance/gen_distance_fast.py $SUBJECT $TMP_DIR xmllint\n   ```\n   After that you can check the generated distance file with\n   ```bash\n   echo \"Distance values:\"\n   head -n5 $TMP_DIR/distance.cfg.txt\n   echo \"...\"\n   tail -n5 $TMP_DIR/distance.cfg.txt\n   ```\n   **Note**: If `distance.cfg.txt` is empty, there was some problem computing the CG-level and BB-level target distance. See `$TMP_DIR/step*.log`.\n\n8) Instrument the subject\n   ```bash\n   export CFLAGS=\"$COPY_CFLAGS -distance=$TMP_DIR/distance.cfg.txt\"\n   export CXXFLAGS=\"$COPY_CXXFLAGS -distance=$TMP_DIR/distance.cfg.txt\"\n\n   # Clean and build subject with distance instrumentation ☕️\n   pushd $SUBJECT\n     make clean\n     ./configure --disable-shared\n     make xmllint\n   popd\n   ```\n   If your compilation crashes in this step, have a look at Issue [#4](https://github.com/aflgo/aflgo/issues/4#issuecomment-333947041).\n\n# How to fuzz the instrumented binary\n* We set the exponential annealing-based power schedule (`-z exp`).\n* We set the time-to-exploitation to 45min (`-c 45m`), assuming the fuzzer is run for about an hour.\n\n(Still take the previous libxml2 as an example)\n```bash\n# Construct seed corpus\nmkdir in\ncp -r $SUBJECT/test/dtd* in\ncp $SUBJECT/test/dtds/* in\n\n$AFLGO/afl-2.57b/afl-fuzz -S ef709ce2 -z exp -c 45m -i in -o out $SUBJECT/xmllint --valid --recover @@\n```\n* **Tipp**: Concurrently fuzz the most recent version as master with classical AFL :)\n```bash\n$AFL/afl-fuzz -M master -i in -o out $MASTER/xmllint --valid --recover @@\n```\n* Run more [fuzzing scripts](./examples) of various real programs like *Binutils*, *jasper*, *lrzip*, *libming* and *DARPA CGC*. Those scripts haven't contained any dependencies installing steps yet. So it's recommended that see READMEs of those projects first to check their requirements.\n\n## Contributors\n\n\u003ca href=\"https://github.com/aflgo/aflgo/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=aflgo/aflgo\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faflgo%2Faflgo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faflgo%2Faflgo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faflgo%2Faflgo/lists"}