Static Protocol Definition

Static functions are used in boofuzz to assemble messages for a protocol definition. They may be obsoleted in future releases by a less static approach to message construction. For now, you can see the Quickstart guide for an intro.

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_mutate()[source]

Mutate the current request and return False if mutations are exhausted, in which case the request has been reverted back to its normal form.

Return type:bool
Returns:True on mutation success, False if mutations exhausted.
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_render()[source]

Render out and return the entire contents of the current request.

Return type:Raw
Returns:Rendered contents
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 to apply sizer to
  • algorithm (str) – (Optional, def=crc32) Checksum algorithm to use. (crc32, adler32, md5, sha1, ipv4, udp)
  • length (int) – (Optional, def=0) NOT IMPLEMENTED. Length of checksum, specify 0 to auto-calculate
  • 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 apply sizer to
  • 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='\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) – (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
  • 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)[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
boofuzz.s_byte(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=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
boofuzz.s_word(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=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
boofuzz.s_dword(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=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
boofuzz.s_qword(value, endian='<', output_format='binary', signed=False, full_range=False, fuzzable=True, name=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

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 implements IFuzzable.
  2. Create an accompanying static primitive function. See boofuzz’s __init__.py file for examples.
  3. ???
  4. 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. Or otherwise be careful. :)