selective instrumentation documented
MODIFY
docs/Changelog.md
docs/Changelog.md
@@ -9,8 +9,11 @@ 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 ++3.01a (release)
+### Version ++3.01a (dev)
- Mac OS ARM64 support
+ - New selective instrumentation option with __AFL_COVERAGE_... commands
+ to be placed in the source code.
+ Check out instrumentation/README.instrument_list.md
- afl-fuzz
- fix crash for very, very fast targets+systems (thanks to mhlakhani
for reporting)

MODIFY
include/config.h
include/config.h
#define TRIM_START_STEPS 16
#define TRIM_END_STEPS 1024
-/* Maximum size of input file, in bytes (keep under 100MB): */
+/* Maximum size of input file, in bytes (keep under 100MB, default 1MB):
+ (note that if this value is changed, several areas in afl-cc.c, afl-fuzz.c
+ and afl-fuzz-state.c have to be changed as well! */
#define MAX_FILE (1 * 1024 * 1024U)

MODIFY
instrumentation/README.instrument_list.md
instrumentation/README.instrument_list.md
# Using afl++ with partial instrumentation
- This file describes how to selectively instrument only source files
- or functions that are of interest to you using the LLVM and GCC_PLUGIN
- instrumentation provided by afl++.
+ This file describes two different mechanisms to selectively instrument
+ only specific parts in the target.
+
+ Both mechanisms work for LLVM and GCC_PLUGIN, but not for afl-clang/afl-gcc.
## 1) Description and purpose
@@ -12,28 +13,42 @@ the program, leaving the rest uninstrumented. This helps to focus the fuzzer
on the important parts of the program, avoiding undesired noise and
disturbance by uninteresting code being exercised.
-For this purpose, a "partial instrumentation" support en par with llvm sancov
-is provided by afl++ that allows to specify on a source file and function
-level which function should be compiled with or without instrumentation.
+For this purpose, "partial instrumentation" support is provided by afl++ that
+allows to specify what should be instrumented and what not.
+
+Both mechanisms can be used together.
+
+## 2) Selective instrumentation with __AFL_COVERAGE_... directives
+
+In this mechanism the selective instrumentation is done in the source code.
-Note: When using PCGUARD mode - and llvm 12+ - you can use this instead:
-https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation
+After the includes a special define has to be made, eg.:
+
+```
+#include <stdio.h>
+#include <stdint.h>
+// ...
+
+__AFL_COVERAGE(); // <- required for this feature to work
+```
-The llvm sancov list format is fully supported by afl++, however afl++ has
-more flexibility.
+If you want to disable the coverage at startup until you specify coverage
+should be started, then add `__AFL_COVERAGE_START_OFF();` at that position.
-## 2a) Building the LLVM module
+From here on out you have the following macros available that you can use
+in any function where you want:
-The new code is part of the existing afl++ LLVM module in the instrumentation/
-subdirectory. There is nothing specifically to do for the build :)
+ * `__AFL_COVERAGE_ON();` - enable coverage from this point onwards
+ * `__AFL_COVERAGE_OFF();` - disable coverage from this point onwards
+ * `__AFL_COVERAGE_DISCARD();` - reset all coverage gathered until this point
+ * `__AFL_COVERAGE_ABORT();` - mark this test case as unimportant. Whatever happens, afl-fuzz will ignore it.
-## 2b) Building the GCC module
+## 3) Selective instrumenation with AFL_LLVM_ALLOWLIST/AFL_LLVM_DENYLIST
-The new code is part of the existing afl++ GCC_PLUGIN module in the
-instrumentation/ subdirectory. There is nothing specifically to do for
-the build :)
+This feature is equivalent to llvm 12 sancov feature and allows to specify
+on a filename and/or function name level to instrument these or skip them.
-## 3) How to use the partial instrumentation mode
+### 3a) How to use the partial instrumentation mode
In order to build with partial instrumentation, you need to build with
afl-clang-fast/afl-clang-fast++ or afl-clang-lto/afl-clang-lto++.
@@ -90,7 +105,7 @@ fun: MallocFoo
```
Note that whitespace is ignored and comments (`# foo`) are supported.
-## 4) UNIX-style pattern matching
+### 3b) UNIX-style pattern matching
You can add UNIX-style pattern matching in the "instrument file list" entries.
See `man fnmatch` for the syntax. We do not set any of the `fnmatch` flags.

MODIFY
src/afl-cc.c
src/afl-cc.c
@@ -827,6 +827,20 @@ static void edit_params(u32 argc, char **argv, char **envp) {
"extern unsigned char *__afl_fuzz_ptr;"
"unsigned char __afl_fuzz_alt[1048576];"
"unsigned char *__afl_fuzz_alt_ptr = __afl_fuzz_alt;";
+ cc_params[cc_par_cnt++] =
+ "-D__AFL_COVERAGE()=int __afl_selective_coverage = 1;"
+ "void __afl_coverage_discard();"
+ "void __afl_coverage_abort();"
+ "void __afl_coverage_on();"
+ "void __afl_coverage_off();";
+ cc_params[cc_par_cnt++] =
+ "-D__AFL_COVERAGE_START_OFF()=int __afl_selective_coverage_start_off = "
+ "1;";
+ cc_params[cc_par_cnt++] = "-D__AFL_COVERAGE_ON()=__afl_coverage_on()";
+ cc_params[cc_par_cnt++] = "-D__AFL_COVERAGE_OFF()=__afl_coverage_off()";
+ cc_params[cc_par_cnt++] =
+ "-D__AFL_COVERAGE_DISCARD()=__afl_coverage_discard()";
+ cc_params[cc_par_cnt++] = "-D__AFL_COVERAGE_ABORT()=__afl_coverage_abort()";
cc_params[cc_par_cnt++] =
"-D__AFL_FUZZ_TESTCASE_BUF=(__afl_fuzz_ptr ? __afl_fuzz_ptr : "
"__afl_fuzz_alt_ptr)";

selective instrumentation documented