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=None, group=None, encoder=None, dep=None, dep_value=None, dep_values=None, 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, optional) – Name of block being opened

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

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

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

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

  • dep_values (List of bytes, optional) – (Optional, def=None) Values that field “dep” may contain for block to be rendered

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

boofuzz.s_block_start(name=None, *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=None, algorithm='crc32', length=0, endian='<', fuzzable=True, name=None, ipv4_src_block_name=None, ipv4_dst_block_name=None)[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.

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

Parameters:

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

  • algorithm (str, function, optional) – 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, defaults to crc32

  • 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

  • fuzzable (bool, optional) – Enable/disable fuzzing.

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

  • 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

boofuzz.s_repeat(block_name=None, min_reps=0, max_reps=25, 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) – (Optional, def=None) Name of block to repeat

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

  • max_reps (int) – (Optional, def=25) 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=None, 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, optional) – Name of block to apply sizer 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, 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) – (Optional, def=” “)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=None, values=None, 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) – (Optional, def=None) Name of group

  • values (List or raw data) – (Optional, def=None) List of possible raw values this group can take.

  • default_value (str or bytes) – (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=0, max_length=1, 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 (str or bytes) – (Optional, def=””) Original value

  • min_length (int) – (Optional, def=0) Minimum length of random block

  • max_length (int) – (Optional, def=1) 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=None, 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=None, padding=b'\x00', encoding='ascii', fuzzable=True, max_len=None, name=None)[source]

Push a string onto the current block stack.

Parameters:

  • value (str) – (Optional, def=””)Default string value

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

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

  • encoding (str) – (Optional, 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=None) Maximum string length

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

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

Push a value from file onto the current block stack.

Parameters:

  • value (bytes) – (Optional, def=b””) Default bytes value

  • filename (str) – (Optional, def=None) Filename pattern to load all fuzz 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

boofuzz.s_bit_field(value=0, width=8, 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) – (Optional, def=0) Default integer value

  • width (int) – (Optional, def=8) Width of bit fields

  • endian (Character) – (Optional, def=LITTLE_ENDIAN) Endianness 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=0, 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|byte) – (Optional, def=0) 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=b'', 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) – (Optional, def=b””)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=0, 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 ((Optional, def=0) 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=0, 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 ((Optional, def=0) 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=0, 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 ((Optional, def=0) 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.