We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Security-Monitoring: IoT Fuzzer Open API Specification - FIWARE Forge Wiki

Security-Monitoring: IoT Fuzzer Open API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the IoT Fuzzer API Specification

This API is deprecated.

IoT 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.

Intended 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.

API Change History

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
  • Initial Release

Additional 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.

General IoT Fuzzer Open Specification Information

Data 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)")

Scenario Definition

A scenario is contained in a autonomous XML file, using a scenario tag as its root, and possibly assisted by message templates defined in the messages.py module.

Here are some message definitions that can be used as templates:

from scapy.layers.sixlowpan import LoWPAN_IPHC
from scapy.layers.inet6 import IPv6, ICMPv6EchoRequest

messages['ping_echo'] = LoWPAN_IPHC() \
  / IPv6(dst="aaaa::11:22ff:fe33:4455", src="aaaa::1", hlim=128) \
  / ICMPv6EchoRequest(id=0x1540, seq=0x01, data="test")

messages['example_2'] = LoWPAN_IPHC()/IPv6("""6000000000000000
aaaa000000000000
001122fffe334455
aaaa000000000000
0000000000000001
8000c4cd00000000""".decode('hex'))

The first message is defined by its protocol attributes, using the Scapy definitions, whereas the second one is defined as a raw string, which could have been acquired through packet capture, for instance. Further information can be found in the Scapy documentation.

Then, those messages can be used in XML scenario definitions, such as the one defined below:

<?xml version="1.0" encoding="utf-8"?>
<scenario name="basic_ping" ignore_router_advertisement="true">
    <send name="1" message="ping_echo" packet_type="6lowpan">
        <field name="dst" layer="IPv6" value="$1" type="console" />
        <field name="src" layer="IPv6" value="$2" type="console" />
        <field name="data" layer="ICMPv6EchoRequest" value="check"
            type="string" />
    </send>
    <recv>
        <test layer="ICMPv6EchoReply" field="data" compare="equal"
            value="check" type="string" />
    </recv>
</scenario>

In this example, a very simple scenario has been defined:

  • first, a message will be sent to the target, using the "ping_echo" template defined in the message.py module excerpt above. It will differ from the template by 3 fields:
    • the dst field of the IPv6 layer will be replaced by the value of the first positional argument (passed on the command line using the -a parameter);
    • the src field of the IPv6 layer will be replaced by the value of the second positional argument (passed on the command line using the -a parameter);
    • the data field of the ICMPv6EchoRequest layer (the actual ICMP payload) will be replaced by the check string;
  • then, a response will be expected from the target device, and the following will be done:
    • the data field of the ICMPv6EchoReply layer (the actual ICMP payload) will be tested, and the test will succeed if it is equal to the check string.
Personal tools
Create a book