ExternalVendorCode/AFLplusplus
1
0
Fork 0
mirror of https://github.com/AFLplusplus/AFLplusplus.git synced 2025-06-12 01:58:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

typos, rewording

Browse Source
This commit is contained in:
hexcoder
2021-03-09 23:04:53 +01:00
committed by GitHub
parent d44b650cd4
commit b865fc6080
1 changed files with 36 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
instrumentation/README.gcc_plugin.md
View File

@ -3,16 +3,20 @@
See [../README.md](../README.md) for the general instruction manual. See [../README.md](../README.md) for the general instruction manual.
See [README.llvm.md](README.llvm.md) for the LLVM-based instrumentation. See [README.llvm.md](README.llvm.md) for the LLVM-based instrumentation.
This document describes how to build and use `afl-gcc-fast` and `afl-g++-fast`,
which instrument the target with the help of gcc plugins.
TLDR: TLDR:
* `apt-get install gcc-VERSION-plugin-dev` * check the version of your gcc compiler: `gcc --version`
* `make` * `apt-get install gcc-VERSION-plugin-dev` or similar to install headers for gcc plugins
* gcc and g++ must point to the gcc-VERSION you you have to set AFL_CC/AFL_CXX * `gcc` and `g++` must match the gcc-VERSION you installed headers for. You can set `AFL_CC`/`AFL_CXX`
to point to these! to point to these!
* just use afl-gcc-fast/afl-g++-fast normally like you would afl-clang-fast * `make`
* just use `afl-gcc-fast`/`afl-g++-fast` normally like you would do with `afl-clang-fast`
## 1) Introduction ## 1) Introduction
The code in this directory allows you to instrument programs for AFL using The code in this directory allows to instrument programs for AFL using
true compiler-level instrumentation, instead of the more crude true compiler-level instrumentation, instead of the more crude
assembly-level rewriting approach taken by afl-gcc and afl-clang. This has assembly-level rewriting approach taken by afl-gcc and afl-clang. This has
several interesting properties: several interesting properties:
@ -27,10 +31,10 @@ several interesting properties:
- The instrumentation is CPU-independent. At least in principle, you should - The instrumentation is CPU-independent. At least in principle, you should
be able to rely on it to fuzz programs on non-x86 architectures (after be able to rely on it to fuzz programs on non-x86 architectures (after
building afl-fuzz with AFL_NOX86=1). building `afl-fuzz` with `AFL_NOX86=1`).
- Because the feature relies on the internals of GCC, it is gcc-specific - Because the feature relies on the internals of GCC, it is gcc-specific
and will *not* work with LLVM (see ../llvm_mode for an alternative). and will *not* work with LLVM (see [README.llvm.md](README.llvm.md) for an alternative).
Once this implementation is shown to be sufficiently robust and portable, it Once this implementation is shown to be sufficiently robust and portable, it
will probably replace afl-gcc. For now, it can be built separately and will probably replace afl-gcc. For now, it can be built separately and
@ -41,29 +45,32 @@ The idea and much of the implementation comes from Laszlo Szekeres.
## 2) How to use ## 2) How to use
In order to leverage this mechanism, you need to have modern enough GCC In order to leverage this mechanism, you need to have modern enough GCC
(>= version 4.5.0) and the plugin headers installed on your system. That (>= version 4.5.0) and the plugin development headers installed on your system. That
should be all you need. On Debian machines, these headers can be acquired by should be all you need. On Debian machines, these headers can be acquired by
installing the `gcc-VERSION-plugin-dev` packages. installing the `gcc-VERSION-plugin-dev` packages.
To build the instrumentation itself, type 'make'. This will generate binaries To build the instrumentation itself, type `make`. This will generate binaries
called afl-gcc-fast and afl-g++-fast in the parent directory. called `afl-gcc-fast` and `afl-g++-fast` in the parent directory.
The gcc and g++ compiler links have to point to gcc-VERSION - or set these The gcc and g++ compiler links have to point to gcc-VERSION - or set these
by pointing the environment variables AFL_CC/AFL_CXX to them. by pointing the environment variables `AFL_CC`/`AFL_CXX` to them.
If the CC/CXX have been overridden, those compilers will be used from If the `CC`/`CXX` environment variables have been set, those compilers will be
those wrappers without using AFL_CXX/AFL_CC settings. preferred over those from the `AFL_CC`/`AFL_CXX` settings.
Once this is done, you can instrument third-party code in a way similar to the Once this is done, you can instrument third-party code in a way similar to the
standard operating mode of AFL, e.g.: standard operating mode of AFL, e.g.:
```
CC=/path/to/afl/afl-gcc-fast ./configure [...options...] CC=/path/to/afl/afl-gcc-fast
CXX=/path/to/afl/afl-g++-fast
export CC CXX
./configure [...options...]
make make
```
Note: We also used `CXX` to set the C++ compiler to `afl-g++-fast` for C++ code.
Be sure to also include CXX set to afl-g++-fast for C++ code. The tool honors roughly the same environmental variables as `afl-gcc` (see
[env_variables.md](../docs/env_variables.md). This includes `AFL_INST_RATIO`,
The tool honors roughly the same environmental variables as afl-gcc (see `AFL_USE_ASAN`, `AFL_HARDEN`, and `AFL_DONT_OPTIMIZE`.
[env_variables.md](../docs/env_variables.md). This includes AFL_INST_RATIO,
AFL_USE_ASAN, AFL_HARDEN, and AFL_DONT_OPTIMIZE.
Note: if you want the GCC plugin to be installed on your system for all Note: if you want the GCC plugin to be installed on your system for all
users, you need to build it before issuing 'make install' in the parent users, you need to build it before issuing 'make install' in the parent
@ -72,7 +79,7 @@ directory.
## 3) Gotchas, feedback, bugs ## 3) Gotchas, feedback, bugs
This is an early-stage mechanism, so field reports are welcome. You can send bug This is an early-stage mechanism, so field reports are welcome. You can send bug
reports to afl@aflplus.plus reports to afl@aflplus.plus.
## 4) Bonus feature #1: deferred initialization ## 4) Bonus feature #1: deferred initialization
@ -88,7 +95,7 @@ file before getting to the fuzzed data.
In such cases, it's beneficial to initialize the forkserver a bit later, once In such cases, it's beneficial to initialize the forkserver a bit later, once
most of the initialization work is already done, but before the binary attempts most of the initialization work is already done, but before the binary attempts
to read the fuzzed input and parse it; in some cases, this can offer a 10x+ to read the fuzzed input and parse it; in some cases, this can offer a 10x+
performance gain. You can implement delayed initialization in LLVM mode in a performance gain. You can implement delayed initialization in GCC mode in a
fairly simple way. fairly simple way.
First, locate a suitable location in the code where the delayed cloning can First, locate a suitable location in the code where the delayed cloning can
@ -117,7 +124,7 @@ With the location selected, add this code in the appropriate spot:
``` ```
You don't need the #ifdef guards, but they will make the program still work as You don't need the #ifdef guards, but they will make the program still work as
usual when compiled with a tool other than afl-gcc-fast/afl-clang-fast. usual when compiled with a compiler other than afl-gcc-fast/afl-clang-fast.
Finally, recompile the program with afl-gcc-fast (afl-gcc or afl-clang will Finally, recompile the program with afl-gcc-fast (afl-gcc or afl-clang will
*not* generate a deferred-initialization binary) - and you should be all set! *not* generate a deferred-initialization binary) - and you should be all set!
@ -127,7 +134,7 @@ Finally, recompile the program with afl-gcc-fast (afl-gcc or afl-clang will
Some libraries provide APIs that are stateless, or whose state can be reset in Some libraries provide APIs that are stateless, or whose state can be reset in
between processing different input files. When such a reset is performed, a between processing different input files. When such a reset is performed, a
single long-lived process can be reused to try out multiple test cases, single long-lived process can be reused to try out multiple test cases,
eliminating the need for repeated fork() calls and the associated OS overhead. eliminating the need for repeated `fork()` calls and the associated OS overhead.
The basic structure of the program that does this would be: The basic structure of the program that does this would be:
@ -160,5 +167,9 @@ wary of memory leaks and the state of file descriptors.
When running in this mode, the execution paths will inherently vary a bit When running in this mode, the execution paths will inherently vary a bit
depending on whether the input loop is being entered for the first time or depending on whether the input loop is being entered for the first time or
executed again. To avoid spurious warnings, the feature implies executed again. To avoid spurious warnings, the feature implies
AFL_NO_VAR_CHECK and hides the "variable path" warnings in the UI. `AFL_NO_VAR_CHECK` and hides the "variable path" warnings in the UI.
## 6) Bonus feature #3: selective instrumentation
It can be more effective to fuzzing to only instrument parts of the code.
For details see [README.instrument_list.md](README.instrument_list.md).