diff options
Diffstat (limited to 'docs/INSTALL.md')
| -rw-r--r-- | docs/INSTALL.md | 140 |
1 files changed, 59 insertions, 81 deletions
diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 637e8658..3089aab2 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -3,12 +3,11 @@ ## Linux on x86 An easy way to install AFL++ with everything compiled is available via docker: -You can use the [Dockerfile](../Dockerfile) (which has gcc-10 and clang-12 - -hence afl-clang-lto is available) or just pull directly from the Docker Hub -(for x86_64 and arm64): +You can use the [Dockerfile](../Dockerfile) or just pull directly from the +Docker Hub (for x86_64 and arm64): ```shell -docker pull aflplusplus/aflplusplus: +docker pull aflplusplus/aflplusplus:latest docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus ``` @@ -21,14 +20,14 @@ development state of AFL++. If you want to build AFL++ yourself, you have many options. The easiest choice is to build and install everything: -NOTE: depending on your Debian/Ubuntu/Kali/... release, replace `-12` with -whatever llvm version is available. We recommend llvm 12, 13 or 14. +NOTE: depending on your Debian/Ubuntu/Kali/... release, replace `-14` with +whatever llvm version is available. We recommend llvm 13 or newer. ```shell sudo apt-get update sudo apt-get install -y build-essential python3-dev automake cmake git flex bison libglib2.0-dev libpixman-1-dev python3-setuptools cargo libgtk-3-dev -# try to install llvm 12 and install the distro default if that fails -sudo apt-get install -y lld-12 llvm-12 llvm-12-dev clang-12 || sudo apt-get install -y lld llvm llvm-dev clang +# try to install llvm 14 and install the distro default if that fails +sudo apt-get install -y lld-14 llvm-14 llvm-14-dev clang-14 || sudo apt-get install -y lld llvm llvm-dev clang sudo apt-get install -y gcc-$(gcc --version|head -n1|sed 's/\..*//'|sed 's/.* //')-plugin-dev libstdc++-$(gcc --version|head -n1|sed 's/\..*//'|sed 's/.* //')-dev sudo apt-get install -y ninja-build # for QEMU mode git clone https://github.com/AFLplusplus/AFLplusplus @@ -68,19 +67,20 @@ These build targets exist: * unit: perform unit tests (based on cmocka) * help: shows these build options -[Unless you are on Mac OS X](https://developer.apple.com/library/archive/qa/qa1118/_index.html), +[Unless you are on macOS](https://developer.apple.com/library/archive/qa/qa1118/_index.html), you can also build statically linked versions of the AFL++ binaries by passing -the `STATIC=1` argument to make: +the `PERFORMANCE=1` argument to make: ```shell -make STATIC=1 +make PERFORMANCE=1 ``` These build options exist: -* STATIC - compile AFL++ static -* CODE_COVERAGE - compile the target for code coverage (see docs/instrumentation/README.llvm.md) -* ASAN_BUILD - compiles AFL++ with memory sanitizer for debug purposes +* PERFORMANCE - compile with performance options that make the binary not transferable to other systems. Recommended (except on macOS)! +* STATIC - compile AFL++ static (does not work on macOS) +* CODE_COVERAGE - compile the target for code coverage (see [README.llvm.md](../instrumentation/README.llvm.md)) +* ASAN_BUILD - compiles AFL++ with address sanitizer for debug purposes * UBSAN_BUILD - compiles AFL++ tools with undefined behaviour sanitizer for debug purposes * DEBUG - no optimization, -ggdb3, all warnings and -Werror * LLVM_DEBUG - shows llvm deprecation warnings @@ -88,104 +88,82 @@ These build options exist: * INTROSPECTION - compile afl-fuzz with mutation introspection * NO_PYTHON - disable python support * NO_SPLICING - disables splicing mutation in afl-fuzz, not recommended for normal fuzzing +* NO_UTF - do not use UTF-8 for line rendering in status screen (fallback to G1 box drawing, of vanilla AFL) * NO_NYX - disable building nyx mode dependencies * NO_CORESIGHT - disable building coresight (arm64 only) * NO_UNICORN_ARM64 - disable building unicorn on arm64 -* AFL_NO_X86 - if compiling on non-intel/amd platforms +* AFL_NO_X86 - if compiling on non-Intel/AMD platforms * LLVM_CONFIG - if your distro doesn't use the standard name for llvm-config (e.g., Debian) e.g.: `make LLVM_CONFIG=llvm-config-14` -## MacOS X on x86 and arm64 (M1) +## macOS on x86_64 and arm64 -MacOS has some gotchas due to the idiosyncrasies of the platform. +macOS has some gotchas due to the idiosyncrasies of the platform. -To build AFL, install llvm (and perhaps gcc) from brew and follow the general -instructions for Linux. If possible, avoid Xcode at all cost. +macOS supports SYSV shared memory used by AFL++'s instrumentation, but the +default settings aren't sufficient. Before even building, increase +them by running the provided script: + +```shell +sudo afl-system-config +``` + +See +[https://www.spy-hill.com/help/apple/SharedMemory.html](https://www.spy-hill.com/help/apple/SharedMemory.html) +for documentation for the shared memory settings and how to make them permanent. + +Next, to build AFL++, install the following packages from brew: ```shell brew install wget git make cmake llvm gdb coreutils ``` -Be sure to setup `PATH` to point to the correct clang binaries and use the -freshly installed clang, clang++, llvm-config, gmake and coreutils, e.g.: +Depending on your macOS system + brew version, brew may be installed in different places. +You can check with `brew info llvm` to know where, then create a variable for it: ```shell -# Depending on your MacOS system + brew version it is either -export PATH="/opt/homebrew/opt/llvm/bin:$PATH" -# or -export PATH="/usr/local/opt/llvm/bin:$PATH" -# you can check with "brew info llvm" +export HOMEBREW_BASE="/opt/homebrew/opt" +``` -export PATH="/usr/local/opt/coreutils/libexec/gnubin:/usr/local/bin:$PATH" +or + +```shell +export HOMEBREW_BASE="/usr/local/opt" +``` + +Set `PATH` to point to the brew clang, clang++, llvm-config, gmake and coreutils. +Also use the brew clang compiler; the Xcode clang compiler must not be used. + +```shell +export PATH="$HOMEBREW_BASE/coreutils/libexec/gnubin:/usr/local/bin:$HOMEBREW_BASE/llvm/bin:$PATH" export CC=clang export CXX=clang++ -gmake -cd frida_mode -gmake -cd .. -sudo gmake install ``` -`afl-gcc` will fail unless you have GCC installed, but that is using outdated -instrumentation anyway. `afl-clang` might fail too depending on your PATH setup. -But you don't want neither, you want `afl-clang-fast` anyway :) Note that -`afl-clang-lto`, `afl-gcc-fast` and `qemu_mode` are not working on MacOS. +Then build following the general Linux instructions. -The crash reporting daemon that comes by default with MacOS X will cause -problems with fuzzing. You need to turn it off: +If everything worked, you should then have `afl-clang-fast` installed, which you can check with: +```shell +which afl-clang-fast ``` -launchctl unload -w /System/Library/LaunchAgents/com.apple.ReportCrash.plist -sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.ReportCrash.Root.plist -``` -The `fork()` semantics on OS X are a bit unusual compared to other unix systems +Note that `afl-clang-lto`, `afl-gcc-fast` and `qemu_mode` are not working on macOS. + +The crash reporting daemon that comes by default with macOS will cause +problems with fuzzing. You need to turn it off, which you can do with `afl-system-config`. + +The `fork()` semantics on macOS are a bit unusual compared to other unix systems and definitely don't look POSIX-compliant. This means two things: - Fuzzing will be probably slower than on Linux. In fact, some folks report considerable performance gains by running the jobs inside a Linux VM on - MacOS X. + macOS. - Some non-portable, platform-specific code may be incompatible with the AFL++ forkserver. If you run into any problems, set `AFL_NO_FORKSRV=1` in the environment before starting afl-fuzz. -User emulation mode of QEMU does not appear to be supported on MacOS X, so +User emulation mode of QEMU does not appear to be supported on macOS, so black-box instrumentation mode (`-Q`) will not work. However, FRIDA mode (`-O`) -works on both x86 and arm64 MacOS boxes. - -MacOS X supports SYSV shared memory used by AFL's instrumentation, but the -default settings aren't usable with AFL++. The default settings on 10.14 seem to -be: - -```bash -$ ipcs -M -IPC status from <running system> as of XXX -shminfo: - shmmax: 4194304 (max shared memory segment size) - shmmin: 1 (min shared memory segment size) - shmmni: 32 (max number of shared memory identifiers) - shmseg: 8 (max shared memory segments per process) - shmall: 1024 (max amount of shared memory in pages) -``` - -To temporarily change your settings to something minimally usable with AFL++, -run these commands as root: - -```bash -sysctl kern.sysv.shmmax=8388608 -sysctl kern.sysv.shmall=4096 -``` - -If you're running more than one instance of AFL, you likely want to make -`shmall` bigger and increase `shmseg` as well: - -```bash -sysctl kern.sysv.shmmax=8388608 -sysctl kern.sysv.shmseg=48 -sysctl kern.sysv.shmall=98304 -``` - -See -[http://www.spy-hill.com/help/apple/SharedMemory.html](http://www.spy-hill.com/help/apple/SharedMemory.html) -for documentation for these settings and how to make them permanent. +works on both x86 and arm64 macOS boxes. |