Protocol Definition

对于老旧风格的协议定义，可以参看 static protocol definition functions，此处描述的是新版本（仍处于实验阶段）的协议格式。

See the Quickstart guide for an intro to using boofuzz in general and a basic protocol definition example.

概述

Request 可以看作是要发送的消息，而 Blocks 则可视为消息内的块， Primitives 则是构成 Block/Request 的元素，这些元素可以是字节、字符串、数字、checksums。

样例

以下是一个 HTTP 消息的例子，演示了如何使用 Request、Block 和 primitives。

req = Request("HTTP-Request",children=(
    Block("Request-Line", children=(
        Group("Method", values= ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE"]),
        Delim("space-1", " "),
        String("URI", "/index.html"),
        Delim("space-2", " "),
        String("HTTP-Version", "HTTP/1.1"),
        Static("CRLF", "\r\n"),
    )),
    Block("Host-Line", children=(
        String("Host-Key", "Host:"),
        Delim("space", " "),
        String("Host-Value", "example.com"),
        Static("CRLF", "\r\n"),
    )),
    Static("CRLF", "\r\n"),
))

下面对协议定义的具体实现展开分析。

Request

Request 是顶级容器，可含有任何 block 结构或原语 primitive。 有一些类的成员变量官方未给出明确说明，在此记录一下笔者的猜测：

  • label：Request 的名称。

  • stack：当前 request 对象的栈，栈中包含该 request 对象含有的块或原语。

  • block_stack：open blocks 列表？

  • names：一个包含多个 Fuzzable 对象的字典，以对象的 qualified_name 为键。

  • mutant：当前 reuqest 对象正被模糊测试的子节点，可能是 String、Delim 等原语。

boofuzz.Request(name=None, children=None)[source]
Parameters:

  • name (str, optional) – 当前 request 的名称

  • children (boofuzz.Fuzzable, optional) – 当前 request 的子节点，默认为空

Blocks

Block

boofuzz.Block(name=None, default_value=None, request=None, children=None, group=None, encoder=None, dep=None, dep_value=None, dep_values=None, dep_compare='==', *args, **kwargs)[source]

基本的构造块（building block），可包含 primitives（原语）、sizers、checksums 以及其它 blocks。

Parameters:

  • name (str, optional) – 当前 blocks 的名称，默认为空

  • default_value (Any, optional) – 当元素不进行模糊测试时的默认值，通常应对应于一个有效的协议字段值，默认为空

  • request (boofuzz.Request, optional) – 当前的 block 所属的 Request 对象，默认为空

  • children (boofuzz.Fuzzable, optional) – 当前 blocks 的子节点，默认为空

  • group (str, optional) – 与当前的 block 相关联的 group 的名称，默认为空

  • encoder (callable, optional) – Optional pointer to a function to pass rendered data to prior to return, defaults to None

  • dep (str, optional) – Optional primitive whose specific value this block is dependant on, defaults to None

  • dep_value (Any, optional) – Value that field “dep” must contain for block to be rendered, defaults to None

  • dep_values (list, optional) – Values that field “dep” may contain for block to be rendered, defaults to None

  • dep_compare (str, optional) – Comparison method to apply to dependency (==, !=, >, >=, <, <=), defaults to None

Checksum

boofuzz.Checksum(name=None, block_name=None, request=None, algorithm='crc32', length=0, endian='<', ipv4_src_block_name=None, ipv4_dst_block_name=None, *args, **kwargs)[source]

Checksum bound to the block with the specified name.

The algorithm may be chosen by name with the algorithm parameter, or a custom function may be specified with the algorithm parameter.

The length field is only necessary for custom algorithms. When using your own custom checksum function, the return value should be the calculated checksum of the data.

Function signature: <function_name>(data_bytes). Returns a number represented as a bytes type.

Recursive checksums are supported; the checksum field itself will render as all zeros for the sake of checksum or length calculations.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • block_name (str) – Name of target block for checksum calculations.

  • request (boofuzz.Request, optional) – Request this block belongs to

  • algorithm (str, function def name, optional) – Checksum algorithm to use from this list, default is crc32 (crc32, crc32c, adler32, md5, sha1, ipv4, udp). See above for custom checksum function example.

  • length (int, optional) – Length of checksum, auto-calculated by default. Must be specified manually when using custom algorithm, defaults to 0

  • endian (chr, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • ipv4_src_block_name (str, optional) – Required for ‘udp’ algorithm. Name of block yielding IPv4 source address, defaults to None

  • ipv4_dst_block_name (str, optional) – Required for ‘udp’ algorithm. Name of block yielding IPv4 destination address, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this block, defaults to true

Repeat

boofuzz.Repeat(name=None, block_name=None, request=None, min_reps=0, max_reps=25, step=1, variable=None, default_value=None, *args, **kwargs)[source]

Repeat the rendered contents of the specified block cycling from min_reps to max_reps counting by step.

By default renders to nothing. This block modifier is useful for fuzzing overflows in table entries. This block modifier MUST come after the block it is being applied to.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • block_name (str, optional) – Name of block to repeat

  • request (boofuzz.Request, optional) – Request this block belongs to, defaults to None

  • min_reps (int, optional) – Minimum number of block repetitions, defaults to 0

  • max_reps (int, optional) – Maximum number of block repetitions, defaults to None

  • step (int, optional) – Step count between min and max reps, defaults to 1

  • variable (Boofuzz Integer Primitive, optional) – Repetitions will be derived from this variable, disables fuzzing, defaults to None

  • default_value (Raw) – Value used when the element is not being fuzzed - should typically represent a valid value, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this block, defaults to true

Size

boofuzz.Size(name=None, block_name=None, request=None, offset=0, length=4, endian='<', output_format='binary', inclusive=False, signed=False, math=None, *args, **kwargs)[source]

Size 用于计算某个 Block 的大小。

示例如下：

    Block("S7COMM", children=(
    Bytes("Protocol ID", default_value=h2b(s7comm.protocol_id), size=1, fuzzable=False),
    Bytes("ROSCTR", default_value=h2b(s7comm.rosctr), size=1, fuzzable=False),
    Bytes("Reserved", default_value=h2b(s7comm.reserved), size=2, fuzzable=False),
    Bytes("PDU Reference", default_value=h2b(s7comm.pdu_reference), size=2, fuzzable=False),
    Bytes("Parameter Length", default_value=h2b(s7comm.parameter_length), size=2, fuzzable=False),
    Bytes("Data Length", default_value=h2b(s7comm.data_length), size=2, fuzzable=False),
    Bytes("Parameter", default_value=h2b(s7comm.parameter), fuzzable=False),
    Bytes("Data", default_value=h2b(s7comm.data), fuzzable=False)
)),
Size(name="test",block_name="S7COMM", fuzzable=False, length=2,output_format="ascii") # 实际使用时注意输出格式

如上代码用一个名为 test 的 Size 计算一个名为 S7COMM 的 Block 的大小，并在模糊测试时将计算结果附加在该 block 之后。

使用时需要注意输出的格式是 ascii 格式还是 binary 格式，同时也要注意端序以及该 Size 本身是否也要算入长度中去。

Create a sizer block bound to the block with the specified name.

Size blocks that size their own parent or grandparent are allowed.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • block_name (str, optional) – Name of block to apply sizer to.

  • request (boofuzz.Request, optional) – Request this block belongs to.

  • offset (int, optional) – Offset for calculated size value, defaults to 0

  • length (int, optional) – Length of sizer, defaults to 4

  • endian (chr, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • output_format (str, optional) – Output format, “binary” or “ascii”, defaults to binary

  • inclusive (bool, optional) – Should the sizer count its own length? Defaults to False

  • signed (bool, optional) – Make size signed vs. unsigned (applicable only with format=”ascii”), defaults to False

  • math (def, optional) – Apply the mathematical op defined in this function to the size, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this block, defaults to true

Aligned

boofuzz.Aligned(name=None, modulus=1, request=None, pattern=b'\x00', *args, **kwargs)[source]

FuzzableBlock that aligns its contents to a certain number of bytes

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • modulus (int, optional) – Pad length of child content to this many bytes, defaults to 1

  • request (boofuzz.Request, optional) – Request this block belongs to

  • pattern (bytes, optional) – Pad using these byte(s)

  • fuzzable (bool, optional) – Enable/disable fuzzing of this block, defaults to true

Primitives

Static

Static 原语是固定的，在模糊测试时并不会发生变异。

boofuzz.Static(name=None, default_value=None, *args, **kwargs)[source]
Parameters:

  • name (str, optional) – Static 原语的名称，默认为 None

  • default_value (Raw, optional) – 原始的静态数据

示例

Static(name="end", default_value="\r\n")

Simple

boofuzz.Simple(name=None, default_value=None, fuzz_values=None, *args, **kwargs)[source]

Simple 原语根据一个由单字节值组成的列表来进行模糊测试。

Parameters:

  • name (str, optional) – Simple 原语的名称，默认为 None

  • default_value (Raw, optional) – 原始静态数据

  • fuzz_values (list, optional) – 由 fuzz 值组成的列表，默认为 None。如果为 None，那么 Simple 原语就等价于 Static 原语了。

  • fuzzable (bool, optional) – 启用/禁用对 Simple 原语的模糊测试，默认为 True

Delim

boofuzz.Delim(name=None, default_value=' ', *args, **kwargs)[source]

表示一个分隔符，比如空格,r,n, ,=,>,< 等等。注意变异包括重复、替换、缺少。

Parameters:

  • name (str, optional) – 名称, 用于后续引用。默认为 None。

  • default_value (char, optional) – 当元素不进行模糊测试时所用的值，通常情况下应是一个合法的协议字段值。

  • fuzzable (bool, optional) – 启用/禁用对该原语的模糊测试，默认为 true。

示例

Delim(name="Space",default_value=" ")

Group

boofuzz.Group(name=None, values=None, default_value=None, encoding='ascii', *args, **kwargs)[source]

Group 原语表示一列静态值，在模糊测试时会逐个遍历这些值并变异它们。

你可以将 Group 原语绑定到某个 block 中以此指明该 block 要对 group 中的每个值进行所有可能的变异。

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • values (list of bytes or list of str) – 该 group 可以取的所有可能的原始值。List of possible raw values this group can take.

  • default_value (str, optional) – Value used when the element is not being fuzzed - should typically represent a valid value, defaults to None

  • encoding (str, optional) – String encoding, ex: utf_16_le for Microsoft Unicode, defaults to ascii

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

RandomData

boofuzz.RandomData(name=None, default_value='', min_length=0, max_length=1, max_mutations=25, step=None, *args, **kwargs)[source]

Generate a random chunk of data while maintaining a copy of the original.

A random length range can be specified. For a static length, set min/max length to be the same.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (str or bytes, optional) – Value used when the element is not being fuzzed - should typically represent a valid value, defaults to None

  • min_length (int, optional) – Minimum length of random block, defaults to 0

  • max_length (int, optional) – Maximum length of random block, defaults to 1

  • max_mutations (int, optional) – Number of mutations to make before reverting to default, defaults to 25

  • step (int, optional) – If not None, step count between min and max reps, otherwise random, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

String

继承自 Fuzzable，注意到 FuzzableBlock 也继承自 Fuzzable。所以 String 不是 FuzzableBlocks 的实例。

boofuzz.String(name=None, default_value='', size=None, padding=b'\x00', encoding='utf-8', max_len=None, *args, **kwargs)[source]

String 原语通过变异事先定义好的字符串库从而进行模糊测试。

类变量 ‘fuzz_library’ 是一个包含着 fuzz 值的列表，所有实例都可共享该变量.

Parameters:

  • name (str, 可选) – 名称，用于后续引用。若未提供名称，那么默认为 None。

  • default_value (str，可选) – 当元素不进行模糊测试时所用的值，通常情况下应是一个有效值。

  • size (int, 可选) – 该字段的静态长度，若为 None 则表示该字段是动态的。默认为 None。

  • padding (chr, 可选) – 用于填充静态字段长度的值，默认为 “x00”。

  • encoding (str, 可选) – 字符串编码类型，比如微软的 Unicode utf_16_le。

  • max_len – 变异字符串的最大长度，默认为 None。

  • fuzzable (bool, 可选) – 启用/禁用对该原语的模糊测试，默认为 true。

FromFile

boofuzz.FromFile(name=None, default_value=b'', filename=None, max_len=0, *args, **kwargs)[source]

Cycles through a list of “bad” values from a file(s).

Takes filename and open the file(s) to read the values to use in fuzzing process. filename may contain glob characters.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (bytes) – Default bytes value

  • filename (str) – Filename pattern to load all fuzz value

  • max_len (int, optional) – Maximum string length, defaults to 0

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

Mirror

boofuzz.Mirror(name=None, primitive_name=None, request=None, *args, **kwargs)[source]

Primitive used to keep updated with another primitive.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • primitive_name (str) – Name of target primitive.

  • request (boofuzz.Request) – Request this primitive belongs to.

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

BitField

boofuzz.BitField(name=None, default_value=0, width=8, max_num=None, endian='<', output_format='binary', signed=False, full_range=False, *args, **kwargs)[source]

The bit field primitive represents a number of variable length and is used to define all other integer types.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (int, optional) – Default integer value, defaults to 0

  • width (int, optional) – Width in bits, defaults to 8

  • max_num (int, optional) – Maximum number to iterate up to, defaults to None

  • endian (char, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • output_format (str, optional) – Output format, “binary” or “ascii”, defaults to binary

  • signed (bool, optional) – Make size signed vs. unsigned (applicable only with format=”ascii”), defaults to False

  • full_range (bool, optional) – If enabled the field mutates through all possible values, defaults to False

  • fuzz_values (list, optional) – List of custom fuzz values to add to the normal mutations, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

Byte

boofuzz.Byte(*args, **kwargs)[source]

The byte sized bit field primitive.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (int, optional) – Default integer value, defaults to 0

  • max_num (int, optional) – 要迭代的最大整数值，默认为 None。例如 max_num=2 则表示该字段的值在0、1之间迭代变异。

  • endian (char, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • output_format (str, optional) – Output format, “binary” or “ascii”, defaults to binary

  • signed (bool, optional) – Make size signed vs. unsigned (applicable only with format=”ascii”), defaults to False

  • full_range (bool, optional) – If enabled the field mutates through all possible values, defaults to False

  • fuzz_values (list, optional) – List of custom fuzz values to add to the normal mutations, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

Bytes

boofuzz.Bytes(name: str = None, default_value: bytes = b'', size: int = None, padding: bytes = b'\x00', max_len: int = None, *args, **kwargs)[source]

Bytes 原语对一个任意长的二进制字节串进行模糊测试。

Parameters:

  • name (str, optional) – 当前 Bytes 对象的名称， 默认为空

  • default_value (bytes, optional) – 当不对当前 Bytes 对象进行模糊测试时所用的默认值，默认为 b””

  • size (int, optional) – 当前 Bytes 对象的固定长度，如果为 None则表示动态长度。size 默认为 None

  • padding (chr, optional) – 为达到固定长度而填充的值，默认为 b”x00”

  • max_len (int, optional) – 最大字符串长度，默认为 None

  • fuzzable (bool, optional) – 是否要对当前 Bytes 对象进行模糊测试，默认为 True

Word

boofuzz.Word(*args, **kwargs)[source]

The 2 byte sized bit field primitive.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (int, optional) – Default integer value, defaults to 0

  • max_num (int, optional) – Maximum number to iterate up to, defaults to None

  • endian (char, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • output_format (str, optional) – Output format, “binary” or “ascii”, defaults to binary

  • signed (bool, optional) – Make size signed vs. unsigned (applicable only with format=”ascii”), defaults to False

  • full_range (bool, optional) – If enabled the field mutates through all possible values, defaults to False

  • fuzz_values (list, optional) – List of custom fuzz values to add to the normal mutations, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

DWord

boofuzz.DWord(*args, **kwargs)[source]

The 4 byte sized bit field primitive.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (int, optional) – Default integer value, defaults to 0

  • max_num (int, optional) – Maximum number to iterate up to, defaults to None

  • endian (char, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • output_format (str, optional) – Output format, “binary” or “ascii”, defaults to binary

  • signed (bool, optional) – Make size signed vs. unsigned (applicable only with format=”ascii”), defaults to False

  • full_range (bool, optional) – If enabled the field mutates through all possible values, defaults to False

  • fuzz_values (list, optional) – List of custom fuzz values to add to the normal mutations, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

QWord

boofuzz.QWord(*args, **kwargs)[source]

The 8 byte sized bit field primitive.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (int, optional) – Default integer value, defaults to 0

  • max_num (int, optional) – Maximum number to iterate up to, defaults to None

  • endian (char, optional) – Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >), defaults to LITTLE_ENDIAN

  • output_format (str, optional) – Output format, “binary” or “ascii”, defaults to binary

  • signed (bool, optional) – Make size signed vs. unsigned (applicable only with format=”ascii”), defaults to False

  • full_range (bool, optional) – If enabled the field mutates through all possible values, defaults to False

  • fuzz_values (list, optional) – List of custom fuzz values to add to the normal mutations, defaults to None

  • fuzzable (bool, optional) – Enable/disable fuzzing of this primitive, defaults to true

Making Your Own Block/Primitive

Now I know what you’re thinking: “With that many sweet primitives and blocks available, what else could I ever conceivably need? And yet, I am urged by joy to contribute my own sweet blocks!”

To make your own block/primitive:

  1. Create an object that inherits from Fuzzable or FuzzableBlock

  2. Override mutations and/or encode.

  3. Optional: Create an accompanying static primitive function. See boofuzz’s __init__.py file for examples.

  4. ???

  5. Profit!

If your block depends on references to other blocks, the way a checksum or length field depends on other parts of the message, see the Size source code for an example of how to avoid recursion issues, and Be Careful. :)

class boofuzz.Fuzzable(name=None, default_value=None, fuzzable=True, fuzz_values=None)[source]

Bases: object

Parent class for all primitives and blocks.

When making new fuzzable types, one will typically override mutations() and/or encode().

mutations() is a generator function yielding mutations, typically of type bytes.

encode() is a function that takes a value and encodes it. The value comes from mutations() or default_value. FuzzableBlock types can also encode the data generated by child nodes.

Implementors may also want to override num_mutations() – the default implementation manually exhausts mutations() to get a number.

The rest of the methods are used by boofuzz to handle fuzzing and are typically not overridden.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • default_value (Any, optional) – Value used when the element is not being fuzzed - should typically represent a valid value. Can be a static value, or a ReferenceValueTestCaseSession, defaults to None

  • fuzzable (bool, optional) – Enable fuzzing of this primitive, defaults to True

  • fuzz_values (list, optional) – List of custom fuzz values to add to the normal mutations, defaults to None

property context_path

该方法返回一个以点分割的字符串，描述了到达当前 Fuzzable 对象的上下文路径。

例如，若有一个名为 user 的 Request 对象，并且该对象包含了一个名为 key 的 String 原语，那么对于这个 String 原语来说，其 context_path 就为 user。

Dot-delimited string that describes the path up to this element. Configured after the object is attached to a Request.

encode(value, mutation_context)[source]

Takes a value and encodes/renders/serializes it to a bytes (byte string).

Optional if mutations() yields bytes.

Example: Yield strings with mutations() and encode them to UTF-8 using encode().

Default behavior: Return value.

Parameters:

  • value – Value to encode. Type should match the type yielded by mutations()

  • mutation_context (MutationContext) – Context for current mutation, if any.

Returns:

Encoded/serialized value.

Return type:

bytes

property fuzzable

If False, this element should not be mutated in normal fuzzing.

get_mutations()[source]

迭代产生变异，由 boofuzz 框架所使用。

Iterate mutations. Used by boofuzz framework.

Yields:

list of Mutation – Mutation 构成的列表（Mutations）

get_num_mutations()[source]
get_value(mutation_context=None)[source]

Helper method to get the currently applicable value.

This is either the default value, or the active mutation value as dictated by mutation_context.

Parameters:

mutation_context (MutationContext) –

Returns:

mutations(default_value)[source]

Generator to yield mutation values for this element.

Values are either plain values or callable functions that take a “default value” and mutate it. Functions are used when the default or “normal” value influences the fuzzed value. Functions are used because the “normal” value is sometimes dynamic and not known at the time of generation.

Each mutation should be a pre-rendered value. That is, it must be suitable to pass to encode().

Default: Empty iterator.

Parameters:

default_value –

property name

Element name, should be unique for each instance.

Return type:

str

name_counter = 0
num_mutations(default_value)[source]

Return the total number of mutations for this element (not counting “fuzz_values”).

Default implementation exhausts the mutations() generator, which is inefficient. Override if you can provide a value more efficiently, or if exhausting the mutations() generator has side effects.

Parameters:

default_value – Use if number of mutations depends on the default value. Provided by FuzzableWrapper. Note: It is generally good behavior to have a consistent number of mutations for a given default value length.

Returns:

Number of mutated forms this primitive can take

Return type:

int

original_value(test_case_context=None)[source]

原始的、未被变异的元素值。

Original, non-mutated value of element.

Parameters:

test_case_context (ProtocolSession) – Used to resolve ReferenceValueTestCaseSession type default values.

Returns: 一般都会返回原语定义时的默认值。

property qualified_name

该方法与 context_path 基本类似，不过在末尾增加上了当前 Fuzzable 对象的 name。

例如，若有一个名为 user 的 Request 对象，并且该对象包含了一个名为 key 的 String 原语，那么对于这个 String 原语来说，其 qualified_name 就为 user.key。

Dot-delimited name that describes the request name and the path to the element within the request.

Example: “request1.block1.block2.node1”

render(mutation_context=None)[source]

Render after applying mutation, if applicable. :type mutation_context: MutationContext

property request

Reference to the Request to which this object is attached.

stop_mutations()[source]

Stop yielding mutations on the currently running mutations() call.

Used by boofuzz to stop fuzzing an element when it’s already caused several failures.

Returns:

None

Return type:

NoneType

class boofuzz.FuzzableBlock(name=None, request=None, children=None, *args, **kwargs)[source]

Bases: Fuzzable

Fuzzable type designed to have children elements.

FuzzableBlock overrides the following methods, changing the default behavior for any type based on FuzzableBlock:

  1. mutations() Iterate through the mutations yielded by all child nodes.

  2. num_mutations() Sum the mutations represented by each child node.

  3. encode() Call get_child_data().

FuzzableBlock adds the following methods:

  1. get_child_data() Render and concatenate all child nodes.

  2. push() Add an additional child node; generally used only internally.

Parameters:

  • name (str, optional) – Name, for referencing later. Names should always be provided, but if not, a default name will be given, defaults to None

  • request (boofuzz.Request, optional) – Request this block belongs to, defaults to None

  • children (boofuzz.Fuzzable, optional) – List of child nodes (typically given to FuzzableBlock types)m defaults to None

encode(value, mutation_context)[source]

Takes a value and encodes/renders/serializes it to a bytes (byte string).

Optional if mutations() yields bytes.

Example: Yield strings with mutations() and encode them to UTF-8 using encode().

Default behavior: Return value.

Parameters:

  • value – Value to encode. Type should match the type yielded by mutations()

  • mutation_context (MutationContext) – Context for current mutation, if any.

Returns:

Encoded/serialized value.

Return type:

bytes

get_child_data(mutation_context)[source]

Get child or referenced data for this node.

For blocks that reference other data from the message structure (e.g. size, checksum, blocks). See FuzzableBlock for an example.

Parameters:

mutation_context (MutationContext) – Mutation context.

Returns:

Child data.

Return type:

bytes

mutations(default_value, skip_elements=None)[source]

Generator to yield mutation values for this element.

Values are either plain values or callable functions that take a “default value” and mutate it. Functions are used when the default or “normal” value influences the fuzzed value. Functions are used because the “normal” value is sometimes dynamic and not known at the time of generation.

Each mutation should be a pre-rendered value. That is, it must be suitable to pass to encode().

Default: Empty iterator.

Parameters:

default_value –

num_mutations(default_value=None)[source]

Return the total number of mutations for this element (not counting “fuzz_values”).

Default implementation exhausts the mutations() generator, which is inefficient. Override if you can provide a value more efficiently, or if exhausting the mutations() generator has side effects.

Parameters:

default_value – Use if number of mutations depends on the default value. Provided by FuzzableWrapper. Note: It is generally good behavior to have a consistent number of mutations for a given default value length.

Returns:

Number of mutated forms this primitive can take

Return type:

int

push(item)[source]

Push a child element onto this block’s stack.

Parameters:

item (Fuzzable) – Some wrapped Fuzzable element

Returns: None