From 1a57253a1c63315b5af8fdbe5081492ce0603278 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Thu, 25 Nov 2021 16:33:29 +0100 Subject: Edit QEMU mode READMEs --- qemu_mode/README.persistent.md | 141 +++++++++++++++++++++-------------------- 1 file changed, 71 insertions(+), 70 deletions(-) (limited to 'qemu_mode/README.persistent.md') diff --git a/qemu_mode/README.persistent.md b/qemu_mode/README.persistent.md index 2ca5c873..7210a8cc 100644 --- a/qemu_mode/README.persistent.md +++ b/qemu_mode/README.persistent.md @@ -2,118 +2,118 @@ ## 1) Introduction -Persistent mode lets you fuzz your target persistently between two -addresses - without forking for every fuzzing attempt. -This increases the speed by a factor between x2 and x5, hence it is -very, very valuable. +Persistent mode lets you fuzz your target persistently between two addresses - +without forking for every fuzzing attempt. This increases the speed by a factor +between x2 and x5, hence it is very, very valuable. -The persistent mode is currently only available for x86/x86_64, arm -and aarch64 targets. +The persistent mode is currently only available for x86/x86_64, arm, and aarch64 +targets. ## 2) How use the persistent mode ### 2.1) The START address -The start of the persistent loop has to be set with env var AFL_QEMU_PERSISTENT_ADDR. +The start of the persistent loop has to be set with environment variable +`AFL_QEMU_PERSISTENT_ADDR`. -This address can be the address of whatever instruction. -Setting this address to the start of a function makes the usage simple. -If the address is however within a function, either RET, OFFSET or EXITS -(see below in 2.2, 2.3, 2.6) have to be set. -This address (as well as the RET address, see below) has to be defined in +This address can be the address of whatever instruction. Setting this address to +the start of a function makes the usage simple. If the address is however within +a function, either RET, OFFSET, or EXITS (see below in 2.2, 2.3, 2.6) have to be +set. This address (as well as the RET address, see below) has to be defined in hexadecimal with the 0x prefix or as a decimal value. If both RET and EXITS are not set, QEMU will assume that START points to a -function and will patch the return address (on stack or in the link register) -to return to START (like WinAFL). +function and will patch the return address (on stack or in the link register) to +return to START (like WinAFL). -*Note:* If the target is compiled with position independant code (PIE/PIC) -qemu loads these to a specific base address. -For 64 bit you have to add 0x4000000000 (9 zeroes) and for 32 bit 0x40000000 -(7 zeroes) to the address. -On strange setups the base address set by QEMU for PIE executable may change, -you can check it printing the process map using -`AFL_QEMU_DEBUG_MAPS=1 afl-qemu-trace TARGET-BINARY` +*Note:* If the target is compiled with position independent code (PIE/PIC) qemu +loads these to a specific base address. For 64 bit you have to add 0x4000000000 +(9 zeroes) and for 32 bit 0x40000000 (7 zeroes) to the address. On strange +setups the base address set by QEMU for PIE executable may change. You can check +it printing the process map using `AFL_QEMU_DEBUG_MAPS=1 afl-qemu-trace +TARGET-BINARY`. If this address is not valid, afl-fuzz will error during startup with the message that the forkserver was not found. ### 2.2) The RET address -The RET address is the last instruction of the persistent loop. -The emulator will emit a jump to START when translating the instruction at RET. -It is optional, and only needed if the return should not be -at the end of the function to which the START address points into, but earlier. +The RET address is the last instruction of the persistent loop. The emulator +will emit a jump to START when translating the instruction at RET. It is +optional and only needed if the return should not be at the end of the function +to which the START address points into, but earlier. -It is defined by setting AFL_QEMU_PERSISTENT_RET, and too 0x4000000000 has to -be set if the target is position independant. +It is defined by setting `AFL_QEMU_PERSISTENT_RET`, and too 0x4000000000 has to +be set if the target is position independent. ### 2.3) The OFFSET This option is valid only for x86/x86_64 only, arm/aarch64 do not save the return address on stack. -If the START address is *not* the beginning of a function, and *no* RET has -been set (so the end of the loop will be at the end of the function but START -will not be at the beginning of it), we need an offset from the ESP pointer -to locate the return address to patch. +If the START address is *not* the beginning of a function, and *no* RET has been +set (so the end of the loop will be at the end of the function but START will +not be at the beginning of it), we need an offset from the ESP pointer to locate +the return address to patch. The value by which the ESP pointer has to be corrected has to be set in the -variable AFL_QEMU_PERSISTENT_RETADDR_OFFSET. +variable `AFL_QEMU_PERSISTENT_RETADDR_OFFSET`. Now to get this value right here is some help: -1. use gdb on the target -2. set a breakpoint to "main" (this is required for PIE/PIC binaries so the - addresses are set up) -3. "run" the target with a valid commandline -4. set a breakpoint to the function in which START is contained -5. set a breakpoint to your START address -6. "continue" to the function start breakpoint -6. print the ESP value with `print $esp` and take note of it -7. "continue" the target until the second breakpoint -8. again print the ESP value -9. calculate the difference between the two values - and this is the offset +1. Use gdb on the target. +2. Set a breakpoint to "main" (this is required for PIE/PIC binaries so the + addresses are set up). +3. "run" the target with a valid commandline. +4. Set a breakpoint to the function in which START is contained. +5. Set a breakpoint to your START address. +6. "continue" to the function start breakpoint. +7. Print the ESP value with `print $esp` and take note of it. +8. "continue" the target until the second breakpoint. +9. Again print the ESP value. +10. Calculate the difference between the two values - and this is the offset. ### 2.4) Resetting the register state It is very, very likely you need to restore the general purpose registers state when starting a new loop. Because of this 99% of the time you should set +``` AFL_QEMU_PERSISTENT_GPR=1 +``` -An example is when you want to use main() as persistent START: +An example is when you want to use `main()` as persistent START: ```c int main(int argc, char **argv) { if (argc < 2) return 1; - + // do stuff } ``` -If you don't save and restore the registers in x86_64, the parameter `argc` -will be lost at the second execution of the loop. +If you don't save and restore the registers in x86_64, the parameter `argc` will +be lost at the second execution of the loop. ### 2.5) Resetting the memory state This option restores the memory state using the AFL++ Snapshot LKM if loaded. Otherwise, all the writeable pages are restored. -To enable this option, set AFL_QEMU_PERSISTENT_MEM=1. +To enable this option, set `AFL_QEMU_PERSISTENT_MEM=1`. ### 2.6) Reset on exit() The user can force QEMU to set the program counter to START instead of executing the exit_group syscall and exit the program. -The env variable is AFL_QEMU_PERSISTENT_EXITS. +The environment variable is `AFL_QEMU_PERSISTENT_EXITS`. ### 2.7) Snapshot -AFL_QEMU_SNAPSHOT=address is just a "syntactical sugar" env variable that is equivalent to -the following set of variables: +`AFL_QEMU_SNAPSHOT=address` is just a "syntactical sugar" environment variable +that is equivalent to the following set of variables: ``` AFL_QEMU_PERSISTENT_ADDR=address @@ -127,26 +127,27 @@ AFL_QEMU_PERSISTENT_EXITS=1 ### 3.1) Loop counter value The more stable your loop in the target, the longer you can run it, the more -unstable it is the lower the loop count should be. A low value would be 100, -the maximum value should be 10000. The default is 1000. -This value can be set with AFL_QEMU_PERSISTENT_CNT +unstable it is the lower the loop count should be. A low value would be 100, the +maximum value should be 10000. The default is 1000. This value can be set with +`AFL_QEMU_PERSISTENT_CNT`. -This is the same concept as in the llvm_mode persistent mode with __AFL_LOOP(). +This is the same concept as in the llvm_mode persistent mode with +`__AFL_LOOP()`. ### 3.2) A hook for in-memory fuzzing -You can increase the speed of the persistent mode even more by bypassing all -the reading of the fuzzing input via a file by reading directly into the -memory address space of the target process. +You can increase the speed of the persistent mode even more by bypassing all the +reading of the fuzzing input via a file by reading directly into the memory +address space of the target process. All this needs is that the START address has a register that can reach the -memory buffer or that the memory buffer is at a known location. You probably need -the value of the size of the buffer (maybe it is in a register when START is -hit). +memory buffer or that the memory buffer is at a known location. You probably +need the value of the size of the buffer (maybe it is in a register when START +is hit). -The persistent hook will execute a function on every persistent iteration -(at the start START) defined in a shared object specified with -AFL_QEMU_PERSISTENT_HOOK=/path/to/hook.so. +The persistent hook will execute a function on every persistent iteration (at +the start START) defined in a shared object specified with +`AFL_QEMU_PERSISTENT_HOOK=/path/to/hook.so`. The signature is: @@ -157,8 +158,8 @@ void afl_persistent_hook(struct ARCH_regs *regs, uint32_t input_buf_len); ``` -Where ARCH is one of x86, x86_64, arm or arm64. -You have to include `path/to/qemuafl/qemuafl/api.h`. +Where ARCH is one of x86, x86_64, arm or arm64. You have to include +`path/to/qemuafl/qemuafl/api.h`. In this hook, you can inspect and change the saved GPR state at START. @@ -168,8 +169,8 @@ with: `int afl_persistent_hook_init(void);` If this routine returns true, the shared mem fuzzing feature of AFL++ is used -and so the input_buf variables of the hook becomes meaningful. Otherwise, -you have to read the input from a file like stdin. +and so the input_buf variables of the hook becomes meaningful. Otherwise, you +have to read the input from a file like stdin. -An example that you can use with little modification for your target can -be found here: [utils/qemu_persistent_hook](../utils/qemu_persistent_hook) +An example that you can use with little modification for your target can be +found here: [utils/qemu_persistent_hook](../utils/qemu_persistent_hook) \ No newline at end of file -- cgit 1.4.1 From a7694e299a331bd8c4826b2402ee68cd6f83d8f9 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Thu, 2 Dec 2021 20:45:48 +0100 Subject: Fix punctuation in connection with "however" --- docs/FAQ.md | 10 +++++++--- docs/best_practices.md | 27 ++++++++++++++++++--------- docs/custom_mutators.md | 10 +++++----- docs/fuzzing_in_depth.md | 10 +++++----- docs/important_changes.md | 4 ++-- instrumentation/README.llvm.md | 11 ++++++----- qemu_mode/README.persistent.md | 8 ++++---- qemu_mode/libcompcov/README.md | 8 ++++---- utils/afl_network_proxy/README.md | 13 +++++++------ utils/afl_untracer/README.md | 6 +++--- 10 files changed, 61 insertions(+), 46 deletions(-) (limited to 'qemu_mode/README.persistent.md') diff --git a/docs/FAQ.md b/docs/FAQ.md index ae4a77dc..49444999 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -12,7 +12,9 @@ If you find an interesting or important question missing, submit it via American Fuzzy Lop (AFL) was developed by Michał "lcamtuf" Zalewski starting in 2013/2014, and when he left Google end of 2017 he stopped developing it. - At the end of 2019, the Google fuzzing team took over maintenance of AFL, however it is only accepting PRs from the community and is not developing enhancements anymore. + At the end of 2019, the Google fuzzing team took over maintenance of AFL, + however, it is only accepting PRs from the community and is not developing + enhancements anymore. In the second quarter of 2019, 1 1/2 years later, when no further development of AFL had happened and it became clear there would none be coming, AFL++ was born, where initially community patches were collected and applied for bug fixes and enhancements. Then from various AFL spin-offs - mostly academic research - features were integrated. @@ -121,8 +123,10 @@ If you find an interesting or important question missing, submit it via Sending the same input again and again should take the exact same path through the target every time. If that is the case, the stability is 100%. - If however randomness happens, e.g. a thread reading other external data, reaction to timing, etc., then in some of the re-executions with the same data the edge coverage result will be different accross runs. - Those edges that change are then flagged "unstable". + If, however, randomness happens, e.g. a thread reading other external data, + reaction to timing, etc., then in some of the re-executions with the same data + the edge coverage result will be different accross runs. Those edges that + change are then flagged "unstable". The more "unstable" edges, the more difficult for AFL++ to identify valid new paths. diff --git a/docs/best_practices.md b/docs/best_practices.md index 979849f4..15f8870c 100644 --- a/docs/best_practices.md +++ b/docs/best_practices.md @@ -54,9 +54,11 @@ to emulate the network. This is also much faster than the real network would be. See [utils/socket_fuzzing/](../utils/socket_fuzzing/). There is an outdated AFL++ branch that implements networking if you are -desperate though: [https://github.com/AFLplusplus/AFLplusplus/tree/networking](https://github.com/AFLplusplus/AFLplusplus/tree/networking) - -however a better option is AFLnet ([https://github.com/aflnet/aflnet](https://github.com/aflnet/aflnet)) -which allows you to define network state with different type of data packets. +desperate though: +[https://github.com/AFLplusplus/AFLplusplus/tree/networking](https://github.com/AFLplusplus/AFLplusplus/tree/networking) +- however, a better option is AFLnet +([https://github.com/aflnet/aflnet](https://github.com/aflnet/aflnet)) which +allows you to define network state with different type of data packets. ## Improvements @@ -72,13 +74,16 @@ which allows you to define network state with different type of data packets. ### Improving stability -For fuzzing a 100% stable target that covers all edges is the best case. -A 90% stable target that covers all edges is however better than a 100% stable target that ignores 10% of the edges. +For fuzzing a 100% stable target that covers all edges is the best case. A 90% +stable target that covers all edges is, however, better than a 100% stable +target that ignores 10% of the edges. With instability, you basically have a partial coverage loss on an edge, with ignored functions you have a full loss on that edges. -There are functions that are unstable, but also provide value to coverage, e.g., init functions that use fuzz data as input. -If however a function that has nothing to do with the input data is the source of instability, e.g., checking jitter, or is a hash map function etc., then it should not be instrumented. +There are functions that are unstable, but also provide value to coverage, e.g., +init functions that use fuzz data as input. If, however, a function that has +nothing to do with the input data is the source of instability, e.g., checking +jitter, or is a hash map function etc., then it should not be instrumented. To be able to exclude these functions (based on AFL++'s measured stability), the following process will allow to identify functions with variable edges. @@ -116,8 +121,12 @@ Four steps are required to do this and it also requires quite some knowledge of If `PCGUARD` is used, then you need to follow this guide (needs llvm 12+!): [https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation](https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation) - Only exclude those functions from instrumentation that provide no value for coverage - that is if it does not process any fuzz data directly or indirectly (e.g. hash maps, thread management etc.). - If however a function directly or indirectly handles fuzz data, then you should not put the function in a deny instrumentation list and rather live with the instability it comes with. + Only exclude those functions from instrumentation that provide no value for + coverage - that is if it does not process any fuzz data directly or + indirectly (e.g. hash maps, thread management etc.). If, however, a + function directly or indirectly handles fuzz data, then you should not put + the function in a deny instrumentation list and rather live with the + instability it comes with. 4. Recompile the target diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md index 4018d633..fc5ecbf9 100644 --- a/docs/custom_mutators.md +++ b/docs/custom_mutators.md @@ -112,11 +112,11 @@ def deinit(): # optional for Python - `fuzz_count` (optional): - When a queue entry is selected to be fuzzed, afl-fuzz selects the number - of fuzzing attempts with this input based on a few factors. - If however the custom mutator wants to set this number instead on how often - it is called for a specific queue entry, use this function. - This function is most useful if `AFL_CUSTOM_MUTATOR_ONLY` is **not** used. + When a queue entry is selected to be fuzzed, afl-fuzz selects the number of + fuzzing attempts with this input based on a few factors. If, however, the + custom mutator wants to set this number instead on how often it is called + for a specific queue entry, use this function. This function is most useful + if `AFL_CUSTOM_MUTATOR_ONLY` is **not** used. - `fuzz` (optional): diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md index 92b3cf86..96e709ab 100644 --- a/docs/fuzzing_in_depth.md +++ b/docs/fuzzing_in_depth.md @@ -131,8 +131,8 @@ The following options are available when you instrument with LTO mode have to compile the target twice, once specifically with/for this mode by setting `AFL_LLVM_CMPLOG=1`, and pass this binary to afl-fuzz via the `-c` parameter. Note that you can compile also just a cmplog binary and use that - for both however there will be a performance penality. You can read more about - this in + for both, however, there will be a performance penality. You can read more + about this in [instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md). If you use LTO, LLVM or GCC_PLUGIN mode @@ -151,7 +151,7 @@ only instrument parts of the target that you are interested in: inlined and then would not match! See [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) -There are many more options and modes available however these are most of the +There are many more options and modes available, however, these are most of the time less effective. See: * [instrumentation/README.ctx.md](../instrumentation/README.ctx.md) * [instrumentation/README.ngram.md](../instrumentation/README.ngram.md) @@ -369,8 +369,8 @@ This step is highly recommended! ### c) Minimizing all corpus files The shorter the input files that still traverse the same path within the target, -the better the fuzzing will be. This minimization is done with `afl-tmin` -however it is a long process as this has to be done for every file: +the better the fuzzing will be. This minimization is done with `afl-tmin`, +however, it is a long process as this has to be done for every file: ``` mkdir input diff --git a/docs/important_changes.md b/docs/important_changes.md index 726de64d..6cd00791 100644 --- a/docs/important_changes.md +++ b/docs/important_changes.md @@ -15,8 +15,8 @@ With AFL++ 3.15 we introduced the following changes from previous behaviors: With AFL++ 3.14 we introduced the following changes from previous behaviors: * afl-fuzz: deterministic fuzzing it not a default for -M main anymore - * afl-cmin/afl-showmap -i now descends into subdirectories (afl-cmin.bash - however does not) + * afl-cmin/afl-showmap -i now descends into subdirectories (afl-cmin.bash, + however, does not) With AFL++ 3.10 we introduced the following changes from previous behaviors: * The '+' feature of the '-t' option now means to auto-calculate the timeout diff --git a/instrumentation/README.llvm.md b/instrumentation/README.llvm.md index 8133cbe4..d16049fa 100644 --- a/instrumentation/README.llvm.md +++ b/instrumentation/README.llvm.md @@ -106,9 +106,10 @@ either setting `AFL_CC_COMPILER=LLVM` or pass the parameter `--afl-llvm` via CFLAGS/CXXFLAGS/CPPFLAGS. The tool honors roughly the same environmental variables as afl-gcc (see -[docs/env_variables.md](../docs/env_variables.md)). This includes AFL_USE_ASAN, -AFL_HARDEN, and AFL_DONT_OPTIMIZE. However AFL_INST_RATIO is not honored as it -does not serve a good purpose with the more effective PCGUARD analysis. +[docs/env_variables.md](../docs/env_variables.md)). This includes +`AFL_USE_ASAN`, `AFL_HARDEN`, and `AFL_DONT_OPTIMIZE`. However, `AFL_INST_RATIO` +is not honored as it does not serve a good purpose with the more effective +PCGUARD analysis. ## 3) Options @@ -125,8 +126,8 @@ For splitting memcmp, strncmp, etc., see Then there are different ways of instrumenting the target: 1. An better instrumentation strategy uses LTO and link time instrumentation. - Note that not all targets can compile in this mode, however if it works it is - the best option you can use. To go with this option, use + Note that not all targets can compile in this mode, however, if it works it + is the best option you can use. To go with this option, use afl-clang-lto/afl-clang-lto++. See [README.lto.md](README.lto.md). 2. Alternatively you can choose a completely different coverage method: diff --git a/qemu_mode/README.persistent.md b/qemu_mode/README.persistent.md index 7210a8cc..ab45860d 100644 --- a/qemu_mode/README.persistent.md +++ b/qemu_mode/README.persistent.md @@ -17,10 +17,10 @@ The start of the persistent loop has to be set with environment variable `AFL_QEMU_PERSISTENT_ADDR`. This address can be the address of whatever instruction. Setting this address to -the start of a function makes the usage simple. If the address is however within -a function, either RET, OFFSET, or EXITS (see below in 2.2, 2.3, 2.6) have to be -set. This address (as well as the RET address, see below) has to be defined in -hexadecimal with the 0x prefix or as a decimal value. +the start of a function makes the usage simple. If the address is, however, +within a function, either RET, OFFSET, or EXITS (see below in 2.2, 2.3, 2.6) +have to be set. This address (as well as the RET address, see below) has to be +defined in hexadecimal with the 0x prefix or as a decimal value. If both RET and EXITS are not set, QEMU will assume that START points to a function and will patch the return address (on stack or in the link register) to diff --git a/qemu_mode/libcompcov/README.md b/qemu_mode/libcompcov/README.md index 6a72f5ff..50f0d802 100644 --- a/qemu_mode/libcompcov/README.md +++ b/qemu_mode/libcompcov/README.md @@ -18,7 +18,7 @@ and this module is not capable to log the coverage in this case. If you have the source code of the fuzzing target you should nto use this library and QEMU but build it with afl-clang-fast and the laf-intel options. -To use this library make sure to preload it with AFL_PRELOAD. +To use this library, make sure to preload it with AFL_PRELOAD. ``` export AFL_PRELOAD=/path/to/libcompcov.so @@ -32,6 +32,6 @@ Level 1 logs just comparison with immediates / read-only memory and level 2 logs all the comparisons. The library make use of https://github.com/ouadev/proc_maps_parser and so it is -Linux specific. However this is not a strict dependency, other UNIX operating -systems can be supported by replacing the code related to the -/proc/self/maps parsing. \ No newline at end of file +Linux specific. However, this is not a strict dependency, other UNIX operating +systems can be supported by replacing the code related to the /proc/self/maps +parsing. \ No newline at end of file diff --git a/utils/afl_network_proxy/README.md b/utils/afl_network_proxy/README.md index 05659c45..d2c00be2 100644 --- a/utils/afl_network_proxy/README.md +++ b/utils/afl_network_proxy/README.md @@ -34,16 +34,17 @@ afl-network-server -i 1111 -m 25M -t 1000 -- /bin/target -f @@ ### on the (afl-fuzz) main node -Just run afl-fuzz with your normal options, however the target should be +Just run afl-fuzz with your normal options, however, the target should be `afl-network-client` with the IP and PORT of the `afl-network-server` and increase the -t value: + ``` afl-fuzz -i in -o out -t 2000+ -- afl-network-client TARGET-IP 1111 ``` -Note the '+' on the -t parameter value. The afl-network-server will take -care of proper timeouts hence afl-fuzz should not. The '+' increases the -timeout and the value itself should be 500-1000 higher than the one on -afl-network-server. + +Note the '+' on the -t parameter value. The afl-network-server will take care of +proper timeouts hence afl-fuzz should not. The '+' increases the timeout and the +value itself should be 500-1000 higher than the one on afl-network-server. ### networking @@ -53,7 +54,7 @@ either. Note that also the outgoing interface can be specified with a '%' for Also make sure your default TCP window size is larger than your MAP_SIZE (130kb is a good value). -On Linux that is the middle value of `/proc/sys/net/ipv4/tcp_rmem` +On Linux that is the middle value of `/proc/sys/net/ipv4/tcp_rmem` ## how to compile and install diff --git a/utils/afl_untracer/README.md b/utils/afl_untracer/README.md index ada0c916..9f41618f 100644 --- a/utils/afl_untracer/README.md +++ b/utils/afl_untracer/README.md @@ -5,9 +5,9 @@ afl-untracer is an example skeleton file which can easily be used to fuzz a closed source library. -It requires less memory and is x3-5 faster than qemu_mode however it is way -more course grained and does not provide interesting features like compcov -or cmplog. +It requires less memory and is x3-5 faster than qemu_mode, however, it is way +more course grained and does not provide interesting features like compcov or +cmplog. Supported is so far Intel (i386/x86_64) and AARCH64. -- cgit 1.4.1