diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Changelog.md | 62 | ||||
| -rw-r--r-- | docs/PATCHES.md | 1 | ||||
| -rw-r--r-- | docs/custom_mutators.md | 34 | ||||
| -rw-r--r-- | docs/env_variables.md | 100 | ||||
| -rw-r--r-- | docs/ideas.md | 2 | ||||
| -rw-r--r-- | docs/notes_for_asan.md | 4 | ||||
| -rw-r--r-- | docs/power_schedules.md | 1 | ||||
| -rw-r--r-- | docs/status_screen.md | 54 |
8 files changed, 181 insertions, 77 deletions
diff --git a/docs/Changelog.md b/docs/Changelog.md index e1f3cd7e..108ebd08 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -9,27 +9,65 @@ Want to stay in the loop on major new features? Join our mailing list by sending a mail to <afl-users+subscribe@googlegroups.com>. -### Version ++2.62d (develop): - +### Version ++2.63d (development): + - llvm_mode LTO mode: + - now requires llvm11 - but compiles all targets! :) + - autodictionary feature added, enable with AFL_LLVM_LTO_AUTODICTIONARY + - variable map size usage + - afl-fuzz: + - variable map size support added (only LTO mode can use this) + - snapshot feature usage now visible in UI + - compare-transform/AFL_LLVM_LAF_TRANSFORM_COMPARES now transforms also + static global and local variable comparisons (cannot find all though) + - extended forkserver: map_size and more information is communicated to + afl-fuzz (and afl-fuzz acts accordingly) + - more refactoring + - if AFL_CC/AFL_CXX is set but empty afl compilers did fail, fixed + (this bug is in vanilla afl too) + + +### Version ++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 - all: - - big code changes to make afl-fuzz thread-safe so afl-fuzz can spawn + - 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 ("fauxserver") + - 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 schedule -p mmopt that ignores the runtime of - queue entries and gives higher weighting to the last 5 queue entries - it is currently experimental and subject to change but preliminary - results are good + - 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't compile + this mode is amazing but requires you to build llvm 11 yourself + - Added llvm_mode NGRAM prev_loc coverage by Adrean Herrera + (https://github.com/adrianherrera/afl-ngram-pass/), activate by setting + AFL_LLVM_INSTRUMENT=NGRAM-<value> or AFL_LLVM_NGRAM_SIZE=<value> + - 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 + - removed workaround for bug where paths were not instrumented and imported fix by author - - made skipping 1 block functions an option and is disable by default, + - 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 @@ -39,6 +77,8 @@ sending a mail to <afl-users+subscribe@googlegroups.com>. - 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): @@ -192,7 +232,7 @@ sending a mail to <afl-users+subscribe@googlegroups.com>. - big code refactoring: * all includes are now in include/ - * all afl sources are now in src/ - see src/README.src + * 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. diff --git a/docs/PATCHES.md b/docs/PATCHES.md index 1dfb6622..a6783523 100644 --- a/docs/PATCHES.md +++ b/docs/PATCHES.md @@ -20,6 +20,7 @@ afl-qemu-speed.diff by abiondo on github afl-qemu-optimize-map.diff by 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 diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md index 14d8f518..49ce761e 100644 --- a/docs/custom_mutators.md +++ b/docs/custom_mutators.md @@ -27,18 +27,16 @@ performed with the custom mutator. C/C++: ```c -void afl_custom_init(unsigned int seed); -size_t afl_custom_fuzz(uint8_t** buf, size_t buf_size, uint8_t* add_buf, - size_t add_buf_size, size_t max_size); -size_t afl_custom_pre_save(uint8_t* buf, size_t buf_size, uint8_t** out_buf); -uint32_t afl_custom_init_trim(uint8_t* buf, size_t buf_size); -void afl_custom_trim(uint8_t** out_buf, size_t* out_buf_size); -uint32_t afl_custom_post_trim(uint8_t success); -size_t afl_custom_havoc_mutation(uint8_t** buf, size_t buf_size, size_t max_size); -uint8_t afl_custom_havoc_mutation_probability(void); -uint8_t afl_custom_queue_get(const uint8_t* filename); -void afl_custom_queue_new_entry(const uint8_t* filename_new_queue, - const uint8_t* filename_orig_queue); +void *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: @@ -76,9 +74,9 @@ def queue_new_entry(filename_new_queue, filename_orig_queue): ### Custom Mutation -- `init` (optional): +- `init`: - This method is called when AFL++ starts up and is used to seed RNG. + This method is called when AFL++ starts up and is used to seed RNG and set up buffers and state. - `queue_get` (optional): @@ -110,7 +108,7 @@ def queue_new_entry(filename_new_queue, filename_orig_queue): - `queue_new_entry` (optional): - This methods is called after adding a new test case to the queue. + This methods is called after adding a new test case to the queue. ### Trimming Support @@ -144,7 +142,7 @@ trimmed input. Here's a quick API description: This method is called for each trimming operation. It doesn'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 + 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 @@ -158,6 +156,8 @@ trimmed input. Here's a quick API description: 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`). +`deinit` the last method to be called, deinitializing the state. + Omitting any of three methods will cause the trimming to be disabled and trigger a fallback to the builtin default trimming routine. @@ -166,7 +166,7 @@ a fallback to the builtin default trimming routine. Optionally, the following environment variables are supported: - `AFL_CUSTOM_MUTATOR_ONLY` - + Disable all other mutation stages. This can prevent broken testcases (those that your Python module can't work with anymore) to fill up your queue. Best combined with a custom trimming routine (see below) because diff --git a/docs/env_variables.md b/docs/env_variables.md index 8c7510cd..7890da35 100644 --- a/docs/env_variables.md +++ b/docs/env_variables.md @@ -31,7 +31,9 @@ tools make fairly broad use of environmental variables: (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) + 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) - Setting AFL_CC, AFL_CXX, and AFL_AS lets you use alternate downstream compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries @@ -91,25 +93,81 @@ of the settings discussed in section #1, with the exception of: Then there are a few specific features that are only available in llvm_mode: +### Select the instrumentation mode + + - AFL_LLVM_INSTRUMENT - this configures the instrumentation mode. + Available options: + DEFAULT - classic AFL (map[cur_loc ^ prev_loc >> 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. + 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 11 or newer is used. + + - AFL_LLVM_LTO_AUTODICTIONARY will generate a dictionary in the target + binary based on string compare and memory compare functions. + afl-fuzz will automatically get these transmitted when starting to + fuzz. -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. + None of the following 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 @@ -134,23 +192,6 @@ are then later combined. See llvm_mode/README.whitelist.md for more information. -### INSTRIM - - This feature increases the speed by whopping 20% but at the cost of a - lower path discovery and therefore coverage. - - - Setting AFL_LLVM_INSTRIM 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 - ### NOT_ZERO - Setting AFL_LLVM_NOT_ZERO=1 during compilation will use counters @@ -221,6 +262,9 @@ checks or alter some of the more exotic semantics of the tool: - 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. + - AFL_NO_SNAPSHOT will advice afl-fuzz not to use the snapshot feature + if the snapshot lkm is loaded + - AFL_SHUFFLE_QUEUE randomly reorders the input queue on startup. Requested by some users for unorthodox parallelized fuzzing setups, but not advisable otherwise. diff --git a/docs/ideas.md b/docs/ideas.md index 44dcccb2..686c262d 100644 --- a/docs/ideas.md +++ b/docs/ideas.md @@ -33,7 +33,7 @@ This is an excellent mutations scheduler based on Particle Swarm Optimization but the current implementation schedule only the mutations that were present on AFL. -AFL++ added a lost of optional mutators like the Input-2-State one based +AFL++ 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. diff --git a/docs/notes_for_asan.md b/docs/notes_for_asan.md index feac49f9..6a4806c0 100644 --- a/docs/notes_for_asan.md +++ b/docs/notes_for_asan.md @@ -28,6 +28,10 @@ Note that ASAN is incompatible with -static, so be mindful of that. (You can also use AFL_USE_MSAN=1 to enable MSAN instead.) +NOTE: 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. + There 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 diff --git a/docs/power_schedules.md b/docs/power_schedules.md index cdada0f6..c69c64d2 100644 --- a/docs/power_schedules.md +++ b/docs/power_schedules.md @@ -20,6 +20,7 @@ We find that AFL's exploitation-based constant schedule assigns **too much energ | `-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)>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'16)](https://www.sigsac.org/ccs/CCS2016/accepted-papers/). diff --git a/docs/status_screen.md b/docs/status_screen.md index 0bc636c4..a66558b9 100644 --- a/docs/status_screen.md +++ b/docs/status_screen.md @@ -372,26 +372,40 @@ 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: - - `start_time` - unix time indicating the start time of afl-fuzz - - `last_update` - unix time corresponding to the last update of this file - - `fuzzer_pid` - PID of the fuzzer process - - `cycles_done` - queue cycles completed so far - - `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_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 - - `stability - percentage of bitmap bytes that behave consistently - - `variable_paths` - number of test cases showing variable behavior - - `unique_crashes` - number of unique crashes recorded - - `unique_hangs` - number of unique hangs encountered - - `command_line` - full command line used for the fuzzing session - - `slowest_exec_ms`- real time of the slowest execution in seconds - - `peak_rss_mb` - max rss usage reached during fuzzing in MB + - `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. |