class DebugDataProvider

public class DebugDataProvider <: FuzzDataProvider

功能:此类继承了 FuzzDataProvider 类型,额外增加了调试信息。

父类型:

func consumeAll()

public override func consumeAll(): Array<UInt8>

功能:将所有数据转换成 UInt8 类型数组。

返回值:

func consumeAllAsAscii()

public override func consumeAllAsAscii(): String

功能:将所有数据转换成 Ascii String 类型。

返回值:

func consumeAllAsString()

public override func consumeAllAsString(): String

功能:将所有数据转换成 utf8 String 类型。

返回值:

func consumeAsciiString(Int64)

public override func consumeAsciiString(maxLength: Int64): String

功能:将数据转换成 Ascii String 类型实例。

参数:

返回值:

func consumeBool()

public override func consumeBool(): Bool

功能:将数据转换成 Bool 类型实例。

返回值:

func consumeBools(Int64)

public override func consumeBools(count: Int64): Array<Bool>

功能:将指定数量的数据转换成 Bool 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeByte()

public override func consumeByte(): Byte

功能:将数据转换成 Byte 类型实例。

返回值:

func consumeBytes(Int64)

public override func consumeBytes(count: Int64): Array<Byte>

功能:将指定数量的数据转换成 Byte 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeFloat32()

public override func consumeFloat32(): Float32

功能:将数据转换成 Float32 类型实例。

返回值:

func consumeFloat64()

public override func consumeFloat64(): Float64

功能:将数据转换成 Float64 类型实例。

返回值:

func consumeInt16()

public override func consumeInt16(): Int16

功能:将数据转换成 Int16 类型实例。

返回值:

func consumeInt16s(Int64)

public override func consumeInt16s(count: Int64): Array<Int16>

功能:将指定数量的数据转换成 Int16 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeInt32()

public override func consumeInt32(): Int32

功能:将数据转换成 Int32 类型实例。

返回值:

func consumeInt32s(Int64)

public override func consumeInt32s(count: Int64): Array<Int32>

功能:将指定数量的数据转换成 Int32 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeInt64()

public override func consumeInt64(): Int64

功能:将数据转换成 Int64 类型实例。

返回值:

func consumeInt64s(Int64)

public override func consumeInt64s(count: Int64): Array<Int64>

功能:将指定数量的数据转换成 Int64 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeInt8()

public override func consumeInt8(): Int8

功能:将数据转换成 Int8 类型实例。

返回值:

func consumeInt8s(Int64)

public override func consumeInt8s(count: Int64): Array<Int8>

功能:将指定数量的数据转换成 Int8 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeRune()

public override func consumeRune(): Rune

功能:将数据转换成 Rune 类型实例。

返回值:

func consumeString(Int64)

public override func consumeString(maxLength: Int64): String

功能:将数据转换成 utf8 String 类型实例。

参数:

返回值:

func consumeUInt16()

public override func consumeUInt16(): UInt16

功能:将数据转换成 UInt16 类型实例。

返回值:

func consumeUInt16s(Int64)

public override func consumeUInt16s(count: Int64): Array<UInt16>

功能:将指定数量的数据转换成 UInt16 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeUInt32()

public override func consumeUInt32(): UInt32

功能:将数据转换成 UInt32 类型实例。

返回值:

func consumeUInt32s(Int64)

public override func consumeUInt32s(count: Int64): Array<UInt32>

功能:将指定数量的数据转换成 UInt32 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeUInt64()

public override func consumeUInt64(): UInt64

功能:将数据转换成 UInt64 类型实例。

返回值:

func consumeUInt64s(Int64)

public override func consumeUInt64s(count: Int64): Array<UInt64>

功能:将指定数量的数据转换成 UInt64 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeUInt8()

public override func consumeUInt8(): UInt8

功能:将数据转换成 UInt8 类型实例。

返回值:

func consumeUInt8s(Int64)

public override func consumeUInt8s(count: Int64): Array<UInt8>

功能:将指定数量的数据转换成 UInt8 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func wrap(FuzzDataProvider)

public static func wrap(dp: FuzzDataProvider): DebugDataProvider

功能:根据 FuzzDataProvider 实例创建 DebugDataProvider 实例。

参数:

返回值:

class Fuzzer

public class Fuzzer {
    public init(targetFunction: (Array<UInt8>) -> Int32)
    public init(targetFunction: (Array<UInt8>) -> Int32, args: Array<String>)
    public init(targetFunction: (FuzzDataProvider) -> Int32)
    public init(targetFunction: (FuzzDataProvider) -> Int32, args: Array<String>)
}

功能:Fuzzer 类提供了 fuzz 工具的创建。用户提供需要进行 fuzz 测试的函数 targetFunction,以及设置特定的 fuzz 运行参数 args 比如 fuzz 执行次数、初始种子、生成数据最大长度等,可创建相应类型的 Fuzzer

init((Array<UInt8>) -> Int32)

public init(targetFunction: (Array<UInt8>) -> Int32)

功能:根据以 UInt8 数组为参数,以 Int32 为返回值的目标函数,创建 Fuzzer 实例。

参数:

init((Array<UInt8>) -> Int32, Array<String>)

public init(targetFunction: (Array<UInt8>) -> Int32, args: Array<String>)

功能:根据以 UInt8 数组为参数,以 Int32 为返回值的目标函数,以及 Fuzz 运行参数,创建 Fuzzer 实例。

参数:

init((FuzzDataProvider) -> Int32)

public init(targetFunction: (FuzzDataProvider) -> Int32)

功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,创建 Fuzzer 实例。

参数:

init((FuzzDataProvider) -> Int32, Array<String>)

public init(targetFunction: (FuzzDataProvider) -> Int32, args: Array<String>)

功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,以及 Fuzz 运行参数,创建 Fuzzer 实例。

参数:

func disableDebugDataProvider()

public func disableDebugDataProvider(): Unit

功能:关闭调试信息打印功能,当 FuzzDataProvider.consumeXXX 被调用时,返回值将不被打印到 stdout

func disableFakeCoverage()

public func disableFakeCoverage(): Unit

功能:关闭调用 enableFakeCoverage 对 Fuzz 的影响。

func enableDebugDataProvider()

public func enableDebugDataProvider(): Unit

功能:启用调试信息打印功能,当 FuzzDataProvider.consumeXXX 被调用时,返回值将被打印到 stdout。该功能默认为关闭。

func enableFakeCoverage()

public func enableFakeCoverage(): Unit

功能:创建一块虚假的覆盖率反馈区域,保持 Fuzz 持续进行。在 FuzzDataProvider 模式下,前几轮运行时可能由于数据不足而导致没有覆盖率,libfuzzer 会退出。该功能默认为关闭。

func getArgs()

public func getArgs(): Array<String>

功能:获取 Fuzz 运行参数。

返回值:

func setArgs(Array<String>)

public func setArgs(args: Array<String>): Unit

功能:设置 Fuzz 运行参数。

参数:

func setTargetFunction((Array<UInt8>) -> Int32)

public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): Unit

功能:设置 Fuzz 目标函数。

参数:

func setTargetFunction((FuzzDataProvider) -> Int32)

public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): Unit

功能:设置 Fuzz 目标函数。

参数:

func startFuzz()

public func startFuzz(): Unit

功能:执行 Fuzz。

class FuzzerBuilder

public class FuzzerBuilder {
    public init(targetFunction: (Array<UInt8>) -> Int32)
    public init(targetFunction: (FuzzDataProvider) -> Int32)
}

功能:此类用于 Fuzzer 类的构建。

init((Array<UInt8>) -> Int32)

public init(targetFunction: (Array<UInt8>) -> Int32)

功能:根据以 UInt8 数组为参数,以 Int32 为返回值的目标函数,创建 FuzzerBuilder 实例。

参数:

init((FuzzDataProvider) -> Int32)

public init(targetFunction: (FuzzDataProvider) -> Int32)

功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,创建 FuzzerBuilder 实例。

参数:

func build()

public func build(): Fuzzer

功能:生成一个 Fuzzer 实例。

返回值:

func setArgs(Array<String>)

public func setArgs(args: Array<String>): FuzzerBuilder

功能:设置 Fuzz 运行参数。

参数:

返回值:

func setTargetFunction((Array<UInt8>) -> Int32)

public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): FuzzerBuilder

功能:设置 Fuzz 目标函数。

参数:

返回值:

func setTargetFunction((FuzzDataProvider) -> Int32)

public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): FuzzerBuilder

功能:设置 Fuzz 目标函数。

参数:

返回值:

class FuzzDataProvider

public open class FuzzDataProvider {
    public let data: Array<UInt8>
    public var remainingBytes: Int64
    public var offset: Int64
}

功能:FuzzDataProvider 是一个工具类,目的是将变异数据的字节流转化为标准的仓颉基本数据。

当前支持的数据结构如下:

目标类型API说明
BoolconsumeBool()获取 1 个 Bool,变异数据长度不足时,抛出 ExhaustedException
Array<Bool>consumeBools(count: Int64)获取 N 个 Bool,变异数据长度不足时,抛出 ExhaustedException
ByteconsumeByte()获取 1 个 Byte,变异数据长度不足时,抛出 ExhaustedException
Array<Byte>consumeBytes(count: Int64)获取 N 个 Byte,变异数据长度不足时,抛出 ExhaustedException
UInt8consumeUInt8()获取 1 个 UInt8,变异数据长度不足时,抛出 ExhaustedException
UInt16consumeUInt16()获取 1 个 UInt16,变异数据长度不足时,抛出 ExhaustedException
UInt32consumeUInt32()获取 1 个 UInt32,变异数据长度不足时,抛出 ExhaustedException
UInt64consumeUInt64()获取 1 个 UInt64,变异数据长度不足时,抛出 ExhaustedException
Int8consumeInt8()获取 1 个 Int8,变异数据长度不足时,抛出 ExhaustedException
Int16consumeInt16()获取 1 个 Int16,变异数据长度不足时,抛出 ExhaustedException
Int32consumeInt32()获取 1 个 Int32,变异数据长度不足时,抛出 ExhaustedException
Int32consumeInt32()获取 1 个 Int32,变异数据长度不足时,抛出 ExhaustedException
Float32consumeFloat32()获取 1 个 Float32,变异数据长度不足时,抛出 ExhaustedException
Float64consumeFloat64()获取 1 个 Float64,变异数据长度不足时,抛出 ExhaustedException
Array<UInt8>consumeUInt8s(count: Int64)获取 N 个 UInt8,变异数据长度不足时,抛出 ExhaustedException
Array<UInt16>consumeUInt16s(count: Int64)获取 N 个 UInt16,变异数据长度不足时,抛出 ExhaustedException
Array<UInt32>consumeUInt32s(count: Int64)获取 N 个 UInt32,变异数据长度不足时,抛出 ExhaustedException
Array<UInt64>consumeUInt64s(count: Int64)获取 N 个 UInt64,变异数据长度不足时,抛出 ExhaustedException
Array<Int8>consumeInt8s(count: Int64)获取 N 个 Int8,变异数据长度不足时,抛出 ExhaustedException
Array<Int16>consumeInt16s(count: Int64)获取 N 个 Int16,变异数据长度不足时,抛出 ExhaustedException
Array<Int32>consumeInt32s(count: Int64)获取 N 个 Int32,变异数据长度不足时,抛出 ExhaustedException
Array<Int32>consumeInt32s(count: Int64)获取 N 个 Int32,变异数据长度不足时,抛出 ExhaustedException
RuneconsumeRune()获取 1 个 Rune,变异数据长度不足时,抛出 ExhaustedException
StringconsumeAsciiString(maxLength: Int64)获取 1 个纯 ASCII 的 String,长度为 0 到 maxLength,可以为 0。
StringconsumeString(maxLength: Int64)获取 1 个 UTF8 String,长度为 0 到 maxLength,可以为 0。
Array<UInt8>consumeAll()FuzzDataProvider 中的剩余内容全部转化为字节数组。
StringconsumeAllAsAscii()FuzzDataProvider 中的剩余内容全部转化为纯 ASCII 的 String
StringconsumeAllAsString()FuzzDataProvider 中的剩余内容全部转化为 UTF8 String,末尾多余的字符不会被消耗。

在数据长度不足时,调用上述大部分虽然会抛出 ExhaustedException,但编写 fuzz 函数时通常并不需要对它进行处理,ExhaustedException 默认会被 fuzz 框架捕获,告诉 libfuzzer 该次运行无效,请继续下一轮变异。随着执行时间的变长,变异数据也会逐渐变长,直到满足 FuzzDataProvider 的需求。

如果达到了 max_len 仍无法满足 FuzzDataProvider 的需求,则进程退出,请修改 fuzz 测试用例(推荐) 或 增大 max_len(不推荐)。

let data

public let data: Array<UInt8>

功能:变异数据。

类型:Array<UInt8>

var offset

public var offset: Int64

功能:已转化的字节数。

类型:Int64

var remainingBytes

public var remainingBytes: Int64

功能:剩余字节数。

类型:Int64

func consumeAll()

public open func consumeAll(): Array<UInt8>

功能:将所有数据转换成 UInt8 类型数组。

返回值:

func consumeAllAsAscii()

public open func consumeAllAsAscii(): String

功能:将所有数据转换成 Ascii String 类型。

返回值:

func consumeAllAsString()

public open func consumeAllAsString(): String

功能:将所有数据转换成 utf8 String 类型。

返回值:

func consumeAsciiString(Int64)

public open func consumeAsciiString(maxLength: Int64): String

功能:将数据转换成 Ascii String 类型实例。

参数:

返回值:

func consumeBool()

public open func consumeBool(): Bool

功能:将数据转换成 Bool 类型实例。

返回值:

func consumeBools(Int64)

public open func consumeBools(count: Int64): Array<Bool>

功能:将指定数量的数据转换成 Bool 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeByte()

public open func consumeByte(): Byte

功能:将数据转换成 Byte 类型实例。

返回值:

func consumeBytes(Int64)

public open func consumeBytes(count: Int64): Array<Byte>

功能:将指定数量的数据转换成 Byte 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeFloat32()

public open func consumeFloat32(): Float32

功能:将数据转换成 Float32 类型实例。

返回值:

func consumeFloat64()

public open func consumeFloat64(): Float64

功能:将数据转换成 Float64 类型实例。

返回值:

func consumeInt16()

public open func consumeInt16(): Int16

功能:将数据转换成 Int16 类型实例。

返回值:

func consumeInt16s(Int64)

public open func consumeInt16s(count: Int64): Array<Int16>

功能:将指定数量的数据转换成 Int16 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeInt32()

public open func consumeInt32(): Int32

功能:将数据转换成 Int32 类型实例。

返回值:

func consumeInt32s(Int64)

public open func consumeInt32s(count: Int64): Array<Int32>

功能:将指定数量的数据转换成 Int32 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeInt64()

public open func consumeInt64(): Int64

功能:将数据转换成 Int64 类型实例。

返回值:

func consumeInt64s(Int64)

public open func consumeInt64s(count: Int64): Array<Int64>

功能:将指定数量的数据转换成 Int64 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeInt8()

public open func consumeInt8(): Int8

功能:将数据转换成 Int8 类型实例。

返回值:

func consumeInt8s(Int64)

public open func consumeInt8s(count: Int64): Array<Int8>

功能:将指定数量的数据转换成 Int8 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeRune()

public open func consumeRune(): Rune

功能:将数据转换成 Rune 类型实例。

返回值:

func consumeString(Int64)

public open func consumeString(maxLength: Int64): String

功能:将数据转换成 utf8 String 类型实例。

参数:

返回值:

func consumeUInt16()

public open func consumeUInt16(): UInt16

功能:将数据转换成 UInt16 类型实例。

返回值:

func consumeUInt16s(Int64)

public open func consumeUInt16s(count: Int64): Array<UInt16>

功能:将指定数量的数据转换成 UInt16 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeUInt32()

public open func consumeUInt32(): UInt32

功能:将数据转换成 UInt32 类型实例。

返回值:

func consumeUInt32s(Int64)

public open func consumeUInt32s(count: Int64): Array<UInt32>

功能:将指定数量的数据转换成 UInt32 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeUInt64()

public open func consumeUInt64(): UInt64

功能:将数据转换成 UInt64 类型实例。

返回值:

func consumeUInt64s(Int64)

public open func consumeUInt64s(count: Int64): Array<UInt64>

功能:将指定数量的数据转换成 UInt64 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

func consumeUInt8()

public open func consumeUInt8(): UInt8

功能:将数据转换成 UInt8 类型实例。

返回值:

func consumeUInt8s(Int64)

public open func consumeUInt8s(count: Int64): Array<UInt8>

功能:将指定数量的数据转换成 UInt8 类型数组。

参数:

  • count: Int64 - 指定转换的数据量。

返回值:

static func withCangjieData(Array<UInt8>)

public static func withCangjieData(data: Array<UInt8>): FuzzDataProvider

功能:使用 Array<UInt8> 类型的数据生成 FuzzDataProvider 类型实例。

参数:

返回值:

static func withNativeData(CPointer<UInt8>, Int64)

public static unsafe func withNativeData(data: CPointer<UInt8>, length: Int64): FuzzDataProvider

功能:使用 C 指针数据生成 FuzzDataProvider 类型实例。

参数:

返回值: