googleprojectzero/jackalopeWindows、macOS、Linux、Android向けのバイナリ、カバレッジガイド付きファザー
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 - 非決定論的ミューテーションに加えて決定論的ミューテーションを使用します。-serverフラグが使用されていない限り、デフォルトはtrue。
-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 - サーバーと通信するためのメソッドを実装します。