9.1Introduction to the IoT Fuzzer API Specification 9.1.1IoT Fuzzer Open Specification Core
The IoT Fuzzer Open Specification defines a XML document format describing scenarios used by the fuzzer, including templates of sent packets, modifications applied to them, and expected responses from the fuzzed device.
9.1.2Intended Audience
This specification is intended for both software developers and reimplementers of this GE. For the former, this document provides a full specification of how to define XML scenarios usable with the IoT Fuzzer. For the latter, this specification provides a full specification of how to reimplement the fuzzer in a way compatible with existing scenarios.
This version of the IoT Fuzzer Open Specification Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:
Revision Date
|
Changes Summary
|
Apr 22, 2013
| | 9.1.4Additional Resources
You can download the most current version of this document from the FIWARE specification website at Security-Monitoring: IoT Fuzzer Open API Specification. For more details about the IoT Fuzzer that this specification is based upon, please refer to High Level Description. Related documents, including an Architectural Description, are available at the same site.
9.2General IoT Fuzzer Open Specification Information 9.2.1Data Types The "scenario" Tag
The root of a scenario definition is the scenario tag, which can have the following attributes:
Attribute
|
Type
|
Description
|
name
|
string
|
The name of the scenario
|
ignore_router_advertisement
|
boolean
|
Can be set to true, to prevent Neighbor Discovery Protocol messages from perturbing the tests
|
Additionally, the scenario tag can have the following children:
-
the send tag, which describes a point of the scenario when packet that has to be forged locally, then sent to the fuzzed device;
-
the recv tag, which describes a point of the scenario when a packet is expected to be received from the fuzzed device, and the fields to check for correctness.
The "send" Tag
The send tag can have the following attributes:
Attribute
|
Type
|
Description
|
name
|
string
|
The name of the scenario
|
message
|
string
|
The packet template to use; the value of the message attribute is the identifier of a message defined in the message.py module
|
payload
|
string
|
The packet template to use; the value of the payload attribute is the packet content, encoded in hexadecimal
|
packet_type
|
string
|
The type of the packet; can take two different values:
-
6lowpan means that the packet will be sent to the air "raw", without alteration, by the RZUSBstick
-
ipv6 means that the RZUSBstick will apply 6LoWPAN header compression before sending the packet to the air
|
Note that the message and payload are mutually exclusive: only one of them should be present in a tag.
Finally, the send tag can have children of field type, that allow to alter the packet template.
The "recv" Tag
The recv tag can have the following attributes:
Attribute
|
Type
|
Description
|
optional
|
boolean
|
When set to true, the reception of this packet is not mandatory, and the test will not fail in the case that the timeout is reached
|
timeout
|
integer
|
The timeout value for this specific packet
|
Finally, the send tag can have children of two types:
-
the test tag is used to test the value of a particular protocol field;
-
the calc tag is used to store the value of a particular protocol field in a scenario variable.
The "field" Tag
The field tag is used inside send tags, and indicates how the packet template shall be modified before it is sent to the RZUSBstick. It can contain the following attributes:
Attribute
|
Type
|
Description
|
layer
|
string
|
The name of the layer containing the field; this MUST be the name of a Scapy module
|
name
|
string
|
The name of the field; this MUST be the name of one attribute inside the Scapy module defined by the layer attribute
|
type
|
string
|
The type of the field; it can take several values:
-
string: the value vill be applied directly to the template
-
int: the value will be cast to an int, then applied to the template
-
random: the value will be randomized using Scapy mechanism
-
console: the value will be replaced with a positional command line argument (defined using the '-a' command line parameter of 6LowFuzzer's executor.py)
-
variable: the value will be replaced with the value of a scenario variable
|
value
|
string
|
The value to assign to the field, its interpretation depends of the field type:
-
string or int: the value will be applied directly
-
console: the value should represent a positional argument, in shell-like syntax, and start at '$1'
|
value_from
|
string
|
The name of the variable to get the value from, in case the type of the field is variable
|
Note that random and console types no not use the value attribute, and that only the variable type uses the value_from attribute.
The "test" Tag
The test tag is used inside recv tags, and indicates how a specific packet field must be tested, against a reference value:
Attribute
|
Type
|
Description
|
layer
|
string
|
The name of the layer containing the field; this MUST be the name of a Scapy module
|
field
|
string
|
The name of the field; this MUST be the name of one attribute inside the Scapy module defined by the layer attribute
|
compare
|
string
|
The operation to use for comparing the field value and the reference value:
-
equal: the field value MUST be equal to the reference value
-
lessthan: the field value MUST be less than the reference value
-
greaterthan: the field value MUST be greater than the reference value
|
value
|
string
|
The reference value against which to compare the field value
|
type
|
string
|
The type of the reference value, can be either int or string
| The "calc" Tag
The calc tag is used inside recv tags, and is used to compute the value of scenario variables. It can contain the following attributes:
Attribute
|
Type
|
Description
|
layer
|
string
|
The name of the layer containing the field; this MUST be the name of a Scapy module
|
field
|
string
|
The name of the field; this MUST be the name of one attribute inside the Scapy module defined by the layer attribute
|
assign_to
|
string
|
The name of the variable to assign the value to
|
code
|
string
|
A string representing calculation to perform on the field value before assigning it to the variable; the following will be performed:
-
first, the code string will be formatted using the value (python: "code = code % value")
-
then, the resulting string will be evaluated (python: "assign_to = eval(code)")
|
Share with your friends: |
