类
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 实例。
参数:
- dp: FuzzDataProvider - 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 实例。
参数:
- targetFunction: (Array<UInt8>) ->Int32 - 以 UInt8 数组为参数,以 Int32 为返回值的目标函数。
- args: Array<String> - Fuzz 运行参数。
init((FuzzDataProvider) -> Int32)
public init(targetFunction: (FuzzDataProvider) -> Int32)
功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,创建 Fuzzer 实例。
参数:
- targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数。
init((FuzzDataProvider) -> Int32, Array<String>)
public init(targetFunction: (FuzzDataProvider) -> Int32, args: Array<String>)
功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,以及 Fuzz 运行参数,创建 Fuzzer 实例。
参数:
- targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数。
- args: Array<String> - Fuzz 运行参数。
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 目标函数。
参数:
- targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数。
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 实例。
参数:
- targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数。
func build()
public func build(): Fuzzer
功能:生成一个 Fuzzer 实例。
返回值:
func setArgs(Array<String>)
public func setArgs(args: Array<String>): FuzzerBuilder
功能:设置 Fuzz 运行参数。
参数:
返回值:
- FuzzerBuilder - 当前 FuzzerBuilder 实例。
func setTargetFunction((Array<UInt8>) -> Int32)
public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): FuzzerBuilder
功能:设置 Fuzz 目标函数。
参数:
返回值:
- FuzzerBuilder - 当前 FuzzerBuilder 实例。
func setTargetFunction((FuzzDataProvider) -> Int32)
public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): FuzzerBuilder
功能:设置 Fuzz 目标函数。
参数:
- targetFunction: (FuzzDataProvider) ->Int32 - 以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数。
返回值:
- FuzzerBuilder - 当前 FuzzerBuilder 实例。
class FuzzDataProvider
public open class FuzzDataProvider {
public let data: Array<UInt8>
public var remainingBytes: Int64
public var offset: Int64
}
功能:FuzzDataProvider 是一个工具类,目的是将变异数据的字节流转化为标准的仓颉基本数据。
当前支持的数据结构如下:
目标类型 | API | 说明 |
---|---|---|
Bool | consumeBool() | 获取 1 个 Bool,变异数据长度不足时,抛出 ExhaustedException。 |
Array<Bool> | consumeBools(count: Int64) | 获取 N 个 Bool,变异数据长度不足时,抛出 ExhaustedException。 |
Byte | consumeByte() | 获取 1 个 Byte,变异数据长度不足时,抛出 ExhaustedException。 |
Array<Byte> | consumeBytes(count: Int64) | 获取 N 个 Byte,变异数据长度不足时,抛出 ExhaustedException。 |
UInt8 | consumeUInt8() | 获取 1 个 UInt8,变异数据长度不足时,抛出 ExhaustedException。 |
UInt16 | consumeUInt16() | 获取 1 个 UInt16,变异数据长度不足时,抛出 ExhaustedException。 |
UInt32 | consumeUInt32() | 获取 1 个 UInt32,变异数据长度不足时,抛出 ExhaustedException。 |
UInt64 | consumeUInt64() | 获取 1 个 UInt64,变异数据长度不足时,抛出 ExhaustedException。 |
Int8 | consumeInt8() | 获取 1 个 Int8,变异数据长度不足时,抛出 ExhaustedException。 |
Int16 | consumeInt16() | 获取 1 个 Int16,变异数据长度不足时,抛出 ExhaustedException。 |
Int32 | consumeInt32() | 获取 1 个 Int32,变异数据长度不足时,抛出 ExhaustedException。 |
Int32 | consumeInt32() | 获取 1 个 Int32,变异数据长度不足时,抛出 ExhaustedException。 |
Float32 | consumeFloat32() | 获取 1 个 Float32,变异数据长度不足时,抛出 ExhaustedException。 |
Float64 | consumeFloat64() | 获取 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。 |
Rune | consumeRune() | 获取 1 个 Rune,变异数据长度不足时,抛出 ExhaustedException。 |
String | consumeAsciiString(maxLength: Int64) | 获取 1 个纯 ASCII 的 String,长度为 0 到 maxLength,可以为 0。 |
String | consumeString(maxLength: Int64) | 获取 1 个 UTF8 String,长度为 0 到 maxLength,可以为 0。 |
Array<UInt8> | consumeAll() | 将 FuzzDataProvider 中的剩余内容全部转化为字节数组。 |
String | consumeAllAsAscii() | 将 FuzzDataProvider 中的剩余内容全部转化为纯 ASCII 的 String。 |
String | consumeAllAsString() | 将 FuzzDataProvider 中的剩余内容全部转化为 UTF8 String,末尾多余的字符不会被消耗。 |
在数据长度不足时,调用上述大部分虽然会抛出 ExhaustedException,但编写 fuzz 函数时通常并不需要对它进行处理,ExhaustedException 默认会被 fuzz 框架捕获,告诉 libfuzzer 该次运行无效,请继续下一轮变异。随着执行时间的变长,变异数据也会逐渐变长,直到满足 FuzzDataProvider 的需求。
如果达到了 max_len
仍无法满足 FuzzDataProvider 的需求,则进程退出,请修改 fuzz 测试用例(推荐) 或 增大 max_len
(不推荐)。
let data
public let data: 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 类型实例。
参数:
返回值:
- FuzzDataProvider - 构造的 FuzzDataProvider 类型实例。
static func withNativeData(CPointer<UInt8>, Int64)
public static unsafe func withNativeData(data: CPointer<UInt8>, length: Int64): FuzzDataProvider
功能:使用 C 指针数据生成 FuzzDataProvider 类型实例。
参数:
返回值:
- FuzzDataProvider - 构造的 FuzzDataProvider 类型实例。