1# Dynamic Instrumentation Filter 2 3Sometimes it can be beneficial to limit the instrumentation feedback to 4specific code locations. It is possible to do so at compile-time by simply 5not instrumenting any undesired locations. However, there are situations 6where doing this dynamically without requiring a new build can be beneficial. 7Especially when dealing with larger builds, it is much more convenient to 8select the target code locations at runtime instead of doing so at build time. 9 10There are two ways of doing this in AFL++. Both approaches require a build of 11AFL++ with `CODE_COVERAGE=1`, so make sure to build AFL++ first by invoking 12 13`CODE_COVERAGE=1 make` 14 15Once you have built AFL++, you can choose out of two approaches: 16 17## Simple Selection with `AFL_PC_FILTER` 18 19This approach requires a build with `AFL_INSTRUMENTATION=llvmnative` or 20`llvmcodecov` as well as an AddressSanitizer build with debug information. 21 22By setting the environment variable `AFL_PC_FILTER` to a string, the runtime 23symbolizer is enabled in the AFL++ runtime. At startup, the runtime will call 24the `__sanitizer_symbolize_pc` API to resolve every PC in every loaded module. 25The runtime then matches the result using `strstr` and disables the PC guard 26if the symbolized PC does not contain the specified string. 27 28This approach has the benefit of being very easy to use. The downside is that 29it causes significant startup delays with large binaries and that it requires 30an AddressSanitizer build. 31 32This method has no additional runtime overhead after startup. 33 34## Selection using pre-symbolized data file with `AFL_PC_FILTER_FILE` 35 36To avoid large startup time delays, a specific module can be pre-symbolized 37using the `make_symbol_list.py` script. This script outputs a sorted list of 38functions with their respective relative offsets and lengths in the target 39binary: 40 41`python3 make_symbol_list.py libxul.so > libxul.symbols.txt` 42 43The resulting list can be filtered, e.g. using grep: 44 45`grep -i "webgl" libxul.symbols.txt > libxul.webgl.symbols.txt` 46 47Finally, you can run with `AFL_PC_FILTER_FILE=libxul.webgl.symbols.txt` to 48restrict instrumentation feedback to the given locations. This approach only 49has a minimal startup time delay due to the implementation only using binary 50search on the given file per PC rather than reading debug information for every 51PC. It also works well with Nyx, where symbolizing is usually disabled for the 52target process to avoid delays with frequent crashes. 53 54Similar to the previous method, This approach requires a build with 55`AFL_INSTRUMENTATION=llvmnative` or `llvmcodecov` as well debug information. 56However, it does not require the ASan runtime as it doesn't do the symbolizing 57in process. Due to the way it maps PCs to symbols, it is less accurate when it 58comes to includes and inlines (it assumes all PCs within a function belong to 59that function and originate from the same file). For most purposes, this should 60be a reasonable simplification to quickly process even the largest binaries. 61