カバレッジ分析

カバレッジ分析は、ファジングの実行中にコードのどの部分が実行されているかを理解するために不可欠です。マジック値チェックなどのファジングブロッカーを識別し、ハーネス改善の効果を時系列で追跡するのに役立ちます。

概要

ファジング中のコードカバレッジは2つの重要な目的を果たします：

1. ハーネス効果の評価: ファジングハーネスによってアプリケーションのどの部分が実際に実行されているかを理解する
2. ファジング進捗の追跡: ハーネス、ファザー、またはテスト対象システム(SUT)を更新した際にカバレッジがどう変化するか監視する

カバレッジはファザーの能力とパフォーマンスの代理指標です。カバレッジは絶対的な意味でファザーのパフォーマンスを測定するのに最適ではありませんが、与えられたセットアップでハーネスが効果的に機能しているかどうかを確実に示します。

主要概念

概念	説明
カバレッジ計測	実行されたコードパスを追跡するコンパイラフラグ
コーパスカバレッジ	ファジングコーパス内のすべてのテストケースを実行することで達成されるカバレッジ
マジック値チェック	ファザーの進捗をブロックする、発見しにくい条件付きチェック
カバレッジ誘導型ファジング	新しいコードパスを発見するインプットを優先するファジング戦略
カバレッジレポート	実行されたコードと未実行コードを視覚的またはテキスト形式で表現

適用する時期

以下の場合にこのテクニックを適用してください：

• 新しいファジングキャンペーンを開始してベースラインを確立する
• ファザーが新しいパスを見つけられずにプラトーに達しているようだ
• ハーネスの修正後に改善を検証する
• 異なるファザー間での移行時
• 辞書エントリやシードインプットが必要な領域を特定する
• 特定のコードパスに到達できない理由をデバッグする

以下の場合はこのテクニックをスキップしてください：

• ファジングキャンペーンが積極的にクラッシュを発見している
• カバレッジインフラがまだセットアップされていない
• 非常に大規模なコードベースで完全なカバレッジレポートが実用的でない
• ファザーの内部カバレッジメトリクスで充分な場合

クイックリファレンス

タスク	コマンド/パターン
LLVM カバレッジ計測 (C/C++)	-fprofile-instr-generate -fcoverage-mapping
GCC カバレッジ計測	-ftest-coverage -fprofile-arcs
cargo-fuzz カバレッジ (Rust)	cargo +nightly fuzz coverage <target>
LLVM プロファイルデータ生成	llvm-profdata merge -sparse file.profraw -o file.profdata
LLVM カバレッジレポート	llvm-cov report ./binary -instr-profile=file.profdata
LLVM HTML レポート	llvm-cov show ./binary -instr-profile=file.profdata -format=html -output-dir html/
gcovr HTML レポート	gcovr --html-details -o coverage.html

理想的なカバレッジワークフロー

次のワークフローは、ファジングキャンペーンにカバレッジ分析を統合するためのベストプラクティスを表しています：

[ファジングキャンペーン]
       |
       v
[コーパス生成]
       |
       v
[カバレッジ分析]
       |
       +---> カバレッジ増加? --> より大きなコーパスでファジング継続
       |
       +---> カバレッジ減少? --> ハーネスを修正するか SUT の変更を調査
       |
       +---> カバレッジ停滞? --> 辞書エントリまたはシードインプットを追加

重要な原則: リアルタイムのファザー統計ではなく、各ファジングキャンペーン後に生成されたコーパスを使用してカバレッジを計算します。このアプローチにより、異なるファジングツール間で再現可能で比較可能な測定値が提供されます。

ステップバイステップ

ステップ 1: カバレッジ計測でビルド

ツールチェーンに基づいて計測方法を選択してください：

LLVM/Clang (C/C++):

clang++ -fprofile-instr-generate -fcoverage-mapping \
  -O2 -DNO_MAIN \
  main.cc harness.cc execute-rt.cc -o fuzz_exec

GCC (C/C++):

g++ -ftest-coverage -fprofile-arcs \
  -O2 -DNO_MAIN \
  main.cc harness.cc execute-rt.cc -o fuzz_exec_gcov

Rust:

rustup toolchain install nightly --component llvm-tools-preview
cargo +nightly fuzz coverage fuzz_target_1

ステップ 2: 実行ランタイムの作成 (C/C++ のみ)

C/C++ プロジェクトの場合、コーパスを実行するランタイムを作成します：

// execute-rt.cc
#include <stdio.h>
#include <stdlib.h>
#include <dirent.h>
#include <stdint.h>

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size);

void load_file_and_test(const char *filename) {
    FILE *file = fopen(filename, "rb");
    if (file == NULL) {
        printf("Failed to open file: %s\n", filename);
        return;
    }

    fseek(file, 0, SEEK_END);
    long filesize = ftell(file);
    rewind(file);

    uint8_t *buffer = (uint8_t*) malloc(filesize);
    if (buffer == NULL) {
        printf("Failed to allocate memory for file: %s\n", filename);
        fclose(file);
        return;
    }

    long read_size = (long) fread(buffer, 1, filesize, file);
    if (read_size != filesize) {
        printf("Failed to read file: %s\n", filename);
        free(buffer);
        fclose(file);
        return;
    }

    LLVMFuzzerTestOneInput(buffer, filesize);

    free(buffer);
    fclose(file);
}

int main(int argc, char **argv) {
    if (argc != 2) {
        printf("Usage: %s <directory>\n", argv[0]);
        return 1;
    }

    DIR *dir = opendir(argv[1]);
    if (dir == NULL) {
        printf("Failed to open directory: %s\n", argv[1]);
        return 1;
    }

    struct dirent *entry;
    while ((entry = readdir(dir)) != NULL) {
        if (entry->d_type == DT_REG) {
            char filepath[1024];
            snprintf(filepath, sizeof(filepath), "%s/%s", argv[1], entry->d_name);
            load_file_and_test(filepath);
        }
    }

    closedir(dir);
    return 0;
}

ステップ 3: コーパスで実行

LLVM (C/C++):

LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec corpus/

GCC (C/C++):

./fuzz_exec_gcov corpus/

Rust: cargo fuzz coverage を実行するときに、カバレッジデータが自動的に生成されます。

ステップ 4: カバレッジデータを処理

LLVM:

# Raw プロファイルデータをマージ
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata

# テキストレポート生成
llvm-cov report ./fuzz_exec \
  -instr-profile=fuzz.profdata \
  -ignore-filename-regex='harness.cc|execute-rt.cc'

# HTML レポート生成
llvm-cov show ./fuzz_exec \
  -instr-profile=fuzz.profdata \
  -ignore-filename-regex='harness.cc|execute-rt.cc' \
  -format=html -output-dir fuzz_html/

GCC with gcovr:

# gcovr をインストール (pip で最新版)
python3 -m venv venv
source venv/bin/activate
pip3 install gcovr

# レポート生成
gcovr --gcov-executable "llvm-cov gcov" \
  --exclude harness.cc --exclude execute-rt.cc \
  --root . --html-details -o coverage.html

Rust:

# 必要なツールをインストール
cargo install cargo-binutils rustfilt

# HTML 生成スクリプトを作成
cat <<'EOF' > ./generate_html
#!/bin/sh
if [ $# -lt 1 ]; then
    echo "Error: Name of fuzz target is required."
    echo "Usage: $0 fuzz_target [sources...]"
    exit 1
fi
FUZZ_TARGET="$1"
shift
SRC_FILTER="$@"
TARGET=$(rustc -vV | sed -n 's|host: ||p')
cargo +nightly cov -- show -Xdemangler=rustfilt \
  "target/$TARGET/coverage/$TARGET/release/$FUZZ_TARGET" \
  -instr-profile="fuzz/coverage/$FUZZ_TARGET/coverage.profdata" \
  -show-line-counts-or-regions -show-instantiations \
  -format=html -o fuzz_html/ $SRC_FILTER
EOF
chmod +x ./generate_html

# HTML レポート生成
./generate_html fuzz_target_1 src/lib.rs

ステップ 5: 結果を分析

カバレッジレポートをレビューして以下を特定します：

• 未カバーのコードブロック: より良いシードインプットまたは辞書エントリが必要な領域
• マジック値チェック: 進捗をブロックするハードコードされた値を持つ条件文
• デッドコード: ハーネスを通じて到達不可能な可能性のある関数
• カバレッジの変化: ベースラインと比較して改善または回帰を追跡

共通パターン

パターン: マジック値の特定

問題: ファザーがマジック値チェックで守られたパスを発見できない。

カバレッジが明らかにするもの:

// カバレッジはこのブロックが決して実行されないことを示す
if (buf == 0x7F454C46) {  // ELF マジック番号
    // buf の解析開始
}

ソリューション: マジック値を辞書ファイルに追加：

# magic.dict
"\x7F\x45\x4C\x46"

パターン: クラッシュインプットの処理

問題: コーパスに不正なインプットが含まれていてカバレッジ生成が失敗する。

修正前:

./fuzz_exec corpus/  # 不正なインプットでクラッシュ、カバレッジ未生成

修正後:

// 実行前にフォーク、クラッシュを隔離
int main(int argc, char **argv) {
    // ... ディレクトリ開閉のコード ...

    while ((entry = readdir(dir)) != NULL) {
        if (entry->d_type == DT_REG) {
            pid_t pid = fork();
            if (pid == 0) {
                // 子プロセス - クラッシュが親に影響しない
                char filepath[1024];
                snprintf(filepath, sizeof(filepath), "%s/%s", argv[1], entry->d_name);
                load_file_and_test(filepath);
                exit(0);
            } else {
                // 親は子の終了を待機
                waitpid(pid, NULL, 0);
            }
        }
    }
}

パターン: CMake 統合

使用例: CMake プロジェクトへのカバレッジビルドの追加。

project(FuzzingProject)
cmake_minimum_required(VERSION 3.0)

# メインバイナリ
add_executable(program main.cc)

# ファジングバイナリ
add_executable(fuzz main.cc harness.cc)
target_compile_definitions(fuzz PRIVATE NO_MAIN=1)
target_compile_options(fuzz PRIVATE -g -O2 -fsanitize=fuzzer)
target_link_libraries(fuzz -fsanitize=fuzzer)

# カバレッジ実行バイナリ
add_executable(fuzz_exec main.cc harness.cc execute-rt.cc)
target_compile_definitions(fuzz_exec PRIVATE NO_MAIN)
target_compile_options(fuzz_exec PRIVATE -O2 -fprofile-instr-generate -fcoverage-mapping)
target_link_libraries(fuzz_exec -fprofile-instr-generate)

ビルド：

cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .
cmake --build . --target fuzz_exec

高度な使用方法

ティップスと トリックス

ティップス	役に立つ理由
LLVM 18+ で -show-directory-coverage を使用	大規模なレポートをフラットなファイル一覧ではなくディレクトリ構造で整理
lcov フォーマットへのエクスポートでより良い HTML	llvm-cov export -format=lcov + genhtml がファイルごとのレポートを提供
キャンペーン間のカバレッジ比較	.profdata ファイルをタイムスタンプとともに保存して時系列で進捗追跡
レポートからハーネスコードを除外	-ignore-filename-regex で SUT カバレッジのみにフォーカス
CI/CD でカバレッジを自動化	スケジュール済みファジング実行後に自動的にカバレッジレポート生成
Clang 14+ に gcovr 5.1+ を使用	古い gcovr 版には最新 LLVM との互換性問題がある

インクリメンタルカバレッジ更新

GCC の gcov 計測は複数実行を通じて .gcda ファイルをインクリメンタルに更新します。テストケースを追加する際にカバレッジを追跡するのに便利です：

# 最初の実行
./fuzz_exec_gcov corpus_batch_1/
gcovr --html coverage_v1.html

# 2番目の実行 (既存のカバレッジに追加)
./fuzz_exec_gcov corpus_batch_2/
gcovr --html coverage_v2.html

# 最初からやり直す
gcovr --delete  # .gcda ファイル削除
./fuzz_exec_gcov corpus/

大規模コードベースの処理

数百のソースファイルがあるプロジェクトの場合：

1. プリフィックスでフィルタ: 関連ディレクトリのレポートのみ生成

   llvm-cov show ./fuzz_exec -instr-profile=fuzz.profdata /path/to/src/
   

2. ディレクトリカバレッジを使用: ディレクトリでグループ化して乱雑さを削減 (LLVM 18+)

   llvm-cov show -show-directory-coverage -format=html -output-dir html/
   

3. プログラム分析用に JSON 生成:

   llvm-cov export -format=lcov > coverage.json
   

差分カバレッジ

2つのファジングキャンペーン間のカバレッジを比較：

# キャンペーン 1
LLVM_PROFILE_FILE=campaign1.profraw ./fuzz_exec corpus1/
llvm-profdata merge -sparse campaign1.profraw -o campaign1.profdata

# キャンペーン 2
LLVM_PROFILE_FILE=campaign2.profraw ./fuzz_exec corpus2/
llvm-profdata merge -sparse campaign2.profraw -o campaign2.profdata

# 比較
llvm-cov show ./fuzz_exec \
  -instr-profile=campaign2.profdata \
  -instr-profile=campaign1.profdata \
  -show-line-counts-or-regions

アンチパターン

アンチパターン	問題	正しいアプローチ
比較にファザーレポート済みカバレッジを使用	異なるファザーはカバレッジを異なる方法で計算するため、クロスツール比較は無意味	再現可能な測定値のために専用ツール (llvm-cov, gcovr) を使用
最適化でカバレッジを生成	-O3 最適化はコードを削除でき、カバレッジが誤解を招く	カバレッジビルドに -O2 または -O0 を使用
ハーネスコードをフィルタしない	ハーネスカバレッジが数値を膨らませ SUT カバレッジを曖昧にする	-ignore-filename-regex または --exclude でハーネスファイルをフィルタ
LLVM と GCC 計測を混合	互換性のない形式がパース失敗を引き起こす	カバレッジビルドに同じツールチェーンを使用
クラッシュインプットを無視	クラッシュがカバレッジ生成を防止、実際のカバレッジデータを隠す	最初にクラッシュを修正するか、プロセスフォークで隔離
時系列でカバレッジを追跡しない	一度のカバレッジチェックは回帰と改善を見逃す	カバレッジデータをタイムスタンプとともに保存してトレンド追跡

ツール別ガイダンス

libFuzzer

libFuzzer はデフォルトで LLVM の SanitizerCoverage をファジング誘導に使用しますが、レポート生成には別の計測が必要です。

カバレッジ用にビルド:

clang++ -fprofile-instr-generate -fcoverage-mapping \
  -O2 -DNO_MAIN \
  main.cc harness.cc execute-rt.cc -o fuzz_exec

コーパスを実行してレポート生成:

LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec corpus/
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata
llvm-cov show ./fuzz_exec -instr-profile=fuzz.profdata -format=html -output-dir html/

統合ティップス:

• カバレッジビルドに -fsanitize=fuzzer を使用しない (プロファイル計測と競合)
• 異なるメイン関数で同じハーネス関数 (LLVMFuzzerTestOneInput) を再利用
• -ignore-filename-regex フラグを使用してカバレッジレポートからハーネスコードを除外
• テンプレート多用の C++ コードに llvm-cov の -show-instantiation フラグの使用を検討

AFL++

AFL++ は独自のカバレッジフィードバック機構を提供していますが、詳細レポートには標準 LLVM/GCC ツールを使用します。

LLVM でカバレッジ用にビルド:

clang++ -fprofile-instr-generate -fcoverage-mapping \
  -O2 main.cc harness.cc execute-rt.cc -o fuzz_exec

GCC でカバレッジ用にビルド:

AFL_USE_ASAN=0 afl-gcc -ftest-coverage -fprofile-arcs \
  main.cc harness.cc execute-rt.cc -o fuzz_exec_gcov

実行してレポート生成:

# LLVM アプローチ
LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec afl_output/queue/
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata
llvm-cov report ./fuzz_exec -instr-profile=fuzz.profdata

# GCC アプローチ
./fuzz_exec_gcov afl_output/queue/
gcovr --html-details -o coverage.html

統合ティップス:

• カバレッジビルドに AFL++ 計測 (afl-clang-fast) を使用しない
• カバレッジフラグで標準コンパイラを代わりに使用
• AFL++ の queue/ ディレクトリはコーパスを含む
• AFL++ の組み込みカバレッジ統計はリアルタイム監視に有用だが詳細分析には不十分

cargo-fuzz (Rust)

cargo-fuzz は LLVM ツールを使用した組み込みのカバレッジ生成を提供します。

前提条件をインストール:

rustup toolchain install nightly --component llvm-tools-preview
cargo install cargo-binutils rustfilt

カバレッジデータ生成:

cargo +nightly fuzz coverage fuzz_target_1

HTML レポートスクリプト作成:

cat <<'EOF' > ./generate_html
#!/bin/sh
FUZZ_TARGET="$1"
shift
SRC_FILTER="$@"
TARGET=$(rustc -vV | sed -n 's|host: ||p')
cargo +nightly cov -- show -Xdemangler=rustfilt \
  "target/$TARGET/coverage/$TARGET/release/$FUZZ_TARGET" \
  -instr-profile="fuzz/coverage/$FUZZ_TARGET/coverage.profdata" \
  -show-line-counts-or-regions -show-instantiations \
  -format=html -o fuzz_html/ $SRC_FILTER
EOF
chmod +x ./generate_html

レポート生成:

./generate_html fuzz_target_1 src/lib.rs

統合ティップス:

• カバレッジに常に nightly ツールチェーンを使用
• -Xdemangler=rustfilt フラグで関数名を読みやすくする
• ソースファイル (e.g., src/lib.rs) でフィルタしてクレートコードにフォーカス
• Rust 固有出力向けに -show-line-counts-or-regions と -show-instantiations を使用
• コーパスは fuzz/corpus/<target>/ に位置

honggfuzz

honggfuzz は標準 LLVM/GCC カバレッジ計測と連携します。

カバレッジ用にビルド:

# honggfuzz コンパイラではなく標準コンパイラを使用
clang -fprofile-instr-generate -fcoverage-mapping \
  -O2 harness.c execute-rt.c -o fuzz_exec

コーパスを実行:

LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec honggfuzz_workspace/

統合ティップス:

• カバレッジビルドに hfuzz-clang を使用しない
• honggfuzz コーパスは通常ワークスペースディレクトリ内
• libFuzzer と同じ LLVM ワークフロー使用

トラブルシューティング

問題	原因	ソリューション
error: no profile data available	プロファイルが生成されていない、またはパス誤り	LLVM_PROFILE_FILE 設定と .profraw ファイルの存在を確認
Failed to load coverage	バイナリとプロファイルデータのミスマッチ	実行時と同じフラグでバイナリを再ビルド
カバレッジレポートが 0%	レポート生成に誤ったバイナリを使用	計測済みバイナリを使用、ファジングバイナリでない
no_working_dir_found エラー (gcovr)	.gcda ファイルが予期した場所にない	--gcov-ignore-errors=no_working_dir_found フラグを追加
クラッシュがカバレッジ生成をブロック	コーパスにクラッシュインプットが含まれている	クラッシュをフィルタするか、フォーク手法で隔離
ハーネス変更後カバレッジ低下	ハーネスが特定のコードパスをスキップするように	ハーネスロジックを見直す、より多くのインプット形式に対応の必要がある
HTML レポートがフラットファイル一覧	古い LLVM バージョン使用	LLVM 18+ にアップグレードして -show-directory-coverage 使用
incompatible instrumentation	LLVM と GCC カバレッジを混合	すべてを同じツールチェーンで再ビルド

関連スキル

このテクニックを使用するツール

スキル	適用方法
libfuzzer	フィードバック用 SanitizerCoverage 使用、カバレッジ分析でハーネス効果を評価
aflpp	フィードバック用エッジカバレッジ使用、詳細分析には別計測が必要
cargo-fuzz	Rust プロジェクト向け組み込み cargo fuzz coverage コマンド
honggfuzz	エッジカバレッジ使用、標準 LLVM/GCC ツールで分析

関連テクニック

スキル	関係性
fuzz-harness-writing	カバレッジはハーネスが到達するコードパスを明らかにし、改善をガイド
fuzzing-dictionaries	カバレッジがマジック値チェックを特定し辞書エントリが必要
corpus-management	カバレッジ分析が冗長テストケース特定でコーパス キュレーション支援
sanitizers	カバレッジがサニタイザー計測コードが実際に実行されていることを検証

リソース

主要外部リソース

LLVM ソースベースコードカバレッジ LLVM のプロファイル計測に関する包括的ガイド。分岐カバレッジ、リージョンカバレッジ、既存ビルドシステムとの統合など高度な機能を含む。コンパイラフラグ、ランタイム動作、プロファイルデータ形式をカバー。

llvm-cov コマンドガイド show、report、export コマンドを含む llvm-cov ツールの詳細 CLI リファレンス。すべてのフィルタリングオプション、出力形式、llvm-profdata との統合をドキュメント化。

gcovr ドキュメンテーション gcov データからカバレッジレポートを生成する gcovr ツールの完全ガイド。HTML テーマ、フィルタリングオプション、マルチディレクトリプロジェクト、CI/CD 統合パターンをカバー。

SanitizerCoverage ドキュメンテーション LLVM の SanitizerCoverage 計測の低レベルドキュメンテーション。インライン 8 ビットカウンタ、PC テーブル、ファザーがカバレッジフィードバックを誘導に使用する方法について説明。

ファザーパフォーマンスの評価について ファジングパフォーマンスメトリクスとしてのカバレッジの限界を検討する研究論文。単純なコードカバレッジ率を超えたより細かい評価方法を主張。

ビデオリソース

該当なし - カバレッジ分析は主にツール機能とワークフロートピックで、ドキュメンテーションと実践的な練習で最適に習得。