Fix punctuation in connection with "e.g."
MODIFY
.github/ISSUE_TEMPLATE/bug_report.md
.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!

MODIFY
CONTRIBUTING.md
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

MODIFY
docs/FAQ.md
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).
</p></details>
<details>
@@ -123,7 +123,7 @@ 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,
+ 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".

MODIFY
docs/INSTALL.md
docs/INSTALL.md
@@ -69,7 +69,8 @@ These build options exist:
* NO_PYTHON - disable python support
* NO_SPLICING - disables splicing mutation in afl-fuzz, not recommended for normal fuzzing
* 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)
+* LLVM_CONFIG - if your distro doesn't use the standard name for llvm-config
+ (e.g., Debian)
e.g.: `make ASAN_BUILD=1`

MODIFY
docs/afl-fuzz_approach.md
docs/afl-fuzz_approach.md
@@ -504,7 +504,7 @@ directory. This includes:
- `peak_rss_mb` - max rss usage reached during fuzzing in MB
- `edges_found` - how many edges have been found
- `var_byte_count` - how many edges are non-deterministic
-- `afl_banner` - banner text (e.g. the target name)
+- `afl_banner` - banner text (e.g., the target name)
- `afl_version` - the version of AFL++ used
- `target_mode` - default, persistent, qemu, unicorn, non-instrumented
- `command_line` - full command line used for the fuzzing session

MODIFY
docs/best_practices.md
docs/best_practices.md
@@ -48,7 +48,7 @@ this with persistent mode [instrumentation/README.persistent_mode.md](../instrum
and you have a performance gain of x10 instead of a performance loss of over
x10 - that is a x100 difference!).
-If modifying the source is not an option (e.g. because you only have a binary
+If modifying the source is not an option (e.g., because you only have a binary
and perform binary fuzzing) you can also use a shared library with AFL_PRELOAD
to emulate the network. This is also much faster than the real network would be.
See [utils/socket_fuzzing/](../utils/socket_fuzzing/).
@@ -123,7 +123,7 @@ Four steps are required to do this and it also requires quite some knowledge of
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
+ 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.

MODIFY
docs/custom_mutators.md
docs/custom_mutators.md
@@ -124,7 +124,7 @@ def deinit(): # optional for Python
additional test case.
Note that this function is optional - but it makes sense to use it.
You would only skip this if `post_process` is used to fix checksums etc.
- so if you are using it e.g. as a post processing library.
+ so if you are using it, e.g., as a post processing library.
Note that a length > 0 *must* be returned!
- `describe` (optional):
@@ -191,8 +191,9 @@ trimmed input. Here's a quick API description:
This method is called at the start of each trimming operation and receives
the initial buffer. It should return the amount of iteration steps possible
- on this input (e.g. if your input has n elements and you want to remove them
- one by one, return n, if you do a binary search, return log(n), and so on).
+ on this input (e.g., if your input has n elements and you want to remove
+ them one by one, return n, if you do a binary search, return log(n), and so
+ on).
If your trimming algorithm doesn't allow to determine the amount of
(remaining) steps easily (esp. while running), then you can alternatively

MODIFY
docs/env_variables.md
docs/env_variables.md
@@ -80,9 +80,9 @@ fairly broad use of environment variables instead:
Setting `AFL_INST_RATIO` to 0 is a valid choice. This will instrument only
the transitions between function entry points, but not individual branches.
- Note that this is an outdated variable. A few instances (e.g. afl-gcc) still
- support these, but state-of-the-art (e.g. LLVM LTO and LLVM PCGUARD) do not
- need this.
+ Note that this is an outdated variable. A few instances (e.g., afl-gcc)
+ still support these, but state-of-the-art (e.g., LLVM LTO and LLVM PCGUARD)
+ do not need this.
- `AFL_NO_BUILTIN` causes the compiler to generate code suitable for use with
libtokencap.so (but perhaps running a bit slower than without the flag).
@@ -319,7 +319,7 @@ checks or alter some of the more exotic semantics of the tool:
afl-fuzz), setting `AFL_PYTHON_MODULE` to a Python module can also provide
additional mutations. If `AFL_CUSTOM_MUTATOR_ONLY` is also set, all
mutations will solely be performed with the custom mutator. This feature
- allows to configure custom mutators which can be very helpful, e.g. fuzzing
+ allows to configure custom mutators which can be very helpful, e.g., fuzzing
XML or other highly flexible structured input. For details, see
[custom_mutators.md](custom_mutators.md).
@@ -449,7 +449,7 @@ checks or alter some of the more exotic semantics of the tool:
not crash the target again when the test case is given. To be able to still
re-trigger these crashes, you can use the `AFL_PERSISTENT_RECORD` variable
with a value of how many previous fuzz cases to keep prio a crash. If set to
- e.g. 10, then the 9 previous inputs are written to out/default/crashes as
+ e.g., 10, then the 9 previous inputs are written to out/default/crashes as
RECORD:000000,cnt:000000 to RECORD:000000,cnt:000008 and
RECORD:000000,cnt:000009 being the crash case. NOTE: This option needs to be
enabled in config.h first!
@@ -493,7 +493,7 @@ checks or alter some of the more exotic semantics of the tool:
This is especially useful when running multiple instances (`-M/-S` for
example). Applied tags are `banner` and `afl_version`. `banner` corresponds
to the name of the fuzzer provided through `-M/-S`. `afl_version`
- corresponds to the currently running AFL++ version (e.g. `++3.0c`). Default
+ corresponds to the currently running AFL++ version (e.g., `++3.0c`). Default
(empty/non present) will add no tags to the metrics. For more information,
see [rpc_statsd.md](rpc_statsd.md).
@@ -535,11 +535,11 @@ The QEMU wrapper used to instrument binary-only code supports several settings:
- `AFL_DEBUG` will print the found entry point for the binary to stderr. Use
this if you are unsure if the entry point might be wrong - but use it
- directly, e.g. `afl-qemu-trace ./program`.
+ directly, e.g., `afl-qemu-trace ./program`.
- `AFL_ENTRYPOINT` allows you to specify a specific entry point into the
binary (this can be very good for the performance!). The entry point is
- specified as hex address, e.g. `0x4004110`. Note that the address must be
+ specified as hex address, e.g., `0x4004110`. Note that the address must be
the address of a basic block.
- Setting `AFL_INST_LIBS` causes the translator to also instrument the code
@@ -595,7 +595,7 @@ QEMU driver to provide a `main` loop for a user provided
`stdin` rather than using in-memory test cases.
* `AFL_FRIDA_EXCLUDE_RANGES` - See `AFL_QEMU_EXCLUDE_RANGES`
* `AFL_FRIDA_INST_COVERAGE_FILE` - File to write DynamoRio format coverage
-information (e.g. to be loaded within IDA lighthouse).
+information (e.g., to be loaded within IDA lighthouse).
* `AFL_FRIDA_INST_DEBUG_FILE` - File to write raw assembly of original blocks
and their instrumented counterparts during block compilation.
* `AFL_FRIDA_INST_JIT` - Enable the instrumentation of Just-In-Time compiled
@@ -617,13 +617,13 @@ child on fork.
* `AFL_FRIDA_INST_RANGES` - See `AFL_QEMU_INST_RANGES`
* `AFL_FRIDA_INST_SEED` - Sets the initial seed for the hash function used to
generate block (and hence edge) IDs. Setting this to a constant value may be
-useful for debugging purposes, e.g. investigating unstable edges.
+useful for debugging purposes, e.g., investigating unstable edges.
* `AFL_FRIDA_INST_TRACE` - Log to stdout the address of executed blocks,
implies `AFL_FRIDA_INST_NO_OPTIMIZE`.
* `AFL_FRIDA_INST_TRACE_UNIQUE` - As per `AFL_FRIDA_INST_TRACE`, but each edge
is logged only once, requires `AFL_FRIDA_INST_NO_OPTIMIZE`.
* `AFL_FRIDA_INST_UNSTABLE_COVERAGE_FILE` - File to write DynamoRio format
-coverage information for unstable edges (e.g. to be loaded within IDA
+coverage information for unstable edges (e.g., to be loaded within IDA
lighthouse).
* `AFL_FRIDA_JS_SCRIPT` - Set the script to be loaded by the FRIDA scripting
engine. See [here](Scripting.md) for details.

MODIFY
docs/fuzzing_binary-only_targets.md
docs/fuzzing_binary-only_targets.md
@@ -113,7 +113,7 @@ If you want to fuzz a binary-only library, then you can fuzz it with frida-gum
via frida_mode/. You will have to write a harness to call the target function in
the library, use afl-frida.c as a template.
-You can also perform remote fuzzing with frida, e.g. if you want to fuzz on
+You can also perform remote fuzzing with frida, e.g., if you want to fuzz on
iPhone or Android devices, for this you can use
[https://github.com/ttdennis/fpicker/](https://github.com/ttdennis/fpicker/) as
an intermediate that uses AFL++ for fuzzing.
@@ -198,8 +198,8 @@ It is at about 80-85% performance.
Dyninst is a binary instrumentation framework similar to Pintool and DynamoRIO.
However, whereas Pintool and DynamoRIO work at runtime, Dyninst instruments the
target at load time and then let it run - or save the binary with the changes.
-This is great for some things, e.g. fuzzing, and not so effective for others,
-e.g. malware analysis.
+This is great for some things, e.g., fuzzing, and not so effective for others,
+e.g., malware analysis.
So, what you can do with Dyninst is taking every basic block and putting AFL++'s
instrumentation code in there - and then save the binary. Afterwards, just fuzz

MODIFY
docs/fuzzing_in_depth.md
docs/fuzzing_in_depth.md
@@ -167,7 +167,7 @@ allows you to find bugs that would not necessarily result in a crash.
Note that sanitizers have a huge impact on CPU (= less executions per second)
and RAM usage. Also you should only run one afl-fuzz instance per sanitizer
-type. This is enough because a use-after-free bug will be picked up, e.g. by
+type. This is enough because a use-after-free bug will be picked up, e.g., by
ASAN (address sanitizer) anyway when syncing to other fuzzing instances, so not
all fuzzing instances need to be instrumented with ASAN.
@@ -179,7 +179,7 @@ The following sanitizers have built-in support in AFL++:
local variable that is defined and read before it is even set. Enabled with
`export AFL_USE_MSAN=1` before compiling.
* UBSAN = Undefined Behavior SANitizer, finds instances where - by the C and C++
- standards - undefined behavior happens, e.g. adding two signed integers
+ standards - undefined behavior happens, e.g., adding two signed integers
together where the result is larger than a signed integer can hold. Enabled
with `export AFL_USE_UBSAN=1` before compiling.
* CFISAN = Control Flow Integrity SANitizer, finds instances where the control
@@ -202,15 +202,15 @@ be looked up in the sanitizer documentation of llvm/clang. afl-fuzz, however,
requires some specific parameters important for fuzzing to be set. If you want
to set your own, it might bail and report what it is missing.
-Note that some sanitizers cannot be used together, e.g. ASAN and MSAN, and
-others often cannot work together because of target weirdness, e.g. ASAN and
+Note that some sanitizers cannot be used together, e.g., ASAN and MSAN, and
+others often cannot work together because of target weirdness, e.g., ASAN and
CFISAN. You might need to experiment which sanitizers you can combine in a
target (which means more instances can be run without a sanitized target, which
is more effective).
### d) Modifying the target
-If the target has features that make fuzzing more difficult, e.g. checksums,
+If the target has features that make fuzzing more difficult, e.g., checksums,
HMAC, etc. then modify the source code so that checks for these values are
removed. This can even be done safely for source code used in operational
products by eliminating these checks within these AFL++ specific blocks:
@@ -250,7 +250,7 @@ Then build the target. (Usually with `make`)
reporting via `export AFL_QUIET=1`.
2. sometimes configure and build systems error on warnings - these should be
- disabled (e.g. `--disable-werror` for some configure scripts).
+ disabled (e.g., `--disable-werror` for some configure scripts).
3. in case the configure/build system complains about AFL++'s compiler and
aborts then set `export AFL_NOOPT=1` which will then just behave like the
@@ -354,7 +354,7 @@ You can find many good examples of starting files in the
Use the AFL++ tool `afl-cmin` to remove inputs from the corpus that do not
produce a new path in the target.
-Put all files from step a) into one directory, e.g. INPUTS.
+Put all files from step a) into one directory, e.g., INPUTS.
If the target program is to be called by fuzzing as `bin/target -d INPUTFILE`
the run afl-cmin like this:
@@ -380,8 +380,8 @@ for i in *; do
done
```
-This step can also be parallelized, e.g. with `parallel`. Note that this step is
-rather optional though.
+This step can also be parallelized, e.g., with `parallel`. Note that this step
+is rather optional though.
### Done!
@@ -503,7 +503,7 @@ can set the cache size (in MB) by setting the environment variable
`AFL_TESTCACHE_SIZE`.
There should be one main fuzzer (`-M main-$HOSTNAME` option) and as many
-secondary fuzzers (e.g. `-S variant1`) as you have cores that you use. Every
+secondary fuzzers (e.g., `-S variant1`) as you have cores that you use. Every
-M/-S entry needs a unique name (that can be whatever), however, the same -o
output directory location has to be used for all instances.
@@ -522,7 +522,7 @@ All other secondaries should be used like this:
* a quarter to a third with the MOpt mutator enabled: `-L 0`
* run with a different power schedule, recommended are:
`fast (default), explore, coe, lin, quad, exploit and rare` which you can set
- with e.g. `-p explore`
+ with, e.g., `-p explore`
* a few instances should use the old queue cycling with `-Z`
Also, it is recommended to set `export AFL_IMPORT_FIRST=1` to load test cases
@@ -547,7 +547,7 @@ A long list can be found at
However, you can also sync AFL++ with honggfuzz, libfuzzer with `-entropic=1`,
etc. Just show the main fuzzer (-M) with the `-F` option where the queue/work
-directory of a different fuzzer is, e.g. `-F /src/target/honggfuzz`. Using
+directory of a different fuzzer is, e.g., `-F /src/target/honggfuzz`. Using
honggfuzz (with `-n 1` or `-n 2`) and libfuzzer in parallel is highly
recommended!
@@ -615,8 +615,8 @@ To restart an afl-fuzz run, just reuse the same command line but replace the `-i
directory` with `-i -` or set `AFL_AUTORESUME=1`.
If you want to add new seeds to a fuzzing campaign you can run a temporary
-fuzzing instance, e.g. when your main fuzzer is using `-o out` and the new seeds
-are in `newseeds/` directory:
+fuzzing instance, e.g., when your main fuzzer is using `-o out` and the new
+seeds are in `newseeds/` directory:
```
AFL_BENCH_JUST_ONE=1 AFL_FAST_CAL=1 afl-fuzz -i newseeds -o out -S newseeds -- ./target
@@ -665,9 +665,9 @@ then you will not touch any of the other library APIs and features.
### h) How long to fuzz a target?
This is a difficult question. Basically if no new path is found for a long time
-(e.g. for a day or a week) then you can expect that your fuzzing won't be
+(e.g., for a day or a week) then you can expect that your fuzzing won't be
fruitful anymore. However, often this just means that you should switch out
-secondaries for others, e.g. custom mutator modules, sync to very different
+secondaries for others, e.g., custom mutator modules, sync to very different
fuzzers, etc.
Keep the queue/ directory (for future fuzzings of the same or similar targets)

MODIFY
docs/ideas.md
docs/ideas.md
@@ -32,7 +32,7 @@ Mentor: any
## Support other programming languages
Other programming languages also use llvm hence they could (easily?) supported
-for fuzzing, e.g. mono, swift, go, kotlin native, fortran, ...
+for fuzzing, e.g., mono, swift, go, kotlin native, fortran, ...
GCC also supports: Objective-C, Fortran, Ada, Go, and D
(according to [Gcc homepage](https://gcc.gnu.org/))

MODIFY
docs/important_changes.md
docs/important_changes.md
@@ -44,7 +44,7 @@ behaviors and defaults:
* `-i` input directory option now descends into subdirectories. It also
does not fatal on crashes and too large files, instead it skips them
and uses them for splicing mutations
- * -m none is now default, set memory limits (in MB) with e.g. -m 250
+ * -m none is now default, set memory limits (in MB) with, e.g., -m 250
* deterministic fuzzing is now disabled by default (unless using -M) and
can be enabled with -D
* a caching of test cases can now be performed and can be modified by

MODIFY
instrumentation/README.llvm.md
instrumentation/README.llvm.md
@@ -40,7 +40,7 @@ The idea and much of the initial implementation came from Laszlo Szekeres.
## 2a) How to use this - short
-Set the `LLVM_CONFIG` variable to the clang version you want to use, e.g.
+Set the `LLVM_CONFIG` variable to the clang version you want to use, e.g.:
```
LLVM_CONFIG=llvm-config-9 make

MODIFY
instrumentation/README.lto.md
instrumentation/README.lto.md
@@ -71,7 +71,7 @@ use an outdated Linux distribution, read the next section.
Installing the llvm snapshot builds is easy and mostly painless:
In the following line, change `NAME` for your Debian or Ubuntu release name
-(e.g. buster, focal, eon, etc.):
+(e.g., buster, focal, eon, etc.):
```
echo deb http://apt.llvm.org/NAME/ llvm-toolchain-NAME NAME >> /etc/apt/sources.list

MODIFY
utils/README.md
utils/README.md
@@ -13,7 +13,7 @@ Here's a quick overview of the stuff you can find in this directory:
- afl_proxy - skeleton file example to show how to fuzz
something where you gather coverage data via
- different means, e.g. hw debugger
+ different means, e.g., hw debugger
- afl_untracer - fuzz binary-only libraries much faster but with
less coverage than qemu_mode

MODIFY
utils/afl_network_proxy/README.md
utils/afl_network_proxy/README.md
@@ -6,7 +6,8 @@ Note that the impact on fuzzing speed will be huge, expect a loss of 90%.
## When to use this
1. when you have to fuzz a target that has to run on a system that cannot
- contain the fuzzing output (e.g. /tmp too small and file system is read-only)
+ contain the fuzzing output (e.g., /tmp too small and file system is
+ read-only)
2. when the target instantly reboots on crashes
3. ... any other reason you would need this
@@ -28,6 +29,7 @@ For most targets this hurts performance though so it is disabled by default.
Run `afl-network-server` with your target with the -m and -t values you need.
Important is the -i parameter which is the TCP port to listen on.
e.g.:
+
```
afl-network-server -i 1111 -m 25M -t 1000 -- /bin/target -f @@
```
@@ -50,7 +52,7 @@ value itself should be 500-1000 higher than the one on afl-network-server.
The TARGET can be an IPv4 or IPv6 address, or a host name that resolves to
either. Note that also the outgoing interface can be specified with a '%' for
-`afl-network-client`, e.g. `fe80::1234%eth0`.
+`afl-network-client`, e.g., `fe80::1234%eth0`.
Also make sure your default TCP window size is larger than your MAP_SIZE
(130kb is a good value).

Fix punctuation in connection with "e.g."