- What is an "edge"?
+ What is an "edge"?
A program contains `functions`, `functions` contain the compiled machine code.
The compiled machine code in a `function` can be in a single or many `basic blocks`.
@@ -77,7 +77,7 @@ If you find an interesting or important question missing, submit it via
## Targets
- How can I fuzz a binary-only target?
+ How can I fuzz a binary-only target?
AFL++ is a great fuzzer if you have the source code available.
@@ -87,7 +87,7 @@ If you find an interesting or important question missing, submit it via
- How can I fuzz a network service?
+ How can I fuzz a network service?
The short answer is - you cannot, at least not "out of the box".
@@ -95,7 +95,7 @@ If you find an interesting or important question missing, submit it via
- How can I fuzz a GUI program?
+ How can I fuzz a GUI program?
Not all GUI programs are suitable for fuzzing. If the GUI program can read the fuzz data from a file without needing any user interaction, then it would be suitable for fuzzing.
@@ -105,13 +105,13 @@ If you find an interesting or important question missing, submit it via
## Performance
- How can I improve the fuzzing speed?
+ How can I improve the fuzzing speed?
There are a few things you can do to improve the fuzzing speed, see [best_practices.md#improving-speed](best_practices.md#improving-speed).
- Why is my stability below 100%?
+ Why is my stability below 100%?
Stability is measured by how many percent of the edges in the target are "stable".
Sending the same input again and again should take the exact same path through the target every time.
@@ -131,7 +131,7 @@ If you find an interesting or important question missing, submit it via
## Troubleshooting
- I got a weird compile error from clang.
+ I got a weird compile error from clang.
If you see this kind of error when trying to instrument a target with afl-cc/afl-clang-fast/afl-clang-lto:
--
cgit 1.4.1
From 492dbe9fb294dec27e5c2bc7297b36526bb8e61f Mon Sep 17 00:00:00 2001
From: llzmb <46303940+llzmb@users.noreply.github.com>
Date: Sun, 21 Nov 2021 18:00:01 +0100
Subject: Clean up docs folder
---
README.md | 5 +-
docs/FAQ.md | 5 +-
docs/best_practices.md | 18 +++--
docs/parallel_fuzzing.md | 182 +++++++++++++++++++++++------------------------
qemu_mode/README.md | 5 +-
5 files changed, 109 insertions(+), 106 deletions(-)
(limited to 'docs/FAQ.md')
diff --git a/README.md b/README.md
index b2714787..fcb6b3c9 100644
--- a/README.md
+++ b/README.md
@@ -132,9 +132,6 @@ The following branches exist:
* [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev): development state of AFL++ - bleeding edge and you might catch a checkout which does not compile or has a bug. *We only accept PRs in dev!!*
* (any other): experimental branches to work on specific features or testing new functionality or changes.
-For releases, please see the [Releases tab](https://github.com/AFLplusplus/AFLplusplus/releases).
-Also take a look at the list of [important changes in AFL++](docs/important_changes.md).
-
## Help wanted
We have several [ideas](docs/ideas.md) we would like to see in AFL++ to make it
@@ -233,4 +230,4 @@ presented at WOOT'20:
}
```
-
+
\ No newline at end of file
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 68ca3bad..34ed4cf5 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -83,7 +83,8 @@ If you find an interesting or important question missing, submit it via
However, if there is only the binary program and no source code available, then the standard non-instrumented mode is not effective.
- To learn how these binaries can be fuzzed, read [binaryonly_fuzzing.md](binaryonly_fuzzing.md).
+ To learn how these binaries can be fuzzed, read
+ [fuzzing_binary-only_targets.md](fuzzing_binary-only_targets.md).
@@ -143,7 +144,7 @@ If you find an interesting or important question missing, submit it via
Target: x86_64-unknown-linux-gnu
Thread model: posix
InstalledDir: /prg/tmp/llvm-project/build/bin
- clang-13: note: diagnostic msg:
+ clang-13: note: diagnostic msg:
********************
```
diff --git a/docs/best_practices.md b/docs/best_practices.md
index 7016f08d..5f2d45ed 100644
--- a/docs/best_practices.md
+++ b/docs/best_practices.md
@@ -4,20 +4,26 @@
### Targets
- * [Fuzzing a binary-only target](#fuzzing-a-binary-only-target)
- * [Fuzzing a GUI program](#fuzzing-a-gui-program)
- * [Fuzzing a network service](#fuzzing-a-network-service)
+* [Fuzzing a target with source code available](#fuzzing-a-target-with-source-code-available)
+* [Fuzzing a binary-only target](#fuzzing-a-binary-only-target)
+* [Fuzzing a GUI program](#fuzzing-a-gui-program)
+* [Fuzzing a network service](#fuzzing-a-network-service)
### Improvements
- * [Improving speed](#improving-speed)
- * [Improving stability](#improving-stability)
+* [Improving speed](#improving-speed)
+* [Improving stability](#improving-stability)
## Targets
+### Fuzzing a target with source code available
+
+To learn how to fuzz a target if source code is available, see [fuzzing_in_depth.md](fuzzing_in_depth.md).
+
### Fuzzing a binary-only target
-For a comprehensive guide, see [binaryonly_fuzzing.md](binaryonly_fuzzing.md).
+For a comprehensive guide, see
+[fuzzing_binary-only_targets.md](fuzzing_binary-only_targets.md).
### Fuzzing a GUI program
diff --git a/docs/parallel_fuzzing.md b/docs/parallel_fuzzing.md
index d24f2837..130cb3ce 100644
--- a/docs/parallel_fuzzing.md
+++ b/docs/parallel_fuzzing.md
@@ -1,28 +1,28 @@
# Tips for parallel fuzzing
-This document talks about synchronizing afl-fuzz jobs on a single machine
-or across a fleet of systems. See README.md for the general instruction manual.
+This document talks about synchronizing afl-fuzz jobs on a single machine or
+across a fleet of systems. See README.md for the general instruction manual.
Note that this document is rather outdated. please refer to the main document
-section on multiple core usage [fuzzing_expert.md#Using multiple cores](fuzzing_expert.md#b-using-multiple-cores)
+section on multiple core usage
+[fuzzing_in_depth.md:b) Using multiple cores](fuzzing_in_depth.md#b-using-multiple-cores)
for up to date strategies!
## 1) Introduction
-Every copy of afl-fuzz will take up one CPU core. This means that on an
-n-core system, you can almost always run around n concurrent fuzzing jobs with
+Every copy of afl-fuzz will take up one CPU core. This means that on an n-core
+system, you can almost always run around n concurrent fuzzing jobs with
virtually no performance hit (you can use the afl-gotcpu tool to make sure).
-In fact, if you rely on just a single job on a multi-core system, you will
-be underutilizing the hardware. So, parallelization is always the right way to
-go.
+In fact, if you rely on just a single job on a multi-core system, you will be
+underutilizing the hardware. So, parallelization is always the right way to go.
When targeting multiple unrelated binaries or using the tool in
"non-instrumented" (-n) mode, it is perfectly fine to just start up several
-fully separate instances of afl-fuzz. The picture gets more complicated when
-you want to have multiple fuzzers hammering a common target: if a hard-to-hit
-but interesting test case is synthesized by one fuzzer, the remaining instances
-will not be able to use that input to guide their work.
+fully separate instances of afl-fuzz. The picture gets more complicated when you
+want to have multiple fuzzers hammering a common target: if a hard-to-hit but
+interesting test case is synthesized by one fuzzer, the remaining instances will
+not be able to use that input to guide their work.
To help with this problem, afl-fuzz offers a simple way to synchronize test
cases on the fly.
@@ -30,15 +30,15 @@ cases on the fly.
It is a good idea to use different power schedules if you run several instances
in parallel (`-p` option).
-Alternatively running other AFL spinoffs in parallel can be of value,
-e.g. Angora (https://github.com/AngoraFuzzer/Angora/)
+Alternatively running other AFL spinoffs in parallel can be of value, e.g.
+Angora (https://github.com/AngoraFuzzer/Angora/)
## 2) Single-system parallelization
-If you wish to parallelize a single job across multiple cores on a local
-system, simply create a new, empty output directory ("sync dir") that will be
-shared by all the instances of afl-fuzz; and then come up with a naming scheme
-for every instance - say, "fuzzer01", "fuzzer02", etc.
+If you wish to parallelize a single job across multiple cores on a local system,
+simply create a new, empty output directory ("sync dir") that will be shared by
+all the instances of afl-fuzz; and then come up with a naming scheme for every
+instance - say, "fuzzer01", "fuzzer02", etc.
Run the first one ("main node", -M) like this:
@@ -57,18 +57,18 @@ Each fuzzer will keep its state in a separate subdirectory, like so:
/path/to/sync_dir/fuzzer01/
-Each instance will also periodically rescan the top-level sync directory
-for any test cases found by other fuzzers - and will incorporate them into
-its own fuzzing when they are deemed interesting enough.
-For performance reasons only -M main node syncs the queue with everyone, the
--S secondary nodes will only sync from the main node.
+Each instance will also periodically rescan the top-level sync directory for any
+test cases found by other fuzzers - and will incorporate them into its own
+fuzzing when they are deemed interesting enough. For performance reasons only -M
+main node syncs the queue with everyone, the -S secondary nodes will only sync
+from the main node.
-The difference between the -M and -S modes is that the main instance will
-still perform deterministic checks; while the secondary instances will
-proceed straight to random tweaks.
+The difference between the -M and -S modes is that the main instance will still
+perform deterministic checks; while the secondary instances will proceed
+straight to random tweaks.
-Note that you must always have one -M main instance!
-Running multiple -M instances is wasteful!
+Note that you must always have one -M main instance! Running multiple -M
+instances is wasteful!
You can also monitor the progress of your jobs from the command line with the
provided afl-whatsup tool. When the instances are no longer finding new paths,
@@ -90,18 +90,18 @@ file name.
## 3) Multiple -M mains
-There is support for parallelizing the deterministic checks.
-This is only needed where
+There is support for parallelizing the deterministic checks. This is only needed
+where
1. many new paths are found fast over a long time and it looks unlikely that
main node will ever catch up, and
2. deterministic fuzzing is actively helping path discovery (you can see this
in the main node for the first for lines in the "fuzzing strategy yields"
- section. If the ration `found/attemps` is high, then it is effective. It
+ section. If the ration `found/attempts` is high, then it is effective. It
most commonly isn't.)
-Only if both are true it is beneficial to have more than one main.
-You can leverage this by creating -M instances like so:
+Only if both are true it is beneficial to have more than one main. You can
+leverage this by creating -M instances like so:
```
./afl-fuzz -i testcase_dir -o sync_dir -M mainA:1/3 [...]
@@ -115,27 +115,26 @@ distribute the deterministic fuzzing across. Note that if you boot up fewer
fuzzers than indicated by the second number passed to -M, you may end up with
poor coverage.
-## 4) Syncing with non-AFL fuzzers or independant instances
+## 4) Syncing with non-AFL fuzzers or independent instances
-A -M main node can be told with the `-F other_fuzzer_queue_directory` option
-to sync results from other fuzzers, e.g. libfuzzer or honggfuzz.
+A -M main node can be told with the `-F other_fuzzer_queue_directory` option to
+sync results from other fuzzers, e.g. libfuzzer or honggfuzz.
-Only the specified directory will by synced into afl, not subdirectories.
-The specified directory does not need to exist yet at the start of afl.
+Only the specified directory will by synced into afl, not subdirectories. The
+specified directory does not need to exist yet at the start of afl.
The `-F` option can be passed to the main node several times.
## 5) Multi-system parallelization
-The basic operating principle for multi-system parallelization is similar to
-the mechanism explained in section 2. The key difference is that you need to
-write a simple script that performs two actions:
+The basic operating principle for multi-system parallelization is similar to the
+mechanism explained in section 2. The key difference is that you need to write a
+simple script that performs two actions:
- - Uses SSH with authorized_keys to connect to every machine and retrieve
- a tar archive of the /path/to/sync_dir/ directory local to
- the machine.
- It is best to use a naming scheme that includes host name and it's being
- a main node (e.g. main1, main2) in the fuzzer ID, so that you can do
+ - Uses SSH with authorized_keys to connect to every machine and retrieve a tar
+ archive of the /path/to/sync_dir/ directory local to the
+ machine. It is best to use a naming scheme that includes host name and it's
+ being a main node (e.g. main1, main2) in the fuzzer ID, so that you can do
something like:
```sh
@@ -163,70 +162,70 @@ There are other (older) more featured, experimental tools:
However these do not support syncing just main nodes (yet).
-When developing custom test case sync code, there are several optimizations
-to keep in mind:
+When developing custom test case sync code, there are several optimizations to
+keep in mind:
- - The synchronization does not have to happen very often; running the
- task every 60 minutes or even less often at later fuzzing stages is
- fine
+ - The synchronization does not have to happen very often; running the task
+ every 60 minutes or even less often at later fuzzing stages is fine
- - There is no need to synchronize crashes/ or hangs/; you only need to
- copy over queue/* (and ideally, also fuzzer_stats).
+ - There is no need to synchronize crashes/ or hangs/; you only need to copy
+ over queue/* (and ideally, also fuzzer_stats).
- - It is not necessary (and not advisable!) to overwrite existing files;
- the -k option in tar is a good way to avoid that.
+ - It is not necessary (and not advisable!) to overwrite existing files; the -k
+ option in tar is a good way to avoid that.
- There is no need to fetch directories for fuzzers that are not running
locally on a particular machine, and were simply copied over onto that
system during earlier runs.
- - For large fleets, you will want to consolidate tarballs for each host,
- as this will let you use n SSH connections for sync, rather than n*(n-1).
+ - For large fleets, you will want to consolidate tarballs for each host, as
+ this will let you use n SSH connections for sync, rather than n*(n-1).
You may also want to implement staged synchronization. For example, you
- could have 10 groups of systems, with group 1 pushing test cases only
- to group 2; group 2 pushing them only to group 3; and so on, with group
+ could have 10 groups of systems, with group 1 pushing test cases only to
+ group 2; group 2 pushing them only to group 3; and so on, with group
eventually 10 feeding back to group 1.
- This arrangement would allow test interesting cases to propagate across
- the fleet without having to copy every fuzzer queue to every single host.
+ This arrangement would allow test interesting cases to propagate across the
+ fleet without having to copy every fuzzer queue to every single host.
- You do not want a "main" instance of afl-fuzz on every system; you should
run them all with -S, and just designate a single process somewhere within
the fleet to run with -M.
- - Syncing is only necessary for the main nodes on a system. It is possible
- to run main-less with only secondaries. However then you need to find out
- which secondary took over the temporary role to be the main node. Look for
- the `is_main_node` file in the fuzzer directories, eg. `sync-dir/hostname-*/is_main_node`
+ - Syncing is only necessary for the main nodes on a system. It is possible to
+ run main-less with only secondaries. However then you need to find out which
+ secondary took over the temporary role to be the main node. Look for the
+ `is_main_node` file in the fuzzer directories, eg.
+ `sync-dir/hostname-*/is_main_node`
It is *not* advisable to skip the synchronization script and run the fuzzers
-directly on a network filesystem; unexpected latency and unkillable processes
-in I/O wait state can mess things up.
+directly on a network filesystem; unexpected latency and unkillable processes in
+I/O wait state can mess things up.
## 6) Remote monitoring and data collection
-You can use screen, nohup, tmux, or something equivalent to run remote
-instances of afl-fuzz. If you redirect the program's output to a file, it will
+You can use screen, nohup, tmux, or something equivalent to run remote instances
+of afl-fuzz. If you redirect the program's output to a file, it will
automatically switch from a fancy UI to more limited status reports. There is
also basic machine-readable information which is always written to the
fuzzer_stats file in the output directory. Locally, that information can be
interpreted with afl-whatsup.
-In principle, you can use the status screen of the main (-M) instance to
-monitor the overall fuzzing progress and decide when to stop. In this
-mode, the most important signal is just that no new paths are being found
-for a longer while. If you do not have a main instance, just pick any
-single secondary instance to watch and go by that.
+In principle, you can use the status screen of the main (-M) instance to monitor
+the overall fuzzing progress and decide when to stop. In this mode, the most
+important signal is just that no new paths are being found for a longer while.
+If you do not have a main instance, just pick any single secondary instance to
+watch and go by that.
-You can also rely on that instance's output directory to collect the
-synthesized corpus that covers all the noteworthy paths discovered anywhere
-within the fleet. Secondary (-S) instances do not require any special
-monitoring, other than just making sure that they are up.
+You can also rely on that instance's output directory to collect the synthesized
+corpus that covers all the noteworthy paths discovered anywhere within the
+fleet. Secondary (-S) instances do not require any special monitoring, other
+than just making sure that they are up.
-Keep in mind that crashing inputs are *not* automatically propagated to the
-main instance, so you may still want to monitor for crashes fleet-wide
-from within your synchronization or health checking scripts (see afl-whatsup).
+Keep in mind that crashing inputs are *not* automatically propagated to the main
+instance, so you may still want to monitor for crashes fleet-wide from within
+your synchronization or health checking scripts (see afl-whatsup).
## 7) Asymmetric setups
@@ -238,21 +237,20 @@ It is perhaps worth noting that all of the following is permitted:
out_dir//queue/* and writing their own finds to sequentially
numbered id:nnnnnn files in out_dir//queue/*.
- - Running some of the synchronized fuzzers with different (but related)
- target binaries. For example, simultaneously stress-testing several
- different JPEG parsers (say, IJG jpeg and libjpeg-turbo) while sharing
- the discovered test cases can have synergistic effects and improve the
- overall coverage.
+ - Running some of the synchronized fuzzers with different (but related) target
+ binaries. For example, simultaneously stress-testing several different JPEG
+ parsers (say, IJG jpeg and libjpeg-turbo) while sharing the discovered test
+ cases can have synergistic effects and improve the overall coverage.
(In this case, running one -M instance per target is necessary.)
- - Having some of the fuzzers invoke the binary in different ways.
- For example, 'djpeg' supports several DCT modes, configurable with
- a command-line flag, while 'dwebp' supports incremental and one-shot
- decoding. In some scenarios, going after multiple distinct modes and then
- pooling test cases will improve coverage.
+ - Having some of the fuzzers invoke the binary in different ways. For example,
+ 'djpeg' supports several DCT modes, configurable with a command-line flag,
+ while 'dwebp' supports incremental and one-shot decoding. In some scenarios,
+ going after multiple distinct modes and then pooling test cases will improve
+ coverage.
- Much less convincingly, running the synchronized fuzzers with different
starting test cases (e.g., progressive and standard JPEG) or dictionaries.
The synchronization mechanism ensures that the test sets will get fairly
- homogeneous over time, but it introduces some initial variability.
+ homogeneous over time, but it introduces some initial variability.
\ No newline at end of file
diff --git a/qemu_mode/README.md b/qemu_mode/README.md
index d28479d9..c62309a2 100644
--- a/qemu_mode/README.md
+++ b/qemu_mode/README.md
@@ -217,5 +217,6 @@ them at run time, can be a faster alternative. That said, static rewriting is
fraught with peril, because it depends on being able to properly and fully model
program control flow without actually executing each and every code path.
-Checkout the "Fuzzing binary-only targets" section in our main README.md and
-the docs/binaryonly_fuzzing.md document for more information and hints.
+Check out
+[docs/fuzzing_binary-only_targets.md](../docs/fuzzing_binary-only_targets.md)
+for more information and hints.
--
cgit 1.4.1
From f63c2ed1450da8ab5ff38dcb7f0ab1a13d9865ca Mon Sep 17 00:00:00 2001
From: llzmb <46303940+llzmb@users.noreply.github.com>
Date: Thu, 2 Dec 2021 17:09:55 +0100
Subject: Change the word "entrypoint" to "entry point"
---
docs/FAQ.md | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
(limited to 'docs/FAQ.md')
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 34ed4cf5..ae4a77dc 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -33,7 +33,10 @@ If you find an interesting or important question missing, submit it via
A program contains `functions`, `functions` contain the compiled machine code.
The compiled machine code in a `function` can be in a single or many `basic blocks`.
- A `basic block` is the largest possible number of subsequent machine code instructions that has exactly one entrypoint (which can be be entered by multiple other basic blocks) and runs linearly without branching or jumping to other addresses (except at the end).
+ A `basic block` is the largest possible number of subsequent machine code
+ instructions that has exactly one entry point (which can be be entered by
+ multiple other basic blocks) and runs linearly without branching or jumping to
+ other addresses (except at the end).
```
function() {
--
cgit 1.4.1
From a7694e299a331bd8c4826b2402ee68cd6f83d8f9 Mon Sep 17 00:00:00 2001
From: llzmb <46303940+llzmb@users.noreply.github.com>
Date: Thu, 2 Dec 2021 20:45:48 +0100
Subject: Fix punctuation in connection with "however"
---
docs/FAQ.md | 10 +++++++---
docs/best_practices.md | 27 ++++++++++++++++++---------
docs/custom_mutators.md | 10 +++++-----
docs/fuzzing_in_depth.md | 10 +++++-----
docs/important_changes.md | 4 ++--
instrumentation/README.llvm.md | 11 ++++++-----
qemu_mode/README.persistent.md | 8 ++++----
qemu_mode/libcompcov/README.md | 8 ++++----
utils/afl_network_proxy/README.md | 13 +++++++------
utils/afl_untracer/README.md | 6 +++---
10 files changed, 61 insertions(+), 46 deletions(-)
(limited to 'docs/FAQ.md')
diff --git a/docs/FAQ.md b/docs/FAQ.md
index ae4a77dc..49444999 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -12,7 +12,9 @@ If you find an interesting or important question missing, submit it via
American Fuzzy Lop (AFL) was developed by Michał "lcamtuf" Zalewski starting in 2013/2014, and when he left Google end of 2017 he stopped developing it.
- At the end of 2019, the Google fuzzing team took over maintenance of AFL, however it is only accepting PRs from the community and is not developing enhancements anymore.
+ At the end of 2019, the Google fuzzing team took over maintenance of AFL,
+ however, it is only accepting PRs from the community and is not developing
+ enhancements anymore.
In the second quarter of 2019, 1 1/2 years later, when no further development of AFL had happened and it became clear there would none be coming, AFL++ was born, where initially community patches were collected and applied for bug fixes and enhancements.
Then from various AFL spin-offs - mostly academic research - features were integrated.
@@ -121,8 +123,10 @@ If you find an interesting or important question missing, submit it via
Sending the same input again and again should take the exact same path through the target every time.
If that is the case, the stability is 100%.
- If however randomness happens, e.g. a thread reading other external data, reaction to timing, etc., then in some of the re-executions with the same data the edge coverage result will be different accross runs.
- Those edges that change are then flagged "unstable".
+ If, however, randomness happens, e.g. a thread reading other external data,
+ reaction to timing, etc., then in some of the re-executions with the same data
+ the edge coverage result will be different accross runs. Those edges that
+ change are then flagged "unstable".
The more "unstable" edges, the more difficult for AFL++ to identify valid new paths.
diff --git a/docs/best_practices.md b/docs/best_practices.md
index 979849f4..15f8870c 100644
--- a/docs/best_practices.md
+++ b/docs/best_practices.md
@@ -54,9 +54,11 @@ to emulate the network. This is also much faster than the real network would be.
See [utils/socket_fuzzing/](../utils/socket_fuzzing/).
There is an outdated AFL++ branch that implements networking if you are
-desperate though: [https://github.com/AFLplusplus/AFLplusplus/tree/networking](https://github.com/AFLplusplus/AFLplusplus/tree/networking) -
-however a better option is AFLnet ([https://github.com/aflnet/aflnet](https://github.com/aflnet/aflnet))
-which allows you to define network state with different type of data packets.
+desperate though:
+[https://github.com/AFLplusplus/AFLplusplus/tree/networking](https://github.com/AFLplusplus/AFLplusplus/tree/networking)
+- however, a better option is AFLnet
+([https://github.com/aflnet/aflnet](https://github.com/aflnet/aflnet)) which
+allows you to define network state with different type of data packets.
## Improvements
@@ -72,13 +74,16 @@ which allows you to define network state with different type of data packets.
### Improving stability
-For fuzzing a 100% stable target that covers all edges is the best case.
-A 90% stable target that covers all edges is however better than a 100% stable target that ignores 10% of the edges.
+For fuzzing a 100% stable target that covers all edges is the best case. A 90%
+stable target that covers all edges is, however, better than a 100% stable
+target that ignores 10% of the edges.
With instability, you basically have a partial coverage loss on an edge, with ignored functions you have a full loss on that edges.
-There are functions that are unstable, but also provide value to coverage, e.g., init functions that use fuzz data as input.
-If however a function that has nothing to do with the input data is the source of instability, e.g., checking jitter, or is a hash map function etc., then it should not be instrumented.
+There are functions that are unstable, but also provide value to coverage, e.g.,
+init functions that use fuzz data as input. If, however, a function that has
+nothing to do with the input data is the source of instability, e.g., checking
+jitter, or is a hash map function etc., then it should not be instrumented.
To be able to exclude these functions (based on AFL++'s measured stability), the following process will allow to identify functions with variable edges.
@@ -116,8 +121,12 @@ Four steps are required to do this and it also requires quite some knowledge of
If `PCGUARD` is used, then you need to follow this guide (needs llvm 12+!):
[https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation](https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation)
- Only exclude those functions from instrumentation that provide no value for coverage - that is if it does not process any fuzz data directly or indirectly (e.g. hash maps, thread management etc.).
- If however a function directly or indirectly handles fuzz data, then you should not put the function in a deny instrumentation list and rather live with the instability it comes with.
+ Only exclude those functions from instrumentation that provide no value for
+ coverage - that is if it does not process any fuzz data directly or
+ indirectly (e.g. hash maps, thread management etc.). If, however, a
+ function directly or indirectly handles fuzz data, then you should not put
+ the function in a deny instrumentation list and rather live with the
+ instability it comes with.
4. Recompile the target
diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md
index 4018d633..fc5ecbf9 100644
--- a/docs/custom_mutators.md
+++ b/docs/custom_mutators.md
@@ -112,11 +112,11 @@ def deinit(): # optional for Python
- `fuzz_count` (optional):
- When a queue entry is selected to be fuzzed, afl-fuzz selects the number
- of fuzzing attempts with this input based on a few factors.
- If however the custom mutator wants to set this number instead on how often
- it is called for a specific queue entry, use this function.
- This function is most useful if `AFL_CUSTOM_MUTATOR_ONLY` is **not** used.
+ When a queue entry is selected to be fuzzed, afl-fuzz selects the number of
+ fuzzing attempts with this input based on a few factors. If, however, the
+ custom mutator wants to set this number instead on how often it is called
+ for a specific queue entry, use this function. This function is most useful
+ if `AFL_CUSTOM_MUTATOR_ONLY` is **not** used.
- `fuzz` (optional):
diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md
index 92b3cf86..96e709ab 100644
--- a/docs/fuzzing_in_depth.md
+++ b/docs/fuzzing_in_depth.md
@@ -131,8 +131,8 @@ The following options are available when you instrument with LTO mode
have to compile the target twice, once specifically with/for this mode by
setting `AFL_LLVM_CMPLOG=1`, and pass this binary to afl-fuzz via the `-c`
parameter. Note that you can compile also just a cmplog binary and use that
- for both however there will be a performance penality. You can read more about
- this in
+ for both, however, there will be a performance penality. You can read more
+ about this in
[instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md).
If you use LTO, LLVM or GCC_PLUGIN mode
@@ -151,7 +151,7 @@ only instrument parts of the target that you are interested in:
inlined and then would not match! See
[instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md)
-There are many more options and modes available however these are most of the
+There are many more options and modes available, however, these are most of the
time less effective. See:
* [instrumentation/README.ctx.md](../instrumentation/README.ctx.md)
* [instrumentation/README.ngram.md](../instrumentation/README.ngram.md)
@@ -369,8 +369,8 @@ This step is highly recommended!
### c) Minimizing all corpus files
The shorter the input files that still traverse the same path within the target,
-the better the fuzzing will be. This minimization is done with `afl-tmin`
-however it is a long process as this has to be done for every file:
+the better the fuzzing will be. This minimization is done with `afl-tmin`,
+however, it is a long process as this has to be done for every file:
```
mkdir input
diff --git a/docs/important_changes.md b/docs/important_changes.md
index 726de64d..6cd00791 100644
--- a/docs/important_changes.md
+++ b/docs/important_changes.md
@@ -15,8 +15,8 @@ With AFL++ 3.15 we introduced the following changes from previous behaviors:
With AFL++ 3.14 we introduced the following changes from previous behaviors:
* afl-fuzz: deterministic fuzzing it not a default for -M main anymore
- * afl-cmin/afl-showmap -i now descends into subdirectories (afl-cmin.bash
- however does not)
+ * afl-cmin/afl-showmap -i now descends into subdirectories (afl-cmin.bash,
+ however, does not)
With AFL++ 3.10 we introduced the following changes from previous behaviors:
* The '+' feature of the '-t' option now means to auto-calculate the timeout
diff --git a/instrumentation/README.llvm.md b/instrumentation/README.llvm.md
index 8133cbe4..d16049fa 100644
--- a/instrumentation/README.llvm.md
+++ b/instrumentation/README.llvm.md
@@ -106,9 +106,10 @@ either setting `AFL_CC_COMPILER=LLVM` or pass the parameter `--afl-llvm` via
CFLAGS/CXXFLAGS/CPPFLAGS.
The tool honors roughly the same environmental variables as afl-gcc (see
-[docs/env_variables.md](../docs/env_variables.md)). This includes AFL_USE_ASAN,
-AFL_HARDEN, and AFL_DONT_OPTIMIZE. However AFL_INST_RATIO is not honored as it
-does not serve a good purpose with the more effective PCGUARD analysis.
+[docs/env_variables.md](../docs/env_variables.md)). This includes
+`AFL_USE_ASAN`, `AFL_HARDEN`, and `AFL_DONT_OPTIMIZE`. However, `AFL_INST_RATIO`
+is not honored as it does not serve a good purpose with the more effective
+PCGUARD analysis.
## 3) Options
@@ -125,8 +126,8 @@ For splitting memcmp, strncmp, etc., see
Then there are different ways of instrumenting the target:
1. An better instrumentation strategy uses LTO and link time instrumentation.
- Note that not all targets can compile in this mode, however if it works it is
- the best option you can use. To go with this option, use
+ Note that not all targets can compile in this mode, however, if it works it
+ is the best option you can use. To go with this option, use
afl-clang-lto/afl-clang-lto++. See [README.lto.md](README.lto.md).
2. Alternatively you can choose a completely different coverage method:
diff --git a/qemu_mode/README.persistent.md b/qemu_mode/README.persistent.md
index 7210a8cc..ab45860d 100644
--- a/qemu_mode/README.persistent.md
+++ b/qemu_mode/README.persistent.md
@@ -17,10 +17,10 @@ The start of the persistent loop has to be set with environment variable
`AFL_QEMU_PERSISTENT_ADDR`.
This address can be the address of whatever instruction. Setting this address to
-the start of a function makes the usage simple. If the address is however within
-a function, either RET, OFFSET, or EXITS (see below in 2.2, 2.3, 2.6) have to be
-set. This address (as well as the RET address, see below) has to be defined in
-hexadecimal with the 0x prefix or as a decimal value.
+the start of a function makes the usage simple. If the address is, however,
+within a function, either RET, OFFSET, or EXITS (see below in 2.2, 2.3, 2.6)
+have to be set. This address (as well as the RET address, see below) has to be
+defined in hexadecimal with the 0x prefix or as a decimal value.
If both RET and EXITS are not set, QEMU will assume that START points to a
function and will patch the return address (on stack or in the link register) to
diff --git a/qemu_mode/libcompcov/README.md b/qemu_mode/libcompcov/README.md
index 6a72f5ff..50f0d802 100644
--- a/qemu_mode/libcompcov/README.md
+++ b/qemu_mode/libcompcov/README.md
@@ -18,7 +18,7 @@ and this module is not capable to log the coverage in this case.
If you have the source code of the fuzzing target you should nto use this
library and QEMU but build it with afl-clang-fast and the laf-intel options.
-To use this library make sure to preload it with AFL_PRELOAD.
+To use this library, make sure to preload it with AFL_PRELOAD.
```
export AFL_PRELOAD=/path/to/libcompcov.so
@@ -32,6 +32,6 @@ Level 1 logs just comparison with immediates / read-only memory and level 2
logs all the comparisons.
The library make use of https://github.com/ouadev/proc_maps_parser and so it is
-Linux specific. However this is not a strict dependency, other UNIX operating
-systems can be supported by replacing the code related to the
-/proc/self/maps parsing.
\ No newline at end of file
+Linux specific. However, this is not a strict dependency, other UNIX operating
+systems can be supported by replacing the code related to the /proc/self/maps
+parsing.
\ No newline at end of file
diff --git a/utils/afl_network_proxy/README.md b/utils/afl_network_proxy/README.md
index 05659c45..d2c00be2 100644
--- a/utils/afl_network_proxy/README.md
+++ b/utils/afl_network_proxy/README.md
@@ -34,16 +34,17 @@ afl-network-server -i 1111 -m 25M -t 1000 -- /bin/target -f @@
### on the (afl-fuzz) main node
-Just run afl-fuzz with your normal options, however the target should be
+Just run afl-fuzz with your normal options, however, the target should be
`afl-network-client` with the IP and PORT of the `afl-network-server` and
increase the -t value:
+
```
afl-fuzz -i in -o out -t 2000+ -- afl-network-client TARGET-IP 1111
```
-Note the '+' on the -t parameter value. The afl-network-server will take
-care of proper timeouts hence afl-fuzz should not. The '+' increases the
-timeout and the value itself should be 500-1000 higher than the one on
-afl-network-server.
+
+Note the '+' on the -t parameter value. The afl-network-server will take care of
+proper timeouts hence afl-fuzz should not. The '+' increases the timeout and the
+value itself should be 500-1000 higher than the one on afl-network-server.
### networking
@@ -53,7 +54,7 @@ either. Note that also the outgoing interface can be specified with a '%' for
Also make sure your default TCP window size is larger than your MAP_SIZE
(130kb is a good value).
-On Linux that is the middle value of `/proc/sys/net/ipv4/tcp_rmem`
+On Linux that is the middle value of `/proc/sys/net/ipv4/tcp_rmem`
## how to compile and install
diff --git a/utils/afl_untracer/README.md b/utils/afl_untracer/README.md
index ada0c916..9f41618f 100644
--- a/utils/afl_untracer/README.md
+++ b/utils/afl_untracer/README.md
@@ -5,9 +5,9 @@
afl-untracer is an example skeleton file which can easily be used to fuzz
a closed source library.
-It requires less memory and is x3-5 faster than qemu_mode however it is way
-more course grained and does not provide interesting features like compcov
-or cmplog.
+It requires less memory and is x3-5 faster than qemu_mode, however, it is way
+more course grained and does not provide interesting features like compcov or
+cmplog.
Supported is so far Intel (i386/x86_64) and AARCH64.
--
cgit 1.4.1
From 65c3db86256b3907404623fe1c52e01c9d12ff97 Mon Sep 17 00:00:00 2001
From: llzmb <46303940+llzmb@users.noreply.github.com>
Date: Thu, 2 Dec 2021 21:03:59 +0100
Subject: Fix punctuation in connection with "e.g."
---
.github/ISSUE_TEMPLATE/bug_report.md | 5 +++--
CONTRIBUTING.md | 2 +-
docs/FAQ.md | 4 ++--
docs/INSTALL.md | 3 ++-
docs/afl-fuzz_approach.md | 2 +-
docs/best_practices.md | 4 ++--
docs/custom_mutators.md | 7 ++++---
docs/env_variables.md | 22 +++++++++++-----------
docs/fuzzing_binary-only_targets.md | 6 +++---
docs/fuzzing_in_depth.md | 32 ++++++++++++++++----------------
docs/ideas.md | 2 +-
docs/important_changes.md | 2 +-
instrumentation/README.llvm.md | 2 +-
instrumentation/README.lto.md | 2 +-
utils/README.md | 2 +-
utils/afl_network_proxy/README.md | 6 ++++--
16 files changed, 54 insertions(+), 49 deletions(-)
(limited to 'docs/FAQ.md')
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 31152cd2..0d80f4a3 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -8,8 +8,9 @@ assignees: ''
---
**IMPORTANT**
-1. You have verified that the issue to be present in the current `dev` branch
-2. Please supply the command line options and relevant environment variables, e.g. a copy-paste of the contents of `out/default/fuzzer_setup`
+1. You have verified that the issue to be present in the current `dev` branch.
+2. Please supply the command line options and relevant environment variables,
+ e.g., a copy-paste of the contents of `out/default/fuzzer_setup`.
Thank you for making AFL++ better!
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0268b2e5..0ab4f8ec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ project, or added a file in a directory we already format, otherwise run:
Regarding the coding style, please follow the AFL style.
No camel case at all and use AFL's macros wherever possible
-(e.g. WARNF, FATAL, MAP_SIZE, ...).
+(e.g., WARNF, FATAL, MAP_SIZE, ...).
Remember that AFL++ has to build and run on many platforms, so
generalize your Makefiles/GNUmakefile (or your patches to our pre-existing
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 49444999..27250415 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -21,7 +21,7 @@ If you find an interesting or important question missing, submit it via
This already resulted in a much advanced AFL.
Until the end of 2019, the AFL++ team had grown to four active developers which then implemented their own research and features, making it now by far the most flexible and feature rich guided fuzzer available as open source.
- And in independent fuzzing benchmarks it is one of the best fuzzers available, e.g. [Fuzzbench Report](https://www.fuzzbench.com/reports/2020-08-03/index.html).
+ And in independent fuzzing benchmarks it is one of the best fuzzers available, e.g., [Fuzzbench Report](https://www.fuzzbench.com/reports/2020-08-03/index.html).