Copyright 2020 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Jackalope 是一个可定制的、分布式的、覆盖率引导的模糊测试器，能够处理黑盒二进制文件。
虽然有很多优秀的覆盖率引导模糊测试器可以在源代码可用的目标上工作，但能在黑盒二进制文件上工作的却相对较少，尤其是在 Windows 和 macOS 操作系统上，而且那些确实存在的工具主要基于不太容易定制的代码库。Jackalope 的初始目标是：
Jackalope 可以独立使用，但作为库使用时更强大，用户可以插入自定义组件来替换默认行为。默认情况下，Jackalope 附带：
Jackalope 可以并行运行
-nthreads 命令行参数传递模糊测试线程数-start_server 命令行标志），并让工作机器上的模糊测试器连接到此服务器（-server 命令行标志）。然后服务器会在工作节点之间收集和分发样本、崩溃和覆盖率。Jackalope 目前不包含高级变异策略。相反，它附带了一组通用变异器，这些变异器对许多目标都有效，但鼓励用户根据他们想要模糊测试的目标编写自定义变异器和变异策略。
目前，黑盒二进制文件的模糊测试支持 Windows、macOS、Linux 和 Android 操作系统。
在 Linux 上，Jackalope 还能够使用 Sanitizer Coverage 运行（需要目标的源代码）。此模式记录在单独的文档中。
先决条件：Python 3
打开终端并根据需要设置构建环境。在 Windows 上，不要打开通用命令提示符，而是要为所构建的平台打开 Visual Studio 命令提示符，或运行 vcvars64.bat / vcvars32.bat。
导航到包含源代码的目录。
运行以下命令：
cd Jackalope
git clone --recurse-submodules [email protected]:googleprojectzero/TinyInst.git
(alternately: git clone --recurse-submodules https://github.com/googleprojectzero/TinyInst.git)
mkdir build
cd build
cmake <generator arguments> ..
cmake --build . --config Release
生成器参数取决于你的环境。在 macOS 上，你会想使用 -G Xcode，而在 Windows 上使用 Visual Studio 2019 进行 64 位构建时，你会使用 -G "Visual Studio 16 2019" -A x64。在 Linux 上，不需要生成器参数。为 Android 交叉编译时需要额外的 cmake 参数，这些参数与 TinyInst 的 Android 构建说明中描述的相同。如果你在支持通过 /dev/shm 使用共享内存的 VM 上对 Android 进行模糊测试，-DANDROID_TARGET=VM 会启用共享内存样本传递。
要构建以在 macOS 上针对 arm64e 二进制文件运行，请参见此处。
在 macOS 上遇到 No CMAKE_C_COMPILER could be found 错误？尝试更新 cmake。还要确保已安装 Xcode 并且至少运行过一次（它会在首次运行时安装一些组件）。
用法：
./fuzzer <fuzzer arguments> <instrumentation and other components arguments> -- <target command line>
支持以下命令行参数：
-in - 输入目录（包含初始样本集的目录）。如果输入目录为 "-"，模糊测试器会尝试恢复上一个会话（与使用 -restore 标志相同）。
-out - 输出目录
-t - 样本超时时间，以毫秒为单位
-t1 - 目标初始化超时时间（例如在到达目标方法之前，如果已定义）。默认为样本超时时间。
-nthreads - 模糊测试器线程数。默认为 1。
-delivery <file|shmem> - 要使用的样本传递机制。如果是 file，每个样本会作为文件输出，目标参数中的 "@@" 会被替换为文件路径。如果是 shmem，模糊测试器会改为创建共享内存，并将目标参数中的 "@@" 替换为共享内存的名称。在这种情况下，目标负责打开共享内存并提取样本。默认为 file。
-file_extension - 使用 file 样本传递时，将指定的扩展名附加到文件名。如果目标期望输入文件具有特定扩展名，这很有用。
-restore 或 -resume - 恢复并继续之前的模糊测试会话。模糊测试器和服务器进程都支持恢复。
-server - 指定要使用的覆盖率服务器。
-start_server - 运行服务器进程而不是模糊测试进程。
-crash_retry - 尝试重现崩溃的次数。默认为 10。在此重试次数内无法重现，或在不使用插桩运行时无法重现的崩溃会被标记为不稳定。
-coverage_retry - 重试重现新覆盖率的次数。在此重试次数内无法可靠重现的覆盖率被视为不稳定。仅包含不稳定覆盖率的样本不会被保存。
-clean_target_on_coverage - 在重现覆盖率时重启目标。默认为 true。
-minimize_samples - 尝试在将新样本保存到语料库之前对其进行最小化。默认为 true。
-iterations_per_round - 在继续处理下一个样本之前，对语料库中的样本进行变异和运行的次数。默认为 1000。对于非常慢的目标，你可以考虑减小此值。
-deterministic_mutations - 除了非确定性变异外，还使用确定性变异。默认为 true，除非使用了 -server 标志。
-deterministic_only - 优先进行确定性变异。注意：即使使用此标志，模糊测试器仍会使用非确定性变异，但仅在所有确定性变异都已用尽之后。当与 -server 一起运行时，让单个客户端实例执行确定性变异可能会很有用。
-max_sample_size - 要使用的最大样本大小。所有大于 max_sample_size 的输入样本都会被裁剪，变异器无法产生超过该大小的新样本。默认为 1000000。警告：使用共享内存样本传递时，max_sample_size 必须与目标期望的最大样本大小匹配，例如此处的测试目标。
-keep_samples_in_memory - 是否始终将所有样本保留在内存中。默认为 true。除非语料库太大而无法放入内存，否则建议使用。
-track_ranges - 启用读取范围跟踪功能。更多信息见此处。
-dry_run - 使 Jackalope 在处理完所有输入样本后、但在开始实际模糊测试之前退出。对于语料库最小化（注意：Jackalope 只会将包含以前未见过的覆盖率的样本添加到输出语料库中）或重现大量崩溃很有用。
-add_all_inputs - 将输入目录中的所有样本添加到模糊测试语料库中，即使那些不会触发任何新覆盖率的样本。默认关闭。
-dict <path> - 提供在变异期间使用的字典。字典应该是一个文本文件，每个条目占一行。可以使用 \xXX 转义序列。
-dump_coverage - 定期导出覆盖率（作为输出目录中的 coverage.txt），格式适合导入到 Lighthouse
有关 TinyInst 插桩命令行参数，请参阅 TinyInst readme。
示例（macOS）：
./fuzzer -in in -out out -t 1000 -delivery shmem -instrument_module test -target_module test -target_method __Z4fuzzPc -nargs 1 -iterations 10000 -persist -loop -cmp_coverage -- ./test -m @@
示例（Windows）：
fuzzer.exe -in in -out out -t 1000 -delivery shmem -instrument_module test.exe -target_module test.exe -target_method fuzz -nargs 1 -iterations 10000 -persist -loop -cmp_coverage -- test.exe -m @@
说明：这使用 "in" 作为输入目录，"out" 作为输出目录来运行模糊测试器。样本通过共享内存传递，不写入磁盘（-delivery shmem）。覆盖率从 test / test.exe 模块收集（-instrument_module 标志）。目标以持久模式运行，来自 test / test.exe 模块的函数 fuzz() 在循环中运行。此函数接受 1 个参数，并将在循环中运行最多 10000 次迭代，然后重启目标进程。使用比较覆盖率（-cmp_coverage 标志）以便轻松暴力破解多字节比较。test.exe -m @@ 是目标命令行，其中 @@ 会被替换为共享内存名称（如果未使用 -delivery shmem，则会被替换为文件名）。
Jackalope 由以下主要类组成：
Fuzzer - "主"类，处理大多数高级任务，例如跟踪语料库和覆盖率、将作业调度到线程、与服务器通信（如果存在）。Fuzzer 类公开了几个虚方法，可用于修改其行为。用户可以通过继承 Fuzzer 类并重载这些方法来创建自定义模糊测试器。
Sample - 用于存储样本数据（字节）的简单类。
Mutator - 处理变异。Mutator 类的主要工作是实现 Mutate() 方法，该方法修改样本。然而，变异器也可以更复杂，例如为每个样本定义额外的上下文，这些上下文将在 Mutate() 调用期间传递。变异器也可以是"元变异器"，以不同方式组合其他变异器。有关内置变异器，请参见 mutator.h。当模糊测试器选择输入样本时，它会在继续处理下一个样本之前对其进行一定数量的"轮次"模糊测试，变异器可以控制轮次数量。具体来说，模糊测试器会继续使用相同的输入样本，直到顶层变异器从其 Mutate() 方法返回 false。
Instrumentation - 处理目标的运行和覆盖率收集。模糊测试器附带了一个使用 TinyInst 的 Instrumentation 实现
SampleDelivery - 处理将样本传递给目标。模糊测试器捆绑了通过文件和通过共享内存的样本传递。
PRNG - 伪随机数生成器。默认情况下，Jackalope 使用基于 Mersenne twister 的 PRNG。
Server - 实现模糊测试器的服务器组件。服务器负责从客户端收集覆盖率以及触发新覆盖率的样本。然后服务器将这些样本分发给其他模糊测试器进程。
Client - 实现与服务器通信的方法。
定制模糊测试器的"预期"方式是继承 Fuzzer 类并重写相关方法。有关简单示例，请参见 main.cpp。可以重写的方法有：
CreateMutator() - 为模糊测试器创建变异器配置。有关示例，请参见 https://github.com/googleprojectzero/Jackalope/blob/main/main.cpp#L25
OutputFilter() - 可以在将样本传递给目标之前修改样本，例如修复头部或校验和。默认实现将按原样传递样本。
AdjustSamplePriority() - 模糊测试器维护一个按优先级排序的待模糊测试样本队列。此方法可用于在每次运行后调整样本的优先级。默认实现会为每次未产生新覆盖率的运行降低样本的优先级。如果某次运行产生了新覆盖率，样本的优先级会被重置。这确保模糊测试器在变异时会将更多时间花在产生新覆盖率的样本上。
CreateSampleDelivery() - 可用于定义将样本传递给目标的自定义机制。一个例子是通过网络或 IPC 发送样本。
CreateInstrumentation() - 可以重写以便模糊测试器使用自定义插桩。
CreatePRNG() - 可以重写以便使用自定义 PRNG。
问：在 macOS 上，我遇到了与 task_for_pid 相关的错误。
答：在 macOS 上，调试器（Jackalope 充当目标的调试器）需要具有调试另一个进程的适当权限。这可以通过两种方式解决：
sudo）。根据目标的不同，可能还需要禁用 SIP。Get Task Allow 授权。最简单的方法是直接使用 XCode 构建目标，因为 XCode 会自动为目标添加适当的调试授权。问：在插桩下运行时，我遇到了在正常运行目标时没有遇到的错误/崩溃/挂起。
答：这些通常可以通过添加以下标志来解决：
-generate_unwind 标志来解决。如果这不起作用，还有一个更激进的 -patch_return_addresses 标志，但请注意它会对性能产生显著影响。你可以在此处阅读有关这些标志的更多信息。在 Windows 上，-generate_unwind/-patch_return_addresses 的另一个替代方案是对目标的 32 位构建进行模糊测试。-stack_offset 0x1000 或其他值。这将解决目标在低于栈指针的地址上写入的插桩问题（这种行为在某些模块的叶函数中在 macOS 上观察到）。问：获得覆盖率很好，但我还能有内存清理吗？
答：我建议使用操作系统本身提供的特殊分配器来更可靠地捕获内存错误。