Static Protocol Definition

Protocol definition via static functions in boofuzz is inherited from Spike. See protocol definition functions for a newer, if still experimental, format.

See the Quickstart guide for an intro to using boofuzz in general.

Requests are messages, Blocks are chunks within a message, and Primitives are the elements (bytes, strings, numbers, checksums, etc.) that make up a Block/Request.

Request Manipulation

boofuzz.s_initialize(name)[source]

Initialize a new block request. All blocks / primitives generated after this call apply to the named request. Use s_switch() to jump between factories.

Parameters

name (str) – Name of request

boofuzz.s_get(name=None)[source]

Return the request with the specified name or the current request if name is not specified. Use this to switch from global function style request manipulation to direct object manipulation. Example:

req = s_get("HTTP BASIC")
print(req.num_mutations())

The selected request is also set as the default current. (ie: s_switch(name) is implied).

Parameters

name (str) – (Optional, def=None) Name of request to return or current request if name is None.

Return type

blocks.Request

Returns

The requested request.

boofuzz.s_num_mutations()[source]

Determine the number of repetitions we will be making.

Return type

int

Returns

Number of mutated forms this primitive can take.

boofuzz.s_switch(name)[source]

Change the current request to the one specified by “name”.

Parameters

name (str) – Name of request

Block Manipulation

boofuzz.s_block(name, group=None, encoder=None, dep=None, dep_value=None, dep_values=(), dep_compare='==')[source]

Open a new block under the current request. The returned instance supports the “with” interface so it will be automatically closed for you:

with s_block("header"):
    s_static("\x00\x01")
    if s_block_start("body"):
        ...
Parameters
  • name (str) – Name of block being opened

  • group (str) – (Optional, def=None) Name of group to associate this block with

  • encoder (Function Pointer) – (Optional, def=None) Optional pointer to a function to pass rendered data to prior to return

  • dep (str) – (Optional, def=None) Optional primitive whose specific value this block is dependant on

  • dep_value (Mixed) – (Optional, def=None) Value that field “dep” must contain for block to be rendered

  • dep_values (List of Mixed Types) – (Optional, def=[]) Values that field “dep” may contain for block to be rendered

  • dep_compare (str) – (Optional, def=”==”) Comparison method to use on dependency (==, !=, >, >=, <, <=)

boofuzz.s_block_start(name, *args, **kwargs)[source]

Open a new block under the current request. This routine always returns an instance so you can make your fuzzer pretty with indenting:

if s_block_start("header"):
    s_static("\x00\x01")
    if s_block_start("body"):
        ...
s_block_close()

:note Prefer using s_block to this function directly :see s_block

boofuzz.s_block_end(name=None)[source]

Close the last opened block. Optionally specify the name of the block being closed (purely for aesthetic purposes).

Parameters

name (str) – (Optional, def=None) Name of block to closed.

boofuzz.s_checksum(block_name, algorithm='crc32', length=0, endian='<', fuzzable=True, name=None, ipv4_src_block_name=None, ipv4_dst_block_name=None)[source]

Create a checksum block bound to the block with the specified name. You can not create a checksum for any currently open blocks.

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

  • algorithm (str, function) – (Optional, def=crc32) Checksum algorithm to use. (crc32, crc32c, adler32, md5, sha1, ipv4, udp) Pass a function to use a custom algorithm. This function has to take and return byte-type data.

  • length (int) – (Optional, def=0) Length of checksum, auto-calculated by default. Must be specified manually when using a custom algorithm.

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianness of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing.

  • name (str) – Name of this checksum field

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

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

boofuzz.s_repeat(block_name, min_reps=0, max_reps=None, step=1, variable=None, fuzzable=True, name=None)[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.

See

Aliases: s_repeater()

Parameters
  • block_name (str) – Name of block to repeat

  • min_reps (int) – (Optional, def=0) Minimum number of block repetitions

  • max_reps (int) – (Optional, def=None) Maximum number of block repetitions

  • step (int) – (Optional, def=1) Step count between min and max reps

  • variable (Sulley Integer Primitive) – (Optional, def=None) An integer primitive which will specify the number of repitions

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_size(block_name, offset=0, length=4, endian='<', output_format='binary', inclusive=False, signed=False, math=None, fuzzable=True, name=None)[source]

Create a sizer block bound to the block with the specified name. You can not create a sizer for any currently open blocks.

See

Aliases: s_sizer()

Parameters
  • block_name (str) – Name of block to apply sizer to

  • offset (int) – (Optional, def=0) Offset to calculated size of block

  • length (int) – (Optional, def=4) Length of sizer

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianess of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • output_format (str) – (Optional, def=binary) Output format, “binary” or “ascii”

  • inclusive (bool) – (Optional, def=False) Should the sizer count its own length?

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

  • math (Function) – (Optional, def=None) Apply the mathematical operations defined in this function to the size

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this sizer

  • name (str) – Name of this sizer field

boofuzz.s_update(name, value)[source]

Update the value of the named primitive in the currently open request.

Parameters
  • name (str) – Name of object whose value we wish to update

  • value (Mixed) – Updated value

Primitive Definition

boofuzz.s_binary(value, name=None)[source]

Parse a variable format binary string into a static value and push it onto the current block stack.

Parameters
  • value (str) – Variable format binary string

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_delim(value, fuzzable=True, name=None)[source]

Push a delimiter onto the current block stack.

Parameters
  • value (Character) – Original value

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_group(name, values, default_value=None)[source]

This primitive represents a list of static values, stepping through each one on mutation. You can tie a block to a group primitive to specify that the block should cycle through all possible mutations for each value within the group. The group primitive is useful for example for representing a list of valid opcodes.

Parameters
  • name (str) – Name of group

  • values (List or raw data) – List of possible raw values this group can take.

  • default_value – (Optional, def=None) Specifying a value when fuzzing() is complete

boofuzz.s_lego(lego_type, value=None, options=())[source]

Legos are pre-built blocks… TODO: finish this doc

Parameters
  • lego_type (str) – Function that represents a lego

  • value – Original value

  • options – Options to pass to lego.

boofuzz.s_random(value, min_length, max_length, num_mutations=25, fuzzable=True, step=None, name=None)[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
  • value (Raw) – Original value

  • min_length (int) – Minimum length of random block

  • max_length (int) – Maximum length of random block

  • num_mutations (int) – (Optional, def=25) Number of mutations to make before reverting to default

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • step (int) – (Optional, def=None) If not null, step count between min and max reps, otherwise random

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_static(value, name=None)[source]

Push a static value onto the current block stack.

See

Aliases: s_dunno(), s_raw(), s_unknown()

Parameters
  • value (Raw) – Raw static data

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_string(value, size=- 1, padding=b'\x00', encoding='ascii', fuzzable=True, max_len=0, name=None)[source]

Push a string onto the current block stack.

Parameters
  • value (str) – Default string value

  • size (int) – (Optional, def=-1) Static size of this field, leave -1 for dynamic.

  • padding (Character) – (Optional, def=”x00”) Value to use as padding to fill static field size.

  • encoding (str) – (Optonal, def=”ascii”) String encoding, ex: utf_16_le for Microsoft Unicode.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • max_len (int) – (Optional, def=0) Maximum string length

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_from_file(value, encoding='ascii', fuzzable=True, max_len=0, name=None, filename=None)[source]

Push a value from file onto the current block stack.

Parameters
  • value (str) – Default string value

  • encoding (str) – (DEPRECIATED, def=”ascii”) String encoding, ex: utf_16_le for Microsoft Unicode.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • max_len (int) – (Optional, def=0) Maximum string length

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

  • filename (str) – (Mandatory) Specify filename where to read fuzz list

boofuzz.s_bit_field(value, width, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=None, fuzz_values=None)[source]

Push a variable length bit field onto the current block stack.

See

Aliases: s_bit(), s_bits()

Parameters
  • value (int) – Default integer value

  • width (int) – Width of bit fields

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianess of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • output_format (str) – (Optional, def=binary) Output format, “binary” or “ascii”

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

  • full_range (bool) – (Optional, def=False) If enabled the field mutates through all possible values.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

  • fuzz_values (list) – List of custom fuzz values to add to the normal mutations.

boofuzz.s_byte(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=None, fuzz_values=None)[source]

Push a byte onto the current block stack.

See

Aliases: s_char()

Parameters
  • value (int|str) – Default integer value

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianess of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • output_format (str) – (Optional, def=binary) Output format, “binary” or “ascii”

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

  • full_range (bool) – (Optional, def=False) If enabled the field mutates through all possible values.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

  • fuzz_values (list) – List of custom fuzz values to add to the normal mutations.

boofuzz.s_bytes(value, size=None, padding=b'\x00', fuzzable=True, max_len=None, name=None)[source]

Push a bytes field of arbitrary length onto the current block stack.

Parameters
  • value (bytes) – Default binary value

  • size (int) – (Optional, def=None) Static size of this field, leave None for dynamic.

  • padding (chr) – (Optional, def=b”x00”) Value to use as padding to fill static field size.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • max_len (int) – (Optional, def=None) Maximum string length

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

boofuzz.s_word(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=None, fuzz_values=None)[source]

Push a word onto the current block stack.

See

Aliases: s_short()

Parameters
  • value (int) – Default integer value

  • endian (chr) – (Optional, def=LITTLE_ENDIAN) Endianess of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • output_format (str) – (Optional, def=binary) Output format, “binary” or “ascii”

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

  • full_range (bool) – (Optional, def=False) If enabled the field mutates through all possible values.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

  • fuzz_values (list) – List of custom fuzz values to add to the normal mutations.

boofuzz.s_dword(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=None, fuzz_values=None)[source]

Push a double word onto the current block stack.

See

Aliases: s_long(), s_int()

Parameters
  • value (int) – Default integer value

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianess of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • output_format (str) – (Optional, def=binary) Output format, “binary” or “ascii”

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

  • full_range (bool) – (Optional, def=False) If enabled the field mutates through all possible values.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

  • fuzz_values (list) – List of custom fuzz values to add to the normal mutations.

boofuzz.s_qword(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=None, fuzz_values=None)[source]

Push a quad word onto the current block stack.

See

Aliases: s_double()

Parameters
  • value (int) – Default integer value

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianess of the bit field (LITTLE_ENDIAN: <, BIG_ENDIAN: >)

  • output_format (str) – (Optional, def=binary) Output format, “binary” or “ascii”

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

  • full_range (bool) – (Optional, def=False) If enabled the field mutates through all possible values.

  • fuzzable (bool) – (Optional, def=True) Enable/disable fuzzing of this primitive

  • name (str) – (Optional, def=None) Specifying a name gives you direct access to a primitive

  • fuzz_values (list) – List of custom fuzz values to add to the normal mutations.