Converting Pits from Peach V2.3 to Peach V 3.X

04/14/2015

Fuzzing definitions (Pits) from Peach version 2.3 do not run “as-is” in the current
version. The changes needed to enable these pits to run in the current version include
a few global issues; advancements in methodology that translate to changes in the
description language; and product improvements, bug fixes, and enhancements.

Changing a Pit to run in Peach version 3.x means that you can run the pit through
the command-line interface.

The remainder of this section addresses the global changes and changes to individual
commands.

GLOBAL CHANGES

The global changes consist of the following items that you need to change for all version 2.3 pits:

The `` element `xmlsns` and `xsi:schemaLocation` attribute values have changed. The simplest fix is to replace the v2.3 `` element with the following:

The `` element for `defaults.xml` is no longer used. Remove the include statement from the pit. An example of the statement to remove follows:

The relationship “from” is no longer used. Remove all “from” relations. An example statement follows:


Peach v2.3 provided “from” relations to boost performance by specifying both sides of a relationship using “of” and “from” parameters, as in the following example.





Peach v3.x does not use the “from” parameter. The following example, written for peach v3.x, provides identical functionality to the previous example.



The `` element is now part of the `` element. Move the Logger element block into the Test element block. For more information, see the next item.
The functionality of the `` element is now part of the `` element. Upon moving the Logger element block into the Test element block, remove the Run element block from the pit. An example follows.












In Peach v3.x, the Test element block identifies the Agent, StateModel (and, by implication, the DataModel), Publisher, and Logger for a fuzzing session. A v3.x Test element block follows. The block is functionally identical the previous example.










NOTE: In the example, the name for the Test element is “Default”. This is the default name for the Test element. At runtime, Peach v3.x automatically looks for and runs the default Test, unless you specify a Test name on the command line.

The parameter names for Monitors and Publishers now use CamelCasing. In the previous example, the param names `“Host”` and `“Port”` for the publisher have changed slightly due to CamelCasing. You can use the Peach DOM reference or the developer’s guide to check parameters that fail validation. Use the following command to genereate the DOM reference.

peach –showenv

TIP
====================================
You can place the data and state model definitions in separate xml files to improve re-use of these definitions. Once defined, you can the pull these definitions into different pits to perform different tests on the same data and state models. Specify the file containing the models using the include xml element.

The following example shows file fragments of a pit and definition files that contain the state and data models. Two include elements are used: 1) the main pit file includes the state model, and 2) the state model file includes the data model.

====================================






CHANGES TO INDIVIDUAL XML ELEMENTS

The following Peach v2.3 xml elements require changes when used with Peach v3.x.

Defaults: The Defaults element contains default values for parameter definitions. If an
individual element does not specify an optional parameter, Peach uses the value
specified in this element block. Values for optional attributes and parameters
are defined in this element.

Note that the “Size” attribute of the number element is a required attribute
that must be specified with each number instance.


This xml element has one attribute, import, that names the python file containing
code. Note the “.py” postfix is not used.

In v3.x, you must specify each python file you want to use. Wildcard characters (*)
are not supported.

The from attribute is now a top-level element named that specifies
the search path for all python modules. Note that a trailing “\” or “/” for the
path is not used. Use multiple elements to tell Peach to search in
more than one place.


Remove all “from” relation statements from all data model elements.


A multiple-bit Flag that uses the value parameter accepts a value expressed as a hexadecimal integer or a sequence of hexadecimal digits.

A value expressed as a hexadecimal integer must fit into the bits allocated for the flag.
A value expressed as a sequence of hexadecimal digits must have sufficient length to span the number of bits in the flag.

value Attribute
When specifying a value for a number, you can use an integer value, a hexadecimal integer value or a sequence of hexadecimal digits. +
A value expressed as a sequence of hexadecimal digits (where valueType=”hex”) must match lengthwise with the allocated size of the number or a validation error occurs. For example, initially setting a 64-bit number to one can be specified as seven digits of zeroes and one digit of one:


For values expressed as hex integers prefix the value with “0x”.


Size is a required attribute. You cannot use a default size specified in the Defaults element block for number elements.


No changes.


Now includes logger definitions, and performs the functionality of the v2.3 Run xml element.


This section is obsolete. Move the Logger into the test section.


RawIpv4
Host and Protocol are required parameters.
The Protocol parameter is required and must have a valid value.
“17” is the value for UDP. “6” is the value for TCP.

The Host parameter is required and must have a valid value, specified as a hostname or an IP address.

The Interface parameter now uses CamelCase with a capitalized first letter. This parameter is optional.

NOTE: While the old publisher name is valid, the current name RawIpv4 is the name used in the documentation and in log messages from the Peach engine.

Top