打造爵士樂

本指南假設您已建立要建構的模糊測試器。這份指南使用與該指南相同的程式碼範例。

Fuchsia 會使用元建構系統 GN，產生 .ninja 檔案，明確說明如何建構系統。GN 目標是建構圖表中的節點，代表特定輸出內容，例如程式庫或執行檔。GN 範本是產生其他目標的規則。

為了讓新增新的模糊測試器變得更容易，Fuchsia 提供模糊測試相關的 GN 範本。

定義建構規則後，您可以使用 fx 建構模糊測試器。

Fuchsia 程式庫模糊 GN 範本

每種語言都有特定的模糊測試 GN 範本：

C/C++

fuchsia_library_fuzzer GN 範本會產生 executable 目標，該目標會編譯並連結雜訊目標函式與測試中的程式碼和雜訊引擎。

如要為 C 或 C++ 模糊測試器建立建構規則，請將 fuchsia_library_fuzzer GN 目標新增至適當的 BUILD.gn，例如含有對應單元測試規則的 BUILD.gn。

例如：

import("//build/fuzz.gni")

fuchsia_library_fuzzer("parser-fuzzer") {
  sources = [ "parser_fuzzer.cc" ]
  deps = [ ":parser-lib" ]
}

荒漠油廠

rustc_fuzzer GN 範本會產生 GN 目標，將 Rust 模糊測試目標函式編譯為 C 物件檔案，然後連結至模糊測試引擎。

如要為 Rust 模糊測試工具建立建構規則，請將 rustc_fuzzer GN 目標新增至 Crate 的 BUILD.gn。

選擇新增這個目標的位置和方式時，請考量下列事項：

  • 建議您讓 fuzzer 名稱與 fuzz 目標函式名稱相符，並在 Rust 程式庫 (即 src/lib.rs) 中加入 fuzz 目標函式。您可以按照這些建議，將範本主體保留空白。例如使用 toy_example_arbitrary 範例，您應將以下內容新增至 BUILD.gn：
import("//build/rust/rustc_fuzzer.gni")

rustc_fuzzer("toy_example_arbitrary") {
}
  • 如果雜訊目標函式名稱與雜訊產生器名稱不同，您必須為其提供 rustfunction 參數。舉例來說，如果您使用 toy_example_u8 範例，請在 BUILD.gn 中新增下列內容：
import("//build/rust/rustc_fuzzer.gni")

rustc_fuzzer("toy_example_raw_bytes") {
    rustfunction = "toy_example_u8"
}

  • 如果無法輕易將測試用的程式碼因式分解至程式庫，則可使用 Rust 二進位檔同時完成兩個額外步驟：

  • 您必須從編譯作業中排除 main 函式，以及在模糊測試時未使用的任何項目，例如僅在 main 中使用的匯入項目。例如：

    #[cfg(not(fuzz))]
use only::used::in::main;

#[cfg(not(fuzz))]
fn main() { ... }

  • 您必須使用 source_root 參數，明確將模糊測試目標函式提供給 rustc_fuzzer。例如，在 BUILD.gn 中：

    import("//build/rust/rustc_fuzzer.gni")

rustc_fuzzer("toy_example_with_main") {
    source_root = "src/main.rs"
}

選取模糊測試變體後，這些範本會連結 [libFuzzer] 編譯器執行階段與提供的 sources、deps 或兩者，藉此建構模糊測試二進位檔。這個程式碼必須提供「模糊目標」函式。

否則，您可以將測試套件與提供的程式碼連結，藉此建構模糊測試單元測試。這個測試架構會以固定的輸入內容 (例如長度為零的輸入內容) 呼叫模糊處理目標函式。這項測試可確保模糊工具能夠編譯和連結，即使未用於模糊化作業也一樣。

主機程式庫模糊 GN 範本

您也可以使用 Fuchsia 建構系統，建構在開發主機上執行的模糊測試工具。如要建構主機模糊測試工具，請使用 host_library_fuzzer GN 範本。

例如：

host_library_fuzzer("my_host_fuzzer") {
  sources = [ ... ]
  deps = [ ... ]
}

您可以使用 fx 建構主機雜訊產生器，而無須將其新增至 Fuchsia 元件或套件。

Fuchsia 模糊元件 GN 範本

fuchsia_fuzzer_component 範本會建立用來執行模糊工具的元件。可包含一般元件參數，例如 component_name 和 deps。

例如：

fuchsia_fuzzer_component("my-fuzzer-component") {
  component_name = "my-fuzzer"
  manifest = "meta/my-fuzzer.cml"
  deps = [ ":my-corpus"]
}

manifest 的程式庫模糊測試器必須包含 libfuzzer 的預設區塊。必須提供模糊測試器的輸出名稱做為套件相關路徑，做為第一個程式引數。其他引數可能包括 libFuzzer 選項，或與測試用輸入內容目錄相關的套件路徑，稱為測試用資料集。

例如：

{
    include: [
        "//sdk/lib/inspect/client.shard.cml",
        "//src/sys/fuzzing/libfuzzer/default.shard.cml",
        "//src/sys/test_runners/fuzz/default.shard.cml",
        "//src/sys/test_runners/tmp_storage.shard.cml",
        "syslog/client.shard.cml",
    ]
    program: {
        args: [
            "test/my-fuzzer",
            "-max_input_size=256",
            "data/my-corpus",
        ]
    }
}

種子語料庫應與元件 deps 中包含的 resource 目標相符。

例如：


import("//build/dist/resource.gni")

resource("my-corpus") {
  sources = [
    "input0",
    "input1",
    "input2",
  ]
  outputs = [ "data/my-corpus/{{source_file_part}}" ]
}

Fuchsia 模糊測試器套件 GN 範本

fuchsia_fuzzer_package 範本會將 fuzzer 元件封裝到 Fuchsia 中。 fuchsia_fuzzer_package 範本的特色在於新增特定建構規則，以便在使用模糊測試工具鏈變化版本建構時，為模糊測試器加上註解。

範本包含參數，這些參數是根據語言排序的模糊測試元件清單。每種語言都有一組支援的消毒劑，由其工具鏈提供，做為編譯器執行階段。如果所選工具鏈變化版本包含特定語言支援的清理器，對應的模糊測試器元件清單就能進行模糊測試。

舉例來說，如果 C++ 工具鍊支援假想的 examplesan，Rust 工具鍊不支援，且已選取 examplesan-fuzzer 變數，那麼下方的套件定義會建立 my-cpp-fuzzer 用於模糊測試，而 my-rust-fuzzer 則僅用於測試。

fuchsia_fuzzer_package("my-fuzzers") {
  cpp_fuzz_components = [ ":my-cpp-fuzzer" ]
  rust_fuzz_components = [ ":my-rust-fuzzer" ]
}

如果套件沒有以對應語言編寫的模糊測試器，則不必納入清單。

fuchsia_fuzzer_package 可使用與 fuchsia_package 相同的所有參數。

例如：

fuchsia_fuzzer_package("my-fuzzers") {
  package_name = "the-fuzzers"
  cpp_fuzz_components = [ ":my-fuzzer" ]
}

定義完成後，套件就必須像其他測試套件一樣，納入建構依附元件圖表中。通常是指將其加入一組測試。

例如：

group("tests") {
  deps = [
    ":my-test-package",
    ":my-fuzzers",
  ]
}

使用 fx 建構模糊測試器

如上所述，只有明確收到模糊測試器，可以使用適當的模糊變數檢測程式碼時，Fchsia 建構系統才會建構該模糊器。這些是結尾為 -fuzzer 的已知變體。每個擴充功能都是sanitizer 變體的擴充功能，包括：

如要建構含有模糊處理變化版本的 fuzzer_package，最簡單的方法就是使用 --fuzz-with <sanitizer> 旗標搭配 fx set。

例如：

fx set core.x64 --fuzz-with asan --with //bundles/tests
fx build

執行 fx set 後，您可以使用 ffx fuzz list 查看目前已設定的模糊測試器。您可以使用其他 ffx fuzz 指令執行模糊測試器。