about summary refs log tree commit diff
path: root/frida_mode/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'frida_mode/README.md')
-rw-r--r--frida_mode/README.md153
1 files changed, 78 insertions, 75 deletions
diff --git a/frida_mode/README.md b/frida_mode/README.md
index 8abee0dd..9f574a4c 100644
--- a/frida_mode/README.md
+++ b/frida_mode/README.md
@@ -1,34 +1,38 @@
 # FRIDA MODE
-The purpose of FRIDA mode is to provide an alternative binary only fuzzer for AFL
-just like that provided by QEMU mode. The intention is to provide a very similar
-user experience, right down to the options provided through environment variables.
+
+The purpose of FRIDA mode is to provide an alternative binary only fuzzer for
+AFL just like that provided by QEMU mode. The intention is to provide a very
+similar user experience, right down to the options provided through environment
+variables.
 
 Whilst AFLplusplus already has some support for running on FRIDA [here](https://github.com/AFLplusplus/AFLplusplus/tree/stable/utils/afl_frida)
 this requires the code to be fuzzed to be provided as a shared library, it
 cannot be used to fuzz executables. Additionally, it requires the user to write
-a small harness around their target code of interest, FRIDA mode instead takes a
-different approach to avoid these limitations.
-
-# Current Progress
-As FRIDA mode is new, it is missing a lot of features. Most importantly,
-persistent mode. The design is such that it should be possible to add these
-features in a similar manner to QEMU mode and perhaps leverage some of its
-design and implementation.
-
-  | Feature/Instrumentation  | frida-mode |
-  | -------------------------|:----------:|
-  | NeverZero                |            |
-  | Persistent Mode          |            |
-  | LAF-Intel / CompCov      |            |
-  | CmpLog                   |            |
-  | Selective Instrumentation|     x      |
-  | Non-Colliding Coverage   |            |
-  | Ngram prev_loc Coverage  |            |
-  | Context Coverage         |            |
-  | Auto Dictionary          |            |
-  | Snapshot LKM Support     |            |
-
-# Compatibility
+a small harness around their target code of interest.
+FRIDA mode instead takes a different approach to avoid these limitations.
+In Frida mode binary programs are instrumented, similarly to QEMU mode.
+
+## Current Progress
+
+As FRIDA mode is new, it is missing a lot of features. The design is such that it
+should be possible to add these features in a similar manner to QEMU mode and
+perhaps leverage some of its design and implementation.
+
+  | Feature/Instrumentation  | frida-mode | Notes                                   |
+  | -------------------------|:----------:|:---------------------------------------:|
+  | NeverZero                |     x      |                                         |
+  | Persistent Mode          |     x      | (x64 only)(Only on function boundaries) |  
+  | LAF-Intel / CompCov      |     -      | (CMPLOG is better 90% of the time)      |
+  | CMPLOG                   |     x      | (x64 only)                              |
+  | Selective Instrumentation|     x      |                                         |
+  | Non-Colliding Coverage   |     -      |                                         |
+  | Ngram prev_loc Coverage  |     -      |                                         |
+  | Context Coverage         |     -      |                                         |
+  | Auto Dictionary          |     -      |                                         |
+  | Snapshot LKM Support     |     -      |                                         |
+  | In-Memory Test Cases     |     x      | (x64 only)                              |
+
+## Compatibility
 Currently FRIDA mode supports Linux and macOS targets on both x86/x64
 architecture and aarch64. Later releases may add support for aarch32 and Windows
 targets as well as embedded linux environments.
@@ -38,54 +42,53 @@ runtime libraries, so porting should be possible. However, the current build
 system does not support cross compilation.
 
 ## Getting Started
+
 To build everything run `make`.
 
-To run the benchmark sample with qemu run `make png_qemu`.
-To run the benchmark sample with frida run `make png_frida`.
+Various tests can be found in subfolders within the `test/` directory. To use
+these, first run `make` to build any dependencies. Then run `make qemu` or
+`make frida` to run on either QEMU of FRIDA mode respectively.
 
 ## Usage
-FRIDA mode requires some small modifications to `afl-fuzz` and similar tools
-in AFLplusplus. The intention is that it behaves identically to QEMU, but uses
+
+FRIDA mode added some small modifications to `afl-fuzz` and similar tools
+in AFLplusplus. The intention was that it behaves identically to QEMU, but it uses
 the 'O' switch rather than 'Q'. Whilst the options 'f', 'F', 's' or 'S' may have
 made more sense for a mode powered by FRIDA Stalker, they were all taken, so
 instead we use 'O' in hommage to the [author](https://github.com/oleavr) of
 FRIDA.
 
 Similarly, the intention is to mimic the use of environment variables used by
-QEMU where possible (although replacing `s/QEMU/FRIDA/g`). Accodingly, the
-following options are currently supported.
+QEMU where possible (by replacing `s/QEMU/FRIDA/g`). Accordingly, the
+following options are currently supported:
 
 * `AFL_FRIDA_DEBUG_MAPS` - See `AFL_QEMU_DEBUG_MAPS`
 * `AFL_FRIDA_EXCLUDE_RANGES` - See `AFL_QEMU_EXCLUDE_RANGES`
 * `AFL_FRIDA_INST_RANGES` - See `AFL_QEMU_INST_RANGES`
+* `AFL_FRIDA_PERSISTENT_ADDR` - See `AFL_QEMU_PERSISTENT_ADDR`
+* `AFL_FRIDA_PERSISTENT_CNT` - See `AFL_QEMU_PERSISTENT_CNT`
+* `AFL_FRIDA_PERSISTENT_HOOK` - See `AFL_QEMU_PERSISTENT_HOOK`
 
-# Performance
+To enable the powerful CMPLOG mechanism, set `-c 0` for `afl-fuzz`.
+
+## Performance
 
 Additionally, the intention is to be able to make a direct performance
-comparison between the two approaches. Accordingly, FRIDA mode includes a test
-target based on the [libpng](https://libpng.sourceforge.io/) benchmark used by
-[fuzzbench](https://google.github.io/fuzzbench/) and integrated with the
+comparison between the two approaches. Accordingly, FRIDA mode includes various
+test targets based on the [libpng](https://libpng.sourceforge.io/) benchmark
+used by [fuzzbench](https://google.github.io/fuzzbench/) and integrated with the
 [StandaloneFuzzTargetMain](https://raw.githubusercontent.com/llvm/llvm-project/main/compiler-rt/lib/fuzzer/standalone/StandaloneFuzzTargetMain.c)
-from the llvm project. This is built and linked without any special
-modifications to suit FRIDA or QEMU. We use the test data provided with libpng
-as our corpus.
-
-Whilst not much performance tuning has been completed to date, performance is
-around 30-50% of that of QEMU mode, however, this gap may reduce with the 
-introduction of persistent mode. Performance can be tested by running 
-`make compare`, albeit a longer time measurement may be required for more 
-accurate results. 
-
-Whilst [afl_frida](https://github.com/AFLplusplus/AFLplusplus/tree/stable/utils/afl_frida)
-claims a 5-10x performance increase over QEMU, it has not been possible to
-reproduce these claims. However, the number of executions per second can vary
-dramatically as a result of the randomization of the fuzzer input. Some inputs
-may traverse relatively few paths before being rejected as invalid whilst others
-may be valid inputs or be subject to much more processing before rejection.
-Accordingly, it is recommended that testing be carried out over prolongued
-periods to gather timings which are more than indicative.
-
-# Design
+from the llvm project. These tests include basic fork-server support, persistent
+mode and persistent mode with in-memory test-cases. These are built and linked
+without any special modifications to suit FRIDA or QEMU. The test data provided
+with libpng is used as the corpus.
+
+The intention is to add support for FRIDA mode to the FuzzBench project and
+perform a like-for-like comparison with QEMU mode to get an accurate
+appreciation of its performance.
+
+## Design
+
 FRIDA mode is supported by using `LD_PRELOAD` (`DYLD_INSERT_LIBRARIES` on macOS)
 to inject a shared library (`afl-frida-trace.so`) into the target. This shared
 library is built using the [frida-gum](https://github.com/frida/frida-gum)
@@ -102,34 +105,34 @@ this coverage information to AFL++ and also provide a fork server. It also makes
 use of the FRIDA [prefetch](https://github.com/frida/frida-gum/blob/56dd9ba3ee9a5511b4b0c629394bf122775f1ab7/gum/gumstalker.h#L115)
 support to feedback instrumented blocks from the child to the parent using a
 shared memory region to avoid the need to regenerate instrumented blocks on each
-fork. 
+fork.
 
 Whilst FRIDA allows for a normal C function to be used to augment instrumented
-code, to minimize the costs of storing and restoring all of the registers, FRIDA
-mode instead makes use of optimized assembly instead on AARCH64 and x86/64
-targets.
+code, FRIDA mode instead makes use of optimized assembly instead on AARCH64 and
+x86/64 targets. By injecting these small snippets of assembly, we avoid having
+to push and pop the full register context. Note that since this instrumentation
+is used on every basic block to generate coverage, it has a large impact on
+performance.
+
+CMPLOG support also adds code to the assembly, however, at present this code
+makes use of a basic C function and is yet to be optimized. Since not all
+instances run CMPLOG mode and instrumentation of the binary is less frequent
+(only on CMP, SUB and CALL instructions) performance is not quite so critical.
+
+## Advanced configuration options
 
-# Advanced configuration options
 * `AFL_FRIDA_INST_NO_OPTIMIZE` - Don't use optimized inline assembly coverage
 instrumentation (the default where available). Required to use
 `AFL_FRIDA_INST_TRACE`.
 * `AFL_FRIDA_INST_NO_PREFETCH` - Disable prefetching. By default the child will
 report instrumented blocks back to the parent so that it can also instrument
 them and they be inherited by the next child on fork.
-* `AFL_FRIDA_INST_STRICT` - Under certain conditions, Stalker may encroach into
-excluded regions and generate both instrumented blocks and coverage data (e.g.
-indirect calls on x86). The excluded block is generally honoured as soon as
-another function is called within the excluded region and so such encroachment
-is usually of little consequence. This detail may however, hinder you when
-checking that the correct number of paths are found for testing purposes or
-similar. There is a performance penatly for this option during block compilation
-where we check the block isn't in a list of excluded ranges.
 * `AFL_FRIDA_INST_TRACE` - Generate some logging when running instrumented code.
 Requires `AFL_FRIDA_INST_NO_OPTIMIZE`.
 
-# TODO
-As can be seen from the progress section above, there are a number of features
-which are missing in its currently form. Chief amongst which is persistent mode.
-The intention is to achieve feature parity with QEMU mode in due course.
-Contributions are welcome, but please get in touch to ensure that efforts are
-deconflicted.
+## TODO
+
+The next features to be added are x86 support, integration with FuzzBench and
+support for ASAN. The intention is to achieve feature parity with QEMU mode in
+due course. Contributions are welcome, but please get in touch to ensure that
+efforts are deconflicted.