en.search-data.min.d53c7849d10764fa6e707193a89686ab11c3c97151406643991130b6a82cd094.js

'use strict';(function(){const indexCfg={cache:true};indexCfg.doc={id:'id',field:['title','content'],store:['title','href'],};const index=FlexSearch.create('balance',indexCfg);window.bookSearchIndex=index;index.add({'id':0,'href':'/building/','title':"Building",'content':"Build and install AFL++ Download the lastest devel version with:\n$ git clone https://github.com/AFLplusplus/AFLplusplus $ cd AFLplusplus AFL++ has many build options. The easiest is to build and install everything:\n$ make distrib $ sudo make install Note that \u0026ldquo;make distrib\u0026rdquo; also builds llvm_mode, qemu_mode, unicorn_mode and more. If you just want plain afl then do \u0026ldquo;make all\u0026rdquo;, however compiling and using at least llvm_mode is highly recommended for much better results - hence in this case\n$ make source-only is what you should choose.\nThese build options exist:\n all: just the main AFL++ binaries binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode, libdislocator, libtokencap, radamsa source-only: everything for source code fuzzing: llvm_mode, libdislocator, libtokencap, radamsa distrib: everything (for both binary-only and source code fuzzing) install: installs everything you have compiled with the build options above clean: cleans everything. for qemu_mode and unicorn_mode it means it deletes all downloads as well code-format: format the code, do this before you commit and send a PR please! tests: runs test cases to ensure that all features are still working as they should help: shows these build options  Unless you are on Mac OS X you can also build statically linked versions of the AFL++ binaries by passing the STATIC=1 argument to make:\n$ make all STATIC=1 Note that AFL++ is faster and better the newer the compilers used are. Hence gcc-9 and especially llvm-9 should be the compilers of choice. If your distribution does not have them, you can use the Dockerfile:\n$ docker build -t aflplusplus "});index.add({'id':1,'href':'/docs/','title':"Docs",'content':"AFL++ Documentation You can browse a part of the AFL++ doc here.\n Binary-only fuzzing Environmant variables Status screen Parallel fuzzing Performance tips Note for ASan Power schedules Custom mutators Technical Details Historical Notes  "});index.add({'id':2,'href':'/docs/tutorials/','title':"Tutorials",'content':"AFL++ Tutorials  Fuzzing libxml2 with AFL++  Third party  Fuzzing software: common challenges and potential solutions (Github Security Lab) AFL++ Docker suite images (Pentagrid) Fuzzing a Gameboy Emulator with AFL++ (bananamafia)  "});index.add({'id':3,'href':'/features/','title':"Features",'content':"AFL++ Features Many improvements were made over the official afl release - which did not get any feature improvements since November 2017.\nAmong other changes afl++ has a more performant llvm_mode, supports llvm up to version 11, QEMU 3.1, more speed and crashfixes for QEMU, better *BSD and Android support and much, much more.\nAdditionally the following features and patches have been integrated:\n  AFLfast\u0026rsquo;s power schedules by Marcel Böhme: https://github.com/mboehme/aflfast\n  The new excellent MOpt mutator: https://github.com/puppet-meteor/MOpt-AFL\n  InsTrim, a very effective CFG llvm_mode instrumentation implementation for large targets: https://github.com/csienslab/instrim\n  C. Holler\u0026rsquo;s afl-fuzz Python mutator module and llvm_mode whitelist support: https://github.com/choller/afl\n  Custom mutator by a library (instead of Python) by kyakdan\n  Unicron mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk)\n  LAF-Intel or CompCov support for llvm_mode, qemu_mode and unicorn_mode\n  NeverZero patch for afl-gcc, llvm_mode, qemu_mode and unicorn_mode which prevents a wrapping map value to zero, increases coverage\n  Persistent mode and deferred forkserver for qemu_mode\n  Win32 PE binary-only fuzzing with QEMU and Wine\n  Radamsa mutator (enable with -R to add or -RR to run it exclusivly).\n  QBDI mode to fuzz android native libraries via QBDI framework\n  The new CmpLog instrumentation for LLVM and QEMU inspired by Redqueen\n  LLVM mode Ngram coverage by Adrian Herrera https://github.com/adrianherrera/afl-ngram-pass\n  A more thorough list is available in the PATCHES file.\n   Feature/Instrumentation afl-gcc llvm_mode gcc_plugin qemu_mode unicorn_mode     NeverZero x x(1) (2) x x   Persistent mode  x x x86[_64]/arm[64] x   LAF-Intel / CompCov  x  x86[_64]/arm[64] x86[_64]/arm   CmpLog  x  x86[_64]/arm[64]    Whitelist  x x (x)(3)    Non-colliding coverage  x(4)  (x)(5)    InsTrim  x      Ngram prev_loc coverage  x(6)      Context coverage  x      Snapshot LKM support  x  (x)(5)     neverZero:\n(1) default for LLVM \u0026gt;= 9.0, env var for older version due an efficiency bug in llvm \u0026lt;= 8\n(2) GCC creates non-performant code, hence it is disabled in gcc_plugin\n(3) partially via AFL_CODE_START/AFL_CODE_END\n(4) Only for LLVM \u0026gt;= 9 and not all targets compile\n(5) upcoming, development in the branch\n(6) not compatible with LTO and InsTrim and needs at least LLVM \u0026gt;= 4.1\nSo all in all this is the best-of afl that is currently out there :-)\n"});index.add({'id':4,'href':'/aflpp_fuzzing_framework_proposal/','title':"Aflpp Fuzzing Framework Proposal",'content':"AFL++ as a Fuzzing Framework Proposal by Andrea.\nBig changes were done in AFL++ to improve usability but the tool remains an extension of the legendary AFL that inherits also its limitations.\nThe future of AFL++, in my opinion, is not to improve the performance of AFL of a percentile.\nWe don\u0026rsquo;t aim to build the \u0026ldquo;best\u0026rdquo; fuzzer, the best fuzzer is the fuzzer that you write for your target. We just want to give you all the pieces to do so easily and effectively.\nA framework to build fuzzers We want to create a fuzzing framework with all the pieces to build fuzzer, a sort of \u0026ldquo;LLVM of fuzzers\u0026rdquo;.\nafl-fuzz will be just one of the frontends to this library.\nWe will code it entirely in C starting from the existing AFl++ codebase for the maximum compatibility. One of our goals is to allow a DBI or a debugger to inject the entire library in a target process (like in frida-fuzzer, but better and NOT in Javascript).\nImagine injecting the library in a Windows application with a DLL injection with a harness that fuzzes an API with a structured mutator and without coverage. Or maybe with hardware feedback as coverage, or using a DBI, there is a landscape of possibilities.\nMultiple fuzzers in one Imagine that you built 2 fuzzers but wants to share their results, we don\u0026rsquo;t want to synchronize testcases anymore (we will ofc maintain the possibility to do that ofc for backward compatibility with AFL but seriously we want to deprecate it).\nYou can define these 2 fuzzers, run the first one a thread and run, e.g., 3 instances of the seconds running on 3 threads. All in the same process sharing results immediately.\nThere are several multithreaded fuzzers, most notably honggfuzz, but our idea is to go further and have different configurations running in different threads, not simply a multithreaded fuzzer.\nBasic building blocks To be an effective framework, we define the basic set of building blocks and how they interact.\nA fuzzer can have multiple executors (a forkserver is an executor), for instance one for CmpLog, one for coverage feedback, one for ASan that executes the binary each time that a new interesting input is found.\nA fuzzer can have multiple feedback mechanisms (one for executor or multiple for executor e.g. edge coverage + cmp). When a new testcase triggers new feedback a callback decides if the new input has to be inserted in the normal queue or in the per-feedback queue or both.\nSo the seed selection (the favored testcases set) can work on both normal queue or per-feedback queue. A mechanism for seed scheduling can be designed to stress a single type of feedback if the others are stuck (e.g. fuzzing does not produce anymore edge coverage but we still produce feedback regards memory allocation size, the fuzzer will use with more probability testcases from this per-feedback queue).\nThere will be also the possibility to use a custom algorithm for calculating the energy of a testcase that can be different for each feedback mechanism.\nMutators are independent sets of mutations. A scheduling policy can be set for such mutations (by default randomly taken like in havoc).\nEntities  Executor  Logger (shared mem or whatever, also a mmaped file, define a generic interface)   Feedback  Feedback specific queue  Feedback specific seed scheduler Feedback specific seed energy     Generic queue  Generic seed scheduler Generic seed scheduler   Stage  Mutator (simple) ScheduledMutator  Mutation Mutations scheduler (only 2 atm, random and mopt)      Interfaces Executor { loggers // more than one init() destroy() run_target() } Logger { start // mem addr end init() destroy() flush() reset() // memset 0 in the edge coverage case in AFL } Feedback { loggers // more than one. also, a logger can be used by multiple feedbacks specific_queue init() destroy() is_interesting() } FeedbackSpecificQueue { feedback scheduler energy_calc } GenericQueue { feedbacks // all feedbacks scheduler energy_calc } Stage { executor init() destroy() run() } Mutator() { mutate() } ScheduledMutator() { scheduler mutations[] mutate() } Example functions From a current source code perspective, afl-fuzz.c would be the main.c and all other files be part of libaflpp.so\nSeeds ssize_t afpp_seedselection_load_seeds(struct_aflpp *aflpp, char *directory_or_file)\n ssize_t := number of seeds loaded  void aflpp_seedselection_configure(struct_aflpp *aflpp, uint32_t weight_time, uint32_t weight_len, uint32_t rare, bool now)\nSetup a specific seed selection strategy. might need more options.\n weight_\u0026hellip; : apply weighting to this characeristic (0 = none, 1 = x1, 2 = x2, etc.) now:= false: starting next cycle, true: immedeatly  int32_t aflpp_seedselection_custom_register(struct_aflpp *aflpp, void *custom_seed_calculation_callback)\nRegister your own seed selection algorithm\n int32_t := -1 : failed, \u0026gt;= 0 : custom_seedselection_id  bool aflpp_seedselection_custom_enable|disable(struct_aflpp *aflpp, int32_t custom_mutator_id)\n bool := true : success, false : failure (not defined)  void aflpp_seedselection_method(struct_aflpp *aflpp, uint32_t method, bool now)\nAlternativly select a pre-coded stategy\n method := enum { EXPLORE, FAST, COE, LIN, QUAD, EXPLOIT, MMOPT, RARE }  bool aflpp_seedselection_next(struct_aflpp *aflpp)\nGo to the next seed. Normally this would not be used as aflpp_mutations_mutate() would do that.\n bool := true: this starts next cycle  Mutation void aflpp_mutations_configure(struct_aflpp *aflpp, uint64_t mutations, bool now)\nConfigure the mutator\n mutations := enum { BITFLIP, ARITH, DICT, HAVOC, MORE_HAVOC, \u0026hellip; }, combined with OR  int32_t aflpp_mutations_custom_register(struct_aflpp *aflpp, void *custom_init, void *custom_new_seed, void *custom_mutate, ... \n int32_t := -1 : failed, \u0026gt;= 0 : custom_mutator_id void* parameters can be NULL  bool aflpp_mutations_custom_enable|disable(struct_aflpp *aflpp, int32_t custom_mutator_id)\n bool := true : success, false : failure (not defined)  ssize_t aflpp_mutations_mutate(struct_aflpp *aflpp, uint32_t end, uint32_t count, uint32_t min_len, uint32_t max_len, void *sender_callback)\n end := enum { NONE, DONE_WITH_SEED, DONE_MUTATION_TYPE), combined with OR count := number of maximum of mutations to perform, 0 = no limit (and basically what end says but can then not be NONE) sender_callback := the function that sends the data to the target (e.g. to stdin, file, tcp/ip, ipc, ioctl, \u0026hellip;) ssize_t := number of mutations performed  ssize_t aflpp_mutations_mutate_specfic(struct_aflpp *aflpp, uint64_t mutator_type, uint32_t count, uint32_t min_len, uint32_t max_len, void *sender_callback)\nsame as aflpp_mutations_mutate() but only use this specific mutator (of enum mutations)\nssize_t aflpp_mutations_mutate_custom(struct_aflpp *aflpp, int32_t custom_mutator_id, uint32_t count, uint32_t min_len, uint32_t max_len, void *sender_callback)\nsame as aflpp_mutations_mutate() but only use this specific mutator (of enum mutations)\nAlso: load dictionary + enable/disable dictionary, etc.\nSending ssize_t sender_callback(struct_aflpp *aflpp, u8 *buf, uint32_t len)\nwe should also have default senders, e.g. aflpp_send_stdin, aflpp_send_file, aflpp_send_argv, aflpp_send_network, \u0026hellip; for which some need a _configure, e.g. for file, network, argv\nstruct_aflpp has pointers to struct_seed, struct_mutation, \u0026hellip;\n"});index.add({'id':5,'href':'/docs/binaryonly_fuzzing/','title':"Binaryonly Fuzzing",'content':"Fuzzing binary-only programs with afl++ afl++, libfuzzer and others are great if you have the source code, and it allows for very fast and coverage guided fuzzing.\nHowever, if there is only the binary program and no source code available, then standard afl-fuzz -n (dumb mode) is not effective.\nThe following is a description of how these binaries can be fuzzed with afl++\nTL;DR: qemu_mode in persistent mode is the fastest - if the stability is high enough. Otherwise try retrowrite, afl-dyninst and if these fail too then standard qemu_mode with AFL_ENTRYPOINT to where you need it.\nQEMU Qemu is the \u0026ldquo;native\u0026rdquo; solution to the program. It is available in the ./qemu_mode/ directory and once compiled it can be accessed by the afl-fuzz -Q command line option. It is the easiest to use alternative and even works for cross-platform binaries.\nThe speed decrease is at about 50%. However various options exist to increase the speed:\n using AFL_ENTRYPOINT to move the forkserver to a later basic block in the binary (+5-10% speed) using persistent mode qemu_mode/README.persistent.md this will result in 150-300% overall speed - so 3-8x the original qemu_mode speed! using AFL_CODE_START/AFL_CODE_END to only instrument specific parts  Note that there is also honggfuzz: https://github.com/google/honggfuzz which now has a qemu_mode, but its performance is just 1.5% \u0026hellip;\nAs it is included in afl++ this needs no URL.\nWINE+QEMU Wine mode can run Win32 PE binaries with the QEMU instrumentation. It needs Wine, python3 and the pefile python package installed.\nAs it is included in afl++ this needs no URL.\nUNICORN Unicorn is a fork of QEMU. The instrumentation is, therefore, very similar. In contrast to QEMU, Unicorn does not offer a full system or even userland emulation. Runtime environment and/or loaders have to be written from scratch, if needed. On top, block chaining has been removed. This means the speed boost introduced in the patched QEMU Mode of afl++ cannot simply be ported over to Unicorn. For further information, check out unicorn_mode/README.md.\nAs it is included in afl++ this needs no URL.\nDYNINST Dyninst is a binary instrumentation framework similar to Pintool and Dynamorio (see far below). However whereas Pintool and Dynamorio work at runtime, dyninst instruments the target at load time, and then let it run - or save the binary with the changes. This is great for some things, e.g. fuzzing, and not so effective for others, e.g. malware analysis.\nSo what we can do with dyninst is taking every basic block, and put afl\u0026rsquo;s instrumention code in there - and then save the binary. Afterwards we can just fuzz the newly saved target binary with afl-fuzz. Sounds great? It is. The issue though - it is a non-trivial problem to insert instructions, which change addresses in the process space, so that everything is still working afterwards. Hence more often than not binaries crash when they are run.\nThe speed decrease is about 15-35%, depending on the optimization options used with afl-dyninst.\nSo if Dyninst works, it is the best option available. Otherwise it just doesn\u0026rsquo;t work well.\nhttps://github.com/vanhauser-thc/afl-dyninst\nRETROWRITE If you have an x86/x86_64 binary that still has it\u0026rsquo;s symbols, is compiled with position independant code (PIC/PIE) and does not use most of the C++ features then the retrowrite solution might be for you. It decompiles to ASM files which can then be instrumented with afl-gcc.\nIt is at about 80-85% performance.\nhttps://github.com/HexHive/retrowrite\nMCSEMA Theoretically you can also decompile to llvm IR with mcsema, and then use llvm_mode to instrument the binary. Good luck with that.\nhttps://github.com/lifting-bits/mcsema\nINTEL-PT If you have a newer Intel CPU, you can make use of Intels processor trace. The big issue with Intel\u0026rsquo;s PT is the small buffer size and the complex encoding of the debug information collected through PT. This makes the decoding very CPU intensive and hence slow. As a result, the overall speed decrease is about 70-90% (depending on the implementation and other factors).\nThere are two afl intel-pt implementations:\n  https://github.com/junxzm1990/afl-pt =\u0026gt; this needs Ubuntu 14.04.05 without any updates and the 4.4 kernel.\n  https://github.com/hunter-ht-2018/ptfuzzer =\u0026gt; this needs a 4.14 or 4.15 kernel. the \u0026ldquo;nopti\u0026rdquo; kernel boot option must be used. This one is faster than the other.\n  Note that there is also honggfuzz: https://github.com/google/honggfuzz But its IPT performance is just 6%!\nCORESIGHT Coresight is ARM\u0026rsquo;s answer to Intel\u0026rsquo;s PT. There is no implementation so far which handle coresight and getting it working on an ARM Linux is very difficult due to custom kernel building on embedded systems is difficult. And finding one that has coresight in the ARM chip is difficult too. My guess is that it is slower than Qemu, but faster than Intel PT.\nIf anyone finds any coresight implementation for afl please ping me: vh@thc.org\nFRIDA Frida is a dynamic instrumentation engine like Pintool, Dyninst and Dynamorio. What is special is that it is written Python, and scripted with Javascript. It is mostly used to reverse binaries on mobile phones however can be used everywhere.\nThere is a WIP fuzzer available at https://github.com/andreafioraldi/frida-fuzzer\nThere is also an early implementation in an AFL++ test branch: https://github.com/AFLplusplus/AFLplusplus/tree/frida\nPIN \u0026amp; DYNAMORIO Pintool and Dynamorio are dynamic instrumentation engines, and they can be used for getting basic block information at runtime. Pintool is only available for Intel x32/x64 on Linux, Mac OS and Windows whereas Dynamorio is additionally available for ARM and AARCH64. Dynamorio is also 10x faster than Pintool.\nThe big issue with Dynamorio (and therefore Pintool too) is speed. Dynamorio has a speed decrease of 98-99% Pintool has a speed decrease of 99.5%\nHence Dynamorio is the option to go for if everything fails, and Pintool only if Dynamorio fails too.\nDynamorio solutions:\n https://github.com/vanhauser-thc/afl-dynamorio https://github.com/mxmssh/drAFL https://github.com/googleprojectzero/winafl/ \u0026lt;= very good but windows only  Pintool solutions:\n https://github.com/vanhauser-thc/afl-pin https://github.com/mothran/aflpin https://github.com/spinpx/afl_pin_mode \u0026lt;= only old Pintool version supported  Non-AFL solutions There are many binary-only fuzzing frameworks. Some are great for CTFs but don\u0026rsquo;t work with large binaries, others are very slow but have good path discovery, some are very hard to set-up \u0026hellip;\n QSYM: https://github.com/sslab-gatech/qsym Manticore: https://github.com/trailofbits/manticore S2E: https://github.com/S2E \u0026hellip; please send me any missing that are good  Closing words That\u0026rsquo;s it! News, corrections, updates? Send an email to vh@thc.org\n"});index.add({'id':6,'href':'/docs/changelog/','title':"Changelog",'content':"Changelog This is the list of all noteworthy changes made in every public release of the tool. See README.md for the general instruction manual.\nStaying informed Want to stay in the loop on major new features? Join our mailing list by sending a mail to afl-users+subscribe@googlegroups.com.\nVersion ++2.63c (release): ! the repository was moved from vanhauser-thc to AFLplusplus. It is now an own organisation :) ! development and acceptance of PRs now happen only in the dev branch and only occasionally when everything is fine we PR to master\n all:  big code changes to make afl-fuzz thread-safe so afl-fuzz can spawn multiple fuzzing threads in the future or even become a library afl basic tools now report on the environment variables picked up more tools get environment variable usage info in the help output force all output to stdout (some OK/SAY/WARN messages were sent to stdout, some to stderr) uninstrumented mode uses an internal forkserver (\u0026ldquo;fauxserver\u0026rdquo;) now builds with -D_FORTIFY_SOURCE=2 drastically reduced number of (de)allocations during fuzzing   afl-fuzz:  python mutator modules and custom mutator modules now use the same interface and hence the API changed AFL_AUTORESUME will resume execution without the need to specify -i - added experimental power schedules (-p):  mmopt: ignores runtime of queue entries, gives higher weighting to the last 5 queue entries rare: puts focus on queue entries that hits rare branches, also ignores runtime     llvm_mode:  added SNAPSHOT feature (using https://github.com/AFLplusplus/AFL-Snapshot-LKM) added Control Flow Integrity sanitizer (AFL_USE_CFISAN) added AFL_LLVM_INSTRUMENT option to control the instrumentation type easier: DEFAULT, CFG (INSTRIM), LTO, CTX, NGRAM-x (x=2-16) made USE_TRACE_PC compile obsolete   LTO collision free instrumented added in llvm_mode with afl-clang-lto - note that this mode is amazing, but quite some targets won\u0026rsquo;t compile Added llvm_mode NGRAM prev_loc coverage by Adrean Herrera (https://github.com/adrianherrera/afl-ngram-pass/), activate by setting AFL_LLVM_INSTRUMENT=NGRAM-or AFL_LLVM_NGRAM_SIZE= Added llvm_mode context sensitive branch coverage, activated by setting AFL_LLVM_INSTRUMENT=CTX or AFL_LLVM_CTX=1 llvm_mode InsTrim mode:  removed workaround for bug where paths were not instrumented and imported fix by author made skipping 1 block functions an option and is disabled by default, set AFL_LLVM_INSTRIM_SKIPSINGLEBLOCK=1 to re-enable this   qemu_mode:  qemu_mode now uses solely the internal capstone version to fix builds on modern Linux distributions QEMU now logs routine arguments for CmpLog when the target is x86   afl-tmin:  now supports hang mode -H to minimize hangs fixed potential afl-tmin missbehavior for targets with multiple hangs   Pressing Control-c in afl-cmin did not terminate it for some OS the custom API was rewritten and is now the same for Python and shared libraries.  Version ++2.62c (release):  Important fix for memory allocation functions that result in afl-fuzz not identifying crashes - UPDATE! Small fix for -E/-V to release the CPU CmpLog does not need sancov anymore  Version ++2.61c (release):  use -march=native if available most tools now check for mistyped environment variables gcc 10 is now supported the memory safety checks are now disabled for a little more speed during fuzzing (only affects creating queue entries), can be toggled in config.h afl-fuzz:  MOpt out of bounds writing crash fixed now prints the real python version support compiled in set stronger performance compile options and little tweaks Android: prefer bigcores when selecting a CPU CmpLog forkserver Redqueen input-2-state mutator (cmp instructions only ATM) all Python 2+3 versions supported now changed execs_per_sec in fuzzer_stats from \u0026ldquo;current\u0026rdquo; execs per second (which is pointless) to total execs per second bugfix for dictionary insert stage count (fix via Google repo PR) added warning if -M is used together with custom mutators with _ONLY option AFL_TMPDIR checks are now later and better explained if they fail   llvm_mode  InsTrim: three bug fixes:  (minor) no pointless instrumentation of 1 block functions (medium) path bug that leads a few blocks not instrumented that should be (major) incorrect prev_loc was written, fixed!     afl-clang-fast:  show in the help output for which llvm version it was compiled for now does not need to be recompiled between trace-pc and pass instrumentation. compile normally and set AFL_LLVM_USE_TRACE_PC :) LLVM 11 is supported CmpLog instrumentation using SanCov (see llvm_mode/README.cmplog.md)   afl-gcc, afl-clang-fast, afl-gcc-fast:  experimental support for undefined behaviour sanitizer UBSAN (set AFL_USE_UBSAN=1) the instrumentation summary output now also lists activated sanitizers afl-as: added isatty(2) check back in added AFL_DEBUG (for upcoming merge)   qemu_mode:  persistent mode is now also available for arm and aarch64 CmpLog instrumentation for QEMU (-c afl-fuzz command line option) for x86, x86_64, arm and aarch64 AFL_PERSISTENT_HOOK callback module for persistent QEMU (see examples/qemu_persistent_hook) added qemu_mode/README.persistent.md documentation AFL_ENTRYPOINT noew has instruction granularity   afl-cmin is now a sh script (invoking awk) instead of bash for portability the original script is still present as afl-cmin.bash afl-showmap: -i dir option now allows processing multiple inputs using the forkserver. This is for enhanced speed in afl-cmin. added blacklist and whitelisting function check in all modules of llvm_mode added fix from Debian project to compile libdislocator and libtokencap libdislocator: AFL_ALIGNED_ALLOC to force size alignment to max_align_t  Version ++2.60c (release):  fixed a critical bug in afl-tmin that was introduced during ++2.53d added test cases for afl-cmin and afl-tmin to test/test.sh added ./examples/argv_fuzzing ld_preload library by Kjell Braden added preeny\u0026rsquo;s desock_dup ld_preload library as ./examples/socket_fuzzing for network fuzzing added AFL_AS_FORCE_INSTRUMENT environment variable for afl-as - this is for the retrorewrite project we now set QEMU_SET_ENV from AFL_PRELOAD when qemu_mode is used  Version ++2.59c (release):  qbdi_mode: fuzz android native libraries via QBDI framework unicorn_mode: switched to the new unicornafl, thanks domenukk (see https://github.com/vanhauser-thc/unicorn) afl-fuzz:  added radamsa as (an optional) mutator stage (-R[R]) added -u command line option to not unlink the fuzz input file Python3 support (autodetect) AFL_DISABLE_TRIM env var to disable the trim stage CPU affinity support for DragonFly   llvm_mode:  float splitting is now configured via AFL_LLVM_LAF_SPLIT_FLOATS support for llvm 10 included now (thanks to devnexen)   libtokencap:  support for *BSD/OSX/Dragonfly added hook common *cmp functions from widely used libraries   compcov:  hook common *cmp functions from widely used libraries floating point splitting support for QEMU on x86 targets   qemu_mode: AFL_QEMU_DISABLE_CACHE env to disable QEMU TranslationBlocks caching afl-analyze: added AFL_SKIP_BIN_CHECK support better random numbers for gcc_plugin and llvm_mode (thanks to devnexen) Dockerfile by courtesy of devnexen added regex.dictionary qemu and unicorn download scripts now try to download until the full download succeeded. f*ckin travis fails downloading 40% of the time! more support for Android (please test!) added the few Android stuff we didnt have already from Google afl repository removed unnecessary warnings  Version ++2.58c (release):  reverted patch to not unlink and recreate the input file, it resulted in performance loss of ~10% added test/test-performance.sh script (re)added gcc_plugin, fast inline instrumentation is not yet finished, however it includes the whitelisting and persistance feature! by hexcoder- gcc_plugin tests added to testing framework  Version ++2.54d-2.57c (release):  we jump to 2.57 instead of 2.55 to catch up with Google\u0026rsquo;s versioning persistent mode for QEMU (see qemu_mode/README.md) custom mutator library is now an additional mutator, to exclusivly use it add AFL_CUSTOM_MUTATOR_ONLY (that will trigger the previous behaviour) new library qemu_mode/unsigaction which filters sigaction events afl-fuzz: new command line option -I to execute a command on a new crash no more unlinking the input file, this way the input file can also be a FIFO or disk partition setting LLVM_CONFIG for llvm_mode will now again switch to the selected llvm version. If your setup is correct. fuzzing strategy yields for custom mutator were missing from the UI, added them :) added \u0026ldquo;make tests\u0026rdquo; which will perform checks to see that all functionality is working as expected. this is currently the starting point, its not complete :) added mutation documentation feature (\u0026ldquo;make document\u0026rdquo;), creates afl-fuzz-document and saves all mutations of the first run on the first file into out/queue/mutations libtokencap and libdislocator now compile to the afl_root directory and are installed to the \u0026hellip;/lib/afl directory when present during make install more BSD support, e.g. free CPU binding code for FreeBSD (thanks to devnexen) reducing duplicate code in afl-fuzz added \u0026ldquo;make help\u0026rdquo; removed compile warnings from python internal stuff added man page for afl-clang-fast[++] updated documentation Wine mode to run Win32 binaries with the QEMU instrumentation (-W) CompareCoverage for ARM target in QEMU/Unicorn laf-intel in llvm_mode now also handles floating point comparisons  Version ++2.54c (release):  big code refactoring:  all includes are now in include/ all afl sources are now in src/ - see src/README.md afl-fuzz was splitted up in various individual files for including functionality in other programs (e.g. forkserver, memory map, etc.) for better readability. new code indention everywhere   auto-generating man pages for all (main) tools added AFL_FORCE_UI to show the UI even if the terminal is not detected llvm 9 is now supported (still needs testing) Android is now supported (thank to JoeyJiao!) - still need to modify the Makefile though fix building qemu on some Ubuntus (thanks to floyd!) custom mutator by a loaded library is now supported (thanks to kyakdan!) added PR that includes peak_rss_mb and slowest_exec_ms in the fuzzer_stats report more support for *BSD (thanks to devnexen!) fix building on *BSD (thanks to tobias.kortkamp for the patch) fix for a few features to support different map sized than 2^16 afl-showmap: new option -r now shows the real values in the buckets (stock afl never did), plus shows tuple content summary information now small docu updates NeverZero counters for QEMU NeverZero counters for Unicorn CompareCoverage Unicorn immediates-only instrumentation for CompareCoverage  Version ++2.53c (release):  README is now README.md imported the few minor changes from the 2.53b release unicorn_mode got added - thanks to domenukk for the patch! fix llvm_mode AFL_TRACE_PC with modern llvm fix a crash in qemu_mode which also exists in stock afl added libcompcov, a laf-intel implementation for qemu! :) see qemu_mode/libcompcov/README.libcompcov.md afl-fuzz now displays the selected core in the status screen (blue {#}) updated afl-fuzz and afl-system-config for new scaling governor location in modern kernels using the old ineffective afl-gcc will now show a deprecation warning all queue, hang and crash files now have their discovery time in their name if llvm_mode was compiled, afl-clang/afl-clang++ will point to these instead of afl-gcc added instrim, a much faster llvm_mode instrumentation at the cost of path discovery. See llvm_mode/README.instrim.md (https://github.com/csienslab/instrim) added MOpt (github.com/puppet-meteor/MOpt-AFL) mode, see docs/README.MOpt.md added code to make it more portable to other platforms than Intel Linux added never zero counters for afl-gcc and optionally (because of an optimization issue in llvm \u0026lt; 9) for llvm_mode (AFL_LLVM_NEVER_ZERO=1) added a new doc about binary only fuzzing: docs/binaryonly_fuzzing.txt more cpu power for afl-system-config added forkserver patch to afl-tmin, makes it much faster (originally from github.com/nccgroup/TriforceAFL) added whitelist support for llvm_mode via AFL_LLVM_WHITELIST to allow only to instrument what is actually interesting. Gives more speed and less map pollution (originally by choller@mozilla) added Python Module mutator support, python2.7-dev is autodetected. see docs/python_mutators.txt (originally by choller@mozilla) added AFL_CAL_FAST for slow applications and AFL_DEBUG_CHILD_OUTPUT for debugging added -V time and -E execs option to better comparison runs, runs afl-fuzz for a specific time/executions. added a -s seed switch to allow afl run with a fixed initial seed that is not updated. This is good for performance and path discovery tests as the random numbers are deterministic then llvm_mode LAF_\u0026hellip; env variables can now be specified as AFL_LLVM_LAF_\u0026hellip; that is longer but in line with other llvm specific env vars  Version ++2.52c (2019-06-05):  Applied community patches. See docs/PATCHES for the full list. LLVM and Qemu modes are now faster. Important changes: afl-fuzz: -e EXTENSION commandline option llvm_mode: LAF-intel performance (needs activation, see llvm/README.laf-intel.md) a few new environment variables for afl-fuzz, llvm and qemu, see docs/env_variables.md Added the power schedules of AFLfast by Marcel Boehme, but set the default to the AFL schedule, not to the FAST schedule. So nothing changes unless you use the new -p option :-) - see docs/power_schedules.md added afl-system-config script to set all system performance options for fuzzing llvm_mode works with llvm 3.9 up to including 8 ! qemu_mode got upgraded from 2.1 to 3.1 - incorporated from https://github.com/andreafioraldi/afl and with community patches added  Version 2.52b (2017-11-04):   Upgraded QEMU patches from 2.3.0 to 2.10.0. Required troubleshooting several weird issues. All the legwork done by Andrew Griffiths.\n  Added setsid to afl-showmap. See the notes for 2.51b.\n  Added target mode (deferred, persistent, qemu, etc) to fuzzer_stats. Requested by Jakub Wilk.\n  afl-tmin should now save a partially minimized file when Ctrl-C is pressed. Suggested by Jakub Wilk.\n  Added an option for afl-analyze to dump offsets in hex. Suggested by Jakub Wilk.\n  Added support for parameters in triage_crashes.sh. Patch by Adam of DC949.\n  Version 2.51b (2017-08-30):  Made afl-tmin call setsid to prevent glibc traceback junk from showing up on the terminal in some distros. Suggested by Jakub Wilk.  Version 2.50b (2017-08-19):   Fixed an interesting timing corner case spotted by Jakub Wilk.\n  Addressed a libtokencap / pthreads incompatibility issue. Likewise, spotted by Jakub Wilk.\n  Added a mention of afl-kit and Pythia.\n  Added AFL_FAST_CAL.\n  In-place resume now preserves .synced. Suggested by Jakub Wilk.\n  Version 2.49b (2017-07-18):   Added AFL_TMIN_EXACT to allow path constraint for crash minimization.\n  Added dates for releases (retroactively for all of 2017).\n  Version 2.48b (2017-07-17):   Added AFL_ALLOW_TMP to permit some scripts to run in /tmp.\n  Fixed cwd handling in afl-analyze (similar to the quirk in afl-tmin).\n  Made it possible to point -o and -f to the same file in afl-tmin.\n  Version 2.47b (2017-07-14):  Fixed cwd handling in afl-tmin. Spotted by Jakub Wilk.  Version 2.46b (2017-07-10):   libdislocator now supports AFL_LD_NO_CALLOC_OVER for folks who do not want to abort on calloc() overflows.\n  Made a minor fix to libtokencap. Reported by Daniel Stender.\n  Added a small JSON dictionary, inspired on a dictionary done by Jakub Wilk.\n  Version 2.45b (2017-07-04):   Added strstr, strcasestr support to libtokencap. Contributed by Daniel Hodson.\n  Fixed a resumption offset glitch spotted by Jakub Wilk.\n  There are definitely no bugs in afl-showmap -c now.\n  Version 2.44b (2017-06-28):   Added a visual indicator of ASAN / MSAN mode when compiling. Requested by Jakub Wilk.\n  Added support for afl-showmap coredumps (-c). Suggested by Jakub Wilk.\n  Added LD_BIND_NOW=1 for afl-showmap by default. Although not really useful, it reportedly helps reproduce some crashes. Suggested by Jakub Wilk.\n  Added a note about allocator_may_return_null=1 not always working with ASAN. Spotted by Jakub Wilk.\n  Version 2.43b (2017-06-16):  Added AFL_NO_ARITH to aid in the fuzzing of text-based formats. Requested by Jakub Wilk.  Version 2.42b (2017-06-02):  Renamed the R() macro to avoid a problem with llvm_mode in the latest versions of LLVM. Fix suggested by Christian Holler.  Version 2.41b (2017-04-12):  Addressed a major user complaint related to timeout detection. Timing out inputs are now binned as \u0026ldquo;hangs\u0026rdquo; only if they exceed a far more generous time limit than the one used to reject slow paths.  Version 2.40b (2017-04-02):   Fixed a minor oversight in the insertion strategy for dictionary words. Spotted by Andrzej Jackowski.\n  Made a small improvement to the havoc block insertion strategy.\n  Adjusted color rules for \u0026ldquo;is it done yet?\u0026rdquo; indicators.\n  Version 2.39b (2017-02-02):   Improved error reporting in afl-cmin. Suggested by floyd.\n  Made a minor tweak to trace-pc-guard support. Suggested by kcc.\n  Added a mention of afl-monitor.\n  Version 2.38b (2017-01-22):  Added -mllvm -sanitizer-coverage-block-threshold=0 to trace-pc-guard mode, as suggested by Kostya Serebryany.  Version 2.37b (2017-01-22):   Fixed a typo. Spotted by Jakub Wilk.\n  Fixed support for make install when using trace-pc. Spotted by Kurt Roeckx.\n  Switched trace-pc to trace-pc-guard, which should be considerably faster and is less quirky. Kudos to Konstantin Serebryany (and sorry for dragging my feet).\nNote that for some reason, this mode doesn\u0026rsquo;t perform as well as \u0026ldquo;vanilla\u0026rdquo; afl-clang-fast / afl-clang.\n  Version 2.36b (2017-01-14):   Fixed a cosmetic bad free() bug when aborting -S sessions. Spotted by Johannes S.\n  Made a small change to afl-whatsup to sort fuzzers by name.\n  Fixed a minor issue with malloc(0) in libdislocator. Spotted by Rene Freingruber.\n  Changed the clobber pattern in libdislocator to a slightly more reliable one. Suggested by Rene Freingruber.\n  Added a note about THP performance. Suggested by Sergey Davidoff.\n  Added a somewhat unofficial support for running afl-tmin with a baseline \u0026ldquo;mask\u0026rdquo; that causes it to minimize only for edges that are unique to the input file, but not to the \u0026ldquo;boring\u0026rdquo; baseline. Suggested by Sami Liedes.\n  \u0026ldquo;Fixed\u0026rdquo; a getPassName() problem with newer versions of clang. Reported by Craig Young and several other folks.\n  Yep, I know I have a backlog on several other feature requests. Stay tuned!\nVersion 2.35b:   Fixed a minor cmdline reporting glitch, spotted by Leo Barnes.\n  Fixed a silly bug in libdislocator. Spotted by Johannes Schultz.\n  Version 2.34b:   Added a note about afl-tmin to technical_details.txt.\n  Added support for AFL_NO_UI, as suggested by Leo Barnes.\n  Version 2.33b:   Added code to strip -Wl,-z,defs and -Wl,\u0026ndash;no-undefined for afl-clang-fast, since they interfere with -shared. Spotted and diagnosed by Toby Hutton.\n  Added some fuzzing tips for Android.\n  Version 2.32b:   Added a check for AFL_HARDEN combined with AFL_USE_*SAN. Suggested by Hanno Boeck.\n  Made several other cosmetic adjustments to cycle timing in the wake of the big tweak made in 2.31b.\n  Version 2.31b:   Changed havoc cycle counts for a marked performance boost, especially with -S / -d. See the discussion of FidgetyAFL in:\nhttps://groups.google.com/forum/#!topic/afl-users/fOPeb62FZUg\nWhile this does not implement the approach proposed by the authors of the CCS paper, the solution is a result of digging into that research; more improvements may follow as I do more experiments and get more definitive data.\n  Version 2.30b:   Made minor improvements to persistent mode to avoid the remote possibility of \u0026ldquo;no instrumentation detected\u0026rdquo; issues with very low instrumentation densities.\n  Fixed a minor glitch with a leftover process in persistent mode. Reported by Jakub Wilk and Daniel Stender.\n  Made persistent mode bitmaps a bit more consistent and adjusted the way this is shown in the UI, especially in persistent mode.\n  Version 2.29b:   Made a minor #include fix to llvm_mode. Suggested by Jonathan Metzman.\n  Made cosmetic updates to the docs.\n  Version 2.28b:   Added \u0026ldquo;life pro tips\u0026rdquo; to docs/.\n  Moved testcases/_extras/ to dictionaries/ for visibility.\n  Made minor improvements to install scripts.\n  Added an important safety tip.\n  Version 2.27b:   Added libtokencap, a simple feature to intercept strcmp / memcmp and generate dictionary entries that can help extend coverage.\n  Moved libdislocator to its own dir, added README.md.\n  The demo in examples/instrumented_cmp is no more.\n  Version 2.26b:   Made a fix for libdislocator.so to compile on MacOS X.\n  Added support for DYLD_INSERT_LIBRARIES.\n  Renamed AFL_LD_PRELOAD to AFL_PRELOAD.\n  Version 2.25b:  Made some cosmetic updates to libdislocator.so, renamed one env variable.  Version 2.24b:  Added libdislocator.so, an experimental, abusive allocator. Try it out with AFL_LD_PRELOAD=/path/to/libdislocator.so when running afl-fuzz.  Version 2.23b:   Improved the stability metric for persistent mode binaries. Problem spotted by Kurt Roeckx.\n  Made a related improvement that may bring the metric to 100% for those targets.\n  Version 2.22b:   Mentioned the potential conflicts between MSAN / ASAN and FORTIFY_SOURCE. There is no automated check for this, since some distros may implicitly set FORTIFY_SOURCE outside of the compiler\u0026rsquo;s argv[].\n  Populated the support for AFL_LD_PRELOAD to all companion tools.\n  Made a change to the handling of ./afl-clang-fast -v. Spotted by Jan Kneschke.\n  Version 2.21b:   Added some crash reporting notes for Solaris in docs/INSTALL, as investigated by Martin Carpenter.\n  Fixed a minor UI mix-up with havoc strategy stats.\n  Version 2.20b:   Revamped the handling of variable paths, replacing path count with a \u0026ldquo;stability\u0026rdquo; score to give users a much better signal. Based on the feedback from Vegard Nossum.\n  Made a stability improvement to the syncing behavior with resuming fuzzers. Based on the feedback from Vegard.\n  Changed the UI to include current input bitmap density along with total density. Ditto.\n  Added experimental support for parallelizing -M.\n  Version 2.19b:  Made a fix to make sure that auto CPU binding happens at non-overlapping times.  Version 2.18b:  Made several performance improvements to has_new_bits() and classify_counts(). This should offer a robust performance bump with fast targets.  Version 2.17b:   Killed the error-prone and manual -Z option. On Linux, AFL will now automatically bind to the first free core (or complain if there are no free cores left).\n  Made some doc updates along these lines.\n  Version 2.16b:   Improved support for older versions of clang (hopefully without breaking anything).\n  Moved version data from Makefile to config.h. Suggested by Jonathan Metzman.\n  Version 2.15b:   Added a README section on looking for non-crashing bugs.\n  Added license data to several boring files. Contributed by Jonathan Metzman.\n  Version 2.14b:   Added FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION as a macro defined when compiling with afl-gcc and friends. Suggested by Kostya Serebryany.\n  Refreshed some of the non-x86 docs.\n  Version 2.13b:   Fixed a spurious build test error with trace-pc and llvm_mode/Makefile. Spotted by Markus Teufelberger.\n  Fixed a cosmetic issue with afl-whatsup. Spotted by Brandon Perry.\n  Version 2.12b:  Fixed a minor issue in afl-tmin that can make alphabet minimization less efficient during passes \u0026gt; 1. Spotted by Daniel Binderman.  Version 2.11b:   Fixed a minor typo in instrumented_cmp, spotted by Hanno Eissfeldt.\n  Added a missing size check for deterministic insertion steps.\n  Made an improvement to afl-gotcpu when -Z not used.\n  Fixed a typo in post_library_png.so.c in examples/. Spotted by Kostya Serebryany.\n  Version 2.10b:  Fixed a minor core counting glitch, reported by Tyler Nighswander.  Version 2.09b:   Made several documentation updates.\n  Added some visual indicators to promote and simplify the use of -Z.\n  Version 2.08b:   Added explicit support for -m32 and -m64 for llvm_mode. Inspired by a request from Christian Holler.\n  Added a new benchmarking option, as requested by Kostya Serebryany.\n  Version 2.07b:   Added CPU affinity option (-Z) on Linux. With some caution, this can offer a significant (10%+) performance bump and reduce jitter. Proposed by Austin Seipp.\n  Updated afl-gotcpu to use CPU affinity where supported.\n  Fixed confusing CPU_TARGET error messages with QEMU build. Spotted by Daniel Komaromy and others.\n  Version 2.06b:   Worked around LLVM persistent mode hiccups with -shared code. Contributed by Christian Holler.\n  Added __AFL_COMPILER as a convenient way to detect that something is built under afl-gcc / afl-clang / afl-clang-fast and enable custom optimizations in your code. Suggested by Pedro Corte-Real.\n  Upstreamed several minor changes developed by Franjo Ivancic to allow AFL to be built as a library. This is fairly use-specific and may have relatively little appeal to general audiences.\n  Version 2.05b:  Put __sanitizer_cov_module_init \u0026amp; co behind #ifdef to avoid problems with ASAN. Spotted by Christian Holler.  Version 2.04b:  Removed indirect-calls coverage from -fsanitize-coverage (since it\u0026rsquo;s redundant). Spotted by Kostya Serebryany.  Version 2.03b:   Added experimental -fsanitize-coverage=trace-pc support that goes with some recent additions to LLVM, as implemented by Kostya Serebryany. Right now, this is cumbersome to use with common build systems, so the mode remains undocumented.\n  Made several substantial improvements to better support non-standard map sizes in LLVM mode.\n  Switched LLVM mode to thread-local execution tracing, which may offer better results in some multithreaded apps.\n  Fixed a minor typo, reported by Heiko Eissfeldt.\n  Force-disabled symbolization for ASAN, as suggested by Christian Holler.\n  AFL_NOX86 renamed to AFL_NO_X86 for consistency.\n  Added AFL_LD_PRELOAD to allow LD_PRELOAD to be set for targets without affecting AFL itself. Suggested by Daniel Godas-Lopez.\n  Version 2.02b:  Fixed a \u0026ldquo;lcamtuf can\u0026rsquo;t count to 16\u0026rdquo; bug in the havoc stage. Reported by Guillaume Endignoux.  Version 2.01b:   Made an improvement to cycle counter color coding, based on feedback from Shai Sarfaty.\n  Added a mention of aflize to sister_projects.txt.\n  Fixed an installation issue with afl-as, as spotted by ilovezfs.\n  Version 2.00b:   Cleaned up color handling after a minor snafu in 1.99b (affecting some terminals).\n  Made minor updates to the documentation.\n  Version 1.99b:   Substantially revamped the output and the internal logic of afl-analyze.\n  Cleaned up some of the color handling code and added support for background colors.\n  Removed some stray files (oops).\n  Updated docs to better explain afl-analyze.\n  Version 1.98b:   Improved to \u0026ldquo;boring string\u0026rdquo; detection in afl-analyze.\n  Added technical_details.txt for afl-analyze.\n  Version 1.97b:   Added afl-analyze, a nifty tool to analyze the structure of a file based on the feedback from AFL instrumentation. This is kinda experimental, so field reports welcome.\n  Added a mention of afl-cygwin.\n  Fixed a couple of typos, as reported by Jakub Wilk and others.\n  Version 1.96b:   Added -fpic to CFLAGS for the clang plugin, as suggested by Hanno Boeck.\n  Made another clang change (IRBuilder) suggested by Jeff Trull.\n  Fixed several typos, spotted by Jakub Wilk.\n  Added support for AFL_SHUFFLE_QUEUE, based on discussions with Christian Holler.\n  Version 1.95b:   Fixed a harmless bug when handling -B. Spotted by Jacek Wielemborek.\n  Made the exit message a bit more accurate when AFL_EXIT_WHEN_DONE is set.\n  Added some error-checking for old-style forkserver syntax. Suggested by Ben Nagy.\n  Switched from exit() to _exit() in injected code to avoid snafus with destructors in C++ code. Spotted by sunblate.\n  Made a change to avoid spuriously setting __AFL_SHM_ID when AFL_DUMB_FORKSRV is set in conjunction with -n. Spotted by Jakub Wilk.\n  Version 1.94b:   Changed allocator alignment to improve support for non-x86 systems (now that llvm_mode makes this more feasible).\n  Fixed a minor typo in afl-cmin. Spotted by Jonathan Neuschafer.\n  Fixed an obscure bug that would affect people trying to use afl-gcc with $TMP set but $TMPDIR absent. Spotted by Jeremy Barnes.\n  Version 1.93b:  Hopefully fixed a problem with MacOS X and persistent mode, spotted by Leo Barnes.  Version 1.92b:  Made yet another C++ fix (namespaces). Reported by Daniel Lockyer.  Version 1.91b:  Made another fix to make 1.90b actually work properly with C++ (d\u0026rsquo;oh). Problem spotted by Daniel Lockyer.  Version 1.90b:   Fixed a minor typo spotted by Kai Zhao; and made several other minor updates to docs.\n  Updated the project URL for python-afl. Requested by Jakub Wilk.\n  Fixed a potential problem with deferred mode signatures getting optimized out by the linker (with \u0026ndash;gc-sections).\n  Version 1.89b:   Revamped the support for persistent and deferred forkserver modes. Both now feature simpler syntax and do not require companion env variables. Suggested by Jakub Wilk.\n  Added a bit more info about afl-showmap. Suggested by Jacek Wielemborek.\n  Version 1.88b:  Made AFL_EXIT_WHEN_DONE work in non-tty mode. Issue spotted by Jacek Wielemborek.  Version 1.87b:   Added QuickStartGuide.txt, a one-page quick start doc.\n  Fixed several typos spotted by Dominique Pelle.\n  Revamped several parts of README.\n  Version 1.86b:   Added support for AFL_SKIP_CRASHES, which is a very hackish solution to the problem of resuming sessions with intermittently crashing inputs.\n  Removed the hard-fail terminal size check, replaced with a dynamic warning shown in place of the UI. Based on feedback from Christian Holler.\n  Fixed a minor typo in show_stats. Spotted by Dingbao Xie.\n  Version 1.85b:   Fixed a garbled sentence in notes on parallel fuzzing. Thanks to Jakub Wilk.\n  Fixed a minor glitch in afl-cmin. Spotted by Jonathan Foote.\n  Version 1.84b:   Made SIMPLE_FILES behave as expected when naming backup directories for crashes and hangs.\n  Added the total number of favored paths to fuzzer_stats. Requested by Ben Nagy.\n  Made afl-tmin, afl-fuzz, and afl-cmin reject negative values passed to -t and -m, since they generally won\u0026rsquo;t work as expected.\n  Made a fix for no lahf / sahf support on older versions of FreeBSD. Patch contributed by Alex Moneger.\n  Version 1.83b:   Fixed a problem with xargs -d on non-Linux systems in afl-cmin. Spotted by teor2345 and Ben Nagy.\n  Fixed an implicit declaration in LLVM mode on MacOS X. Reported by Kai Zhao.\n  Version 1.82b:   Fixed a harmless but annoying race condition in persistent mode - signal delivery is a bit more finicky than I thought.\n  Updated the documentation to explain persistent mode a bit better.\n  Tweaked AFL_PERSISTENT to force AFL_NO_VAR_CHECK.\n  Version 1.81b:   Added persistent mode for in-process fuzzing. See llvm_mode/README.llvm. Inspired by Kostya Serebryany and Christian Holler.\n  Changed the in-place resume code to preserve crashes/README.txt. Suggested by Ben Nagy.\n  Included a potential fix for LLVM mode issues on MacOS X, based on the investigation done by teor2345.\n  Version 1.80b:   Made afl-cmin tolerant of whitespaces in filenames. Suggested by Jonathan Neuschafer and Ketil Froyn.\n  Added support for AFL_EXIT_WHEN_DONE, as suggested by Michael Rash.\n  Version 1.79b:   Added support for dictionary levels, see testcases/README.testcases.\n  Reworked the SQL dictionary to use levels.\n  Added a note about Preeny.\n  Version 1.78b:   Added a dictionary for PDF, contributed by Ben Nagy.\n  Added several references to afl-cov, a new tool by Michael Rash.\n  Fixed a problem with crash reporter detection on MacOS X, as reported by Louis Dassy.\n  Version 1.77b:   Extended the -x option to support single-file dictionaries.\n  Replaced factory-packaged dictionaries with file-based variants.\n  Removed newlines from HTML keywords in testcases/_extras/html/.\n  Version 1.76b:   Very significantly reduced the number of duplicate execs during deterministic checks, chiefly in int16 and int32 stages. Confirmed identical path yields. This should improve early-stage efficiency by around 5-10%.\n  Reduced the likelihood of duplicate non-deterministic execs by bumping up lowest stacking factor from 1 to 2. Quickly confirmed that this doesn\u0026rsquo;t seem to have significant impact on coverage with libpng.\n  Added a note about integrating afl-fuzz with third-party tools.\n  Version 1.75b:   Improved argv_fuzzing to allow it to emit empty args. Spotted by Jakub Wilk.\n  afl-clang-fast now defines __AFL_HAVE_MANUAL_INIT. Suggested by Jakub Wilk.\n  Fixed a libtool-related bug with afl-clang-fast that would make some ./configure invocations generate incorrect output. Spotted by Jakub Wilk.\n  Removed flock() on Solaris. This means no locking on this platform, but so be it. Problem reported by Martin Carpenter.\n  Fixed a typo. Reported by Jakub Wilk.\n  Version 1.74b:   Added an example argv[] fuzzing wrapper in examples/argv_fuzzing. Reworked the bash example to be faster, too.\n  Clarified llvm_mode prerequisites for FreeBSD.\n  Improved afl-tmin to use /tmp if cwd is not writeable.\n  Removed redundant includes for sys/fcntl.h, which caused warnings with some nitpicky versions of libc.\n  Added a corpus of basic HTML tags that parsers are likely to pay attention to (no attributes).\n  Added EP_EnabledOnOptLevel0 to llvm_mode, so that the instrumentation is inserted even when AFL_DONT_OPTIMIZE=1 is set.\n  Switched qemu_mode to use the newly-released QEMU 2.3.0, which contains a couple of minor bugfixes.\n  Version 1.73b:  Fixed a pretty stupid bug in effector maps that could sometimes cause AFL to fuzz slightly more than necessary; and in very rare circumstances, could lead to SEGV if eff_map is aligned with page boundary and followed by an unmapped page. Spotted by Jonathan Gray.  Version 1.72b:   Fixed a glitch in non-x86 install, spotted by Tobias Ospelt.\n  Added a minor safeguard to llvm_mode Makefile following a report from Kai Zhao.\n  Version 1.71b:   Fixed a bug with installed copies of AFL trying to use QEMU mode. Spotted by G.M. Lime.\n  Added last path / crash / hang times to fuzzer_stats, suggested by Richard Hipp.\n  Fixed a typo, thanks to Jakub Wilk.\n  Version 1.70b:   Modified resumption code to reuse the original timeout value when resuming a session if -t is not given. This prevents timeout creep in continuous fuzzing.\n  Added improved error messages for failed handshake when AFL_DEFER_FORKSRV is set.\n  Made a slight improvement to llvm_mode/Makefile based on feedback from Jakub Wilk.\n  Refreshed several bits of documentation.\n  Added a more prominent note about the MacOS X trade-offs to Makefile.\n  Version 1.69b:  Added support for deferred initialization in LLVM mode. Suggested by Richard Godbee.  Version 1.68b:   Fixed a minor PRNG glitch that would make the first seconds of a fuzzing job deterministic. Thanks to Andreas Stieger.\n  Made tmp[] static in the LLVM runtime to keep Valgrind happy (this had no impact on anything else). Spotted by Richard Godbee.\n  Clarified the footnote in README.\n  Version 1.67b:  Made one more correction to llvm_mode Makefile, spotted by Jakub Wilk.  Version 1.66b:   Added CC / CXX support to llvm_mode Makefile. Requested by Charlie Eriksen.\n  Fixed \u0026lsquo;make clean\u0026rsquo; with gmake. Suggested by Oliver Schneider.\n  Fixed \u0026lsquo;make -j n clean all\u0026rsquo;. Suggested by Oliver Schneider.\n  Removed build date and time from banners to give people deterministic builds. Requested by Jakub Wilk.\n  Version 1.65b:   Fixed a snafu with some leftover code in afl-clang-fast.\n  Corrected even moar typos.\n  Version 1.64b:   Further simplified afl-clang-fast runtime by reverting .init_array to attribute((constructor(0)). This should improve compatibility with non-ELF platforms.\n  Fixed a problem with afl-clang-fast and -shared libraries. Simplified the code by getting rid of .preinit_array and replacing it with a .comm object. Problem reported by Charlie Eriksen.\n  Removed unnecessary instrumentation density adjustment for the LLVM mode. Reported by Jonathan Neuschafer.\n  Version 1.63b:   Updated cgroups_asan/ with a new version from Sam, made a couple changes to streamline it and keep parallel afl instances in separate groups.\n  Fixed typos, thanks to Jakub Wilk.\n  Version 1.62b:   Improved the handling of -x in afl-clang-fast,\n  Improved the handling of low AFL_INST_RATIO settings for QEMU and LLVM modes.\n  Fixed the llvm-config bug for good (thanks to Tobias Ospelt).\n  Version 1.61b:   Fixed an obscure bug compiling OpenSSL with afl-clang-fast. Patch by Laszlo Szekeres.\n  Fixed a \u0026lsquo;make install\u0026rsquo; bug on non-x86 systems, thanks to Tobias Ospelt.\n  Fixed a problem with half-broken llvm-config on Odroid, thanks to Tobias Ospelt. (There is another odd bug there that hasn\u0026rsquo;t been fully fixed - TBD).\n  Version 1.60b:   Allowed examples/llvm_instrumentation/ to graduate to llvm_mode/.\n  Removed examples/arm_support/, since it\u0026rsquo;s completely broken and likely unnecessary with LLVM support in place.\n  Added ASAN cgroups script to examples/asan_cgroups/, updated existing docs. Courtesy Sam Hakim and David A. Wheeler.\n  Refactored afl-tmin to reduce the number of execs in common use cases. Ideas from Jonathan Neuschafer and Turo Lamminen.\n  Added a note about CLAs at the bottom of README.\n  Renamed testcases_readme.txt to README.testcases for some semblance of consistency.\n  Made assorted updates to docs.\n  Added MEM_BARRIER() to afl-showmap and afl-tmin, just to be safe.\n  Version 1.59b:   Imported Laszlo Szekeres\u0026rsquo; experimental LLVM instrumentation into examples/llvm_instrumentation. I\u0026rsquo;ll work on including it in the \u0026ldquo;mainstream\u0026rdquo; version soon.\n  Fixed another typo, thanks to Jakub Wilk.\n  Version 1.58b:   Added a workaround for abort() behavior in -lpthread programs in QEMU mode. Spotted by Aidan Thornton.\n  Made several documentation updates, including links to the static instrumentation tool (sister_projects.txt).\n  Version 1.57b:   Fixed a problem with exception handling on some versions of MacOS X. Spotted by Samir Aguiar and Anders Wang Kristensen.\n  Tweaked afl-gcc to use BIN_PATH instead of a fixed string in help messages.\n  Version 1.56b:   Renamed related_work.txt to historical_notes.txt.\n  Made minor edits to the ASAN doc.\n  Added docs/sister_projects.txt with a list of inspired or closely related utilities.\n  Version 1.55b:  Fixed a glitch with afl-showmap opening /dev/null with O_RDONLY when running in quiet mode. Spotted by Tyler Nighswander.  Version 1.54b:   Added another postprocessor example for PNG.\n  Made a cosmetic fix to realloc() handling in examples/post_library/, suggested by Jakub Wilk.\n  Improved -ldl handling. Suggested by Jakub Wilk.\n  Version 1.53b:  Fixed an -l ordering issue that is apparently still a problem on Ubuntu. Spotted by William Robinet.  Version 1.52b:  Added support for file format postprocessors. Requested by Ben Nagy. This feature is intentionally buried, since it\u0026rsquo;s fairly easy to misuse and useful only in some scenarios. See examples/post_library/.  Version 1.51b:   Made it possible to properly override LD_BIND_NOW after one very unusual report of trouble.\n  Cleaned up typos, thanks to Jakub Wilk.\n  Fixed a bug in AFL_DUMB_FORKSRV.\n  Version 1.50b:   Fixed a flock() bug that would prevent dir reuse errors from kicking in every now and then.\n  Renamed references to ppvm (the project is now called recidivm).\n  Made improvements to file descriptor handling to avoid leaving some fds unnecessarily open in the child process.\n  Fixed a typo or two.\n  Version 1.49b:  Added code to save original command line in fuzzer_stats and crashes/README.txt. Also saves fuzzer version in fuzzer_stats. Requested by Ben Nagy.  Version 1.48b:  Fixed a bug with QEMU fork server crashes when translation is attempted after a jump to an invalid pointer in the child process (i.e., after bumping into a particularly nasty security bug in the tested binary). Reported by Tyler Nighswander.  Version 1.47b:   Fixed a bug with afl-cmin in -Q mode complaining about binary being not instrumented. Thanks to Jonathan Neuschafer for the bug report.\n  Fixed another bug with argv handling for afl-fuzz in -Q mode. Reported by Jonathan Neuschafer.\n  Improved the use of colors when showing crash counts in -C mode.\n  Version 1.46b:   Improved instrumentation performance on 32-bit systems by getting rid of xor-swap (oddly enough, xor-swap is still faster on 64-bit) and tweaking alignment.\n  Made path depth numbers more accurate with imported test cases.\n  Version 1.45b:   Added support for SIMPLE_FILES in config.h for folks who don\u0026rsquo;t like descriptive file names. Generates very simple names without colons, commas, plus signs, dashes, etc.\n  Replaced zero-sized files with symlinks in the variable behavior state dir to simplify examining the relevant test cases.\n  Changed the period of limited-range block ops from 5 to 10 minutes based on a couple of experiments. The basic goal of this delay timer behavior is to better support jobs that are seeded with completely invalid files, in which case, the first few queue cycles may be completed very quickly without discovering new paths. Should have no effect on well-seeded jobs.\n  Made several minor updates to docs.\n  Version 1.44b:   Corrected two bungled attempts to get the -C mode work properly with afl-cmin (accounting for the short-lived releases tagged 1.42 and 1.43b) - sorry.\n  Removed AFL_ALLOW_CRASHES in favor of the -C mode in said tool.\n  Said goodbye to Hello Kitty, as requested by Padraig Brady.\n  Version 1.41b:   Added AFL_ALLOW_CRASHES=1 to afl-cmin. Allows crashing inputs in the output corpus. Changed the default behavior to disallow it.\n  Made the afl-cmin output dir default to 0700, not 0755, to be consistent with afl-fuzz; documented the rationale for 0755 in afl-plot.\n  Lowered the output dir reuse time limit to 25 minutes as a dice-roll compromise after a discussion on afl-users@.\n  Made afl-showmap accept -o /dev/null without borking out.\n  Added support for crash / hang info in exit codes of afl-showmap.\n  Tweaked block operation scaling to also factor in ballpark run time in cases where queue passes take very little time.\n  Fixed typos and made improvements to several docs.\n  Version 1.40b:   Switched to smaller block op sizes during the first passes over the queue. Helps keep test cases small.\n  Added memory barrier for run_target(), just in case compilers get smarter than they are today.\n  Updated a bunch of docs.\n  Version 1.39b:   Added the ability to skip inputs by sending SIGUSR1 to the fuzzer.\n  Reworked several portions of the documentation.\n  Changed the code to reset splicing perf scores between runs to keep them closer to intended length.\n  Reduced the minimum value of -t to 5 for afl-fuzz (~200 exec/sec) and to 10 for auxiliary tools (due to the absence of a fork server).\n  Switched to more aggressive default timeouts (rounded up to 25 ms versus 50 ms - ~40 execs/sec) and made several other cosmetic changes to the timeout code.\n  Version 1.38b:   Fixed a bug in the QEMU build script, spotted by William Robinet.\n  Improved the reporting of skipped bitflips to keep the UI counters a bit more accurate.\n  Cleaned up related_work.txt and added some non-goals.\n  Fixed typos, thanks to Jakub Wilk.\n  Version 1.37b:   Added effector maps, which detect regions that do not seem to respond to bitflips and subsequently exclude them from more expensive steps (arithmetics, known ints, etc). This should offer significant performance improvements with quite a few types of text-based formats, reducing the number of deterministic execs by a factor of 2 or so.\n  Cleaned up mem limit handling in afl-cmin.\n  Switched from uname -i to uname -m to work around Gentoo-specific issues with coreutils when building QEMU. Reported by William Robinet.\n  Switched from PID checking to flock() to detect running sessions. Problem, against all odds, bumped into by Jakub Wilk.\n  Added SKIP_COUNTS and changed the behavior of COVERAGE_ONLY in config.h. Useful only for internal benchmarking.\n  Made improvements to UI refresh rates and exec/sec stats to make them more stable.\n  Made assorted improvements to the documentation and to the QEMU build script.\n  Switched from perror() to strerror() in error macros, thanks to Jakub Wilk for the nag.\n  Moved afl-cmin back to bash, wasn\u0026rsquo;t thinking straight. It has to stay on bash because other shells may have restrictive limits on array sizes.\n  Version 1.36b:   Switched afl-cmin over to /bin/sh. Thanks to Jonathan Gray.\n  Fixed an off-by-one bug in queue limit check when resuming sessions (could cause NULL ptr deref if you are really unlucky).\n  Fixed the QEMU script to tolerate i686 if returned by uname -i. Based on a problem report from Sebastien Duquette.\n  Added multiple references to Jakub\u0026rsquo;s ppvm tool.\n  Made several minor improvements to the Makefile.\n  Believe it or not, fixed some typos. Thanks to Jakub Wilk.\n  Version 1.35b:  Cleaned up regular expressions in some of the scripts to avoid errors on *BSD systems. Spotted by Jonathan Gray.  Version 1.34b:  Performed a substantial documentation and program output cleanup to better explain the QEMU feature.  Version 1.33b:   Added support for AFL_INST_RATIO and AFL_INST_LIBS in the QEMU mode.\n  Fixed a stack allocation crash in QEMU mode (bug in QEMU, fixed with an extra patch applied to the downloaded release).\n  Added code to test the QEMU instrumentation once the afl-qemu-trace binary is built.\n  Modified afl-tmin and afl-showmap to search $PATH for binaries and to better handle QEMU support.\n  Added a check for instrumented binaries when passing -Q to afl-fuzz.\n  Version 1.32b:   Fixed \u0026lsquo;make install\u0026rsquo; following the QEMU changes. Spotted by Hanno Boeck.\n  Fixed EXTRA_PAR handling in afl-cmin.\n  Version 1.31b:   Hallelujah! Thanks to Andrew Griffiths, we now support very fast, black-box instrumentation of binary-only code. See qemu_mode/README.qemu.\nTo use this feature, you need to follow the instructions in that directory and then run afl-fuzz with -Q.\n  Version 1.30b:   Added -s (summary) option to afl-whatsup. Suggested by Jodie Cunningham.\n  Added a sanity check in afl-tmin to detect minimization to zero len or excess hangs.\n  Fixed alphabet size counter in afl-tmin.\n  Slightly improved the handling of -B in afl-fuzz.\n  Fixed process crash messages with -m none.\n  Version 1.29b:   Improved the naming of test cases when orig: is already present in the file name.\n  Made substantial improvements to technical_details.txt.\n  Version 1.28b:   Made a minor tweak to the instrumentation to preserve the directionality of tuples (i.e., A -\u0026gt; B != B -\u0026gt; A) and to maintain the identity of tight loops (A -\u0026gt; A). You need to recompile targeted binaries to leverage this.\n  Cleaned up some of the afl-whatsup stats.\n  Added several sanity checks to afl-cmin.\n  Version 1.27b:   Made afl-tmin recursive. Thanks to Hanno Boeck for the tip.\n  Added docs/technical_details.txt.\n  Changed afl-showmap search strategy in afl-cmap to just look into the same place that afl-cmin is executed from. Thanks to Jakub Wilk.\n  Removed current_todo.txt and cleaned up the remaining docs.\n  Version 1.26b:   Added total execs/sec stat for afl-whatsup.\n  afl-cmin now auto-selects between cp or ln. Based on feedback from Even Huus.\n  Fixed a typo. Thanks to Jakub Wilk.\n  Made afl-gotcpu a bit more accurate by using getrusage instead of times. Thanks to Jakub Wilk.\n  Fixed a memory limit issue during the build process on NetBSD-current. Reported by Thomas Klausner.\n  Version 1.25b:   Introduced afl-whatsup, a simple tool for querying the status of local synced instances of afl-fuzz.\n  Added -x compiler to clang options on Darwin. Suggested by Filipe Cabecinhas.\n  Improved exit codes for afl-gotcpu.\n  Improved the checks for -m and -t values in afl-cmin. Bug report from Evan Huus.\n  Version 1.24b:  Introduced afl-getcpu, an experimental tool to empirically measure CPU preemption rates. Thanks to Jakub Wilk for the idea.  Version 1.23b:  Reverted one change to afl-cmin that actually made it slower.  Version 1.22b:   Reworked afl-showmap.c to support normal options, including -o, -q, -e. Also added support for timeouts and memory limits.\n  Made changes to afl-cmin and other scripts to accommodate the new semantics.\n  Officially retired AFL_EDGES_ONLY.\n  Fixed another typo in afl-tmin, courtesy of Jakub Wilk.\n  Version 1.21b:   Graduated minimize_corpus.sh to afl-cmin. It is now a first-class utility bundled with the fuzzer.\n  Made significant improvements to afl-cmin to make it faster, more robust, and more versatile.\n  Refactored some of afl-tmin code to make it a bit more readable.\n  Made assorted changes to the doc to document afl-cmin and other stuff.\n  Version 1.20b:   Added AFL_DUMB_FORKSRV, as requested by Jakub Wilk. This works only in -n mode and allows afl-fuzz to run with \u0026ldquo;dummy\u0026rdquo; fork servers that don\u0026rsquo;t output any instrumentation, but follow the same protocol.\n  Renamed AFL_SKIP_CHECKS to AFL_SKIP_BIN_CHECK to make it at least somewhat descriptive.\n  Switched to using clang as the default assembler on MacOS X to work around Xcode issues with newer builds of clang. Testing and patch by Nico Weber.\n  Fixed a typo (via Jakub Wilk).\n  Version 1.19b:   Improved exec failure detection in afl-fuzz and afl-showmap.\n  Improved Ctrl-C handling in afl-showmap.\n  Added afl-tmin, a handy instrumentation-enabled minimizer.\n  Version 1.18b:   Fixed a serious but short-lived bug in the resumption behavior introduced in version 1.16b.\n  Added -t nn+ mode for soft-skipping timing-out paths.\n  Version 1.17b:   Fixed a compiler warning introduced in 1.16b for newer versions of GCC. Thanks to Jakub Wilk and Ilfak Guilfanov.\n  Improved the consistency of saving fuzzer_stats, bitmap info, and auto-dictionaries when aborting fuzzing sessions.\n  Made several noticeable performance improvements to deterministic arith and known int steps.\n  Version 1.16b:   Added a bit of code to make resumption pick up from the last known offset in the queue, rather than always rewinding to the start. Suggested by Jakub Wilk.\n  Switched to tighter timeout control for slow programs (3x rather than 5x average exec speed at init).\n  Version 1.15b:   Added support for AFL_NO_VAR_CHECK to speed up resumption and inhibit variable path warnings for some programs.\n  Made the trimmer run even for variable paths, since there is no special harm in doing so and it can be very beneficial if the trimming still pans out.\n  Made the UI a bit more descriptive by adding \u0026ldquo;n/a\u0026rdquo; instead of \u0026ldquo;0\u0026rdquo; in a couple of corner cases.\n  Version 1.14b:   Added a (partial) dictionary for JavaScript.\n  Added AFL_NO_CPU_RED, as suggested by Jakub Wilk.\n  Tweaked the havoc scaling logic added in 1.12b.\n  Version 1.13b:   Improved the performance of minimize_corpus.sh by switching to a sort-based approach.\n  Made several minor revisions to the docs.\n  Version 1.12b:   Made an improvement to dictionary generation to avoid runs of identical bytes.\n  Added havoc cycle scaling to help with slow binaries in -d mode. Based on a thread with Sami Liedes.\n  Added AFL_SYNC_FIRST for afl-fuzz. This is useful for those who obsess over stats, no special purpose otherwise.\n  Switched to more robust box drawing codes, suggested by Jakub Wilk.\n  Created faster 64-bit variants of several critical-path bitmap functions (sorry, no difference on 32 bits).\n  Fixed moar typos, as reported by Jakub Wilk.\n  Version 1.11b:  Added a bit more info about dictionary strategies to the status screen.  Version 1.10b:   Revised the dictionary behavior to use insertion and overwrite in deterministic steps, rather than just the latter. This improves coverage with SQL and the like.\n  Added a mention of \u0026ldquo;*\u0026rdquo; in status_screen.txt, as suggested by Jakub Wilk.\n  Version 1.09b:   Corrected a cosmetic problem with \u0026lsquo;extras\u0026rsquo; stage count not always being accurate in the stage yields view.\n  Fixed a typo reported by Jakub Wilk and made some minor documentation improvements.\n  Version 1.08b:  Fixed a div-by-zero bug in the newly-added code when using a dictionary.  Version 1.07b:   Added code that automatically finds and extracts syntax tokens from the input corpus.\n  Fixed a problem with ld dead-code removal option on MacOS X, reported by Filipe Cabecinhas.\n  Corrected minor typos spotted by Jakub Wilk.\n  Added a couple of more exotic archive format samples.\n  Version 1.06b:   Switched to slightly more accurate (if still not very helpful) reporting of short read and short write errors. These theoretically shouldn\u0026rsquo;t happen unless you kill the forkserver or run out of disk space. Suggested by Jakub Wilk.\n  Revamped some of the allocator and debug code, adding comments and cleaning up other mess.\n  Tweaked the odds of fuzzing non-favored test cases to make sure that baseline coverage of all inputs is reached sooner.\n  Version 1.05b:   Added a dictionary for WebP.\n  Made some additional performance improvements to minimize_corpus.sh, getting deeper into the bash woods.\n  Version 1.04b:   Made substantial performance improvements to minimize_corpus.sh with large datasets, albeit at the expense of having to switch back to bash (other shells may have limits on array sizes, etc).\n  Tweaked afl-showmap to support the format used by the new script.\n  Version 1.03b:   Added code to skip README.txt in the input directory to make the crash exploration mode work better. Suggested by Jakub Wilk.\n  Added a dictionary for SQLite.\n  Version 1.02b:   Reverted the ./ search path in minimize_corpus.sh because people did not like it.\n  Added very explicit warnings not to run various shell scripts that read or write to /tmp/ (since this is generally a pretty bad idea on multi-user systems).\n  Added a check for /tmp binaries and -f locations in afl-fuzz.\n  Version 1.01b:  Added dictionaries for XML and GIF.  Version 1.00b:   Slightly improved the performance of minimize_corpus.sh, especially on Linux.\n  Made a couple of improvements to calibration timeouts for resumed scans.\n  Version 0.99b:   Fixed minimize_corpus.sh to work with dash, as suggested by Jakub Wilk.\n  Modified minimize_corpus.sh to try locate afl-showmap in $PATH and ./. The first part requested by Jakub Wilk.\n  Added support for afl-as \u0026ndash;version, as required by one funky build script. Reported by William Robinet.\n  Version 0.98b:   Added a dictionary for TIFF.\n  Fixed another cosmetic snafu with stage exec counts for -x.\n  Switched afl-plot to /bin/sh, since it seems bashism-free. Also tried to remove any obvious bashisms from other examples/ scripts, most notably including minimize_corpus.sh and triage_crashes.sh. Requested by Jonathan Gray.\n  Version 0.97b:   Fixed cosmetic issues around the naming of -x strategy files.\n  Added a dictionary for JPEG.\n  Fixed a very rare glitch when running instrumenting 64-bit code that makes heavy use of xmm registers that are also touched by glibc.\n  Version 0.96b:   Added support for extra dictionaries, provided testcases/_extras/png/ as a demo.\n  Fixed a minor bug in number formatting routines used by the UI.\n  Added several additional PNG test cases that are relatively unlikely to be hit by chance.\n  Fixed afl-plot syntax for gnuplot 5.x. Reported by David Necas.\n  Version 0.95b:   Cleaned up the OSX ReportCrash code. Thanks to Tobias Ospelt for help.\n  Added some extra tips for AFL_NO_FORKSERVER on OSX.\n  Refreshed the INSTALL file.\n  Version 0.94b:   Added in-place resume (-i-) to address a common user complaint.\n  Added an awful workaround for ReportCrash on MacOS X. Problem spotted by Joseph Gentle.\n  Version 0.93b:  Fixed the link() workaround, as reported by Jakub Wilk.  Version 0.92b:   Added support for reading test cases from another filesystem. Requested by Jakub Wilk.\n  Added pointers to the mailing list.\n  Added a sample PDF document.\n  Version 0.91b:   Refactored minimize_corpus.sh to make it a bit more user-friendly and to select for smallest files, not largest bitmaps. Offers a modest corpus size improvement in most cases.\n  Slightly improved the performance of splicing code.\n  Version 0.90b:   Moved to an algorithm where paths are marked as preferred primarily based on size and speed, rather than bitmap coverage. This should offer noticeable performance gains in many use cases.\n  Refactored path calibration code; calibration now takes place as soon as a test case is discovered, to facilitate better prioritization decisions later on.\n  Changed the way of marking variable paths to avoid .state metadata inconsistencies.\n  Made sure that calibration routines always create a new test case to avoid hypothetical problems with utilities that modify the input file.\n  Added bitmap saturation to fuzzer stats and plot data.\n  Added a testcase for JPEG XR.\n  Added a tty check for the colors warning in Makefile, to keep distro build logs tidy. Suggested by Jakub Wilk.\n  Version 0.89b:   Renamed afl-plot.sh to afl-plot, as requested by Padraig Brady.\n  Improved the compatibility of afl-plot with older versions of gnuplot.\n  Added banner information to fuzzer_stats, populated it to afl-plot.\n  Version 0.88b:   Added support for plotting, with design and implementation based on a prototype design proposed by Michael Rash. Huge thanks!\n  Added afl-plot.sh, which allows you to, well, generate a nice plot using this data.\n  Refactored the code slightly to make more frequent updates to fuzzer_stats and to provide more detail about synchronization.\n  Added an fflush(stdout) call for non-tty operation, as requested by Joonas Kuorilehto.\n  Added some detail to fuzzer_stats for parity with plot_file.\n  Version 0.87b:  Added support for MSAN, via AFL_USE_MSAN, same gotchas as for ASAN.  Version 0.86b:   Added AFL_NO_FORKSRV, allowing the forkserver to be bypassed. Suggested by Ryan Govostes.\n  Simplified afl-showmap.c to make use of the no-forkserver mode.\n  Made minor improvements to crash_triage.sh, as suggested by Jakub Wilk.\n  Version 0.85b:   Fixed the CPU counting code - no sysctlbyname() on OpenBSD, d\u0026rsquo;oh. Bug reported by Daniel Dickman.\n  Made a slight correction to error messages - the advice on testing with ulimit was a tiny bit off by a factor of 1024.\n  Version 0.84b:   Added support for the CPU widget on some non-Linux platforms (I hope). Based on feedback from Ryan Govostes.\n  Cleaned up the changelog (very meta).\n  Version 0.83b:   Added examples/clang_asm_normalize/ and related notes in env_variables.txt and afl-as.c. Thanks to Ryan Govostes for the idea.\n  Added advice on hardware utilization in README.\n  Version 0.82b:   Made additional fixes for Xcode support, juggling -Q and -q flags. Thanks to Ryan Govostes.\n  Added a check for asm blocks and switches to .intel_syntax in assembly. Based on feedback from Ryan Govostes.\n  Version 0.81b:   A workaround for Xcode 6 as -Q flag glitch. Spotted by Ryan Govostes.\n  Improved Solaris build instructions, as suggested by Martin Carpenter.\n  Fix for a slightly busted path scoring conditional. Minor practical impact.\n  Version 0.80b:   Added a check for $PATH-induced loops. Problem noticed by Kartik Agaram.\n  Added AFL_KEEP_ASSEMBLY for easier troubleshooting.\n  Added an override for AFL_USE_ASAN if set at afl compile time. Requested by Hanno Boeck.\n  Version 0.79b:   Made minor adjustments to path skipping logic.\n  Made several documentation updates to reflect the path selection changes made in 0.78b.\n  Version 0.78b:   Added a CPU governor check. Bug report from Joe Zbiciak.\n  Favored paths are now selected strictly based on new edges, not hit counts. This speeds up the first pass by a factor of 3-6x without significantly impacting ultimate coverage (tested with libgif, libpng, libjpeg).\nIt also allows some performance \u0026amp; memory usage improvements by making some of the in-memory bitmaps much smaller.\n  Made multiple significant performance improvements to bitmap checking functions, plus switched to a faster hash.\n  Owing largely to these optimizations, bumped the size of the bitmap to 64k and added a warning to detect older binaries that rely on smaller bitmaps.\n  Version 0.77b:   Added AFL_SKIP_CHECKS to bypass binary checks when really warranted. Feature requested by Jakub Wilk.\n  Fixed a couple of typos.\n  Added a warning for runs that are aborted early on.\n  Version 0.76b:  Incorporated another signal handling fix for Solaris. Suggestion submitted by Martin Carpenter.  Version 0.75b:   Implemented a slightly more \u0026ldquo;elegant\u0026rdquo; kludge for the %llu glitch (see types.h).\n  Relaxed CPU load warnings to stay in sync with reality.\n  Version 0.74b:   Switched to more responsive exec speed averages and better UI speed scaling.\n  Fixed a bug with interrupted reads on Solaris. Issue spotted by Martin Carpenter.\n  Version 0.73b:  Fixed a stray memcpy() instead of memmove() on overlapping buffers. Mostly harmless but still dumb. Mistake spotted thanks to David Higgs.  Version 0.72b:   Bumped map size up to 32k. You may want to recompile instrumented binaries (but nothing horrible will happen if you don\u0026rsquo;t).\n  Made huge performance improvements for bit-counting functions.\n  Default optimizations now include -funroll-loops. This should have interesting effects on the instrumentation. Frankly, I\u0026rsquo;m just going to ship it and see what happens next. I have a good feeling about this.\n  Made a fix for stack alignment crash on MacOS X 10.10; looks like the rhetorical question in the comments in afl-as.h has been answered. Tracked down by Mudge Zatko.\n  Version 0.71b:   Added a fix for the nonsensical MacOS ELF check. Spotted by Mudge Zatko.\n  Made some improvements to ASAN checks.\n  Version 0.70b:   Added explicit detection of ASANified binaries.\n  Fixed compilation issues on Solaris. Reported by Martin Carpenter.\n  Version 0.69b:   Improved the detection of non-instrumented binaries.\n  Made the crash counter in -C mode accurate.\n  Fixed an obscure install bug that made afl-as non-functional with the tool installed to /usr/bin instead of /usr/local/bin. Found by Florian Kiersch.\n  Fixed for a cosmetic SIGFPE when Ctrl-C is pressed while the fork server is spinning up.\n  Version 0.68b:  Added crash exploration mode! Woot!  Version 0.67b:   Fixed several more typos, the project is now cartified 100% typo-free. Thanks to Thomas Jarosch and Jakub Wilk.\n  Made a change to write fuzzer_stats early on.\n  Fixed a glitch when (not!) running on MacOS X as root. Spotted by Tobias Ospelt.\n  Made it possible to override -O3 in Makefile. Suggested by Jakub Wilk.\n  Version 0.66b:   Fixed a very obscure issue with build systems that use gcc as an assembler for hand-written .s files; this would confuse afl-as. Affected nss, reported by Hanno Boeck.\n  Fixed a bug when cleaning up synchronized fuzzer output dirs. Issue reported by Thomas Jarosch.\n  Version 0.65b:   Cleaned up shell printf escape codes in Makefile. Reported by Jakub Wilk.\n  Added more color to fuzzer_stats, provided short documentation of the file format, and made several other stats-related improvements.\n  Version 0.64b:  Enabled GCC support on MacOS X.  Version 0.63b:   Provided a new, simplified way to pass data in files (@@). See README.\n  Made additional fixes for 64-bit MacOS X, working around a crashing bug in their linker (umpf) and several other things. It\u0026rsquo;s alive!\n  Added a minor workaround for a bug in 64-bit FreeBSD (clang -m32 -g doesn\u0026rsquo;t work on that platform, but clang -m32 does, so we no longer insert -g).\n  Added a build-time warning for inverse video terminals and better instructions in status_screen.txt.\n  Version 0.62b:   Made minor improvements to the allocator, as suggested by Tobias Ospelt.\n  Added example instrumented memcmp() in examples/instrumented_cmp.\n  Added a speculative fix for MacOS X (clang detection, again).\n  Fixed typos in parallel_fuzzing.txt. Problems spotted by Thomas Jarosch.\n  Version 0.61b:   Fixed a minor issue with clang detection on systems with a clang cc wrapper, so that afl-gcc doesn\u0026rsquo;t confuse it with GCC.\n  Made cosmetic improvements to docs and to the CPU load indicator.\n  Fixed a glitch with crash removal (README.txt left behind, d\u0026rsquo;oh).\n  Version 0.60b:   Fixed problems with jump tables generated by exotic versions of GCC. This solves an outstanding problem on OpenBSD when using afl-gcc + PIE (not present with afl-clang).\n  Fixed permissions on one of the sample archives.\n  Added a lahf / sahf workaround for OpenBSD (their assembler doesn\u0026rsquo;t know about these opcodes).\n  Added docs/INSTALL.\n  Version 0.59b:   Modified \u0026lsquo;make install\u0026rsquo; to also install test cases.\n  Provided better pointers to installed README in afl-fuzz.\n  More work on RLIMIT_AS for OpenBSD.\n  Version 0.58b:   Added a core count check on Linux.\n  Refined the code for the lack-of-RLIMIT_AS case on OpenBSD.\n  Added a rudimentary CPU utilization meter to help with optimal loading.\n  Version 0.57b:   Made fixes to support FreeBSD and OpenBSD: use_64bit is now inferred if not explicitly specified when calling afl-as, and RLIMIT_AS is behind an #ifdef. Thanks to Fabian Keil and Jonathan Gray for helping troubleshoot this.\n  Modified \u0026lsquo;make install\u0026rsquo; to also install docs (in /usr/local/share/doc/afl).\n  Fixed a typo in status_screen.txt.\n  Made a couple of Makefile improvements as proposed by Jakub Wilk.\n  Version 0.56b:   Added probabilistic instrumentation density reduction in ASAN mode. This compensates for ASAN-specific branches in a crude but workable way.\n  Updated notes_for_asan.txt.\n  Version 0.55b:   Implemented smarter out_dir behavior, automatically deleting directories that don\u0026rsquo;t contain anything of special value. Requested by several folks, including Hanno Boeck.\n  Added more detail in fuzzer_stats (start time, run time, fuzzer PID).\n  Implemented support for configurable install prefixes in Makefile ($PREFIX), as requested by Luca Barbato.\n  Made it possible to resume by doing -i \u0026lt;out_dir\u0026gt;, without having to specify -i \u0026lt;out_dir\u0026gt;/queue/.\n  Version 0.54b:  Added a fix for -Wformat warning messages (oops, I thought this had been in place for a while).  Version 0.53b:   Redesigned the crash \u0026amp; hang duplicate detection code to better deal with fault conditions that can be reached in a multitude of ways.\nThe old approach could be compared to hashing stack traces to de-dupe crashes, a method prone to crash count inflation. The alternative I wanted to avoid would be equivalent to just looking at crash %eip, which can have false negatives in common functions such as memcpy().\nThe middle ground currently used in afl-fuzz can be compared to looking at every line item in the stack trace and tagging crashes as unique if we see any function name that we haven\u0026rsquo;t seen before (or if something that we have always seen there suddenly disappears). We do the comparison without paying any attention to ordering or hit counts. This can still cause some crash inflation early on, but the problem will quickly taper off. So, you may get 20 dupes instead of 5,000.\n  Added a fix for harmless but absurd trim ratios shown if the first exec in the trimmer timed out. Spotted by @EspenGx.\n  Version 0.52b:   Added a quick summary of the contents in examples/.\n  Made a fix to the process of writing fuzzer_stats.\n  Slightly reorganized the .state/ directory, now recording redundant paths, too. Note that this breaks the ability to properly resume older sessions\n sorry about that.  (To fix this, simply move \u0026lt;out_dir\u0026gt;/.state/* from an older run to \u0026lt;out_dir\u0026gt;/.state/deterministic_done/*.)\n  Version 0.51b:   Changed the search order for afl-as to avoid the problem with older copies installed system-wide; this also means that I can remove the Makefile check for that.\n  Made it possible to set instrumentation ratio of 0%.\n  Introduced some typos, fixed others.\n  Fixed the test_prev target in Makefile, as reported by Ozzy Johnson.\n  Version 0.50b:   Improved the \u0026lsquo;make install\u0026rsquo; logic, as suggested by Padraig Brady.\n  Revamped various bits of the documentation, especially around perf_tips.txt; based on the feedback from Alexander Cherepanov.\n  Added AFL_INST_RATIO to afl-as. The only case where this comes handy is ffmpeg, at least as far as I can tell. (Trivia: the current version of ffmpeg ./configure also ignores CC and \u0026ndash;cc, probably unintentionally).\n  Added documentation for all environmental variables (env_variables.txt).\n  Implemented a visual warning for excessive or insufficient bitmap density.\n  Changed afl-gcc to add -O3 by default; use AFL_DONT_OPTIMIZE if you don\u0026rsquo;t like that. Big speed gain for ffmpeg, so seems like a good idea.\n  Made a regression fix to afl-as to ignore .LBB labels in gcc mode.\n  Version 0.49b:   Fixed more typos, as found by Jakub Wilk.\n  Added support for clang!\n  Changed AFL_HARDEN to not include ASAN by default. Use AFL_USE_ASAN if needed. The reasons for this are in notes_for_asan.txt.\n  Switched from configure auto-detection to isatty() to keep afl-as and afl-gcc quiet.\n  Improved installation process to properly create symlinks, rather than copies of binaries.\n  Version 0.48b:   Improved afl-fuzz to force-set ASAN_OPTIONS=abort_on_error=1. Otherwise, ASAN crashes wouldn\u0026rsquo;t be caught at all. Reported by Hanno Boeck.\n  Improved Makefile mkdir logic, as suggested by Hanno Boeck.\n  Improved the 64-bit instrumentation to properly save r8-r11 registers in the x86 setup code. The old behavior could cause rare problems running without instrumentation when the first function called in a particular .o file has 5+ parameters. No impact on code running under afl-fuzz or afl-showmap. Issue spotted by Padraig Brady.\n  Version 0.47b:   Fixed another Makefile bug for parallel builds of afl. Problem identified by Richard W. M. Jones.\n  Added support for suffixes for -m.\n  Updated the documentation and added notes_for_asan.txt. Based on feedback from Hanno Boeck, Ben Laurie, and others.\n  Moved the project to http://lcamtuf.coredump.cx/afl/.\n  Version 0.46b:   Cleaned up Makefile dependencies for parallel builds. Requested by Richard W. M. Jones.\n  Added support for DESTDIR in Makefile. Once again suggested by Richard W. M. Jones :-)\n  Removed all the USE_64BIT stuff; we now just auto-detect compilation mode. As requested by many callers to the show.\n  Fixed rare problems with programs that use snippets of assembly and switch between .code32 and .code64. Addresses a glitch spotted by Hanno Boeck with compiling ToT gdb.\n  Version 0.45b:   Implemented a test case trimmer. Results in 20-30% size reduction for many types of work loads, with very pronounced improvements in path discovery speeds.\n  Added better warnings for various problems with input directories.\n  Added a Makefile warning for older copies, based on counterintuitive behavior observed by Hovik Manucharyan.\n  Added fuzzer_stats file for status monitoring. Suggested by @dronesec.\n  Fixed moar typos, thanks to Alexander Cherepanov.\n  Implemented better warnings for ASAN memory requirements, based on calls from several angry listeners.\n  Switched to saner behavior with non-tty stdout (less output generated, no ANSI art).\n  Version 0.44b:   Added support for AFL_CC and AFL_CXX, based on a patch from Ben Laurie.\n  Replaced afl-fuzz -S -D with -M for simplicity.\n  Added a check for .section .text; lack of this prevented main() from getting instrumented for some users. Reported by Tom Ritter.\n  Reorganized the testcases/ directory.\n  Added an extra check to confirm that the build is operational.\n  Made more consistent use of color reset codes, as suggested by Oliver Kunz.\n  Version 0.43b:   Fixed a bug with 64-bit gcc -shared relocs.\n  Removed echo -e from Makefile for compatibility with dash. Suggested by Jakub Wilk.\n  Added status_screen.txt.\n  Added examples/canvas_harness.\n  Made a minor change to the Makefile GCC check. Suggested by Hanno Boeck.\n  Version 0.42b:   Fixed a bug with red zone handling for 64-bit (oops!). Problem reported by Felix Groebert.\n  Implemented horribly experimental ARM support in examples/arm_support.\n  Made several improvements to error messages.\n  Added AFL_QUIET to silence afl-gcc and afl-as when using wonky build systems. Reported by Hanno Boeck.\n  Improved check for 64-bit compilation, plus several sanity checks in Makefile.\n  Version 0.41b:   Fixed a fork served bug for processes that call execve().\n  Made minor compatibility fixes to Makefile, afl-gcc; suggested by Jakub Wilk.\n  Fixed triage_crashes.sh to work with the new layout of output directories. Suggested by Jakub Wilk.\n  Made multiple performance-related improvements to the injected instrumentation.\n  Added visual indication of the number of imported paths.\n  Fixed afl-showmap to make it work well with new instrumentation.\n  Added much better error messages for crashes when importing test cases or otherwise calibrating the binary.\n  Version 0.40b:   Added support for parallelized fuzzing. Inspired by earlier patch from Sebastian Roschke.\n  Added an example in examples/distributed_fuzzing/.\n  Version 0.39b:   Redesigned status screen, now 90% more spiffy.\n  Added more verbose and user-friendly messages for some common problems.\n  Modified the resumption code to reconstruct path depth.\n  Changed the code to inhibit core dumps and improve the ability to detect SEGVs.\n  Added a check for redirection of core dumps to programs.\n  Made a minor improvement to the handling of variable paths.\n  Made additional performance tweaks to afl-fuzz, chiefly around mem limits.\n  Added performance_tips.txt.\n  Version 0.38b:   Fixed an fd leak and +cov tracking bug resulting from changes in 0.37b.\n  Implemented auto-scaling for screen update speed.\n  Added a visual indication when running in non-instrumented mode.\n  Version 0.37b:   Added fuzz state tracking for more seamless resumption of aborted fuzzing sessions.\n  Removed the -D option, as it\u0026rsquo;s no longer necessary.\n  Refactored calibration code and improved startup reporting.\n  Implemented dynamically scaled timeouts, so that you don\u0026rsquo;t need to play with -t except in some very rare cases.\n  Added visual notification for slow binaries.\n  Improved instrumentation to explicitly cover the other leg of every branch.\n  Version 0.36b:   Implemented fork server support to avoid the overhead of execve(). A nearly-verbatim design from Jann Horn; still pending part 2 that would also skip initial setup steps (thinking about reliable heuristics now).\n  Added a check for shell scripts used as fuzz targets.\n  Added a check for fuzz jobs that don\u0026rsquo;t seem to be finding anything.\n  Fixed the way IGNORE_FINDS works (was a bit broken after adding splicing and path skip heuristics).\n  Version 0.35b:  Properly integrated 64-bit instrumentation into afl-as.  Version 0.34b:  Added a new exec count classifier (the working theory is that it gets meaningful coverage with fewer test cases spewed out).  Version 0.33b:   Switched to new, somewhat experimental instrumentation that tries to target only arcs, rather than every line. May be fragile, but is a lot faster (2x+).\n  Made several other cosmetic fixes and typo corrections, thanks to Jakub Wilk.\n  Version 0.32b:  Another take at fixing the C++ exception thing. Reported by Jakub Wilk.  Version 0.31b:  Made another fix to afl-as to address a potential problem with newer versions of GCC (introduced in 0.28b). Thanks to Jann Horn.  Version 0.30b:  Added more detail about the underlying operations in file names.  Version 0.29b:  Made some general improvements to chunk operations.  Version 0.28b:   Fixed C++ exception handling in newer versions of GCC. Problem diagnosed by Eberhard Mattes.\n  Fixed the handling of the overflow flag. Once again, thanks to Eberhard Mattes.\n  Version 0.27b:   Added prioritization of new paths over the already-fuzzed ones.\n  Included spliced test case ID in the output file name.\n  Fixed a rare, cosmetic null ptr deref after Ctrl-C.\n  Refactored the code to make copies of test cases in the output directory.\n  Switched to better output file names, keeping track of stage and splicing sources.\n  Version 0.26b:   Revamped storage of testcases, -u option removed,\n  Added a built-in effort minimizer to get rid of potentially redundant inputs,\n  Provided a testcase count minimization script in examples/,\n  Made miscellaneous improvements to directory and file handling.\n  Fixed a bug in timeout detection.\n  Version 0.25b:   Improved count-based instrumentation.\n  Improved the hang deduplication logic.\n  Added -cov prefixes for test cases.\n  Switched from readdir() to scandir() + alphasort() to preserve ordering of test cases.\n  Added a splicing strategy.\n  Made various minor UI improvements and several other bugfixes.\n  Version 0.24b:  Added program name to the status screen, plus the -T parameter to go with it.  Version 0.23b:   Improved the detection of variable behaviors.\n  Added path depth tracking,\n  Improved the UI a bit,\n  Switched to simplified (XOR-based) tuple instrumentation.\n  Version 0.22b:   Refactored the handling of long bitflips and some swaps.\n  Fixed the handling of gcc -pipe, thanks to anonymous reporter.\n  Version 0.21b (2013-11-12):  Initial public release.  "});index.add({'id':7,'href':'/docs/custom_mutator/','title':"Custom Mutator",'content':"Adding custom mutators to AFL This file describes how you can implement custom mutations to be used in AFL.\nImplemented by Khaled Yakdan from Code Intelligence yakdan@code-intelligence.de\n1) Description Custom mutator libraries can be passed to afl-fuzz to perform custom mutations on test cases beyond those available in AFL - for example, to enable structure-aware fuzzing by using libraries that perform mutations according to a given grammar.\nThe custom mutator library is passed to afl-fuzz via the AFL_CUSTOM_MUTATOR_LIBRARY environment variable. The library must export the afl_custom_mutator() function and must be compiled as a shared object. For example: $CC -shared -Wall -O3 .c -o .so\nNote: unless AFL_CUSTOM_MUTATOR_ONLY is set, its state mutator like any others, so it will be used for some test cases, and other mutators for others.\nOnly if AFL_CUSTOM_MUTATOR_ONLY is set the afl_custom_mutator() function will be called every time it needs to mutate test case!\nFor some cases, the format of the mutated data returned from the custom mutator is not suitable to directly execute the target with this input. For example, when using libprotobuf-mutator, the data returned is in a protobuf format which corresponds to a given grammar. In order to execute the target, the protobuf data must be converted to the plain-text format expected by the target. In such scenarios, the user can define the afl_pre_save_handler() function. This function is then transforms the data into the format expected by the API before executing the target. afl_pre_save_handler is optional and does not have to be implemented if its functionality is not needed.\n2) Example A simple example is provided in ../examples/custom_mutators/\n"});index.add({'id':8,'href':'/docs/custom_mutators/','title':"Custom Mutators",'content':"Custom Mutators in AFL++ This file describes how you can implement custom mutations to be used in AFL. For now, we support C/C++ library and Python module, collectivelly named as the custom mutator.\nImplemented by\n C/C++ library (*.so): Khaled Yakdan from Code Intelligence (yakdan@code-intelligence.de) Python module: Christian Holler from Mozilla (choller@mozilla.com)  1) Introduction Custom mutators can be passed to afl-fuzz to perform custom mutations on test cases beyond those available in AFL. For example, to enable structure-aware fuzzing by using libraries that perform mutations according to a given grammar.\nThe custom mutator is passed to afl-fuzz via the AFL_CUSTOM_MUTATOR_LIBRARY or AFL_PYTHON_MODULE environment variable, and must export a fuzz function. Please see APIs and Usage for detail.\nThe custom mutation stage is set to be the first non-deterministic stage (right before the havoc stage).\nNote: If AFL_CUSTOM_MUTATOR_ONLY is set, all mutations will solely be performed with the custom mutator.\n2) APIs C/C++:\nvoid *afl_custom_init(afl_t *afl, unsigned int seed); size_t afl_custom_fuzz(void *data, uint8_t *buf, size_t buf_size, u8 **out_buf, uint8_t *add_buf, size_t add_buf_size, size_t max_size); size_t afl_custom_pre_save(void *data, uint8_t *buf, size_t buf_size, uint8_t **out_buf); int32_t afl_custom_init_trim(void *data, uint8_t *buf, size_t buf_size); size_t afl_custom_trim(void *data, uint8_t **out_buf); int32_t afl_custom_post_trim(void *data, int success) { size_t afl_custom_havoc_mutation(void *data, u8 *buf, size_t buf_size, u8 **out_buf, size_t max_size); uint8_t afl_custom_havoc_mutation_probability(void *data); uint8_t afl_custom_queue_get(void *data, const uint8_t *filename); void afl_custom_queue_new_entry(void *data, const uint8_t *filename_new_queue, const uint8_t *filename_orig_queue); void afl_custom_deinit(void *data); Python:\ndef init(seed): pass def fuzz(buf, add_buf, max_size): return mutated_out def pre_save(buf): return out_buf def init_trim(buf): return cnt def trim(): return out_buf def post_trim(success): return next_index def havoc_mutation(buf, max_size): return mutated_out def havoc_mutation_probability(): return probability # int in [0, 100] def queue_get(filename): return True def queue_new_entry(filename_new_queue, filename_orig_queue): pass Custom Mutation   init:\nThis method is called when AFL++ starts up and is used to seed RNG and set up buffers and state.\n  queue_get (optional):\nThis method determines whether the fuzzer should fuzz the current queue entry or not\n  fuzz (required):\nThis method performs custom mutations on a given input. It also accepts an additional test case.\n  havoc_mutation and havoc_mutation_probability (optional):\nhavoc_mutation performs a single custom mutation on a given input. This mutation is stacked with the other mutations in havoc. The other method, havoc_mutation_probability, returns the probability that havoc_mutation is called in havoc. By default, it is 6%.\n  pre_save (optional):\nFor some cases, the format of the mutated data returned from the custom mutator is not suitable to directly execute the target with this input. For example, when using libprotobuf-mutator, the data returned is in a protobuf format which corresponds to a given grammar. In order to execute the target, the protobuf data must be converted to the plain-text format expected by the target. In such scenarios, the user can define the pre_save function. This function is then transforms the data into the format expected by the API before executing the target.\n  queue_new_entry (optional):\nThis methods is called after adding a new test case to the queue.\n  Trimming Support The generic trimming routines implemented in AFL++ can easily destroy the structure of complex formats, possibly leading to a point where you have a lot of test cases in the queue that your Python module cannot process anymore but your target application still accepts. This is especially the case when your target can process a part of the input (causing coverage) and then errors out on the remaining input.\nIn such cases, it makes sense to implement a custom trimming routine. The API consists of multiple methods because after each trimming step, we have to go back into the C code to check if the coverage bitmap is still the same for the trimmed input. Here\u0026rsquo;s a quick API description:\n  init_trim (optional):\nThis method is called at the start of each trimming operation and receives the initial buffer. It should return the amount of iteration steps possible on this input (e.g. if your input has n elements and you want to remove them one by one, return n, if you do a binary search, return log(n), and so on).\nIf your trimming algorithm doesn\u0026rsquo;t allow you to determine the amount of (remaining) steps easily (esp. while running), then you can alternatively return 1 here and always return 0 in post_trim until you are finished and no steps remain. In that case, returning 1 in post_trim will end the trimming routine. The whole current index/max iterations stuff is only used to show progress.\n  trim (optional)\nThis method is called for each trimming operation. It doesn\u0026rsquo;t have any arguments because we already have the initial buffer from init_trim and we can memorize the current state in the data variables. This can also save reparsing steps for each iteration. It should return the trimmed input buffer, where the returned data must not exceed the initial input data in length. Returning anything that is larger than the original data (passed to init_trim) will result in a fatal abort of AFL++.\n  post_trim (optional)\nThis method is called after each trim operation to inform you if your trimming step was successful or not (in terms of coverage). If you receive a failure here, you should reset your input to the last known good state. In any case, this method must return the next trim iteration index (from 0 to the maximum amount of steps you returned in init_trim).\n  deinit the last method to be called, deinitializing the state.\nOmitting any of three methods will cause the trimming to be disabled and trigger a fallback to the builtin default trimming routine.\nEnvironment Variables Optionally, the following environment variables are supported:\n  AFL_CUSTOM_MUTATOR_ONLY\nDisable all other mutation stages. This can prevent broken testcases (those that your Python module can\u0026rsquo;t work with anymore) to fill up your queue. Best combined with a custom trimming routine (see below) because trimming can cause the same test breakage like havoc and splice.\n  AFL_PYTHON_ONLY\nDeprecated and removed, use AFL_CUSTOM_MUTATOR_ONLY instead trimming can cause the same test breakage like havoc and splice.\n  AFL_DEBUG\nWhen combined with AFL_NO_UI, this causes the C trimming code to emit additional messages about the performance and actions of your custom trimmer. Use this to see if it works :)\n  3) Usage Prerequisite For Python mutator, the python 3 or 2 development package is required. On Debian/Ubuntu/Kali this can be done:\nsudo apt install python3-dev # or sudo apt install python-dev Then, AFL++ can be compiled with Python support. The AFL++ Makefile detects Python 2 and 3 through python-config if it is in the PATH and compiles afl-fuzz with the feature if available.\nNote: for some distributions, you might also need the package python[23]-apt. In case your setup is different, set the necessary variables like this: PYTHON_INCLUDE=/path/to/python/include LDFLAGS=-L/path/to/python/lib make.\nCustom Mutator Preparation For C/C++ mutator, the source code must be compiled as a shared object:\ngcc -shared -Wall -O3 example.c -o example.so Run C/C++\nexport AFL_CUSTOM_MUTATOR_LIBRARY=/full/path/to/example.so afl-fuzz /path/to/program Python\nexport PYTHONPATH=`dirname /full/path/to/example.py` export AFL_PYTHON_MODULE=example afl-fuzz /path/to/program 4) Example Please see example.c and example.py\n5) Other Resources  AFL libprotobuf mutator  bruce30262/libprotobuf-mutator_fuzzing_learning thebabush/afl-libprotobuf-mutator   XML Fuzzing@NullCon 2017  A bug detected by AFL + XML-aware mutators    "});index.add({'id':9,'href':'/docs/env_variables/','title':"Env Variables",'content':"Environmental variables This document discusses the environment variables used by American Fuzzy Lop++ to expose various exotic functions that may be (rarely) useful for power users or for some types of custom fuzzing setups. See README.md for the general instruction manual.\n1) Settings for afl-gcc, afl-clang, and afl-as - and gcc_plugin afl-gcc-fast Because they can\u0026rsquo;t directly accept command-line options, the compile-time tools make fairly broad use of environmental variables:\n  Most afl tools do not print any ouput if stout/stderr are redirected. If you want to have the output into a file then set the AFL_DEBUG environment variable. This is sadly necessary for various build processes which fail otherwise.\n  Setting AFL_HARDEN automatically adds code hardening options when invoking the downstream compiler. This currently includes -D_FORTIFY_SOURCE=2 and -fstack-protector-all. The setting is useful for catching non-crashing memory bugs at the expense of a very slight (sub-5%) performance loss.\n  By default, the wrapper appends -O3 to optimize builds. Very rarely, this will cause problems in programs built with -Werror, simply because -O3 enables more thorough code analysis and can spew out additional warnings. To disable optimizations, set AFL_DONT_OPTIMIZE.\n  Setting AFL_USE_ASAN automatically enables ASAN, provided that your compiler supports that. Note that fuzzing with ASAN is mildly challenging\n see notes_for_asan.md.  (You can also enable MSAN via AFL_USE_MSAN; ASAN and MSAN come with the same gotchas; the modes are mutually exclusive. UBSAN can be enabled similarly by setting the environment variable AFL_USE_UBSAN=1. Finally there is the Control Flow Integrity sanitizer that can be activated by AFL_USE_CFISAN=1)\n  Setting AFL_CC, AFL_CXX, and AFL_AS lets you use alternate downstream compilation tools, rather than the default \u0026lsquo;clang\u0026rsquo;, \u0026lsquo;gcc\u0026rsquo;, or \u0026lsquo;as\u0026rsquo; binaries in your $PATH.\n  AFL_PATH can be used to point afl-gcc to an alternate location of afl-as. One possible use of this is examples/clang_asm_normalize/, which lets you instrument hand-written assembly when compiling clang code by plugging a normalizer into the chain. (There is no equivalent feature for GCC.)\n  Setting AFL_INST_RATIO to a percentage between 0 and 100% controls the probability of instrumenting every branch. This is (very rarely) useful when dealing with exceptionally complex programs that saturate the output bitmap. Examples include v8, ffmpeg, and perl.\n(If this ever happens, afl-fuzz will warn you ahead of the time by displaying the \u0026ldquo;bitmap density\u0026rdquo; field in fiery red.)\nSetting AFL_INST_RATIO to 0 is a valid choice. This will instrument only the transitions between function entry points, but not individual branches.\n  AFL_NO_BUILTIN causes the compiler to generate code suitable for use with libtokencap.so (but perhaps running a bit slower than without the flag).\n  TMPDIR is used by afl-as for temporary files; if this variable is not set, the tool defaults to /tmp.\n  Setting AFL_KEEP_ASSEMBLY prevents afl-as from deleting instrumented assembly files. Useful for troubleshooting problems or understanding how the tool works. To get them in a predictable place, try something like:\nmkdir assembly_here TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all\n  If you are a weird person that wants to compile and instrument asm text files then use the AFL_AS_FORCE_INSTRUMENT variable: AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo\n  Setting AFL_QUIET will prevent afl-cc and afl-as banners from being displayed during compilation, in case you find them distracting.\n  Setting AFL_CAL_FAST will speed up the initial calibration, if the application is very slow\n  2) Settings for afl-clang-fast / afl-clang-fast++ / afl-gcc-fast / afl-g++-fast The native instrumentation helpers (llvm_mode and gcc_plugin) accept a subset of the settings discussed in section #1, with the exception of:\n  AFL_AS, since this toolchain does not directly invoke GNU as.\n  TMPDIR and AFL_KEEP_ASSEMBLY, since no temporary assembly files are created.\n  AFL_INST_RATIO, as we switched for instrim instrumentation which is more effective but makes not much sense together with this option.\n  Then there are a few specific features that are only available in llvm_mode:\nSelect the instrumentation mode - AFL_LLVM_INSTRUMENT - this configures the instrumentation mode. Available options: DEFAULT - classic AFL (map[cur_loc ^ prev_loc \u0026gt;\u0026gt; 1]++) CFG - InsTrim instrumentation (see below) LTO - LTO instrumentation (see below) CTX - context sensitive instrumentation (see below) NGRAM-x - deeper previous location coverage (from NGRAM-2 up to NGRAM-16) Only one can be used.  LTO This is a different kind way of instrumentation: first it compiles all code in LTO (link time optimization) and then performs an edge inserting instrumentation which is 100% collision free (collisions are a big issue in afl and afl-like instrumentations). This is performed by using afl-clang-lto/afl-clang-lto++ instead of afl-clang-fast, but is only built if LLVM 9 or newer is used. None of these options are necessary to be used and are rather for manual use (which only ever the author of this LTO implementation will use ;-) These are used if several seperated instrumentation are performed which are then later combined.   AFL_LLVM_LTO_STARTID sets the starting location ID for the instrumentation. This defaults to 1 AFL_LLVM_LTO_DONTWRITEID prevents that the highest location ID written into the instrumentation is set in a global variable  See llvm_mode/README.LTO.md for more information.  INSTRIM This feature increases the speed by ~15% without any disadvantages. - Setting AFL_LLVM_INSTRIM or AFL_LLVM_INSTRUMENT=CFG to activates this mode - Setting AFL_LLVM_INSTRIM_LOOPHEAD=1 expands on INSTRIM to optimize loops. afl-fuzz will only be able to see the path the loop took, but not how many times it was called (unless it is a complex loop). - Setting AFL_LLVM_INSTRIM_SKIPSINGLEBLOCK=1 will skip instrumenting functions with a single basic block. This is useful for most C and some C++ targets. See llvm_mode/README.instrim.md  NGRAM - Setting AFL_LLVM_NGRAM_SIZE or AFL_LLVM_INSTRUMENT=NGRAM-{value} activates ngram prev_loc coverage, good values are 2, 4 or 8 (any value between 2 and 16 is valid). It is highly recommended to increase the MAP_SIZE_POW2 definition in config.h to at least 18 and maybe up to 20 for this as otherwise too many map collisions occur. See llvm_mode/README.ctx.md  CTX - Setting AFL_LLVM_CTX or AFL_LLVM_INSTRUMENT=CTX activates context sensitive branch coverage - meaning that each edge is additionally combined with its caller. It is highly recommended to increase the MAP_SIZE_POW2 definition in config.h to at least 18 and maybe up to 20 for this as otherwise too many map collisions occur. See llvm_mode/README.ngram.md  LAF-INTEL This great feature will split compares to series of single byte comparisons to allow afl-fuzz to find otherwise rather impossible paths. It is not restricted to Intel CPUs ;-) - Setting AFL_LLVM_LAF_SPLIT_SWITCHES will split switch()es - Setting AFL_LLVM_LAF_TRANSFORM_COMPARES will split string compare functions - Setting AFL_LLVM_LAF_SPLIT_COMPARES will split all floating point and 64, 32 and 16 bit integer CMP instructions See llvm_mode/README.laf-intel.md for more information.  WHITELIST This feature allows selectively instrumentation of the source - Setting AFL_LLVM_WHITELIST with a filename will only instrument those files that match the names listed in this file. See llvm_mode/README.whitelist.md for more information.  NOT_ZERO - Setting AFL_LLVM_NOT_ZERO=1 during compilation will use counters that skip zero on overflow. This is the default for llvm \u0026gt;= 9, however for llvm versions below that this will increase an unnecessary slowdown due a performance issue that is only fixed in llvm 9+. This feature increases path discovery by a little bit. See llvm_mode/README.neverzero.md  CMPLOG - Setting AFL_LLVM_CMPLOG=1 during compilation will tell afl-clang-fast to produce a CmpLog binary. See llvm_mode/README.cmplog.md See llvm_mode/README.neverzero.md  Then there are a few specific features that are only available in the gcc_plugin:\nWHITELIST This feature allows selective instrumentation of the source - Setting AFL_GCC_WHITELIST with a filename will only instrument those files that match the names listed in this file (one filename per line). See gcc_plugin/README.whitelist.md for more information.  3) Settings for afl-fuzz The main fuzzer binary accepts several options that disable a couple of sanity checks or alter some of the more exotic semantics of the tool:\n  Setting AFL_SKIP_CPUFREQ skips the check for CPU scaling policy. This is useful if you can\u0026rsquo;t change the defaults (e.g., no root access to the system) and are OK with some performance loss.\n  Setting AFL_NO_FORKSRV disables the forkserver optimization, reverting to fork + execve() call for every tested input. This is useful mostly when working with unruly libraries that create threads or do other crazy things when initializing (before the instrumentation has a chance to run).\nNote that this setting inhibits some of the user-friendly diagnostics normally done when starting up the forkserver and causes a pretty significant performance drop.\n  AFL_EXIT_WHEN_DONE causes afl-fuzz to terminate when all existing paths have been fuzzed and there were no new finds for a while. This would be normally indicated by the cycle counter in the UI turning green. May be convenient for some types of automated jobs.\n  Setting AFL_NO_AFFINITY disables attempts to bind to a specific CPU core on Linux systems. This slows things down, but lets you run more instances of afl-fuzz than would be prudent (if you really want to).\n  AFL_SKIP_CRASHES causes AFL to tolerate crashing files in the input queue. This can help with rare situations where a program crashes only intermittently, but it\u0026rsquo;s not really recommended under normal operating conditions.\n  Setting AFL_HANG_TMOUT allows you to specify a different timeout for deciding if a particular test case is a \u0026ldquo;hang\u0026rdquo;. The default is 1 second or the value of the -t parameter, whichever is larger. Dialing the value down can be useful if you are very concerned about slow inputs, or if you don\u0026rsquo;t want AFL to spend too much time classifying that stuff and just rapidly put all timeouts in that bin.\n  AFL_NO_ARITH causes AFL to skip most of the deterministic arithmetics. This can be useful to speed up the fuzzing of text-based file formats.\n  AFL_NO_SNAPSHOT will advice afl-fuzz not to use the snapshot feature if the snapshot lkm is loaded\n  AFL_SHUFFLE_QUEUE randomly reorders the input queue on startup. Requested by some users for unorthodox parallelized fuzzing setups, but not advisable otherwise.\n  AFL_TMPDIR is used to write the .cur_input file to if exists, and in the normal output directory otherwise. You would use this to point to a ramdisk/tmpfs. This increases the speed by a small value but also reduces the stress on SSDs.\n  When developing custom instrumentation on top of afl-fuzz, you can use AFL_SKIP_BIN_CHECK to inhibit the checks for non-instrumented binaries and shell scripts; and AFL_DUMB_FORKSRV in conjunction with the -n setting to instruct afl-fuzz to still follow the fork server protocol without expecting any instrumentation data in return.\n  When running in the -M or -S mode, setting AFL_IMPORT_FIRST causes the fuzzer to import test cases from other instances before doing anything else. This makes the \u0026ldquo;own finds\u0026rdquo; counter in the UI more accurate. Beyond counter aesthetics, not much else should change.\n  Setting AFL_POST_LIBRARY allows you to configure a postprocessor for mutated files - say, to fix up checksums. See examples/post_library/ for more.\n  Setting AFL_CUSTOM_MUTATOR_LIBRARY to a shared library with afl_custom_fuzz() creates additional mutations through this library. If afl-fuzz is compiled with Python (which is autodetected during builing afl-fuzz), setting AFL_PYTHON_MODULE to a Python module can also provide additional mutations. If AFL_CUSTOM_MUTATOR_ONLY is also set, all mutations will solely be performed with the custom mutator. This feature allows to configure custom mutators which can be very helpful, e.g. fuzzing XML or other highly flexible structured input. Please see custom_mutators.md.\n  AFL_FAST_CAL keeps the calibration stage about 2.5x faster (albeit less precise), which can help when starting a session against a slow target.\n  The CPU widget shown at the bottom of the screen is fairly simplistic and may complain of high load prematurely, especially on systems with low core counts. To avoid the alarming red color, you can set AFL_NO_CPU_RED.\n  In QEMU mode (-Q), AFL_PATH will be searched for afl-qemu-trace.\n  Setting AFL_PRELOAD causes AFL to set LD_PRELOAD for the target binary without disrupting the afl-fuzz process itself. This is useful, among other things, for bootstrapping libdislocator.so.\n  Setting AFL_NO_UI inhibits the UI altogether, and just periodically prints some basic stats. This behavior is also automatically triggered when the output from afl-fuzz is redirected to a file or to a pipe.\n  Setting AFL_FORCE_UI will force painting the UI on the screen even if no valid terminal was detected (for virtual consoles)\n  If you are Jakub, you may need AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES. Others need not apply.\n  Benchmarking only: AFL_BENCH_JUST_ONE causes the fuzzer to exit after processing the first queue entry; and AFL_BENCH_UNTIL_CRASH causes it to exit soon after the first crash is found.\n  Setting AFL_DEBUG_CHILD_OUTPUT will not suppress the child output. Not pretty but good for debugging purposes.\n  Setting AFL_NO_CPU_RED will not display very high cpu usages in red color.\n  Setting AFL_AUTORESUME will resume a fuzz run (same as providing -i -) for an existing out folder, even if a different -i was provided. Without this setting, afl-fuzz will refuse execution for a long-fuzzed out dir.\n  Outdated environment variables that are that not supported anymore: AFL_DEFER_FORKSRV AFL_PERSISTENT\n  4) Settings for afl-qemu-trace The QEMU wrapper used to instrument binary-only code supports several settings:\n  It is possible to set AFL_INST_RATIO to skip the instrumentation on some of the basic blocks, which can be useful when dealing with very complex binaries.\n  Setting AFL_INST_LIBS causes the translator to also instrument the code inside any dynamically linked libraries (notably including glibc).\n  Setting AFL_COMPCOV_LEVEL enables the CompareCoverage tracing of all cmp and sub in x86 and x86_64 and memory comparions functions (e.g. strcmp, memcmp, \u0026hellip;) when libcompcov is preloaded using AFL_PRELOAD. More info at qemu_mode/libcompcov/README.md. There are two levels at the moment, AFL_COMPCOV_LEVEL=1 that instruments only comparisons with immediate values / read-only memory and AFL_COMPCOV_LEVEL=2 that instruments all the comparions. Level 2 is more accurate but may need a larger shared memory.\n  Setting AFL_QEMU_COMPCOV enables the CompareCoverage tracing of all cmp and sub in x86 and x86_64. This is an alias of AFL_COMPCOV_LEVEL=1 when AFL_COMPCOV_LEVEL is not specified.\n  The underlying QEMU binary will recognize any standard \u0026ldquo;user space emulation\u0026rdquo; variables (e.g., QEMU_STACK_SIZE), but there should be no reason to touch them.\n  AFL_DEBUG will print the found entrypoint for the binary to stderr. Use this if you are unsure if the entrypoint might be wrong - but use it directly, e.g. afl-qemu-trace ./program\n  AFL_ENTRYPOINT allows you to specify a specific entrypoint into the binary (this can be very good for the performance!). The entrypoint is specified as hex address, e.g. 0x4004110 Note that the address must be the address of a basic block.\n  When the target is i386/x86_64 you can specify the address of the function that has to be the body of the persistent loop using AFL_QEMU_PERSISTENT_ADDR=start addr.\n  Another modality to execute the persistent loop is to specify also the AFL_QEMU_PERSISTENT_RET=end addr env variable. With this variable assigned, instead of patching the return address, the specified instruction is transformed to a jump towards start addr.\n  AFL_QEMU_PERSISTENT_GPR=1 QEMU will save the original value of general purpose registers and restore them in each persistent cycle.\n  With AFL_QEMU_PERSISTENT_RETADDR_OFFSET you can specify the offset from the stack pointer in which QEMU can find the return address when start addr is hitted.\n  5) Settings for afl-cmin The corpus minimization script offers very little customization:\n  Setting AFL_PATH offers a way to specify the location of afl-showmap and afl-qemu-trace (the latter only in -Q mode).\n  AFL_KEEP_TRACES makes the tool keep traces and other metadata used for minimization and normally deleted at exit. The files can be found in the \u0026lt;out_dir\u0026gt;/.traces/*.\n  AFL_ALLOW_TMP permits this and some other scripts to run in /tmp. This is a modest security risk on multi-user systems with rogue users, but should be safe on dedicated fuzzing boxes.\n  #6) Settings for afl-tmin Virtually nothing to play with. Well, in QEMU mode (-Q), AFL_PATH will be searched for afl-qemu-trace. In addition to this, TMPDIR may be used if a temporary file can\u0026rsquo;t be created in the current working directory.\nYou can specify AFL_TMIN_EXACT if you want afl-tmin to require execution paths to match when minimizing crashes. This will make minimization less useful, but may prevent the tool from \u0026ldquo;jumping\u0026rdquo; from one crashing condition to another in very buggy software. You probably want to combine it with the -e flag.\n7) Settings for afl-analyze You can set AFL_ANALYZE_HEX to get file offsets printed as hexadecimal instead of decimal.\n8) Settings for libdislocator The library honors these environmental variables:\n  AFL_LD_LIMIT_MB caps the size of the maximum heap usage permitted by the library, in megabytes. The default value is 1 GB. Once this is exceeded, allocations will return NULL.\n  AFL_LD_HARD_FAIL alters the behavior by calling abort() on excessive allocations, thus causing what AFL would perceive as a crash. Useful for programs that are supposed to maintain a specific memory footprint.\n  AFL_LD_VERBOSE causes the library to output some diagnostic messages that may be useful for pinpointing the cause of any observed issues.\n  AFL_LD_NO_CALLOC_OVER inhibits abort() on calloc() overflows. Most of the common allocators check for that internally and return NULL, so it\u0026rsquo;s a security risk only in more exotic setups.\n  AFL_ALIGNED_ALLOC=1 will force the alignment of the allocation size to max_align_t to be compliant with the C standard.\n  9) Settings for libtokencap This library accepts AFL_TOKEN_FILE to indicate the location to which the discovered tokens should be written.\n10) Third-party variables set by afl-fuzz \u0026amp; other tools Several variables are not directly interpreted by afl-fuzz, but are set to optimal values if not already present in the environment:\n  By default, LD_BIND_NOW is set to speed up fuzzing by forcing the linker to do all the work before the fork server kicks in. You can override this by setting LD_BIND_LAZY beforehand, but it is almost certainly pointless.\n  By default, ASAN_OPTIONS are set to:\nabort_on_error=1 detect_leaks=0 malloc_context_size=0 symbolize=0 allocator_may_return_null=1\nIf you want to set your own options, be sure to include abort_on_error=1 - otherwise, the fuzzer will not be able to detect crashes in the tested app. Similarly, include symbolize=0, since without it, AFL may have difficulty telling crashes and hangs apart.\n  In the same vein, by default, MSAN_OPTIONS are set to:\nexit_code=86 (required for legacy reasons) abort_on_error=1 symbolize=0 msan_track_origins=0 allocator_may_return_null=1\nBe sure to include the first one when customizing anything, since some MSAN versions don\u0026rsquo;t call abort() on error, and we need a way to detect faults.\n  "});index.add({'id':10,'href':'/docs/historical_notes/','title':"Historical Notes",'content':"Historical notes This doc talks about the rationale of some of the high-level design decisions for American Fuzzy Lop. It\u0026rsquo;s adopted from a discussion with Rob Graham. See README.md for the general instruction manual, and technical_details.md for additional implementation-level insights.\n1) Influences In short, afl-fuzz is inspired chiefly by the work done by Tavis Ormandy back in 2007. Tavis did some very persuasive experiments using gcov block coverage to select optimal test cases out of a large corpus of data, and then using them as a starting point for traditional fuzzing workflows.\n(By \u0026ldquo;persuasive\u0026rdquo;, I mean: netting a significant number of interesting vulnerabilities.)\nIn parallel to this, both Tavis and I were interested in evolutionary fuzzing. Tavis had his experiments, and I was working on a tool called bunny-the-fuzzer, released somewhere in 2007.\nBunny used a generational algorithm not much different from afl-fuzz, but also tried to reason about the relationship between various input bits and the internal state of the program, with hopes of deriving some additional value from that. The reasoning / correlation part was probably in part inspired by other projects done around the same time by Will Drewry and Chris Evans.\nThe state correlation approach sounded very sexy on paper, but ultimately, made the fuzzer complicated, brittle, and cumbersome to use; every other target program would require a tweak or two. Because Bunny didn\u0026rsquo;t fare a whole lot better than less sophisticated brute-force tools, I eventually decided to write it off. You can still find its original documentation at:\nhttps://code.google.com/p/bunny-the-fuzzer/wiki/BunnyDoc\nThere has been a fair amount of independent work, too. Most notably, a few weeks earlier that year, Jared DeMott had a Defcon presentation about a coverage-driven fuzzer that relied on coverage as a fitness function.\nJared\u0026rsquo;s approach was by no means identical to what afl-fuzz does, but it was in the same ballpark. His fuzzer tried to explicitly solve for the maximum coverage with a single input file; in comparison, afl simply selects for cases that do something new (which yields better results - see technical_details.md).\nA few years later, Gabriel Campana released fuzzgrind, a tool that relied purely on Valgrind and a constraint solver to maximize coverage without any brute-force bits; and Microsoft Research folks talked extensively about their still non-public, solver-based SAGE framework.\nIn the past six years or so, I\u0026rsquo;ve also seen a fair number of academic papers that dealt with smart fuzzing (focusing chiefly on symbolic execution) and a couple papers that discussed proof-of-concept applications of genetic algorithms with the same goals in mind. I\u0026rsquo;m unconvinced how practical most of these experiments were; I suspect that many of them suffer from the bunny-the-fuzzer\u0026rsquo;s curse of being cool on paper and in carefully designed experiments, but failing the ultimate test of being able to find new, worthwhile security bugs in otherwise well-fuzzed, real-world software.\nIn some ways, the baseline that the \u0026ldquo;cool\u0026rdquo; solutions have to compete against is a lot more impressive than it may seem, making it difficult for competitors to stand out. For a singular example, check out the work by Gynvael and Mateusz Jurczyk, applying \u0026ldquo;dumb\u0026rdquo; fuzzing to ffmpeg, a prominent and security-critical component of modern browsers and media players:\nhttp://googleonlinesecurity.blogspot.com/2014/01/ffmpeg-and-thousand-fixes.html\nEffortlessly getting comparable results with state-of-the-art symbolic execution in equally complex software still seems fairly unlikely, and hasn\u0026rsquo;t been demonstrated in practice so far.\nBut I digress; ultimately, attribution is hard, and glorying the fundamental concepts behind AFL is probably a waste of time. The devil is very much in the often-overlooked details, which brings us to\u0026hellip;\n2. Design goals for afl-fuzz In short, I believe that the current implementation of afl-fuzz takes care of several itches that seemed impossible to scratch with other tools:\n  Speed. It\u0026rsquo;s genuinely hard to compete with brute force when your \u0026ldquo;smart\u0026rdquo; approach is resource-intensive. If your instrumentation makes it 10x more likely to find a bug, but runs 100x slower, your users are getting a bad deal.\nTo avoid starting with a handicap, afl-fuzz is meant to let you fuzz most of the intended targets at roughly their native speed - so even if it doesn\u0026rsquo;t add value, you do not lose much.\nOn top of this, the tool leverages instrumentation to actually reduce the amount of work in a couple of ways: for example, by carefully trimming the corpus or skipping non-functional but non-trimmable regions in the input files.\n  Rock-solid reliability. It\u0026rsquo;s hard to compete with brute force if your approach is brittle and fails unexpectedly. Automated testing is attractive because it\u0026rsquo;s simple to use and scalable; anything that goes against these principles is an unwelcome trade-off and means that your tool will be used less often and with less consistent results.\nMost of the approaches based on symbolic execution, taint tracking, or complex syntax-aware instrumentation are currently fairly unreliable with real-world targets. Perhaps more importantly, their failure modes can render them strictly worse than \u0026ldquo;dumb\u0026rdquo; tools, and such degradation can be difficult for less experienced users to notice and correct.\nIn contrast, afl-fuzz is designed to be rock solid, chiefly by keeping it simple. In fact, at its core, it\u0026rsquo;s designed to be just a very good traditional fuzzer with a wide range of interesting, well-researched strategies to go by. The fancy parts just help it focus the effort in places where it matters the most.\n  Simplicity. The author of a testing framework is probably the only person who truly understands the impact of all the settings offered by the tool - and who can dial them in just right. Yet, even the most rudimentary fuzzer frameworks often come with countless knobs and fuzzing ratios that need to be guessed by the operator ahead of the time. This can do more harm than good.\nAFL is designed to avoid this as much as possible. The three knobs you can play with are the output file, the memory limit, and the ability to override the default, auto-calibrated timeout. The rest is just supposed to work. When it doesn\u0026rsquo;t, user-friendly error messages outline the probable causes and workarounds, and get you back on track right away.\n  Chainability. Most general-purpose fuzzers can\u0026rsquo;t be easily employed against resource-hungry or interaction-heavy tools, necessitating the creation of custom in-process fuzzers or the investment of massive CPU power (most of which is wasted on tasks not directly related to the code we actually want to test).\nAFL tries to scratch this itch by allowing users to use more lightweight targets (e.g., standalone image parsing libraries) to create small corpora of interesting test cases that can be fed into a manual testing process or a UI harness later on.\n  As mentioned in technical_details.md, AFL does all this not by systematically applying a single overarching CS concept, but by experimenting with a variety of small, complementary methods that were shown to reliably yields results better than chance. The use of instrumentation is a part of that toolkit, but is far from being the most important one.\nUltimately, what matters is that afl-fuzz is designed to find cool bugs - and has a pretty robust track record of doing just that.\n"});index.add({'id':11,'href':'/docs/ideas/','title':"Ideas",'content':"Ideas for afl++ In the following, we describe a variety of ideas that could be implemented for future AFL++ versions.\nFor GSOC2020 interested students please see https://github.com/AFLplusplus/AFLplusplus/issues/208\nFlexible Grammar Mutator Currently, AFL++'s mutation does not have deeper knowledge about the fuzzed binary, apart from feedback, even though the developer may have insights about the target.\nA developer may choose to provide dictionaries and implement own mutations in python or C, but an easy mutator that behaves according to a given grammar, does not exist.\nState-of-the-art research on grammar fuzzing has some problems in their implementations like code quality, scalability, or ease of use and other common issues of the academic code.\nWe aim to develop a pluggable grammar mutator for afl++ that combines various results.\nMentor: andreafioraldi\nExpand on the MOpt mutator Work on the MOpt mutator that is already in AFL++.\nThis is an excellent mutations scheduler based on Particle Swarm Optimization but the current implementation schedule only the mutations that were present on AFL.\nAFL++ added a lot of optional mutators like the Input-2-State one based on Redqueen, the Radamsa mutator, the Custom mutator (the user can define its own mutator) and the work is to generalize MOpt for all the current and future mutators.\nMentor: vanhauser-thc or andreafioraldi\nperf-fuzz Linux Kernel Module Either Port the patch to the upcoming Ubuntu LTS 20.04 default kernel and provide a qemu-kvm image or find a different userspace snapshot solution that has a good performance and is reliable, e.g. with docker. perf-fuzz The perf-fuzz kernel can be found at https://github.com/sslab-gatech/perf-fuzz There also is/was a FreeBSD project at https://github.com/veracode-research/freebsd-perf-fuzz\nThis enables snapshot fuzzing on Linux with an incredible performance!\nMentor: any Idea/Issue tracker: https://github.com/AFLplusplus/AFLplusplus/issues/248\nQEMU 4-based Instrumentation First tests to use QEMU 4 for binary-only AFL++ showed that caching behavior changed, which vastly decreases fuzzing speeds.\nThis is the cause why, right now, we cannot switch to QEMU 4.2.\nUnderstanding the current instrumentation and fixing the current caching issues will be needed.\nMentor: andreafioraldi\nWASM Instrumentation Currently, AFL++ can be used for source code fuzzing and traditional binaries. With the rise of WASM as compile target, however, a novel way of instrumentation needs to be implemented for binaries compiled to Webassembly. This can either be done by inserting instrumentation directly into the WASM AST, or by patching feedback into a WASM VMs of choice, similar to the current Unicorn instrumentation.\nMentor: any\nMachine Learning Something with machine learning, better than NEUZZ :-) Either improve a single mutator thorugh learning of many different bugs (a bug class) or gather deep insights about a single target beforehand (CFG, DFG, VFG, \u0026hellip;?) and improve performance for a single target.\nMentor: domenukk\nReengineer afl-fuzz as Thread Safe, Embeddable Library Right now, afl-fuzz is single threaded, cannot safely be embedded in tools, and not multi-threaded. It makes use of a large number of globals, must always be the parent process and exec child processes. Instead, afl-fuzz could be refactored to contain no global state and globals. This allows for different use cases that could be implemented during this project. Note that in the mean time a lot has happened here already, but e.g. making it all work and implement multithreading in afl-fuzz \u0026hellip; there is still quite some work to do.\nMentor: hexcoder- or vanhauser-thc\nCollision-free Binary-Only Maps AFL++ supports collison-free maps using an LTO (link-time-optimization) pass. This should be possible to implement for QEMU and Unicorn instrumentations. As the forkserver parent caches just in time translated translation blocks, adding a simple counter between jumps should be doable.\nNote: this is already in development for qemu by Andrea, so for people who want to contribute it might make more sense to port his solution to unicorn.\nMentor: andreafioraldi or domenukk Issue/idea tracker: https://github.com/AFLplusplus/AFLplusplus/issues/237\nYour idea! Finally, we are open to proposals! Create an issue at https://github.com/AFLplusplus/AFLplusplus/issues and let\u0026rsquo;s discuss :-)\n"});index.add({'id':12,'href':'/docs/install/','title':"I N S T a L L",'content':"Installation instructions This document provides basic installation instructions and discusses known issues for a variety of platforms. See README.md for the general instruction manual.\n1) Linux on x86  This platform is expected to work well. Compile the program with:\nmake You can start using the fuzzer without installation, but it is also possible to install it with:\nmake install There are no special dependencies to speak of; you will need GNU make and a working compiler (gcc or clang). Some of the optional scripts bundled with the program may depend on bash, gdb, and similar basic tools.\nIf you are using clang, please review llvm_mode/README.md; the LLVM integration mode can offer substantial performance gains compared to the traditional approach.\nYou may have to change several settings to get optimal results (most notably, disable crash reporting utilities and switch to a different CPU governor), but afl-fuzz will guide you through that if necessary.\nOpenBSD, FreeBSD, NetBSD on x86 Similarly to Linux, these platforms are expected to work well and are regularly tested. Compile everything with GNU make:\ngmake Note that BSD make will not work; if you do not have gmake on your system, please install it first. As on Linux, you can use the fuzzer itself without installation, or install it with:\ngmake install Keep in mind that if you are using csh as your shell, the syntax of some of the shell commands given in the README.md and other docs will be different.\nThe llvm_mode requires a dynamically linked, fully-operational installation of clang. At least on FreeBSD, the clang binaries are static and do not include some of the essential tools, so if you want to make it work, you may need to follow the instructions in llvm_mode/README.md.\nBeyond that, everything should work as advertised.\nThe QEMU mode is currently supported only on Linux. I think it\u0026rsquo;s just a QEMU problem, I couldn\u0026rsquo;t get a vanilla copy of user-mode emulation support working correctly on BSD at all.\n3. MacOS X on x86 MacOS X should work, but there are some gotchas due to the idiosyncrasies of the platform. On top of this, I have limited release testing capabilities and depend mostly on user feedback.\nTo build AFL, install Xcode and follow the general instructions for Linux.\nThe Xcode \u0026lsquo;gcc\u0026rsquo; tool is just a wrapper for clang, so be sure to use afl-clang to compile any instrumented binaries; afl-gcc will fail unless you have GCC installed from another source (in which case, please specify AFL_CC and AFL_CXX to point to the \u0026ldquo;real\u0026rdquo; GCC binaries).\nOnly 64-bit compilation will work on the platform; porting the 32-bit instrumentation would require a fair amount of work due to the way OS X handles relocations, and today, virtually all MacOS X boxes are 64-bit.\nThe crash reporting daemon that comes by default with MacOS X will cause problems with fuzzing. You need to turn it off by following the instructions provided here: http://goo.gl/CCcd5u\nThe fork() semantics on OS X are a bit unusual compared to other unix systems and definitely don\u0026rsquo;t look POSIX-compliant. This means two things:\n Fuzzing will be probably slower than on Linux. In fact, some folks report considerable performance gains by running the jobs inside a Linux VM on MacOS X. Some non-portable, platform-specific code may be incompatible with the AFL forkserver. If you run into any problems, set AFL_NO_FORKSRV=1 in the environment before starting afl-fuzz.  User emulation mode of QEMU does not appear to be supported on MacOS X, so black-box instrumentation mode (-Q) will not work.\nThe llvm_mode requires a fully-operational installation of clang. The one that comes with Xcode is missing some of the essential headers and helper tools. See llvm_mode/README.md for advice on how to build the compiler from scratch.\n4. Linux or *BSD on non-x86 systems Standard build will fail on non-x86 systems, but you should be able to leverage two other options:\n The LLVM mode (see llvm_mode/README.md), which does not rely on x86-specific assembly shims. It\u0026rsquo;s fast and robust, but requires a complete installation of clang. The QEMU mode (see qemu_mode/README.md), which can be also used for fuzzing cross-platform binaries. It\u0026rsquo;s slower and more fragile, but can be used even when you don\u0026rsquo;t have the source for the tested app.  If you\u0026rsquo;re not sure what you need, you need the LLVM mode. To get it, try:\nAFL_NO_X86=1 gmake \u0026amp;\u0026amp; gmake -C llvm_mode \u0026hellip;and compile your target program with afl-clang-fast or afl-clang-fast++ instead of the traditional afl-gcc or afl-clang wrappers.\n5. Solaris on x86 The fuzzer reportedly works on Solaris, but I have not tested this first-hand, and the user base is fairly small, so I don\u0026rsquo;t have a lot of feedback.\nTo get the ball rolling, you will need to use GNU make and GCC or clang. I\u0026rsquo;m being told that the stock version of GCC that comes with the platform does not work properly due to its reliance on a hardcoded location for \u0026lsquo;as\u0026rsquo; (completely ignoring the -B parameter or $PATH).\nTo fix this, you may want to build stock GCC from the source, like so:\n./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \\  --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr make sudo make install Do not specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that ignores the -B flag and you will be back to square one.\nNote that Solaris reportedly comes with crash reporting enabled, which causes problems with crashes being misinterpreted as hangs, similarly to the gotchas for Linux and MacOS X. AFL does not auto-detect crash reporting on this particular platform, but you may need to run the following command:\ncoreadm -d global -d global-setid -d process -d proc-setid \\  -d kzone -d log User emulation mode of QEMU is not available on Solaris, so black-box instrumentation mode (-Q) will not work.\n6. Everything else You\u0026rsquo;re on your own. On POSIX-compliant systems, you may be able to compile and run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code.\nThe fuzzer will run on Windows in WSL only. It will not work under Cygwin on in the normal Windows world. It could be ported to the latter platform fairly easily, but it\u0026rsquo;s a pretty bad idea, because Cygwin is extremely slow. It makes much more sense to use VirtualBox or so to run a hardware-accelerated Linux VM; it will run around 20x faster or so. If you have a really compelling use case for Cygwin, let me know.\nAlthough Android on x86 should theoretically work, the stock kernel may have SHM support compiled out, and if so, you may have to address that issue first. It\u0026rsquo;s possible that all you need is this workaround:\nhttps://github.com/pelya/android-shmem\nJoshua J. Drake notes that the Android linker adds a shim that automatically intercepts SIGSEGV and related signals. To fix this issue and be able to see crashes, you need to put this at the beginning of the fuzzed program:\nsignal(SIGILL, SIG_DFL); signal(SIGABRT, SIG_DFL); signal(SIGBUS, SIG_DFL); signal(SIGFPE, SIG_DFL); signal(SIGSEGV, SIG_DFL); You may need to #include \u0026lt;signal.h\u0026gt; first.\n"});index.add({'id':13,'href':'/docs/life_pro_tips/','title':"Life Pro Tips",'content':"AFL \u0026ldquo;Life Pro Tips\u0026rdquo; Bite-sized advice for those who understand the basics, but can\u0026rsquo;t be bothered to read or memorize every other piece of documentation for AFL.\nGet more bang for your buck by using fuzzing dictionaries. See dictionaries/README.md to learn how.\nYou can get the most out of your hardware by parallelizing AFL jobs. See parallel_fuzzing.md for step-by-step tips.\nImprove the odds of spotting memory corruption bugs with libdislocator.so! It\u0026rsquo;s easy. Consult libdislocator/README.md for usage tips.\nWant to understand how your target parses a particular input file? Try the bundled afl-analyze tool; it\u0026rsquo;s got colors and all!\nYou can visually monitor the progress of your fuzzing jobs. Run the bundled afl-plot utility to generate browser-friendly graphs.\nNeed to monitor AFL jobs programmatically? Check out the fuzzer_stats file in the AFL output dir or try afl-whatsup.\nPuzzled by something showing up in red or purple in the AFL UI? It could be important - consult docs/status_screen.md right away!\nKnow your target? Convert it to persistent mode for a huge performance gain! Consult section #5 in llvm_mode/README.md for tips.\nUsing clang? Check out llvm_mode/ for a faster alternative to afl-gcc!\nDid you know that AFL can fuzz closed-source or cross-platform binaries? Check out qemu_mode/README.md and unicorn_mode/README.md for more.\nDid you know that afl-fuzz can minimize any test case for you? Try the bundled afl-tmin tool - and get small repro files fast!\nNot sure if a crash is exploitable? AFL can help you figure it out. Specify -C to enable the peruvian were-rabbit mode.\nTrouble dealing with a machine uprising? Relax, we\u0026rsquo;ve all been there. Find essential survival tips at http://lcamtuf.coredump.cx/prep/.\nWant to automatically spot non-crashing memory handling bugs? Try running an AFL-generated corpus through ASAN, MSAN, or Valgrind.\nGood selection of input files is critical to a successful fuzzing job. See docs/perf_tips.md for pro tips.\nYou can improve the odds of automatically spotting stack corruption issues. Specify AFL_HARDEN=1 in the environment to enable hardening flags.\nBumping into problems with non-reproducible crashes? It happens, but usually isn\u0026rsquo;t hard to diagnose. See section #7 in README.md for tips.\nFuzzing is not just about memory corruption issues in the codebase. Add some sanity-checking assert() / abort() statements to effortlessly catch logic bugs.\nHey kid\u0026hellip; pssst\u0026hellip; want to figure out how AFL really works? Check out docs/technical_details.md for all the gory details in one place!\nThere\u0026rsquo;s a ton of third-party helper tools designed to work with AFL! Be sure to check out docs/sister_projects.md before writing your own.\nNeed to fuzz the command-line arguments of a particular program? You can find a simple solution in examples/argv_fuzzing.\nAttacking a format that uses checksums? Remove the checksum-checking code or use a postprocessor! See examples/post_library/ for more.\nDealing with a very slow target or hoping for instant results? Specify -d when calling afl-fuzz!\n"});index.add({'id':14,'href':'/docs/notes_for_asan/','title':"Notes for Asan",'content':"Notes for using ASAN with afl-fuzz This file discusses some of the caveats for fuzzing under ASAN, and suggests a handful of alternatives. See README.md for the general instruction manual.\n1) Short version ASAN on 64-bit systems requests a lot of memory in a way that can\u0026rsquo;t be easily distinguished from a misbehaving program bent on crashing your system.\nBecause of this, fuzzing with ASAN is recommended only in four scenarios:\n  On 32-bit systems, where we can always enforce a reasonable memory limit (-m 800 or so is a good starting point),\n  On 64-bit systems only if you can do one of the following:\n  Compile the binary in 32-bit mode (gcc -m32),\n  Precisely gauge memory needs using http://jwilk.net/software/recidivm .\n  Limit the memory available to process using cgroups on Linux (see examples/asan_cgroups).\n    To compile with ASAN, set AFL_USE_ASAN=1 before calling \u0026lsquo;make clean all\u0026rsquo;. The afl-gcc / afl-clang wrappers will pick that up and add the appropriate flags. Note that ASAN is incompatible with -static, so be mindful of that.\n(You can also use AFL_USE_MSAN=1 to enable MSAN instead.)\nNOTE: if you run several slaves only one should run the target compiled with ASAN (and UBSAN, CFISAN), the others should run the target with no sanitizers compiled in.\nThere is also the option of generating a corpus using a non-ASAN binary, and then feeding it to an ASAN-instrumented one to check for bugs. This is faster, and can give you somewhat comparable results. You can also try using libdislocator (see libdislocator/README.dislocator.md in the parent directory) as a lightweight and hassle-free (but less thorough) alternative.\n2) Long version ASAN allocates a huge region of virtual address space for bookkeeping purposes. Most of this is never actually accessed, so the OS never has to allocate any real pages of memory for the process, and the VM grabbed by ASAN is essentially \u0026ldquo;free\u0026rdquo; - but the mapping counts against the standard OS-enforced limit (RLIMIT_AS, aka ulimit -v).\nOn our end, afl-fuzz tries to protect you from processes that go off-rails and start consuming all the available memory in a vain attempt to parse a malformed input file. This happens surprisingly often, so enforcing such a limit is important for almost any fuzzer: the alternative is for the kernel OOM handler to step in and start killing random processes to free up resources. Needless to say, that\u0026rsquo;s not a very nice prospect to live with.\nUnfortunately, un*x systems offer no portable way to limit the amount of pages actually given to a process in a way that distinguishes between that and the harmless \u0026ldquo;land grab\u0026rdquo; done by ASAN. In principle, there are three standard ways to limit the size of the heap:\n  The RLIMIT_AS mechanism (ulimit -v) caps the size of the virtual space - but as noted, this pays no attention to the number of pages actually in use by the process, and doesn\u0026rsquo;t help us here.\n  The RLIMIT_DATA mechanism (ulimit -d) seems like a good fit, but it applies only to the traditional sbrk() / brk() methods of requesting heap space; modern allocators, including the one in glibc, routinely rely on mmap() instead, and circumvent this limit completely.\n  Finally, the RLIMIT_RSS limit (ulimit -m) sounds like what we need, but doesn\u0026rsquo;t work on Linux - mostly because nobody felt like implementing it.\n  There are also cgroups, but they are Linux-specific, not universally available even on Linux systems, and they require root permissions to set up; I\u0026rsquo;m a bit hesitant to make afl-fuzz require root permissions just for that. That said, if you are on Linux and want to use cgroups, check out the contributed script that ships in examples/asan_cgroups/.\nIn settings where cgroups aren\u0026rsquo;t available, we have no nice, portable way to avoid counting the ASAN allocation toward the limit. On 32-bit systems, or for binaries compiled in 32-bit mode (-m32), this is not a big deal: ASAN needs around 600-800 MB or so, depending on the compiler - so all you need to do is to specify -m that is a bit higher than that.\nOn 64-bit systems, the situation is more murky, because the ASAN allocation is completely outlandish - around 17.5 TB in older versions, and closer to 20 TB with newest ones. The actual amount of memory on your system is (probably!) just a tiny fraction of that - so unless you dial the limit with surgical precision, you will get no protection from OOM bugs.\nOn my system, the amount of memory grabbed by ASAN with a slightly older version of gcc is around 17,825,850 MB; for newest clang, it\u0026rsquo;s 20,971,600. But there is no guarantee that these numbers are stable, and if you get them wrong by \u0026ldquo;just\u0026rdquo; a couple gigs or so, you will be at risk.\nTo get the precise number, you can use the recidivm tool developed by Jakub Wilk (http://jwilk.net/software/recidivm). In absence of this, ASAN is not recommended when fuzzing 64-bit binaries, unless you are confident that they are robust and enforce reasonable memory limits (in which case, you can specify \u0026lsquo;-m none\u0026rsquo; when calling afl-fuzz).\nUsing recidivm or running with no limits aside, there are two other decent alternatives: build a corpus of test cases using a non-ASAN binary, and then examine them with ASAN, Valgrind, or other heavy-duty tools in a more controlled setting; or compile the target program with -m32 (32-bit mode) if your system supports that.\n3) Interactions with the QEMU mode ASAN, MSAN, and other sanitizers appear to be incompatible with QEMU user emulation, so please do not try to use them with the -Q option; QEMU doesn\u0026rsquo;t seem to appreciate the shadow VM trick used by these tools, and will likely just allocate all your physical memory, then crash.\nYou can, however, use QASan to run binaries that are not instrumented with ASan under QEMU with the AFL++ instrumentation.\nhttps://github.com/andreafioraldi/qasan\n4) ASAN and OOM crashes By default, ASAN treats memory allocation failures as fatal errors, immediately causing the program to crash. Since this is a departure from normal POSIX semantics (and creates the appearance of security issues in otherwise properly-behaving programs), we try to disable this by specifying allocator_may_return_null=1 in ASAN_OPTIONS.\nUnfortunately, it\u0026rsquo;s been reported that this setting still causes ASAN to trigger phantom crashes in situations where the standard allocator would simply return NULL. If this is interfering with your fuzzing jobs, you may want to cc: yourself on this bug:\nhttps://bugs.llvm.org/show_bug.cgi?id=22026\n5) What about UBSAN? New versions of UndefinedBehaviorSanitizer offers the -fsanitize=undefined-trap-on-error compiler flag that tells UBSan to insert an istruction that will cause SIGILL (ud2 on x86) when an undefined behaviour is detected. This is the option that you want to use when combining AFL++ and UBSan.\nAFL_USE_UBSAN=1 env var will add this compiler flag to afl-clang-fast, afl-gcc-fast and afl-gcc for you.\nOld versions of UBSAN don\u0026rsquo;t offer a consistent way to abort() on fault conditions or to terminate with a distinctive exit code but there are some versions of the library can be binary-patched to address this issue. You can also preload a shared library that substitute all the UBSan routines used to report errors with abort().\n"});index.add({'id':15,'href':'/docs/parallel_fuzzing/','title':"Parallel Fuzzing",'content':"Tips for parallel fuzzing This document talks about synchronizing afl-fuzz jobs on a single machine or across a fleet of systems. See README.md for the general instruction manual.\n1) Introduction Every copy of afl-fuzz will take up one CPU core. This means that on an n-core system, you can almost always run around n concurrent fuzzing jobs with virtually no performance hit (you can use the afl-gotcpu tool to make sure).\nIn fact, if you rely on just a single job on a multi-core system, you will be underutilizing the hardware. So, parallelization is usually the right way to go.\nWhen targeting multiple unrelated binaries or using the tool in \u0026ldquo;dumb\u0026rdquo; (-n) mode, it is perfectly fine to just start up several fully separate instances of afl-fuzz. The picture gets more complicated when you want to have multiple fuzzers hammering a common target: if a hard-to-hit but interesting test case is synthesized by one fuzzer, the remaining instances will not be able to use that input to guide their work.\nTo help with this problem, afl-fuzz offers a simple way to synchronize test cases on the fly.\nNote that afl++ has AFLfast\u0026rsquo;s power schedules implemented. It is therefore a good idea to use different power schedules if you run several instances in parallel. See power_schedules.md\nAlternatively running other AFL spinoffs in parallel can be of value, e.g. Angora (https://github.com/AngoraFuzzer/Angora/)\n2) Single-system parallelization If you wish to parallelize a single job across multiple cores on a local system, simply create a new, empty output directory (\u0026ldquo;sync dir\u0026rdquo;) that will be shared by all the instances of afl-fuzz; and then come up with a naming scheme for every instance - say, \u0026ldquo;fuzzer01\u0026rdquo;, \u0026ldquo;fuzzer02\u0026rdquo;, etc.\nRun the first one (\u0026ldquo;master\u0026rdquo;, -M) like this:\n$ ./afl-fuzz -i testcase_dir -o sync_dir -M fuzzer01 [...other stuff...] \u0026hellip;and then, start up secondary (-S) instances like this:\n$ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer02 [...other stuff...] $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer03 [...other stuff...] Each fuzzer will keep its state in a separate subdirectory, like so:\n/path/to/sync_dir/fuzzer01/\nEach instance will also periodically rescan the top-level sync directory for any test cases found by other fuzzers - and will incorporate them into its own fuzzing when they are deemed interesting enough.\nThe difference between the -M and -S modes is that the master instance will still perform deterministic checks; while the secondary instances will proceed straight to random tweaks. If you don\u0026rsquo;t want to do deterministic fuzzing at all, it\u0026rsquo;s OK to run all instances with -S. With very slow or complex targets, or when running heavily parallelized jobs, this is usually a good plan.\nNote that running multiple -M instances is wasteful, although there is an experimental support for parallelizing the deterministic checks. To leverage that, you need to create -M instances like so:\n$ ./afl-fuzz -i testcase_dir -o sync_dir -M masterA:1/3 [...] $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterB:2/3 [...] $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterC:3/3 [...] \u0026hellip;where the first value after \u0026lsquo;:\u0026rsquo; is the sequential ID of a particular master instance (starting at 1), and the second value is the total number of fuzzers to distribute the deterministic fuzzing across. Note that if you boot up fewer fuzzers than indicated by the second number passed to -M, you may end up with poor coverage.\nYou can also monitor the progress of your jobs from the command line with the provided afl-whatsup tool. When the instances are no longer finding new paths, it\u0026rsquo;s probably time to stop.\nWARNING: Exercise caution when explicitly specifying the -f option. Each fuzzer must use a separate temporary file; otherwise, things will go south. One safe example may be:\n$ ./afl-fuzz [...] -S fuzzer10 -f file10.txt ./fuzzed/binary @@ $ ./afl-fuzz [...] -S fuzzer11 -f file11.txt ./fuzzed/binary @@ $ ./afl-fuzz [...] -S fuzzer12 -f file12.txt ./fuzzed/binary @@ This is not a concern if you use @@ without -f and let afl-fuzz come up with the file name.\n3) Multi-system parallelization The basic operating principle for multi-system parallelization is similar to the mechanism explained in section 2. The key difference is that you need to write a simple script that performs two actions:\n  Uses SSH with authorized_keys to connect to every machine and retrieve a tar archive of the /path/to/sync_dir/\u0026lt;fuzzer_id\u0026gt;/queue/ directories for every \u0026lt;fuzzer_id\u0026gt; local to the machine. It\u0026rsquo;s best to use a naming scheme that includes host name in the fuzzer ID, so that you can do something like:\nfor s in {1..10}; do ssh user@host${s} \u0026#34;tar -czf - sync/host${s}_fuzzid*/[qf]*\u0026#34; \u0026gt;host${s}.tgz done   Distributes and unpacks these files on all the remaining machines, e.g.:\nfor s in {1..10}; do for d in {1..10}; do test \u0026#34;$s\u0026#34; = \u0026#34;$d\u0026#34; \u0026amp;\u0026amp; continue ssh user@host${d} \u0026#39;tar -kxzf -\u0026#39; \u0026lt;host${s}.tgz done done   There is an example of such a script in examples/distributed_fuzzing/; you can also find a more featured, experimental tool developed by Martijn Bogaard at:\nhttps://github.com/MartijnB/disfuzz-afl\nAnother client-server implementation from Richo Healey is:\nhttps://github.com/richo/roving\nNote that these third-party tools are unsafe to run on systems exposed to the Internet or to untrusted users.\nWhen developing custom test case sync code, there are several optimizations to keep in mind:\n  The synchronization does not have to happen very often; running the task every 30 minutes or so may be perfectly fine.\n  There is no need to synchronize crashes/ or hangs/; you only need to copy over queue/* (and ideally, also fuzzer_stats).\n  It is not necessary (and not advisable!) to overwrite existing files; the -k option in tar is a good way to avoid that.\n  There is no need to fetch directories for fuzzers that are not running locally on a particular machine, and were simply copied over onto that system during earlier runs.\n  For large fleets, you will want to consolidate tarballs for each host, as this will let you use n SSH connections for sync, rather than n*(n-1).\nYou may also want to implement staged synchronization. For example, you could have 10 groups of systems, with group 1 pushing test cases only to group 2; group 2 pushing them only to group 3; and so on, with group eventually 10 feeding back to group 1.\nThis arrangement would allow test interesting cases to propagate across the fleet without having to copy every fuzzer queue to every single host.\n  You do not want a \u0026ldquo;master\u0026rdquo; instance of afl-fuzz on every system; you should run them all with -S, and just designate a single process somewhere within the fleet to run with -M.\n  It is not advisable to skip the synchronization script and run the fuzzers directly on a network filesystem; unexpected latency and unkillable processes in I/O wait state can mess things up.\n4) Remote monitoring and data collection You can use screen, nohup, tmux, or something equivalent to run remote instances of afl-fuzz. If you redirect the program\u0026rsquo;s output to a file, it will automatically switch from a fancy UI to more limited status reports. There is also basic machine-readable information always written to the fuzzer_stats file in the output directory. Locally, that information can be interpreted with afl-whatsup.\nIn principle, you can use the status screen of the master (-M) instance to monitor the overall fuzzing progress and decide when to stop. In this mode, the most important signal is just that no new paths are being found for a longer while. If you do not have a master instance, just pick any single secondary instance to watch and go by that.\nYou can also rely on that instance\u0026rsquo;s output directory to collect the synthesized corpus that covers all the noteworthy paths discovered anywhere within the fleet. Secondary (-S) instances do not require any special monitoring, other than just making sure that they are up.\nKeep in mind that crashing inputs are not automatically propagated to the master instance, so you may still want to monitor for crashes fleet-wide from within your synchronization or health checking scripts (see afl-whatsup).\n5) Asymmetric setups It is perhaps worth noting that all of the following is permitted:\n  Running afl-fuzz with conjunction with other guided tools that can extend coverage (e.g., via concolic execution). Third-party tools simply need to follow the protocol described above for pulling new test cases from out_dir/\u0026lt;fuzzer_id\u0026gt;/queue/* and writing their own finds to sequentially numbered id:nnnnnn files in out_dir/\u0026lt;ext_tool_id\u0026gt;/queue/*.\n  Running some of the synchronized fuzzers with different (but related) target binaries. For example, simultaneously stress-testing several different JPEG parsers (say, IJG jpeg and libjpeg-turbo) while sharing the discovered test cases can have synergistic effects and improve the overall coverage.\n(In this case, running one -M instance per each binary is a good plan.)\n  Having some of the fuzzers invoke the binary in different ways. For example, \u0026lsquo;djpeg\u0026rsquo; supports several DCT modes, configurable with a command-line flag, while \u0026lsquo;dwebp\u0026rsquo; supports incremental and one-shot decoding. In some scenarios, going after multiple distinct modes and then pooling test cases will improve coverage.\n  Much less convincingly, running the synchronized fuzzers with different starting test cases (e.g., progressive and standard JPEG) or dictionaries. The synchronization mechanism ensures that the test sets will get fairly homogeneous over time, but it introduces some initial variability.\n  "});index.add({'id':16,'href':'/docs/patches/','title':"P a T C H E S",'content':"Applied Patches The following patches from https://github.com/vanhauser-thc/afl-patches have been installed or not installed:\nINSTALLED afl-llvm-fix.diff\tby kcwu(at)csie(dot)org afl-sort-all_uniq-fix.diff\tby legarrec(dot)vincent(at)gmail(dot)com laf-intel.diff\tby heiko(dot)eissfeldt(at)hexco(dot)de afl-llvm-optimize.diff\tby mh(at)mh-sec(dot)de afl-fuzz-tmpdir.diff\tby mh(at)mh-sec(dot)de afl-fuzz-79x24.diff\tby heiko(dot)eissfeldt(at)hexco(dot)de afl-fuzz-fileextensionopt.diff\ttbd afl-as-AFL_INST_RATIO.diff\tby legarrec(dot)vincent(at)gmail(dot)com afl-qemu-ppc64.diff\tby william(dot)barsse(at)airbus(dot)com afl-qemu-optimize-entrypoint.diff\tby mh(at)mh-sec(dot)de afl-qemu-speed.diff\tby abiondo on github afl-qemu-optimize-map.diff\tby mh(at)mh-sec(dot)de  llvm_mode ngram prev_loc coverage (github.com/adrianherrera/afl-ngram-pass) Custom mutator (native library) (by kyakdan) unicorn_mode (modernized and updated by domenukk) instrim (https://github.com/csienslab/instrim) was integrated MOpt (github.com/puppet-meteor/MOpt-AFL) was imported AFLfast additions (github.com/mboehme/aflfast) were incorporated. Qemu 3.1 upgrade with enhancement patches (github.com/andreafioraldi/afl) Python mutator modules support (github.com/choller/afl) Whitelisting in LLVM mode (github.com/choller/afl) forkserver patch for afl-tmin (github.com/nccgroup/TriforceAFL)  NOT INSTALLED afl-fuzz-context_sensitive.diff\t- changes too much of the behaviour afl-tmpfs.diff - same as afl-fuzz-tmpdir.diff but more complex afl-cmin-reduce-dataset.diff - unsure of the impact afl-llvm-fix2.diff - not needed with the other patches "});index.add({'id':17,'href':'/docs/perf_tips/','title':"Perf Tips",'content':"Tips for performance optimization This file provides tips for troubleshooting slow or wasteful fuzzing jobs. See README.md for the general instruction manual.\n1. Keep your test cases small This is probably the single most important step to take! Large test cases do not merely take more time and memory to be parsed by the tested binary, but also make the fuzzing process dramatically less efficient in several other ways.\nTo illustrate, let\u0026rsquo;s say that you\u0026rsquo;re randomly flipping bits in a file, one bit at a time. Let\u0026rsquo;s assume that if you flip bit #47, you will hit a security bug; flipping any other bit just results in an invalid document.\nNow, if your starting test case is 100 bytes long, you will have a 71% chance of triggering the bug within the first 1,000 execs - not bad! But if the test case is 1 kB long, the probability that we will randomly hit the right pattern in the same timeframe goes down to 11%. And if it has 10 kB of non-essential cruft, the odds plunge to 1%.\nOn top of that, with larger inputs, the binary may be now running 5-10x times slower than before - so the overall drop in fuzzing efficiency may be easily as high as 500x or so.\nIn practice, this means that you shouldn\u0026rsquo;t fuzz image parsers with your vacation photos. Generate a tiny 16x16 picture instead, and run it through jpegtran or pngcrunch for good measure. The same goes for most other types of documents.\nThere\u0026rsquo;s plenty of small starting test cases in ../testcases/ - try them out or submit new ones!\nIf you want to start with a larger, third-party corpus, run afl-cmin with an aggressive timeout on that data set first.\n2. Use a simpler target Consider using a simpler target binary in your fuzzing work. For example, for image formats, bundled utilities such as djpeg, readpng, or gifhisto are considerably (10-20x) faster than the convert tool from ImageMagick - all while exercising roughly the same library-level image parsing code.\nEven if you don\u0026rsquo;t have a lightweight harness for a particular target, remember that you can always use another, related library to generate a corpus that will be then manually fed to a more resource-hungry program later on.\nAlso note that reading the fuzzing input via stdin is faster than reading from a file.\n3. Use LLVM instrumentation When fuzzing slow targets, you can gain 20-100% performance improvement by using the LLVM-based instrumentation mode described in the llvm_mode README. Note that this mode requires the use of clang and will not work with GCC.\nThe LLVM mode also offers a \u0026ldquo;persistent\u0026rdquo;, in-process fuzzing mode that can work well for certain types of self-contained libraries, and for fast targets, can offer performance gains up to 5-10x; and a \u0026ldquo;deferred fork server\u0026rdquo; mode that can offer huge benefits for programs with high startup overhead. Both modes require you to edit the source code of the fuzzed program, but the changes often amount to just strategically placing a single line or two.\nIf there are important data comparisons performed (e.g. strcmp(ptr, MAGIC_HDR)) then using laf-intel (see llvm_mode/README.laf-intel.md) will help afl-fuzz a lot to get to the important parts in the code.\nIf you are only interested in specific parts of the code being fuzzed, you can whitelist the files that are actually relevant. This improves the speed and accuracy of afl. See llvm_mode/README.whitelist.md\nAlso use the InsTrim mode on larger binaries, this improves performance and coverage a lot.\n4. Profile and optimize the binary Check for any parameters or settings that obviously improve performance. For example, the djpeg utility that comes with IJG jpeg and libjpeg-turbo can be called with:\n-dct fast -nosmooth -onepass -dither none -scale 1/4 \u0026hellip;and that will speed things up. There is a corresponding drop in the quality of decoded images, but it\u0026rsquo;s probably not something you care about.\nIn some programs, it is possible to disable output altogether, or at least use an output format that is computationally inexpensive. For example, with image transcoding tools, converting to a BMP file will be a lot faster than to PNG.\nWith some laid-back parsers, enabling \u0026ldquo;strict\u0026rdquo; mode (i.e., bailing out after first error) may result in smaller files and improved run time without sacrificing coverage; for example, for sqlite, you may want to specify -bail.\nIf the program is still too slow, you can use strace -tt or an equivalent profiling tool to see if the targeted binary is doing anything silly. Sometimes, you can speed things up simply by specifying /dev/null as the config file, or disabling some compile-time features that aren\u0026rsquo;t really needed for the job (try ./configure --help). One of the notoriously resource-consuming things would be calling other utilities via exec*(), popen(), system(), or equivalent calls; for example, tar can invoke external decompression tools when it decides that the input file is a compressed archive.\nSome programs may also intentionally call sleep(), usleep(), or nanosleep(); vim is a good example of that. Other programs may attempt fsync() and so on. There are third-party libraries that make it easy to get rid of such code, e.g.:\nhttps://launchpad.net/libeatmydata\nIn programs that are slow due to unavoidable initialization overhead, you may want to try the LLVM deferred forkserver mode (see llvm_mode/README.md), which can give you speed gains up to 10x, as mentioned above.\nLast but not least, if you are using ASAN and the performance is unacceptable, consider turning it off for now, and manually examining the generated corpus with an ASAN-enabled binary later on.\n5. Instrument just what you need Instrument just the libraries you actually want to stress-test right now, one at a time. Let the program use system-wide, non-instrumented libraries for any functionality you don\u0026rsquo;t actually want to fuzz. For example, in most cases, it doesn\u0026rsquo;t make to instrument libgmp just because you\u0026rsquo;re testing a crypto app that relies on it for bignum math.\nBeware of programs that come with oddball third-party libraries bundled with their source code (Spidermonkey is a good example of this). Check ./configure options to use non-instrumented system-wide copies instead.\n6. Parallelize your fuzzers The fuzzer is designed to need ~1 core per job. This means that on a, say, 4-core system, you can easily run four parallel fuzzing jobs with relatively little performance hit. For tips on how to do that, see parallel_fuzzing.md.\nThe afl-gotcpu utility can help you understand if you still have idle CPU capacity on your system. (It won\u0026rsquo;t tell you about memory bandwidth, cache misses, or similar factors, but they are less likely to be a concern.)\n7. Keep memory use and timeouts in check If you have increased the -m or -t limits more than truly necessary, consider dialing them back down.\nFor programs that are nominally very fast, but get sluggish for some inputs, you can also try setting -t values that are more punishing than what afl-fuzz dares to use on its own. On fast and idle machines, going down to -t 5 may be a viable plan.\nThe -m parameter is worth looking at, too. Some programs can end up spending a fair amount of time allocating and initializing megabytes of memory when presented with pathological inputs. Low -m values can make them give up sooner and not waste CPU time.\n8. Check OS configuration There are several OS-level factors that may affect fuzzing speed:\n If you have no risk of power loss then run your fuzzing on a tmpfs partition. This increases the performance noticably. Alternatively you can use AFL_TMPDIR to point to a tmpfs location to just write the input file to a tmpfs. High system load. Use idle machines where possible. Kill any non-essential CPU hogs (idle browser windows, media players, complex screensavers, etc). Network filesystems, either used for fuzzer input / output, or accessed by the fuzzed binary to read configuration files (pay special attention to the home directory - many programs search it for dot-files). On-demand CPU scaling. The Linux ondemand governor performs its analysis on a particular schedule and is known to underestimate the needs of short-lived processes spawned by afl-fuzz (or any other fuzzer). On Linux, this can be fixed with:  cd /sys/devices/system/cpu echo performance | tee cpu*/cpufreq/scaling_governor On other systems, the impact of CPU scaling will be different; when fuzzing, use OS-specific tools to find out if all cores are running at full speed.   Transparent huge pages. Some allocators, such as jemalloc, can incur a heavy fuzzing penalty when transparent huge pages (THP) are enabled in the kernel. You can disable this via:  echo never \u0026gt; /sys/kernel/mm/transparent_hugepage/enabled  Suboptimal scheduling strategies. The significance of this will vary from one target to another, but on Linux, you may want to make sure that the following options are set:  echo 1 \u0026gt;/proc/sys/kernel/sched_child_runs_first echo 1 \u0026gt;/proc/sys/kernel/sched_autogroup_enabled Setting a different scheduling policy for the fuzzer process - say `SCHED_RR` - can usually speed things up, too, but needs to be done with care.   Use the afl-system-config script to set all proc/sys settings above in one go. Disable all the spectre, meltdown etc. security countermeasures in the kernel if your machine is properly separated:  ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off spectre_v2=off stf_barrier=off In most Linux distributions you can put this into a `/etc/default/grub` variable.  9. If all other options fail, use -d For programs that are genuinely slow, in cases where you really can\u0026rsquo;t escape using huge input files, or when you simply want to get quick and dirty results early on, you can always resort to the -d mode.\nThe mode causes afl-fuzz to skip all the deterministic fuzzing steps, which makes output a lot less neat and can ultimately make the testing a bit less in-depth, but it will give you an experience more familiar from other fuzzing tools.\n"});index.add({'id':18,'href':'/docs/power_schedules/','title':"Power Schedules",'content':"afl++'s power schedules based on AFLfast Power schedules implemented by Marcel Böhme \u0026lt;marcel.boehme@acm.org\u0026gt;. AFLFast is an extension of AFL which is written and maintained by Michal Zalewski \u0026lt;lcamtuf@google.com\u0026gt;.\nAFLfast has helped in the success of Team Codejitsu at the finals of the DARPA Cyber Grand Challenge where their bot Galactica took 2nd place in terms of #POVs proven (see red bar at https://www.cybergrandchallenge.com/event#results). AFLFast exposed several previously unreported CVEs that could not be exposed by AFL in 24 hours and otherwise exposed vulnerabilities significantly faster than AFL while generating orders of magnitude more unique crashes.\nEssentially, we observed that most generated inputs exercise the same few \u0026ldquo;high-frequency\u0026rdquo; paths and developed strategies to gravitate towards low-frequency paths, to stress significantly more program behavior in the same amount of time. We devised several search strategies that decide in which order the seeds should be fuzzed and power schedules that smartly regulate the number of inputs generated from a seed (i.e., the time spent fuzzing a seed). We call the number of inputs generated from a seed, the seed\u0026rsquo;s energy.\nWe find that AFL\u0026rsquo;s exploitation-based constant schedule assigns too much energy to seeds exercising high-frequency paths (e.g., paths that reject invalid inputs) and not enough energy to seeds exercising low-frequency paths (e.g., paths that stress interesting behaviors). Technically, we modified the computation of a seed\u0026rsquo;s performance score (calculate_score), which seed is marked as favourite (update_bitmap_score), and which seed is chosen next from the circular queue (main). We implemented the following schedules (in the order of their effectiveness, best first):\n   AFL flag Power Schedule     -p explore (default)    -p fast    -p coe    -p quad    -p lin    -p exploit (AFL)    -p mmopt Experimental: explore with no weighting to runtime and increased weighting on the last 5 queue entries   -p rare Experimental: rare puts focus on queue entries that hit rare edges   where α(i) is the performance score that AFL uses to compute for the seed input i, β(i)\u0026gt;1 is a constant, s(i) is the number of times that seed i has been chosen from the queue, f(i) is the number of generated inputs that exercise the same path as seed i, and μ is the average number of generated inputs exercising a path.     More details can be found in the paper that was accepted at the 23rd ACM Conference on Computer and Communications Security (CCS\u0026rsquo;16).\nPS: In parallel mode (several instances with shared queue), we suggest to run the master using the exploit schedule (-p exploit) and the slaves with a combination of cut-off-exponential (-p coe), exponential (-p fast; default), and explore (-p explore) schedules. In single mode, the default settings will do. EDIT: In parallel mode, AFLFast seems to perform poorly because the path probability estimates are incorrect for the imported seeds. Pull requests to fix this issue by syncing the estimates accross instances are appreciated :)\nCopyright 2013, 2014, 2015, 2016 Google Inc. All rights reserved. Released under terms and conditions of Apache License, Version 2.0.\n"});index.add({'id':19,'href':'/docs/python_mutators/','title':"Python Mutators",'content':"Adding custom mutators to AFL using Python modules This file describes how you can utilize the external Python API to write your own custom mutation routines.\nNote: This feature is highly experimental. Use at your own risk.\nImplemented by Christian Holler (:decoder) choller@mozilla.com.\nNOTE: Only cPython 2.7, 3.7 and above are supported, although others may work. Depending on with which version afl-fuzz was compiled against, you must use python2 or python3 syntax in your scripts! After a major version upgrade (e.g. 3.7 -\u0026gt; 3.8), a recompilation of afl-fuzz may be needed.\nFor an example and a template see ../examples/python_mutators/\n1) Description and purpose While AFLFuzz comes with a good selection of generic deterministic and non-deterministic mutation operations, it sometimes might make sense to extend these to implement strategies more specific to the target you are fuzzing.\nFor simplicity and in order to allow people without C knowledge to extend AFLFuzz, I implemented a \u0026ldquo;Python\u0026rdquo; stage that can make use of an external module (written in Python) that implements a custom mutation stage.\nThe main motivation behind this is to lower the barrier for people experimenting with this tool. Hopefully, someone will be able to do useful things with this extension.\nIf you find it useful, have questions or need additional features added to the interface, feel free to send a mail to choller@mozilla.com.\nSee the following information to get a better pictures: https://www.agarri.fr/docs/XML_Fuzzing-NullCon2017-PUBLIC.pdf https://bugs.chromium.org/p/chromium/issues/detail?id=930663\n2) How the Python module looks like You can find a simple example in pymodules/example.py including documentation explaining each function. In the same directory, you can find another simple module that performs simple mutations.\nRight now, \u0026ldquo;init\u0026rdquo; is called at program startup and can be used to perform any kinds of one-time initializations while \u0026ldquo;fuzz\u0026rdquo; is called each time a mutation is requested.\nThere is also optional support for a trimming API, see the section below for further information about this feature.\n3) How to compile AFLFuzz with Python support You must install the python 3 or 2 development package of your Linux distribution before this will work. On Debian/Ubuntu/Kali this can be done with either: apt install python3-dev or apt install python-dev Note that for some distributions you might also need the package python[23]-apt\nA prerequisite for using this mode is to compile AFLFuzz with Python support.\nThe AFL++ Makefile detects Python 3 and 2 through python-config if is is in the PATH and compiles afl-fuzz with the feature if available.\nIn case your setup is different set the necessary variables like this: PYTHON_INCLUDE=/path/to/python/include LDFLAGS=-L/path/to/python/lib make\n4) How to run AFLFuzz with your custom module You must pass the module name inside the env variable AFL_PYTHON_MODULE.\nIn addition, if you are trying to load the module from the local directory, you must adjust your PYTHONPATH to reflect this circumstance. The following command should work if you are inside the aflfuzz directory:\n$ AFL_PYTHON_MODULE=\u0026quot;pymodules.test\u0026rdquo; PYTHONPATH=. ./afl-fuzz\nOptionally, the following environment variables are supported:\nAFL_PYTHON_ONLY - Disable all other mutation stages. This can prevent broken testcases (those that your Python module can\u0026rsquo;t work with anymore) to fill up your queue. Best combined with a custom trimming routine (see below) because trimming can cause the same test breakage like havoc and splice.\nAFL_DEBUG - When combined with AFL_NO_UI, this causes the C trimming code to emit additional messages about the performance and actions of your custom Python trimmer. Use this to see if it works :)\n5) Order and statistics The Python stage is set to be the first non-deterministic stage (right before the havoc stage). In the statistics however, it shows up as the third number under \u0026ldquo;havoc\u0026rdquo;. That\u0026rsquo;s because I\u0026rsquo;m lazy and I didn\u0026rsquo;t want to mess with the UI too much ;)\n6) Trimming support The generic trimming routines implemented in AFLFuzz can easily destroy the structure of complex formats, possibly leading to a point where you have a lot of testcases in the queue that your Python module cannot process anymore but your target application still accepts. This is especially the case when your target can process a part of the input (causing coverage) and then errors out on the remaining input.\nIn such cases, it makes sense to implement a custom trimming routine in Python. The API consists of multiple methods because after each trimming step, we have to go back into the C code to check if the coverage bitmap is still the same for the trimmed input. Here\u0026rsquo;s a quick API description:\ninit_trim: This method is called at the start of each trimming operation and receives the initial buffer. It should return the amount of iteration steps possible on this input (e.g. if your input has n elements and you want to remove them one by one, return n, if you do a binary search, return log(n), and so on\u0026hellip;).\n If your trimming algorithm doesn't allow you to determine the amount of (remaining) steps easily (esp. while running), then you can alternatively return 1 here and always return 0 in post_trim until you are finished and no steps remain. In that case, returning 1 in post_trim will end the trimming routine. The whole current index/max iterations stuff is only used to show progress.  trim: This method is called for each trimming operation. It doesn\u0026rsquo;t have any arguments because we already have the initial buffer from init_trim and we can memorize the current state in global variables. This can also save reparsing steps for each iteration. It should return the trimmed input buffer, where the returned data must not exceed the initial input data in length. Returning anything that is larger than the original data (passed to init_trim) will result in a fatal abort of AFLFuzz.\npost_trim: This method is called after each trim operation to inform you if your trimming step was successful or not (in terms of coverage). If you receive a failure here, you should reset your input to the last known good state. In any case, this method must return the next trim iteration index (from 0 to the maximum amount of steps you returned in init_trim).\nOmitting any of the methods will cause Python trimming to be disabled and trigger a fallback to the builtin default trimming routine.\n"});index.add({'id':20,'href':'/docs/quickstartguide/','title':"Quick Start Guide",'content':"AFL quick start guide You should read README.md - it\u0026rsquo;s pretty short. If you really can\u0026rsquo;t, here\u0026rsquo;s how to hit the ground running:\n  Compile AFL with \u0026lsquo;make\u0026rsquo;. If build fails, see INSTALL.md for tips.\n  Find or write a reasonably fast and simple program that takes data from a file or stdin, processes it in a test-worthy way, then exits cleanly. If testing a network service, modify it to run in the foreground and read from stdin. When fuzzing a format that uses checksums, comment out the checksum verification code, too. If this is not possible (e.g. in -Q(emu) mode) then use AFL_POST_LIBRARY to calculate the values with your own library.\nThe program must crash properly when a fault is encountered. Watch out for custom SIGSEGV or SIGABRT handlers and background processes. For tips on detecting non-crashing flaws, see section 11 in README.md .\n  Compile the program / library to be fuzzed using afl-gcc. A common way to do this would be:\nCC=/path/to/afl-gcc CXX=/path/to/afl-g++ ./configure \u0026ndash;disable-shared make clean all\nIf program build fails, ping afl-users@googlegroups.com.\n  Get a small but valid input file that makes sense to the program. When fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described in dictionaries/README.md, too.\n  If the program reads from stdin, run \u0026lsquo;afl-fuzz\u0026rsquo; like so:\n./afl-fuzz -i testcase_dir -o findings_dir \u0026ndash;\n/path/to/tested/program [\u0026hellip;program\u0026rsquo;s cmdline\u0026hellip;]\nIf the program takes input from a file, you can put @@ in the program\u0026rsquo;s command line; AFL will put an auto-generated file name in there for you.\n  Investigate anything shown in red in the fuzzer UI by promptly consulting status_screen.md.\n  compile and use llvm_mode (afl-clang-fast/afl-clang-fast++) as it is way faster and has a few cool features\n  There is a basic docker build with \u0026lsquo;docker build -t aflplusplus .\u0026rsquo;\n  That\u0026rsquo;s it. Sit back, relax, and - time permitting - try to skim through the following files:\n README.md - A general introduction to AFL, docs/perf_tips.md - Simple tips on how to fuzz more quickly, docs/status_screen.md - An explanation of the tidbits shown in the UI, docs/parallel_fuzzing.md - Advice on running AFL on multiple cores.  "});index.add({'id':21,'href':'/docs/readme/','title':"R E a D M E",'content':"american fuzzy lop plus plus (afl++) Release Version: 2.60c\nGithub Version: 2.60d\nincludes all necessary/interesting changes from Google\u0026rsquo;s afl 2.56b\nOriginally developed by Michal \u0026ldquo;lcamtuf\u0026rdquo; Zalewski.\nRepository: https://github.com/AFLplusplus/AFLplusplus\nafl++ is maintained by Marc \u0026ldquo;van Hauser\u0026rdquo; Heuse mh@mh-sec.de, Heiko \u0026ldquo;hexcoder-\u0026rdquo; Eißfeldt heiko.eissfeldt@hexco.de, Andrea Fioraldi andreafioraldi@gmail.com and Dominik Maier mail@dmnk.co.\nNote that although afl now has a Google afl repository https://github.com/Google/afl, it is unlikely to receive any noteable enhancements: https://twitter.com/Dor3s/status/1154737061787660288\nThe enhancements compared to the original stock afl Many improvements were made over the official afl release - which did not get any feature improvements since November 2017.\nAmong other changes afl++ has a more performant llvm_mode, supports llvm up to version 11, QEMU 3.1, more speed and crashfixes for QEMU, better *BSD and Android support and much, much more.\nAdditionally the following features and patches have been integrated:\n  AFLfast\u0026rsquo;s power schedules by Marcel Böhme: https://github.com/mboehme/aflfast\n  The new excellent MOpt mutator: https://github.com/puppet-meteor/MOpt-AFL\n  InsTrim, a very effective CFG llvm_mode instrumentation implementation for large targets: https://github.com/csienslab/instrim\n  C. Holler\u0026rsquo;s afl-fuzz Python mutator module and llvm_mode whitelist support: https://github.com/choller/afl\n  Custom mutator by a library (instead of Python) by kyakdan\n  unicorn_mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk)\n  laf-intel or CompCov support for llvm_mode, qemu_mode and unicorn_mode\n  NeverZero patch for afl-gcc, llvm_mode, qemu_mode and unicorn_mode which prevents a wrapping map value to zero, increases coverage\n  Persistent mode and deferred forkserver for qemu_mode\n  Win32 PE binary-only fuzzing with QEMU and Wine\n  Radamsa mutator (enable with -R to add or -RR to run it exclusivly).\n  qbdi_mode: fuzz android native libraries via QBDI framework\n  A more thorough list is available in the PATCHES file.\n   Feature/Instrumentation afl-gcc llvm_mode gcc_plugin qemu_mode unicorn_mode     laf-intel / CompCov  x  x86/arm x86/arm   NeverZero x x(1) (2) x x   Persistent mode  x x x86 x   Whitelist  x x     InsTrim  x       neverZero:\n(1) only in LLVM \u0026gt;= 9.0 due to a bug in llvm in previous versions\n(2) gcc creates non-performant code, hence it is disabled in gcc_plugin\nSo all in all this is the best-of afl that is currently out there :-)\nFor new versions and additional information, check out: https://github.com/AFLplusplus/AFLplusplus\nTo compare notes with other users or get notified about major new features, send a mail to afl-users+subscribe@googlegroups.com.\nSee docs/QuickStartGuide.md if you don\u0026rsquo;t have time to read this file.\n0) Building and installing afl++ afl++ has many build options. The easiest is to build and install everything:\n$ make distrib $ sudo make install Note that \u0026ldquo;make distrib\u0026rdquo; also builds llvm_mode, qemu_mode, unicorn_mode and more. If you just want plain afl then do \u0026ldquo;make all\u0026rdquo;, however compiling and using at least llvm_mode is highly recommended for much better results - hence in this case\n$ make source-only is what you should choose.\nThese build options exist:\n all: just the main afl++ binaries binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode, libdislocator, libtokencap, radamsa source-only: everything for source code fuzzing: llvm_mode, libdislocator, libtokencap, radamsa distrib: everything (for both binary-only and source code fuzzing) install: installs everything you have compiled with the build options above clean: cleans everything. for qemu_mode and unicorn_mode it means it deletes all downloads as well code-format: format the code, do this before you commit and send a PR please! tests: runs test cases to ensure that all features are still working as they should help: shows these build options  Unless you are on Mac OS X you can also build statically linked versions of the afl++ binaries by passing the STATIC=1 argument to make:\n$ make all STATIC=1 Note that afl++ is faster and better the newer the compilers used are. Hence gcc-9 and especially llvm-9 should be the compilers of choice. If your distribution does not have them, you can use the Dockerfile:\n$ docker build -t aflplusplus 1) Challenges of guided fuzzing Fuzzing is one of the most powerful and proven strategies for identifying security issues in real-world software; it is responsible for the vast majority of remote code execution and privilege escalation bugs found to date in security-critical software.\nUnfortunately, fuzzing is also relatively shallow; blind, random mutations make it very unlikely to reach certain code paths in the tested code, leaving some vulnerabilities firmly outside the reach of this technique.\nThere have been numerous attempts to solve this problem. One of the early approaches - pioneered by Tavis Ormandy - is corpus distillation. The method relies on coverage signals to select a subset of interesting seeds from a massive, high-quality corpus of candidate files, and then fuzz them by traditional means. The approach works exceptionally well, but requires such a corpus to be readily available. In addition, block coverage measurements provide only a very simplistic understanding of program state, and are less useful for guiding the fuzzing effort in the long haul.\nOther, more sophisticated research has focused on techniques such as program flow analysis (\u0026ldquo;concolic execution\u0026rdquo;), symbolic execution, or static analysis. All these methods are extremely promising in experimental settings, but tend to suffer from reliability and performance problems in practical uses - and currently do not offer a viable alternative to \u0026ldquo;dumb\u0026rdquo; fuzzing techniques.\n2) The afl-fuzz approach American Fuzzy Lop is a brute-force fuzzer coupled with an exceedingly simple but rock-solid instrumentation-guided genetic algorithm. It uses a modified form of edge coverage to effortlessly pick up subtle, local-scale changes to program control flow.\nSimplifying a bit, the overall algorithm can be summed up as:\n  Load user-supplied initial test cases into the queue,\n  Take next input file from the queue,\n  Attempt to trim the test case to the smallest size that doesn\u0026rsquo;t alter the measured behavior of the program,\n  Repeatedly mutate the file using a balanced and well-researched variety of traditional fuzzing strategies,\n  If any of the generated mutations resulted in a new state transition recorded by the instrumentation, add mutated output as a new entry in the queue.\n  Go to 2.\n  The discovered test cases are also periodically culled to eliminate ones that have been obsoleted by newer, higher-coverage finds; and undergo several other instrumentation-driven effort minimization steps.\nAs a side result of the fuzzing process, the tool creates a small, self-contained corpus of interesting test cases. These are extremely useful for seeding other, labor- or resource-intensive testing regimes - for example, for stress-testing browsers, office applications, graphics suites, or closed-source tools.\nThe fuzzer is thoroughly tested to deliver out-of-the-box performance far superior to blind fuzzing or coverage-only tools.\n3) Instrumenting programs for use with AFL PLEASE NOTE: llvm_mode compilation with afl-clang-fast/afl-clang-fast++ instead of afl-gcc/afl-g++ is much faster and has a few cool features. See llvm_mode/ - however few code does not compile with llvm. We support llvm versions 3.8.0 to 11.\nWhen source code is available, instrumentation can be injected by a companion tool that works as a drop-in replacement for gcc or clang in any standard build process for third-party code.\nThe instrumentation has a fairly modest performance impact; in conjunction with other optimizations implemented by afl-fuzz, most programs can be fuzzed as fast or even faster than possible with traditional tools.\nThe correct way to recompile the target program may vary depending on the specifics of the build process, but a nearly-universal approach would be:\n$ CC=/path/to/afl/afl-gcc ./configure $ make clean all For C++ programs, you\u0026rsquo;d would also want to set CXX=/path/to/afl/afl-g++.\nThe clang wrappers (afl-clang and afl-clang++) can be used in the same way; clang users may also opt to leverage a higher-performance instrumentation mode, as described in llvm_mode/README.md. Clang/LLVM has a much better performance and works with LLVM version 3.8.0 to 11.\nUsing the LAF Intel performance enhancements are also recommended, see llvm_mode/README.laf-intel.md\nUsing partial instrumentation is also recommended, see llvm_mode/README.whitelist.md\nWhen testing libraries, you need to find or write a simple program that reads data from stdin or from a file and passes it to the tested library. In such a case, it is essential to link this executable against a static version of the instrumented library, or to make sure that the correct .so file is loaded at runtime (usually by setting LD_LIBRARY_PATH). The simplest option is a static build, usually possible via:\n$ CC=/path/to/afl/afl-gcc ./configure --disable-shared Setting AFL_HARDEN=1 when calling \u0026lsquo;make\u0026rsquo; will cause the CC wrapper to automatically enable code hardening options that make it easier to detect simple memory bugs. Libdislocator, a helper library included with AFL (see libdislocator/README.md) can help uncover heap corruption issues, too.\nPS. ASAN users are advised to review docs/notes_for_asan.md file for important caveats.\n4) Instrumenting binary-only apps When source code is NOT available, the fuzzer offers experimental support for fast, on-the-fly instrumentation of black-box binaries. This is accomplished with a version of QEMU running in the lesser-known \u0026ldquo;user space emulation\u0026rdquo; mode.\nQEMU is a project separate from AFL, but you can conveniently build the feature by doing:\n$ cd qemu_mode $ ./build_qemu_support.sh For additional instructions and caveats, see qemu_mode/README.md.\nThe mode is approximately 2-5x slower than compile-time instrumentation, is less conducive to parallelization, and may have some other quirks.\nIf afl-dyninst works for your binary, then you can use afl-fuzz normally and it will have twice the speed compared to qemu_mode.\nA more comprehensive description of these and other options can be found in docs/binaryonly_fuzzing.md\n5) Power schedules The power schedules were copied from Marcel Böhme\u0026rsquo;s excellent AFLfast implementation and expand on the ability to discover new paths and therefore may increase the code coverage.\nThe available schedules are:\n explore (default) fast coe quad lin exploit  In parallel mode (-M/-S, several instances with shared queue), we suggest to run the master using the exploit schedule (-p exploit) and the slaves with a combination of cut-off-exponential (-p coe), exponential (-p fast; default), and explore (-p explore) schedules.\nIn single mode, using -p fast is usually more beneficial than the default explore mode. (We don\u0026rsquo;t want to change the default behaviour of afl, so \u0026ldquo;fast\u0026rdquo; has not been made the default mode).\nMore details can be found in the paper published at the 23rd ACM Conference on Computer and Communications Security CCS\u0026rsquo;16\n6) Choosing initial test cases To operate correctly, the fuzzer requires one or more starting file that contains a good example of the input data normally expected by the targeted application. There are two basic rules:\n  Keep the files small. Under 1 kB is ideal, although not strictly necessary. For a discussion of why size matters, see perf_tips.md.\n  Use multiple test cases only if they are functionally different from each other. There is no point in using fifty different vacation photos to fuzz an image library.\n  You can find many good examples of starting files in the testcases/ subdirectory that comes with this tool.\nPS. If a large corpus of data is available for screening, you may want to use the afl-cmin utility to identify a subset of functionally distinct files that exercise different code paths in the target binary.\n7) Fuzzing binaries The fuzzing process itself is carried out by the afl-fuzz utility. This program requires a read-only directory with initial test cases, a separate place to store its findings, plus a path to the binary to test.\nFor target binaries that accept input directly from stdin, the usual syntax is:\n$ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program [...params...] For programs that take input from a file, use \u0026lsquo;@@\u0026rsquo; to mark the location in the target\u0026rsquo;s command line where the input file name should be placed. The fuzzer will substitute this for you:\n$ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@ You can also use the -f option to have the mutated data written to a specific file. This is useful if the program expects a particular file extension or so.\nNon-instrumented binaries can be fuzzed in the QEMU mode (add -Q in the command line) or in a traditional, blind-fuzzer mode (specify -n).\nYou can use -t and -m to override the default timeout and memory limit for the executed process; rare examples of targets that may need these settings touched include compilers and video decoders.\nTips for optimizing fuzzing performance are discussed in perf_tips.md.\nNote that afl-fuzz starts by performing an array of deterministic fuzzing steps, which can take several days, but tend to produce neat test cases. If you want quick \u0026amp; dirty results right away - akin to zzuf and other traditional fuzzers - add the -d option to the command line.\n8) Interpreting output See the docs/status_screen.md file for information on how to interpret the displayed stats and monitor the health of the process. Be sure to consult this file especially if any UI elements are highlighted in red.\nThe fuzzing process will continue until you press Ctrl-C. At minimum, you want to allow the fuzzer to complete one queue cycle, which may take anywhere from a couple of hours to a week or so.\nThere are three subdirectories created within the output directory and updated in real time:\n  queue/ - test cases for every distinctive execution path, plus all the starting files given by the user. This is the synthesized corpus mentioned in section 2.\n Before using this corpus for any other purposes, you can shrink it to a smaller size using the afl-cmin tool. The tool will find a smaller subset of files offering equivalent edge coverage.    crashes/ - unique test cases that cause the tested program to receive a fatal signal (e.g., SIGSEGV, SIGILL, SIGABRT). The entries are grouped by the received signal.\n  hangs/ - unique test cases that cause the tested program to time out. The default time limit before something is classified as a hang is the larger of 1 second and the value of the -t parameter. The value can be fine-tuned by setting AFL_HANG_TMOUT, but this is rarely necessary.\n  Crashes and hangs are considered \u0026ldquo;unique\u0026rdquo; if the associated execution paths involve any state transitions not seen in previously-recorded faults. If a single bug can be reached in multiple ways, there will be some count inflation early in the process, but this should quickly taper off.\nThe file names for crashes and hangs are correlated with parent, non-faulting queue entries. This should help with debugging.\nWhen you can\u0026rsquo;t reproduce a crash found by afl-fuzz, the most likely cause is that you are not setting the same memory limit as used by the tool. Try:\n$ LIMIT_MB=50 $ ( ulimit -Sv $[LIMIT_MB \u0026lt;\u0026lt; 10]; /path/to/tested_binary ... ) Change LIMIT_MB to match the -m parameter passed to afl-fuzz. On OpenBSD, also change -Sv to -Sd.\nAny existing output directory can be also used to resume aborted jobs; try:\n$ ./afl-fuzz -i- -o existing_output_dir [...etc...] If you have gnuplot installed, you can also generate some pretty graphs for any active fuzzing task using afl-plot. For an example of how this looks like, see http://lcamtuf.coredump.cx/afl/plot/.\n9) Parallelized fuzzing Every instance of afl-fuzz takes up roughly one core. This means that on multi-core systems, parallelization is necessary to fully utilize the hardware. For tips on how to fuzz a common target on multiple cores or multiple networked machines, please refer to docs/parallel_fuzzing.md.\nThe parallel fuzzing mode also offers a simple way for interfacing AFL to other fuzzers, to symbolic or concolic execution engines, and so forth; again, see the last section of docs/parallel_fuzzing.md for tips.\n10) Fuzzer dictionaries By default, afl-fuzz mutation engine is optimized for compact data formats - say, images, multimedia, compressed data, regular expression syntax, or shell scripts. It is somewhat less suited for languages with particularly verbose and redundant verbiage - notably including HTML, SQL, or JavaScript.\nTo avoid the hassle of building syntax-aware tools, afl-fuzz provides a way to seed the fuzzing process with an optional dictionary of language keywords, magic headers, or other special tokens associated with the targeted data type \u0026ndash; and use that to reconstruct the underlying grammar on the go:\nhttp://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html\nTo use this feature, you first need to create a dictionary in one of the two formats discussed in dictionaries/README.md; and then point the fuzzer to it via the -x option in the command line.\n(Several common dictionaries are already provided in that subdirectory, too.)\nThere is no way to provide more structured descriptions of the underlying syntax, but the fuzzer will likely figure out some of this based on the instrumentation feedback alone. This actually works in practice, say:\nhttp://lcamtuf.blogspot.com/2015/04/finding-bugs-in-sqlite-easy-way.html\nPS. Even when no explicit dictionary is given, afl-fuzz will try to extract existing syntax tokens in the input corpus by watching the instrumentation very closely during deterministic byte flips. This works for some types of parsers and grammars, but isn\u0026rsquo;t nearly as good as the -x mode.\nIf a dictionary is really hard to come by, another option is to let AFL run for a while, and then use the token capture library that comes as a companion utility with AFL. For that, see libtokencap/README.md.\n11) Crash triage The coverage-based grouping of crashes usually produces a small data set that can be quickly triaged manually or with a very simple GDB or Valgrind script. Every crash is also traceable to its parent non-crashing test case in the queue, making it easier to diagnose faults.\nHaving said that, it\u0026rsquo;s important to acknowledge that some fuzzing crashes can be difficult to quickly evaluate for exploitability without a lot of debugging and code analysis work. To assist with this task, afl-fuzz supports a very unique \u0026ldquo;crash exploration\u0026rdquo; mode enabled with the -C flag.\nIn this mode, the fuzzer takes one or more crashing test cases as the input, and uses its feedback-driven fuzzing strategies to very quickly enumerate all code paths that can be reached in the program while keeping it in the crashing state.\nMutations that do not result in a crash are rejected; so are any changes that do not affect the execution path.\nThe output is a small corpus of files that can be very rapidly examined to see what degree of control the attacker has over the faulting address, or whether it is possible to get past an initial out-of-bounds read - and see what lies beneath.\nOh, one more thing: for test case minimization, give afl-tmin a try. The tool can be operated in a very simple way:\n$ ./afl-tmin -i test_case -o minimized_result -- /path/to/program [...] The tool works with crashing and non-crashing test cases alike. In the crash mode, it will happily accept instrumented and non-instrumented binaries. In the non-crashing mode, the minimizer relies on standard AFL instrumentation to make the file simpler without altering the execution path.\nThe minimizer accepts the -m, -t, -f and @@ syntax in a manner compatible with afl-fuzz.\nAnother recent addition to AFL is the afl-analyze tool. It takes an input file, attempts to sequentially flip bytes, and observes the behavior of the tested program. It then color-codes the input based on which sections appear to be critical, and which are not; while not bulletproof, it can often offer quick insights into complex file formats. More info about its operation can be found near the end of docs/technical_details.md.\n12) Going beyond crashes Fuzzing is a wonderful and underutilized technique for discovering non-crashing design and implementation errors, too. Quite a few interesting bugs have been found by modifying the target programs to call abort() when, say:\n  Two bignum libraries produce different outputs when given the same fuzzer-generated input,\n  An image library produces different outputs when asked to decode the same input image several times in a row,\n  A serialization / deserialization library fails to produce stable outputs when iteratively serializing and deserializing fuzzer-supplied data,\n  A compression library produces an output inconsistent with the input file when asked to compress and then decompress a particular blob.\n  Implementing these or similar sanity checks usually takes very little time; if you are the maintainer of a particular package, you can make this code conditional with #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION (a flag also shared with libfuzzer) or #ifdef __AFL_COMPILER (this one is just for AFL).\n13) Common-sense risks Please keep in mind that, similarly to many other computationally-intensive tasks, fuzzing may put strain on your hardware and on the OS. In particular:\n  Your CPU will run hot and will need adequate cooling. In most cases, if cooling is insufficient or stops working properly, CPU speeds will be automatically throttled. That said, especially when fuzzing on less suitable hardware (laptops, smartphones, etc), it\u0026rsquo;s not entirely impossible for something to blow up.\n  Targeted programs may end up erratically grabbing gigabytes of memory or filling up disk space with junk files. AFL tries to enforce basic memory limits, but can\u0026rsquo;t prevent each and every possible mishap. The bottom line is that you shouldn\u0026rsquo;t be fuzzing on systems where the prospect of data loss is not an acceptable risk.\n  Fuzzing involves billions of reads and writes to the filesystem. On modern systems, this will be usually heavily cached, resulting in fairly modest \u0026ldquo;physical\u0026rdquo; I/O - but there are many factors that may alter this equation. It is your responsibility to monitor for potential trouble; with very heavy I/O, the lifespan of many HDDs and SSDs may be reduced.\nA good way to monitor disk I/O on Linux is the \u0026lsquo;iostat\u0026rsquo; command:\n  $ iostat -d 3 -x -k [...optional disk ID...] 14) Known limitations \u0026amp; areas for improvement Here are some of the most important caveats for AFL:\n  AFL detects faults by checking for the first spawned process dying due to a signal (SIGSEGV, SIGABRT, etc). Programs that install custom handlers for these signals may need to have the relevant code commented out. In the same vein, faults in child processed spawned by the fuzzed target may evade detection unless you manually add some code to catch that.\n  As with any other brute-force tool, the fuzzer offers limited coverage if encryption, checksums, cryptographic signatures, or compression are used to wholly wrap the actual data format to be tested.\nTo work around this, you can comment out the relevant checks (see examples/libpng_no_checksum/ for inspiration); if this is not possible, you can also write a postprocessor, as explained in examples/post_library/ (with AFL_POST_LIBRARY)\n  There are some unfortunate trade-offs with ASAN and 64-bit binaries. This isn\u0026rsquo;t due to any specific fault of afl-fuzz; see docs/notes_for_asan.md for tips.\n  There is no direct support for fuzzing network services, background daemons, or interactive apps that require UI interaction to work. You may need to make simple code changes to make them behave in a more traditional way. Preeny may offer a relatively simple option, too - see: https://github.com/zardus/preeny\nSome useful tips for modifying network-based services can be also found at: https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop\n  AFL doesn\u0026rsquo;t output human-readable coverage data. If you want to monitor coverage, use afl-cov from Michael Rash: https://github.com/mrash/afl-cov\n  Occasionally, sentient machines rise against their creators. If this happens to you, please consult http://lcamtuf.coredump.cx/prep/.\n  Beyond this, see INSTALL for platform-specific tips.\n15) Special thanks Many of the improvements to the original afl and afl++ wouldn\u0026rsquo;t be possible without feedback, bug reports, or patches from:\n Jann Horn Hanno Boeck Felix Groebert Jakub Wilk Richard W. M. Jones Alexander Cherepanov Tom Ritter Hovik Manucharyan Sebastian Roschke Eberhard Mattes Padraig Brady Ben Laurie @dronesec Luca Barbato Tobias Ospelt Thomas Jarosch Martin Carpenter Mudge Zatko Joe Zbiciak Ryan Govostes Michael Rash William Robinet Jonathan Gray Filipe Cabecinhas Nico Weber Jodie Cunningham Andrew Griffiths Parker Thompson Jonathan Neuschaefer Tyler Nighswander Ben Nagy Samir Aguiar Aidan Thornton Aleksandar Nikolich Sam Hakim Laszlo Szekeres David A. Wheeler Turo Lamminen Andreas Stieger Richard Godbee Louis Dassy teor2345 Alex Moneger Dmitry Vyukov Keegan McAllister Kostya Serebryany Richo Healey Martijn Bogaard rc0r Jonathan Foote Christian Holler Dominique Pelle Jacek Wielemborek Leo Barnes Jeremy Barnes Jeff Trull Guillaume Endignoux ilovezfs Daniel Godas-Lopez Franjo Ivancic Austin Seipp Daniel Komaromy Daniel Binderman Jonathan Metzman Vegard Nossum Jan Kneschke Kurt Roeckx Marcel Boehme Van-Thuan Pham Abhik Roychoudhury Joshua J. Drake Toby Hutton Rene Freingruber Sergey Davidoff Sami Liedes Craig Young Andrzej Jackowski Daniel Hodson Nathan Voss Dominik Maier Andrea Biondo Vincent Le Garrec Khaled Yakdan Kuang-che Wu Thank you!\n16) Contact Questions? Concerns? Bug reports? The contributors can be reached via https://github.com/AFLplusplus/AFLplusplus\nThere is also a mailing list for the afl project; to join, send a mail to afl-users+subscribe@googlegroups.com. Or, if you prefer to browse archives first, try: https://groups.google.com/group/afl-users\n"});index.add({'id':22,'href':'/docs/readme.mopt/','title':"R E a D M E. M Opt",'content':"MOpt(imized) AFL by puppet@zju.edu.cn 1. Description MOpt-AFL is a AFL-based fuzzer that utilizes a customized Particle Swarm Optimization (PSO) algorithm to find the optimal selection probability distribution of operators with respect to fuzzing effectiveness. More details can be found in the technical report.\n2. Cite Information Chenyang Lyu, Shouling Ji, Chao Zhang, Yuwei Li, Wei-Han Lee, Yu Song and Raheem Beyah, MOPT: Optimized Mutation Scheduling for Fuzzers, USENIX Security 2019.\n3. Seed Sets We open source all the seed sets used in the paper \u0026ldquo;MOPT: Optimized Mutation Scheduling for Fuzzers\u0026rdquo;.\n4. Experiment Results The experiment results can be found in https://drive.google.com/drive/folders/184GOzkZGls1H2NuLuUfSp9gfqp1E2-lL?usp=sharing. We only open source the crash files since the space is limited.\n5. Technical Report MOpt_TechReport.pdf is the technical report of the paper \u0026ldquo;MOPT: Optimized Mutation Scheduling for Fuzzers\u0026rdquo;, which contains more deatails.\n6. Parameter Introduction Most important, you must add the parameter -L (e.g., -L 0) to launch the MOpt scheme.\nOption \u0026lsquo;-L\u0026rsquo; controls the time to move on to the pacemaker fuzzing mode. \u0026lsquo;-L t\u0026rsquo;: when MOpt-AFL finishes the mutation of one input, if it has not discovered any new unique crash or path for more than t minutes, MOpt-AFL will enter the pacemaker fuzzing mode.\nSetting 0 will enter the pacemaker fuzzing mode at first, which is recommended in a short time-scale evaluation.\nOther important parameters can be found in afl-fuzz.c, for instance,\n\u0026lsquo;swarm_num\u0026rsquo;: the number of the PSO swarms used in the fuzzing process. \u0026lsquo;period_pilot\u0026rsquo;: how many times MOpt-AFL will execute the target program in the pilot fuzzing module, then it will enter the core fuzzing module. \u0026lsquo;period_core\u0026rsquo;: how many times MOpt-AFL will execute the target program in the core fuzzing module, then it will enter the PSO updating module. \u0026lsquo;limit_time_bound\u0026rsquo;: control how many interesting test cases need to be found before MOpt-AFL quits the pacemaker fuzzing mode and reuses the deterministic stage. 0 \u0026lt; \u0026lsquo;limit_time_bound\u0026rsquo; \u0026lt; 1, MOpt-AFL-tmp. \u0026lsquo;limit_time_bound\u0026rsquo; \u0026gt;= 1, MOpt-AFL-ever.\nHave fun with MOpt in AFL!\n"});index.add({'id':23,'href':'/docs/readme.radamsa/','title':"R E a D M E.radamsa",'content':"libradamsa Pretranslated radamsa library. This code belongs to the radamsa author.\n Original repository: https://gitlab.com/akihe/radamsa\n  Source commit: 7b2cc2d0\n  The code here is adapted for AFL++ with minor changes respect the original version\n "});index.add({'id':24,'href':'/docs/sister_projects/','title':"Sister Projects",'content':"Sister projects This doc lists some of the projects that are inspired by, derived from, designed for, or meant to integrate with AFL. See README.md for the general instruction manual.\n!!! !!! This list is outdated and needs an update, missing: e.g. Angora, FairFuzz !!!\nSupport for other languages / environments: Python AFL (Jakub Wilk) Allows fuzz-testing of Python programs. Uses custom instrumentation and its own forkserver.\nhttp://jwilk.net/software/python-afl\nGo-fuzz (Dmitry Vyukov) AFL-inspired guided fuzzing approach for Go targets:\nhttps://github.com/dvyukov/go-fuzz\nafl.rs (Keegan McAllister) Allows Rust features to be easily fuzzed with AFL (using the LLVM mode).\nhttps://github.com/kmcallister/afl.rs\nOCaml support (KC Sivaramakrishnan) Adds AFL-compatible instrumentation to OCaml programs.\nhttps://github.com/ocamllabs/opam-repo-dev/pull/23 http://canopy.mirage.io/Posts/Fuzzing\nAFL for GCJ Java and other GCC frontends (-) GCC Java programs are actually supported out of the box - simply rename afl-gcc to afl-gcj. Unfortunately, by default, unhandled exceptions in GCJ do not result in abort() being called, so you will need to manually add a top-level exception handler that exits with SIGABRT or something equivalent.\nOther GCC-supported languages should be fairly easy to get working, but may face similar problems. See https://gcc.gnu.org/frontends.html for a list of options.\nAFL-style in-process fuzzer for LLVM (Kostya Serebryany) Provides an evolutionary instrumentation-guided fuzzing harness that allows some programs to be fuzzed without the fork / execve overhead. (Similar functionality is now available as the \u0026ldquo;persistent\u0026rdquo; feature described in the llvm_mode readme)\nhttp://llvm.org/docs/LibFuzzer.html\nAFL fixup shim (Ben Nagy) Allows AFL_POST_LIBRARY postprocessors to be written in arbitrary languages that don\u0026rsquo;t have C / .so bindings. Includes examples in Go.\nhttps://github.com/bnagy/aflfix\nTriforceAFL (Tim Newsham and Jesse Hertz) Leverages QEMU full system emulation mode to allow AFL to target operating systems and other alien worlds:\nhttps://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2016/june/project-triforce-run-afl-on-everything/\nWinAFL (Ivan Fratric) As the name implies, allows you to fuzz Windows binaries (using DynamoRio).\nhttps://github.com/ivanfratric/winafl\nAnother Windows alternative may be:\nhttps://github.com/carlosgprado/BrundleFuzz/\nNetwork fuzzing Preeny (Yan Shoshitaishvili) Provides a fairly simple way to convince dynamically linked network-centric programs to read from a file or not fork. Not AFL-specific, but described as useful by many users. Some assembly required.\nhttps://github.com/zardus/preeny\nDistributed fuzzing and related automation roving (Richo Healey) A client-server architecture for effortlessly orchestrating AFL runs across a fleet of machines. You don\u0026rsquo;t want to use this on systems that face the Internet or live in other untrusted environments.\nhttps://github.com/richo/roving\nDistfuzz-AFL (Martijn Bogaard) Simplifies the management of afl-fuzz instances on remote machines. The author notes that the current implementation isn\u0026rsquo;t secure and should not be exposed on the Internet.\nhttps://github.com/MartijnB/disfuzz-afl\nAFLDFF (quantumvm) A nice GUI for managing AFL jobs.\nhttps://github.com/quantumvm/AFLDFF\nafl-launch (Ben Nagy) Batch AFL launcher utility with a simple CLI.\nhttps://github.com/bnagy/afl-launch\nAFL Utils (rc0r) Simplifies the triage of discovered crashes, start parallel instances, etc.\nhttps://github.com/rc0r/afl-utils\nAnother crash triage tool:\nhttps://github.com/floyd-fuh/afl-crash-analyzer\nafl-fuzzing-scripts (Tobias Ospelt) Simplifies starting up multiple parallel AFL jobs.\nhttps://github.com/floyd-fuh/afl-fuzzing-scripts/\nafl-sid (Jacek Wielemborek) Allows users to more conveniently build and deploy AFL via Docker.\nhttps://github.com/d33tah/afl-sid\nAnother Docker-related project:\nhttps://github.com/ozzyjohnson/docker-afl\nafl-monitor (Paul S. Ziegler) Provides more detailed and versatile statistics about your running AFL jobs.\nhttps://github.com/reflare/afl-monitor\nFEXM (Security in Telecommunications) Fully automated fuzzing framework, based on AFL\nhttps://github.com/fgsect/fexm\nCrash triage, coverage analysis, and other companion tools: afl-crash-analyzer (Tobias Ospelt) Makes it easier to navigate and annotate crashing test cases.\nhttps://github.com/floyd-fuh/afl-crash-analyzer/\nCrashwalk (Ben Nagy) AFL-aware tool to annotate and sort through crashing test cases.\nhttps://github.com/bnagy/crashwalk\nafl-cov (Michael Rash) Produces human-readable coverage data based on the output queue of afl-fuzz.\nhttps://github.com/mrash/afl-cov\nafl-sancov (Bhargava Shastry) Similar to afl-cov, but uses clang sanitizer instrumentation.\nhttps://github.com/bshastry/afl-sancov\nRecidiVM (Jakub Wilk) Makes it easy to estimate memory usage limits when fuzzing with ASAN or MSAN.\nhttp://jwilk.net/software/recidivm\naflize (Jacek Wielemborek) Automatically build AFL-enabled versions of Debian packages.\nhttps://github.com/d33tah/aflize\nafl-ddmin-mod (Markus Teufelberger) A variant of afl-tmin that uses a more sophisticated (but slower) minimization algorithm.\nhttps://github.com/MarkusTeufelberger/afl-ddmin-mod\nafl-kit (Kuang-che Wu) Replacements for afl-cmin and afl-tmin with additional features, such as the ability to filter crashes based on stderr patterns.\nhttps://github.com/kcwu/afl-kit\nNarrow-purpose or experimental: Cygwin support (Ali Rizvi-Santiago) Pretty self-explanatory. As per the author, this \u0026ldquo;mostly\u0026rdquo; ports AFL to Windows. Field reports welcome!\nhttps://github.com/arizvisa/afl-cygwin\nPause and resume scripts (Ben Nagy) Simple automation to suspend and resume groups of fuzzing jobs.\nhttps://github.com/bnagy/afl-trivia\nStatic binary-only instrumentation (Aleksandar Nikolich) Allows black-box binaries to be instrumented statically (i.e., by modifying the binary ahead of the time, rather than translating it on the run). Author reports better performance compared to QEMU, but occasional translation errors with stripped binaries.\nhttps://github.com/vanhauser-thc/afl-dyninst\nAFL PIN (Parker Thompson) Early-stage Intel PIN instrumentation support (from before we settled on faster-running QEMU).\nhttps://github.com/mothran/aflpin\nAFL-style instrumentation in llvm (Kostya Serebryany) Allows AFL-equivalent instrumentation to be injected at compiler level. This is currently not supported by AFL as-is, but may be useful in other projects.\nhttps://code.google.com/p/address-sanitizer/wiki/AsanCoverage#Coverage_counters\nAFL JS (Han Choongwoo) One-off optimizations to speed up the fuzzing of JavaScriptCore (now likely superseded by LLVM deferred forkserver init - see llvm_mode/README.md).\nhttps://github.com/tunz/afl-fuzz-js\nAFL harness for fwknop (Michael Rash) An example of a fairly involved integration with AFL.\nhttps://github.com/mrash/fwknop/tree/master/test/afl\nBuilding harnesses for DNS servers (Jonathan Foote, Ron Bowes) Two articles outlining the general principles and showing some example code.\nhttps://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop https://goo.gl/j9EgFf\nFuzzer shell for SQLite (Richard Hipp) A simple SQL shell designed specifically for fuzzing the underlying library.\nhttp://www.sqlite.org/src/artifact/9e7e273da2030371\nSupport for Python mutation modules (Christian Holler) now integrated in AFL++, originally from here https://github.com/choller/afl/blob/master/docs/mozilla/python_modules.txt\nSupport for selective instrumentation (Christian Holler) now integrated in AFL++, originally from here https://github.com/choller/afl/blob/master/docs/mozilla/partial_instrumentation.txt\nSyzkaller (Dmitry Vyukov) A similar guided approach as applied to fuzzing syscalls:\nhttps://github.com/google/syzkaller/wiki/Found-Bugs https://github.com/dvyukov/linux/commit/33787098ffaaa83b8a7ccf519913ac5fd6125931 http://events.linuxfoundation.org/sites/events/files/slides/AFL%20filesystem%20fuzzing%2C%20Vault%202016_0.pdf\nKernel Snapshot Fuzzing using Unicornafl (Security in Telecommunications) https://github.com/fgsect/unicorefuzz\nAndroid support (ele7enxxh) Based on a somewhat dated version of AFL:\nhttps://github.com/ele7enxxh/android-afl\nCGI wrapper (floyd) Facilitates the testing of CGI scripts.\nhttps://github.com/floyd-fuh/afl-cgi-wrapper\nFuzzing difficulty estimation (Marcel Boehme) A fork of AFL that tries to quantify the likelihood of finding additional paths or crashes at any point in a fuzzing job.\nhttps://github.com/mboehme/pythia\n"});index.add({'id':25,'href':'/docs/status_screen/','title':"Status Screen",'content':"Understanding the status screen This document provides an overview of the status screen - plus tips for troubleshooting any warnings and red text shown in the UI. See README.md for the general instruction manual.\nA note about colors The status screen and error messages use colors to keep things readable and attract your attention to the most important details. For example, red almost always means \u0026ldquo;consult this doc\u0026rdquo; :-)\nUnfortunately, the UI will render correctly only if your terminal is using traditional un*x palette (white text on black background) or something close to that.\nIf you are using inverse video, you may want to change your settings, say:\n For GNOME Terminal, go to Edit \u0026gt; Profile preferences, select the \u0026ldquo;colors\u0026rdquo; tab, and from the list of built-in schemes, choose \u0026ldquo;white on black\u0026rdquo;. For the MacOS X Terminal app, open a new window using the \u0026ldquo;Pro\u0026rdquo; scheme via the Shell \u0026gt; New Window menu (or make \u0026ldquo;Pro\u0026rdquo; your default).  Alternatively, if you really like your current colors, you can edit config.h to comment out USE_COLORS, then do make clean all.\nI\u0026rsquo;m not aware of any other simple way to make this work without causing other side effects - sorry about that.\nWith that out of the way, let\u0026rsquo;s talk about what\u0026rsquo;s actually on the screen\u0026hellip;\nThe status bar The top line shows you which mode afl-fuzz is running in (normal: \u0026ldquo;american fuzy lop\u0026rdquo;, crash exploration mode: \u0026ldquo;peruvian rabbit mode\u0026rdquo;) and the version of afl++. Next to the version is the banner, which, if not set with -T by hand, will either show the binary name being fuzzed, or the -M/-S master/slave name for parallel fuzzing. Finally, the last item is the power schedule mode being run (default: explore).\nProcess timing  +----------------------------------------------------+ | run time : 0 days, 8 hrs, 32 min, 43 sec | | last new path : 0 days, 0 hrs, 6 min, 40 sec | | last uniq crash : none seen yet | | last uniq hang : 0 days, 1 hrs, 24 min, 32 sec | +----------------------------------------------------+ This section is fairly self-explanatory: it tells you how long the fuzzer has been running and how much time has elapsed since its most recent finds. This is broken down into \u0026ldquo;paths\u0026rdquo; (a shorthand for test cases that trigger new execution patterns), crashes, and hangs.\nWhen it comes to timing: there is no hard rule, but most fuzzing jobs should be expected to run for days or weeks; in fact, for a moderately complex project, the first pass will probably take a day or so. Every now and then, some jobs will be allowed to run for months.\nThere\u0026rsquo;s one important thing to watch out for: if the tool is not finding new paths within several minutes of starting, you\u0026rsquo;re probably not invoking the target binary correctly and it never gets to parse the input files we\u0026rsquo;re throwing at it; another possible explanations are that the default memory limit (-m) is too restrictive, and the program exits after failing to allocate a buffer very early on; or that the input files are patently invalid and always fail a basic header check.\nIf there are no new paths showing up for a while, you will eventually see a big red warning in this section, too :-)\nOverall results  +-----------------------+ | cycles done : 0 | | total paths : 2095 | | uniq crashes : 0 | | uniq hangs : 19 | +-----------------------+ The first field in this section gives you the count of queue passes done so far - that is, the number of times the fuzzer went over all the interesting test cases discovered so far, fuzzed them, and looped back to the very beginning. Every fuzzing session should be allowed to complete at least one cycle; and ideally, should run much longer than that.\nAs noted earlier, the first pass can take a day or longer, so sit back and relax. If you want to get broader but more shallow coverage right away, try the -d option - it gives you a more familiar experience by skipping the deterministic fuzzing steps. It is, however, inferior to the standard mode in a couple of subtle ways.\nTo help make the call on when to hit Ctrl-C, the cycle counter is color-coded. It is shown in magenta during the first pass, progresses to yellow if new finds are still being made in subsequent rounds, then blue when that ends - and finally, turns green after the fuzzer hasn\u0026rsquo;t been seeing any action for a longer while.\nThe remaining fields in this part of the screen should be pretty obvious: there\u0026rsquo;s the number of test cases (\u0026ldquo;paths\u0026rdquo;) discovered so far, and the number of unique faults. The test cases, crashes, and hangs can be explored in real-time by browsing the output directory, as discussed in README.md.\nCycle progress  +-------------------------------------+ | now processing : 1296 (61.86%) | | paths timed out : 0 (0.00%) | +-------------------------------------+ This box tells you how far along the fuzzer is with the current queue cycle: it shows the ID of the test case it is currently working on, plus the number of inputs it decided to ditch because they were persistently timing out.\nThe \u0026ldquo;*\u0026rdquo; suffix sometimes shown in the first line means that the currently processed path is not \u0026ldquo;favored\u0026rdquo; (a property discussed later on).\nIf you feel that the fuzzer is progressing too slowly, see the note about the -d option in this doc.\nMap coverage  +--------------------------------------+ | map density : 10.15% / 29.07% | | count coverage : 4.03 bits/tuple | +--------------------------------------+ The section provides some trivia about the coverage observed by the instrumentation embedded in the target binary.\nThe first line in the box tells you how many branch tuples we have already hit, in proportion to how much the bitmap can hold. The number on the left describes the current input; the one on the right is the value for the entire input corpus.\nBe wary of extremes:\n Absolute numbers below 200 or so suggest one of three things: that the program is extremely simple; that it is not instrumented properly (e.g., due to being linked against a non-instrumented copy of the target library); or that it is bailing out prematurely on your input test cases. The fuzzer will try to mark this in pink, just to make you aware. Percentages over 70% may very rarely happen with very complex programs that make heavy use of template-generated code. Because high bitmap density makes it harder for the fuzzer to reliably discern new program states, I recommend recompiling the binary with AFL_INST_RATIO=10 or so and trying again (see env_variables.md). The fuzzer will flag high percentages in red. Chances are, you will never see that unless you\u0026rsquo;re fuzzing extremely hairy software (say, v8, perl, ffmpeg).  The other line deals with the variability in tuple hit counts seen in the binary. In essence, if every taken branch is always taken a fixed number of times for all the inputs we have tried, this will read 1.00. As we manage to trigger other hit counts for every branch, the needle will start to move toward 8.00 (every bit in the 8-bit map hit), but will probably never reach that extreme.\nTogether, the values can be useful for comparing the coverage of several different fuzzing jobs that rely on the same instrumented binary.\nStage progress  +-------------------------------------+ | now trying : interest 32/8 | | stage execs : 3996/34.4k (11.62%) | | total execs : 27.4M | | exec speed : 891.7/sec | +-------------------------------------+ This part gives you an in-depth peek at what the fuzzer is actually doing right now. It tells you about the current stage, which can be any of:\n calibration - a pre-fuzzing stage where the execution path is examined to detect anomalies, establish baseline execution speed, and so on. Executed very briefly whenever a new find is being made. trim L/S - another pre-fuzzing stage where the test case is trimmed to the shortest form that still produces the same execution path. The length (L) and stepover (S) are chosen in general relationship to file size. bitflip L/S - deterministic bit flips. There are L bits toggled at any given time, walking the input file with S-bit increments. The current L/S variants are: 1/1, 2/1, 4/1, 8/8, 16/8, 32/8. arith L/8 - deterministic arithmetics. The fuzzer tries to subtract or add small integers to 8-, 16-, and 32-bit values. The stepover is always 8 bits. interest L/8 - deterministic value overwrite. The fuzzer has a list of known \u0026ldquo;interesting\u0026rdquo; 8-, 16-, and 32-bit values to try. The stepover is 8 bits. extras - deterministic injection of dictionary terms. This can be shown as \u0026ldquo;user\u0026rdquo; or \u0026ldquo;auto\u0026rdquo;, depending on whether the fuzzer is using a user-supplied dictionary (-x) or an auto-created one. You will also see \u0026ldquo;over\u0026rdquo; or \u0026ldquo;insert\u0026rdquo;, depending on whether the dictionary words overwrite existing data or are inserted by offsetting the remaining data to accommodate their length. havoc - a sort-of-fixed-length cycle with stacked random tweaks. The operations attempted during this stage include bit flips, overwrites with random and \u0026ldquo;interesting\u0026rdquo; integers, block deletion, block duplication, plus assorted dictionary-related operations (if a dictionary is supplied in the first place). splice - a last-resort strategy that kicks in after the first full queue cycle with no new paths. It is equivalent to \u0026lsquo;havoc\u0026rsquo;, except that it first splices together two random inputs from the queue at some arbitrarily selected midpoint. sync - a stage used only when -M or -S is set (see parallel_fuzzing.md). No real fuzzing is involved, but the tool scans the output from other fuzzers and imports test cases as necessary. The first time this is done, it may take several minutes or so.  The remaining fields should be fairly self-evident: there\u0026rsquo;s the exec count progress indicator for the current stage, a global exec counter, and a benchmark for the current program execution speed. This may fluctuate from one test case to another, but the benchmark should be ideally over 500 execs/sec most of the time - and if it stays below 100, the job will probably take very long.\nThe fuzzer will explicitly warn you about slow targets, too. If this happens, see the perf_tips.md file included with the fuzzer for ideas on how to speed things up.\nFindings in depth  +--------------------------------------+ | favored paths : 879 (41.96%) | | new edges on : 423 (20.19%) | | total crashes : 0 (0 unique) | | total tmouts : 24 (19 unique) | +--------------------------------------+ This gives you several metrics that are of interest mostly to complete nerds. The section includes the number of paths that the fuzzer likes the most based on a minimization algorithm baked into the code (these will get considerably more air time), and the number of test cases that actually resulted in better edge coverage (versus just pushing the branch hit counters up). There are also additional, more detailed counters for crashes and timeouts.\nNote that the timeout counter is somewhat different from the hang counter; this one includes all test cases that exceeded the timeout, even if they did not exceed it by a margin sufficient to be classified as hangs.\nFuzzing strategy yields  +-----------------------------------------------------+ | bit flips : 57/289k, 18/289k, 18/288k | | byte flips : 0/36.2k, 4/35.7k, 7/34.6k | | arithmetics : 53/2.54M, 0/537k, 0/55.2k | | known ints : 8/322k, 12/1.32M, 10/1.70M | | dictionary : 9/52k, 1/53k, 1/24k | | havoc : 1903/20.0M, 0/0 | | trim : 20.31%/9201, 17.05% | +-----------------------------------------------------+ This is just another nerd-targeted section keeping track of how many paths we have netted, in proportion to the number of execs attempted, for each of the fuzzing strategies discussed earlier on. This serves to convincingly validate assumptions about the usefulness of the various approaches taken by afl-fuzz.\nThe trim strategy stats in this section are a bit different than the rest. The first number in this line shows the ratio of bytes removed from the input files; the second one corresponds to the number of execs needed to achieve this goal. Finally, the third number shows the proportion of bytes that, although not possible to remove, were deemed to have no effect and were excluded from some of the more expensive deterministic fuzzing steps.\nPath geometry  +---------------------+ | levels : 5 | | pending : 1570 | | pend fav : 583 | | own finds : 0 | | imported : 0 | | stability : 100.00% | +---------------------+ The first field in this section tracks the path depth reached through the guided fuzzing process. In essence: the initial test cases supplied by the user are considered \u0026ldquo;level 1\u0026rdquo;. The test cases that can be derived from that through traditional fuzzing are considered \u0026ldquo;level 2\u0026rdquo;; the ones derived by using these as inputs to subsequent fuzzing rounds are \u0026ldquo;level 3\u0026rdquo;; and so forth. The maximum depth is therefore a rough proxy for how much value you\u0026rsquo;re getting out of the instrumentation-guided approach taken by afl-fuzz.\nThe next field shows you the number of inputs that have not gone through any fuzzing yet. The same stat is also given for \u0026ldquo;favored\u0026rdquo; entries that the fuzzer really wants to get to in this queue cycle (the non-favored entries may have to wait a couple of cycles to get their chance).\nNext, we have the number of new paths found during this fuzzing section and imported from other fuzzer instances when doing parallelized fuzzing; and the extent to which identical inputs appear to sometimes produce variable behavior in the tested binary.\nThat last bit is actually fairly interesting: it measures the consistency of observed traces. If a program always behaves the same for the same input data, it will earn a score of 100%. When the value is lower but still shown in purple, the fuzzing process is unlikely to be negatively affected. If it goes into red, you may be in trouble, since AFL will have difficulty discerning between meaningful and \u0026ldquo;phantom\u0026rdquo; effects of tweaking the input file.\nNow, most targets will just get a 100% score, but when you see lower figures, there are several things to look at:\n The use of uninitialized memory in conjunction with some intrinsic sources of entropy in the tested binary. Harmless to AFL, but could be indicative of a security bug. Attempts to manipulate persistent resources, such as left over temporary files or shared memory objects. This is usually harmless, but you may want to double-check to make sure the program isn\u0026rsquo;t bailing out prematurely. Running out of disk space, SHM handles, or other global resources can trigger this, too. Hitting some functionality that is actually designed to behave randomly. Generally harmless. For example, when fuzzing sqlite, an input like select random(); will trigger a variable execution path. Multiple threads executing at once in semi-random order. This is harmless when the \u0026lsquo;stability\u0026rsquo; metric stays over 90% or so, but can become an issue if not. Here\u0026rsquo;s what to try:  Use afl-clang-fast from llvm_mode - it uses a thread-local tracking model that is less prone to concurrency issues, See if the target can be compiled or run without threads. Common ./configure options include --without-threads, --disable-pthreads, or --disable-openmp. Replace pthreads with GNU Pth (https://www.gnu.org/software/pth/), which allows you to use a deterministic scheduler.   In persistent mode, minor drops in the \u0026ldquo;stability\u0026rdquo; metric can be normal, because not all the code behaves identically when re-entered; but major dips may signify that the code within __AFL_LOOP() is not behaving correctly on subsequent iterations (e.g., due to incomplete clean-up or reinitialization of the state) and that most of the fuzzing effort goes to waste.  The paths where variable behavior is detected are marked with a matching entry in the \u0026lt;out_dir\u0026gt;/queue/.state/variable_behavior/ directory, so you can look them up easily.\nCPU load  [cpu: 25%] This tiny widget shows the apparent CPU utilization on the local system. It is calculated by taking the number of processes in the \u0026ldquo;runnable\u0026rdquo; state, and then comparing it to the number of logical cores on the system.\nIf the value is shown in green, you are using fewer CPU cores than available on your system and can probably parallelize to improve performance; for tips on how to do that, see parallel_fuzzing.md.\nIf the value is shown in red, your CPU is possibly oversubscribed, and running additional fuzzers may not give you any benefits.\nOf course, this benchmark is very simplistic; it tells you how many processes are ready to run, but not how resource-hungry they may be. It also doesn\u0026rsquo;t distinguish between physical cores, logical cores, and virtualized CPUs; the performance characteristics of each of these will differ quite a bit.\nIf you want a more accurate measurement, you can run the afl-gotcpu utility from the command line.\nAddendum: status and plot files For unattended operation, some of the key status screen information can be also found in a machine-readable format in the fuzzer_stats file in the output directory. This includes:\n start_time - unix time indicating the start time of afl-fuzz last_update - unix time corresponding to the last update of this file run_time - run time in seconds to the last update of this file fuzzer_pid - PID of the fuzzer process cycles_done - queue cycles completed so far cycles_wo_finds - number of cycles without any new paths found execs_done - number of execve() calls attempted execs_per_sec - overall number of execs per second paths_total - total number of entries in the queue paths_favored - number of queue entries that are favored paths_found - number of entries discovered through local fuzzing paths_imported - number of entries imported from other instances max_depth - number of levels in the generated data set cur_path - currently processed entry number pending_favs - number of favored entries still waiting to be fuzzed pending_total - number of all entries waiting to be fuzzed variable_paths - number of test cases showing variable behavior stability - percentage of bitmap bytes that behave consistently bitmap_cvg - percentage of edge coverage found in the map so far unique_crashes - number of unique crashes recorded unique_hangs - number of unique hangs encountered last_path - seconds since the last path was found last_crash - seconds since the last crash was found last_hang - seconds since the last hang was found execs_since_crash - execs since the last crash was found exec_timeout - the -t command line value slowest_exec_ms - real time of the slowest execution in ms peak_rss_mb - max rss usage reached during fuzzing in MB edges_found - how many edges have been found var_byte_count - how many edges are non-deterministic afl_banner - banner text (e.g. the target name) afl_version - the version of afl used target_mode - default, persistent, qemu, unicorn, dumb command_line - full command line used for the fuzzing session  Most of these map directly to the UI elements discussed earlier on.\nOn top of that, you can also find an entry called plot_data, containing a plottable history for most of these fields. If you have gnuplot installed, you can turn this into a nice progress report with the included afl-plot tool.\n"});index.add({'id':26,'href':'/docs/technical_details/','title':"Technical Details",'content':"Technical \u0026ldquo;whitepaper\u0026rdquo; for afl-fuzz This document provides a quick overview of the guts of American Fuzzy Lop. See README.md for the general instruction manual; and for a discussion of motivations and design goals behind AFL, see historical_notes.md.\n0. Design statement American Fuzzy Lop does its best not to focus on any singular principle of operation and not be a proof-of-concept for any specific theory. The tool can be thought of as a collection of hacks that have been tested in practice, found to be surprisingly effective, and have been implemented in the simplest, most robust way I could think of at the time.\nMany of the resulting features are made possible thanks to the availability of lightweight instrumentation that served as a foundation for the tool, but this mechanism should be thought of merely as a means to an end. The only true governing principles are speed, reliability, and ease of use.\n1. Coverage measurements The instrumentation injected into compiled programs captures branch (edge) coverage, along with coarse branch-taken hit counts. The code injected at branch points is essentially equivalent to:\ncur_location = \u0026lt;COMPILE_TIME_RANDOM\u0026gt;; shared_mem[cur_location ^ prev_location]++; prev_location = cur_location \u0026gt;\u0026gt; 1; The cur_location value is generated randomly to simplify the process of linking complex projects and keep the XOR output distributed uniformly.\nThe shared_mem[] array is a 64 kB SHM region passed to the instrumented binary by the caller. Every byte set in the output map can be thought of as a hit for a particular (branch_src, branch_dst) tuple in the instrumented code.\nThe size of the map is chosen so that collisions are sporadic with almost all of the intended targets, which usually sport between 2k and 10k discoverable branch points:\n Branch cnt | Colliding tuples | Example targets ------------+------------------+----------------- 1,000 | 0.75% | giflib, lzo 2,000 | 1.5% | zlib, tar, xz 5,000 | 3.5% | libpng, libwebp 10,000 | 7% | libxml 20,000 | 14% | sqlite 50,000 | 30% | - At the same time, its size is small enough to allow the map to be analyzed in a matter of microseconds on the receiving end, and to effortlessly fit within L2 cache.\nThis form of coverage provides considerably more insight into the execution path of the program than simple block coverage. In particular, it trivially distinguishes between the following execution traces:\n A -\u0026gt; B -\u0026gt; C -\u0026gt; D -\u0026gt; E (tuples: AB, BC, CD, DE) A -\u0026gt; B -\u0026gt; D -\u0026gt; C -\u0026gt; E (tuples: AB, BD, DC, CE) This aids the discovery of subtle fault conditions in the underlying code, because security vulnerabilities are more often associated with unexpected or incorrect state transitions than with merely reaching a new basic block.\nThe reason for the shift operation in the last line of the pseudocode shown earlier in this section is to preserve the directionality of tuples (without this, A ^ B would be indistinguishable from B ^ A) and to retain the identity of tight loops (otherwise, A ^ A would be obviously equal to B ^ B).\nThe absence of simple saturating arithmetic opcodes on Intel CPUs means that the hit counters can sometimes wrap around to zero. Since this is a fairly unlikely and localized event, it\u0026rsquo;s seen as an acceptable performance trade-off.\n2. Detecting new behaviors The fuzzer maintains a global map of tuples seen in previous executions; this data can be rapidly compared with individual traces and updated in just a couple of dword- or qword-wide instructions and a simple loop.\nWhen a mutated input produces an execution trace containing new tuples, the corresponding input file is preserved and routed for additional processing later on (see section #3). Inputs that do not trigger new local-scale state transitions in the execution trace (i.e., produce no new tuples) are discarded, even if their overall control flow sequence is unique.\nThis approach allows for a very fine-grained and long-term exploration of program state while not having to perform any computationally intensive and fragile global comparisons of complex execution traces, and while avoiding the scourge of path explosion.\nTo illustrate the properties of the algorithm, consider that the second trace shown below would be considered substantially new because of the presence of new tuples (CA, AE):\n #1: A -\u0026gt; B -\u0026gt; C -\u0026gt; D -\u0026gt; E #2: A -\u0026gt; B -\u0026gt; C -\u0026gt; A -\u0026gt; E At the same time, with #2 processed, the following pattern will not be seen as unique, despite having a markedly different overall execution path:\n #3: A -\u0026gt; B -\u0026gt; C -\u0026gt; A -\u0026gt; B -\u0026gt; C -\u0026gt; A -\u0026gt; B -\u0026gt; C -\u0026gt; D -\u0026gt; E In addition to detecting new tuples, the fuzzer also considers coarse tuple hit counts. These are divided into several buckets:\n 1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+ To some extent, the number of buckets is an implementation artifact: it allows an in-place mapping of an 8-bit counter generated by the instrumentation to an 8-position bitmap relied on by the fuzzer executable to keep track of the already-seen execution counts for each tuple.\nChanges within the range of a single bucket are ignored; transition from one bucket to another is flagged as an interesting change in program control flow, and is routed to the evolutionary process outlined in the section below.\nThe hit count behavior provides a way to distinguish between potentially interesting control flow changes, such as a block of code being executed twice when it was normally hit only once. At the same time, it is fairly insensitive to empirically less notable changes, such as a loop going from 47 cycles to 48. The counters also provide some degree of \u0026ldquo;accidental\u0026rdquo; immunity against tuple collisions in dense trace maps.\nThe execution is policed fairly heavily through memory and execution time limits; by default, the timeout is set at 5x the initially-calibrated execution speed, rounded up to 20 ms. The aggressive timeouts are meant to prevent dramatic fuzzer performance degradation by descending into tarpits that, say, improve coverage by 1% while being 100x slower; we pragmatically reject them and hope that the fuzzer will find a less expensive way to reach the same code. Empirical testing strongly suggests that more generous time limits are not worth the cost.\n3. Evolving the input queue Mutated test cases that produced new state transitions within the program are added to the input queue and used as a starting point for future rounds of fuzzing. They supplement, but do not automatically replace, existing finds.\nIn contrast to more greedy genetic algorithms, this approach allows the tool to progressively explore various disjoint and possibly mutually incompatible features of the underlying data format, as shown in this image:\nSeveral practical examples of the results of this algorithm are discussed here:\nhttp://lcamtuf.blogspot.com/2014/11/pulling-jpegs-out-of-thin-air.html http://lcamtuf.blogspot.com/2014/11/afl-fuzz-nobody-expects-cdata-sections.html\nThe synthetic corpus produced by this process is essentially a compact collection of \u0026ldquo;hmm, this does something new!\u0026rdquo; input files, and can be used to seed any other testing processes down the line (for example, to manually stress-test resource-intensive desktop apps).\nWith this approach, the queue for most targets grows to somewhere between 1k and 10k entries; approximately 10-30% of this is attributable to the discovery of new tuples, and the remainder is associated with changes in hit counts.\nThe following table compares the relative ability to discover file syntax and explore program states when using several different approaches to guided fuzzing. The instrumented target was GNU patch 2.7k.3 compiled with -O3 and seeded with a dummy text file; the session consisted of a single pass over the input queue with afl-fuzz:\n Fuzzer guidance | Blocks | Edges | Edge hit | Highest-coverage strategy used | reached | reached | cnt var | test case generated ------------------+---------+---------+----------+--------------------------- (Initial file) | 156 | 163 | 1.00 | (none) | | | | Blind fuzzing S | 182 | 205 | 2.23 | First 2 B of RCS diff Blind fuzzing L | 228 | 265 | 2.23 | First 4 B of -c mode diff Block coverage | 855 | 1,130 | 1.57 | Almost-valid RCS diff Edge coverage | 1,452 | 2,070 | 2.18 | One-chunk -c mode diff AFL model | 1,765 | 2,597 | 4.99 | Four-chunk -c mode diff The first entry for blind fuzzing (\u0026ldquo;S\u0026rdquo;) corresponds to executing just a single round of testing; the second set of figures (\u0026ldquo;L\u0026rdquo;) shows the fuzzer running in a loop for a number of execution cycles comparable with that of the instrumented runs, which required more time to fully process the growing queue.\nRoughly similar results have been obtained in a separate experiment where the fuzzer was modified to compile out all the random fuzzing stages and leave just a series of rudimentary, sequential operations such as walking bit flips. Because this mode would be incapable of altering the size of the input file, the sessions were seeded with a valid unified diff:\n Queue extension | Blocks | Edges | Edge hit | Number of unique strategy used | reached | reached | cnt var | crashes found ------------------+---------+---------+----------+------------------ (Initial file) | 624 | 717 | 1.00 | - | | | | Blind fuzzing | 1,101 | 1,409 | 1.60 | 0 Block coverage | 1,255 | 1,649 | 1.48 | 0 Edge coverage | 1,259 | 1,734 | 1.72 | 0 AFL model | 1,452 | 2,040 | 3.16 | 1 At noted earlier on, some of the prior work on genetic fuzzing relied on maintaining a single test case and evolving it to maximize coverage. At least in the tests described above, this \u0026ldquo;greedy\u0026rdquo; approach appears to confer no substantial benefits over blind fuzzing strategies.\n4. Culling the corpus The progressive state exploration approach outlined above means that some of the test cases synthesized later on in the game may have edge coverage that is a strict superset of the coverage provided by their ancestors.\nTo optimize the fuzzing effort, AFL periodically re-evaluates the queue using a fast algorithm that selects a smaller subset of test cases that still cover every tuple seen so far, and whose characteristics make them particularly favorable to the tool.\nThe algorithm works by assigning every queue entry a score proportional to its execution latency and file size; and then selecting lowest-scoring candidates for each tuple.\nThe tuples are then processed sequentially using a simple workflow:\n Find next tuple not yet in the temporary working set, Locate the winning queue entry for this tuple, Register all tuples present in that entry\u0026rsquo;s trace in the working set, Go to #1 if there are any missing tuples in the set.  The generated corpus of \u0026ldquo;favored\u0026rdquo; entries is usually 5-10x smaller than the starting data set. Non-favored entries are not discarded, but they are skipped with varying probabilities when encountered in the queue:\n If there are new, yet-to-be-fuzzed favorites present in the queue, 99% of non-favored entries will be skipped to get to the favored ones. If there are no new favorites:  If the current non-favored entry was fuzzed before, it will be skipped 95% of the time. If it hasn\u0026rsquo;t gone through any fuzzing rounds yet, the odds of skipping drop down to 75%.    Based on empirical testing, this provides a reasonable balance between queue cycling speed and test case diversity.\nSlightly more sophisticated but much slower culling can be performed on input or output corpora with afl-cmin. This tool permanently discards the redundant entries and produces a smaller corpus suitable for use with afl-fuzz or external tools.\n5. Trimming input files File size has a dramatic impact on fuzzing performance, both because large files make the target binary slower, and because they reduce the likelihood that a mutation would touch important format control structures, rather than redundant data blocks. This is discussed in more detail in perf_tips.md.\nThe possibility that the user will provide a low-quality starting corpus aside, some types of mutations can have the effect of iteratively increasing the size of the generated files, so it is important to counter this trend.\nLuckily, the instrumentation feedback provides a simple way to automatically trim down input files while ensuring that the changes made to the files have no impact on the execution path.\nThe built-in trimmer in afl-fuzz attempts to sequentially remove blocks of data with variable length and stepover; any deletion that doesn\u0026rsquo;t affect the checksum of the trace map is committed to disk. The trimmer is not designed to be particularly thorough; instead, it tries to strike a balance between precision and the number of execve() calls spent on the process, selecting the block size and stepover to match. The average per-file gains are around 5-20%.\nThe standalone afl-tmin tool uses a more exhaustive, iterative algorithm, and also attempts to perform alphabet normalization on the trimmed files. The operation of afl-tmin is as follows.\nFirst, the tool automatically selects the operating mode. If the initial input crashes the target binary, afl-tmin will run in non-instrumented mode, simply keeping any tweaks that produce a simpler file but still crash the target. The same mode is used for hangs, if -H (hang mode) is specified. If the target is non-crashing, the tool uses an instrumented mode and keeps only the tweaks that produce exactly the same execution path.\nThe actual minimization algorithm is:\n Attempt to zero large blocks of data with large stepovers. Empirically, this is shown to reduce the number of execs by preempting finer-grained efforts later on. Perform a block deletion pass with decreasing block sizes and stepovers, binary-search-style. Perform alphabet normalization by counting unique characters and trying to bulk-replace each with a zero value. As a last result, perform byte-by-byte normalization on non-zero bytes.  Instead of zeroing with a 0x00 byte, afl-tmin uses the ASCII digit \u0026lsquo;0\u0026rsquo;. This is done because such a modification is much less likely to interfere with text parsing, so it is more likely to result in successful minimization of text files.\nThe algorithm used here is less involved than some other test case minimization approaches proposed in academic work, but requires far fewer executions and tends to produce comparable results in most real-world applications.\n6. Fuzzing strategies The feedback provided by the instrumentation makes it easy to understand the value of various fuzzing strategies and optimize their parameters so that they work equally well across a wide range of file types. The strategies used by afl-fuzz are generally format-agnostic and are discussed in more detail here:\nhttp://lcamtuf.blogspot.com/2014/08/binary-fuzzing-strategies-what-works.html\nIt is somewhat notable that especially early on, most of the work done by afl-fuzz is actually highly deterministic, and progresses to random stacked modifications and test case splicing only at a later stage. The deterministic strategies include:\n Sequential bit flips with varying lengths and stepovers, Sequential addition and subtraction of small integers, Sequential insertion of known interesting integers (0, 1, INT_MAX, etc),  The purpose of opening with deterministic steps is related to their tendency to produce compact test cases and small diffs between the non-crashing and crashing inputs.\nWith deterministic fuzzing out of the way, the non-deterministic steps include stacked bit flips, insertions, deletions, arithmetics, and splicing of different test cases.\nThe relative yields and execve() costs of all these strategies have been investigated and are discussed in the aforementioned blog post.\nFor the reasons discussed in historical_notes.md (chiefly, performance, simplicity, and reliability), AFL generally does not try to reason about the relationship between specific mutations and program states; the fuzzing steps are nominally blind, and are guided only by the evolutionary design of the input queue.\nThat said, there is one (trivial) exception to this rule: when a new queue entry goes through the initial set of deterministic fuzzing steps, and tweaks to some regions in the file are observed to have no effect on the checksum of the execution path, they may be excluded from the remaining phases of deterministic fuzzing - and the fuzzer may proceed straight to random tweaks. Especially for verbose, human-readable data formats, this can reduce the number of execs by 10-40% or so without an appreciable drop in coverage. In extreme cases, such as normally block-aligned tar archives, the gains can be as high as 90%.\nBecause the underlying \u0026ldquo;effector maps\u0026rdquo; are local every queue entry and remain in force only during deterministic stages that do not alter the size or the general layout of the underlying file, this mechanism appears to work very reliably and proved to be simple to implement.\n7. Dictionaries The feedback provided by the instrumentation makes it easy to automatically identify syntax tokens in some types of input files, and to detect that certain combinations of predefined or auto-detected dictionary terms constitute a valid grammar for the tested parser.\nA discussion of how these features are implemented within afl-fuzz can be found here:\nhttp://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html\nIn essence, when basic, typically easily-obtained syntax tokens are combined together in a purely random manner, the instrumentation and the evolutionary design of the queue together provide a feedback mechanism to differentiate between meaningless mutations and ones that trigger new behaviors in the instrumented code - and to incrementally build more complex syntax on top of this discovery.\nThe dictionaries have been shown to enable the fuzzer to rapidly reconstruct the grammar of highly verbose and complex languages such as JavaScript, SQL, or XML; several examples of generated SQL statements are given in the blog post mentioned above.\nInterestingly, the AFL instrumentation also allows the fuzzer to automatically isolate syntax tokens already present in an input file. It can do so by looking for run of bytes that, when flipped, produce a consistent change to the program\u0026rsquo;s execution path; this is suggestive of an underlying atomic comparison to a predefined value baked into the code. The fuzzer relies on this signal to build compact \u0026ldquo;auto dictionaries\u0026rdquo; that are then used in conjunction with other fuzzing strategies.\n8. De-duping crashes De-duplication of crashes is one of the more important problems for any competent fuzzing tool. Many of the naive approaches run into problems; in particular, looking just at the faulting address may lead to completely unrelated issues being clustered together if the fault happens in a common library function (say, strcmp, strcpy); while checksumming call stack backtraces can lead to extreme crash count inflation if the fault can be reached through a number of different, possibly recursive code paths.\nThe solution implemented in afl-fuzz considers a crash unique if any of two conditions are met:\n The crash trace includes a tuple not seen in any of the previous crashes, The crash trace is missing a tuple that was always present in earlier faults.  The approach is vulnerable to some path count inflation early on, but exhibits a very strong self-limiting effect, similar to the execution path analysis logic that is the cornerstone of afl-fuzz.\n9. Investigating crashes The exploitability of many types of crashes can be ambiguous; afl-fuzz tries to address this by providing a crash exploration mode where a known-faulting test case is fuzzed in a manner very similar to the normal operation of the fuzzer, but with a constraint that causes any non-crashing mutations to be thrown away.\nA detailed discussion of the value of this approach can be found here:\nhttp://lcamtuf.blogspot.com/2014/11/afl-fuzz-crash-exploration-mode.html\nThe method uses instrumentation feedback to explore the state of the crashing program to get past the ambiguous faulting condition and then isolate the newly-found inputs for human review.\nOn the subject of crashes, it is worth noting that in contrast to normal queue entries, crashing inputs are not trimmed; they are kept exactly as discovered to make it easier to compare them to the parent, non-crashing entry in the queue. That said, afl-tmin can be used to shrink them at will.\n10 The fork server To improve performance, afl-fuzz uses a \u0026ldquo;fork server\u0026rdquo;, where the fuzzed process goes through execve(), linking, and libc initialization only once, and is then cloned from a stopped process image by leveraging copy-on-write. The implementation is described in more detail here:\nhttp://lcamtuf.blogspot.com/2014/10/fuzzing-binaries-without-execve.html\nThe fork server is an integral aspect of the injected instrumentation and simply stops at the first instrumented function to await commands from afl-fuzz.\nWith fast targets, the fork server can offer considerable performance gains, usually between 1.5x and 2x. It is also possible to:\n Use the fork server in manual (\u0026ldquo;deferred\u0026rdquo;) mode, skipping over larger, user-selected chunks of initialization code. It requires very modest code changes to the targeted program, and With some targets, can produce 10x+ performance gains. Enable \u0026ldquo;persistent\u0026rdquo; mode, where a single process is used to try out multiple inputs, greatly limiting the overhead of repetitive fork() calls. This generally requires some code changes to the targeted program, but can improve the performance of fast targets by a factor of 5 or more - approximating the benefits of in-process fuzzing jobs while still maintaining very robust isolation between the fuzzer process and the targeted binary.  11. Parallelization The parallelization mechanism relies on periodically examining the queues produced by independently-running instances on other CPU cores or on remote machines, and then selectively pulling in the test cases that, when tried out locally, produce behaviors not yet seen by the fuzzer at hand.\nThis allows for extreme flexibility in fuzzer setup, including running synced instances against different parsers of a common data format, often with synergistic effects.\nFor more information about this design, see parallel_fuzzing.md.\n12. Binary-only instrumentation Instrumentation of black-box, binary-only targets is accomplished with the help of a separately-built version of QEMU in \u0026ldquo;user emulation\u0026rdquo; mode. This also allows the execution of cross-architecture code - say, ARM binaries on x86.\nQEMU uses basic blocks as translation units; the instrumentation is implemented on top of this and uses a model roughly analogous to the compile-time hooks:\nif (block_address \u0026gt; elf_text_start \u0026amp;\u0026amp; block_address \u0026lt; elf_text_end) { cur_location = (block_address \u0026gt;\u0026gt; 4) ^ (block_address \u0026lt;\u0026lt; 8); shared_mem[cur_location ^ prev_location]++; prev_location = cur_location \u0026gt;\u0026gt; 1; } The shift-and-XOR-based scrambling in the second line is used to mask the effects of instruction alignment.\nThe start-up of binary translators such as QEMU, DynamoRIO, and PIN is fairly slow; to counter this, the QEMU mode leverages a fork server similar to that used for compiler-instrumented code, effectively spawning copies of an already-initialized process paused at _start.\nFirst-time translation of a new basic block also incurs substantial latency. To eliminate this problem, the AFL fork server is extended by providing a channel between the running emulator and the parent process. The channel is used to notify the parent about the addresses of any newly-encountered blocks and to add them to the translation cache that will be replicated for future child processes.\nAs a result of these two optimizations, the overhead of the QEMU mode is roughly 2-5x, compared to 100x+ for PIN.\n13. The afl-analyze tool The file format analyzer is a simple extension of the minimization algorithm discussed earlier on; instead of attempting to remove no-op blocks, the tool performs a series of walking byte flips and then annotates runs of bytes in the input file.\nIt uses the following classification scheme:\n \u0026ldquo;No-op blocks\u0026rdquo; - segments where bit flips cause no apparent changes to control flow. Common examples may be comment sections, pixel data within a bitmap file, etc. \u0026ldquo;Superficial content\u0026rdquo; - segments where some, but not all, bitflips produce some control flow changes. Examples may include strings in rich documents (e.g., XML, RTF). \u0026ldquo;Critical stream\u0026rdquo; - a sequence of bytes where all bit flips alter control flow in different but correlated ways. This may be compressed data, non-atomically compared keywords or magic values, etc. \u0026ldquo;Suspected length field\u0026rdquo; - small, atomic integer that, when touched in any way, causes a consistent change to program control flow, suggestive of a failed length check. \u0026ldquo;Suspected cksum or magic int\u0026rdquo; - an integer that behaves similarly to a length field, but has a numerical value that makes the length explanation unlikely. This is suggestive of a checksum or other \u0026ldquo;magic\u0026rdquo; integer. \u0026ldquo;Suspected checksummed block\u0026rdquo; - a long block of data where any change always triggers the same new execution path. Likely caused by failing a checksum or a similar integrity check before any subsequent parsing takes place. \u0026ldquo;Magic value section\u0026rdquo; - a generic token where changes cause the type of binary behavior outlined earlier, but that doesn\u0026rsquo;t meet any of the other criteria. May be an atomically compared keyword or so.  "});index.add({'id':27,'href':'/docs/tutorials/libxml2_tutorial/','title':"Libxml2 Tutorial",'content':"Fuzzing libxml2 with AFL++ Before starting, build AFL++ LLVM mode and QEMU mode.\nI assume that the path to AFL++ is ~/AFLplusplus, change it in the commands if your installation path is different.\nDownload the source of libxml2 with\n$ git clone https://gitlab.gnome.org/GNOME/libxml2.git $ cd libxml2 Now configure it disabling the shared libraries\n$ ./autogen.sh $ ./configure --enable-shared=no If you want to enable the sanitizers, use the proper env var.\nIn this tutorial, we will enable ASan and UBSan.\n$ export AFL_USE_UBSAN=1 $ export AFL_USE_ASAN=1 Build the library using the clang wrappers\n$ make CC=~/AFLplusplus/afl-clang-fast CXX=~/AFLplusplus/afl-clang-fast++ LD=~/AFLplusplus/afl-clang-fast When the job is completed, we start to fuzz libxml2 using the tool xmllint as harness and take some testcases from the test folder as initial seeds.\n$ mkdir fuzz $ cp xmllint fuzz/xmllint_cov $ mkdir fuzz/in $ cp test/*.xml fuzz/in/ $ cd fuzz Make sure to configure your system with our script before start afl-fuzz\n$ sudo ~/AFLplusplus/afl-system-config Here we are!\n$ ~/AFLplusplus/afl-fuzz -i in/ -o out -m none -d -- ./xmllint_cov @@ Beware of the -m none. We built it using AddressSanitizer that maps a lot of pages for the shadow memory so we have to remove the memory limit to have it up and running.\nXML is a highly structured input so -d is a good choice. It enables FidgetyAFL, a modality that skips the deterministic stages (that are well suited for binary formats) in favor of the random stages.\nNow, knowing that libxml2 is a library and so the code is reentrant, we can speedup our fuzzing process using persistent mode.\nPersistent mode avoids the overhead of forking and gives a lot of speedup.\nTo enable it, we have to choose a reentrant routine and set up a persistent loop patching the code.\ndiff --git a/xmllint.c b/xmllint.c index 735d951d..64725e9c 100644 --- a/xmllint.c +++ b/xmllint.c @@ -3102,8 +3102,19 @@ static void deregisterNode(xmlNodePtr node)  nbregister--; } +int main(int argc, char** argv) { + + if (argc \u0026lt; 2) return 1; + + while (__AFL_LOOP(10000)) + parseAndPrintFile(argv[1], NULL); + + return 0; + +} +  int -main(int argc, char **argv) { +old_main(int argc, char **argv) {  int i, acount; int files = 0; int version = 0; In this case, I choose parseAndPrintFile, the main parsing routine called from the xmllint main. As you can see, I created a new main function that loops around that function.\n__AFL_LOOP is the way that we have to tell AFL++ that we want persistent mode. Each fuzzing iteration, instead of to fork and re-execute the target with a different input, is just an execution of this loop.\nThe number 10000 tells that after 10000 runs with fuzzed inputs generated by AFL++ the harness has to fork and reset the state of the target. This is useful when the fuzzed routine is reentrant but, for example, has memory leaks and so we want to restore the target after a fixed number of executions to avoid filling the heap with useless allocated memory.\nTo build it, just remove the previously compiled xmllint and recompile it.\n$ cd .. $ rm xmllint $ make CC=~/AFLplusplus/afl-clang-fast CXX=~/AFLplusplus/afl-clang-fast++ LD=~/AFLplusplus/afl-clang-fast $ cp xmllint fuzz/xmllint_persistent Now restart the fuzzer\n$ cd fuzz $ ~/AFLplusplus/afl-fuzz -i in/ -o out -m none -d -- ./xmllint_persistent @@ As you can see, the speedup is impressive.\nNow we\u0026rsquo;ll fuzz xmllint using the binary-only instrumentation with QEMU.\nWe will act as if we don\u0026rsquo;t have the source code and therefore we will not patch anything in the source.\nFirstly, build an uninstrumented binary. Remind to revert the applied patch for LLVM persistent before proceed.\n$ cd ... $ make clean $ make $ cp xmllint fuzz/ To fuzz it in the simple fork-based fashion under QEMU, just add the -Q flag to afl-fuzz.\n$ cd fuzz $ ~/AFLplusplus/afl-fuzz -i in/ -o out -m none -d -Q -- ./xmllint @@ You\u0026rsquo;ve probably noticed that the speed is faster than the LLVM fork-based fuzzing. This is because we used ASan+UBSan in the previous steps based on LLVM (so a 2x slowdown in average).\nNote that so the slowdown of QEMU is circa 2x in this specific case, quite good.\nBut what if we want the speed of persistent mode for a closed source binary?\nNo pain, there is QEMU persistent mode, a new feature introduced in AFL++.\nThere are two possibilities in persistent QEMU, loop around a function (like WinAFL) or loop around a specific portion of code.\nIn this tutorial, we will go for the easy path, we will loop around parseAndPrintFile.\nFirstly, locate the address of the function:\n$ nm xmllint | grep parseAndPrintFile 0000000000019be0 t parseAndPrintFile The binary is position independent and QEMU persistent needs the real addresses, not the offsets. Fortunately, QEMU loads PIE executables at a fixed address, 0x4000000000 for x86_64.\nWe can check it using AFL_QEMU_DEBUG_MAPS. You don\u0026rsquo;t need this step if your binary is not PIE.\n$ AFL_QEMU_DEBUG_MAPS=1 ~/AFLplusplus/afl-qemu-trace ./xmllint - 4000000000-400013e000 r-xp 00000000 103:06 18676576 /home/andrea/libxml2/fuzz/xmllint 400013e000-400033e000 ---p 00000000 00:00 0 400033e000-4000346000 r--p 0013e000 103:06 18676576 /home/andrea/libxml2/fuzz/xmllint 4000346000-4000347000 rw-p 00146000 103:06 18676576 /home/andrea/libxml2/fuzz/xmllint 4000347000-4000355000 rw-p 00000000 00:00 0 ... Now, we set the address of the function that has to loop\n$ export AFL_QEMU_PERSISTENT_ADDR=0x4000019be0 We are on x86_64 and the parameters are passed in the registers. When, at the end of the function, we return to the starting address, the registers are clobbered so we don\u0026rsquo;t have anymore the pointer to the filename in rdi.\nTo avoid that, we can save and restore the state of the general-purpose registers at each iteration setting AFL_QEMU_PERSISTENT_GPR.\n$ export AFL_QEMU_PERSISTENT_GPR=1 Here we go, rerun the previous afl-fuzz command:\n$ ~/AFLplusplus/afl-fuzz -i in/ -o out -m none -d -Q -- ./xmllint @@ As for persistent LLVM, the speedup is incredible.\nEnjoy AFL++, stay tuned for other beginners tutorial of this kind in the future.\nAndrea.\n"});index.add({'id':28,'href':'/categories/','title':"Categories",'content':""});index.add({'id':29,'href':'/tags/','title':"Tags",'content':""});index.add({'id':30,'href':'/','title':"The AFL++ fuzzing framework",'content':"AFL++ Overview AFLplusplus is the son of the American Fuzzy Lop fuzzer by Michal \u0026ldquo;lcamtuf\u0026rdquo; Zalewski and was created initially to incorporate all the best features developed in the years for the fuzzers in the AFL family and not merged in AFL cause it is not updated since November 2017.\nThe AFL++ fuzzing framework includes the following:\n A fuzzer with many mutators and configurations: afl-fuzz. Different source code instrumentation modules: LLVM mode, afl-as, GCC plugin. Different binary code instrumentation modules: QEMU mode, Unicorn mode, QBDI mode. Utilities for testcase/corpus minimization: afl-tmin, afl-cmin. Helper libraries: libtokencap, libdislocator, libcompcov.  It includes a lot of changes, optimizations and new features respect to AFL like the AFLfast power schedules, QEMU 3.1 upgrade with CompareCoverage, MOpt mutators, InsTrim instrumentation and a lot more.\nSee the Features page.\nIf you are a student or enthusiast developer and want to contribute, we have an idea list what would be cool to have! :-)\nIt is maintained by Marc \u0026ldquo;van Hauser\u0026rdquo; Heuse mh@mh-sec.de, Heiko \u0026ldquo;hexcoder-\u0026rdquo; Eißfeldt heiko.eissfeldt@hexco.de, Andrea Fioraldi andreafioraldi@gmail.com and Dominik Maier mail@dmnk.co.\nCheck out the GitHub repository here.\nTrophies  VLC  CVE-2019-14437 CVE-2019-14438 CVE-2019-14498 CVE-2019-14533 CVE-2019-14534 CVE-2019-14535 CVE-2019-14776 CVE-2019-14777 CVE-2019-14778 CVE-2019-14779 CVE-2019-14970 by Antonio Morales (GitHub Security Lab)   Sqlite  CVE-2019-16168 by Xingwei Lin   Vim  CVE-2019-20079 by Dhiraj (blog)   Tcpdump  CVE-2020-8036 by Reza Mirzazade   Gifsicle  Issue 130 by Ashish Kunwar   FFmpeg  Ticket 8592 Ticket 8593 Ticket 8594 Ticket 8596 by Andrea Fioraldi    "});})();