Protocol Modeling#

In the API, the Protocol class is the entry point for defining a complete protocol made of a state machine and different format messages.

class Protocol(name, path_zdl=None)[source]#

The Protocol class provides a wrapper for the state machine model and the format messages model (i.e. the permitted symbols) of a protocol.

The Protocol constructor expects some parameters:

Parameters

  • name (an str, required) – This parameter is the name of the protocol.

  • path_zdl (an str, optional) – The directory path containing the .zdl files of the format messages and the automaton. Default is None.

The Protocol class provides the following public variables:

Variables

  • name (str) – The name of the protocol.

  • symbols (a dict where keys are symbol names and values are Symbol) – The defined symbols for the protocol.

  • automata (an Automata) – The automaton defined for the protocol.

If .zdl files are provided, they should follow a specific convention to contain the defined symbols and automaton:

  • The .zdl file for the format messages should be named {PROTOCOL_NAME}_format.zdl, and should contain a variable named symbols that contains a list of Symbol.

  • The .zdl file for the automaton should be named {PROTOCOL_NAME}_automata.zdl, and should contain a variable named automata that contains an Automata.

The following code describes the instantiation of a new Protocol, without .zdl files:

>>> from netzob.all import *
>>> icmp = Protocol("ICMP")
>>> icmp.name
'ICMP'

The following code describes the instantiation of a new Protocol with provided protocol definition in .zdl files. The automaton is retrieved and rendered with a dot syntax.

>>> udp = Protocol("UDP", path_zdl="test/resources/files/UDP_example/")
>>> udp.name
'UDP'
>>> udp.symbols
Symbols(udp)
>>> dot_code = udp.automata.generateDotCode()
>>> print(dot_code)  
digraph G {
"Initial state" [shape=doubleoctagon, label="Initial state", style=filled, fillcolor=white, URL="..."];
"Channel opened" [shape=ellipse, label="Channel opened", style=filled, fillcolor=white, URL="..."];
"Initial state" -> "Channel opened" [fontsize=5, label="OpenChannelTransition", URL="..."];
}

For visualization purposes, the following lines would generate a PNG file with the dot representation of the automaton:

fd = open("/tmp/dotcode.dot", "w")
fd.write(dotCode)
fd.close()

And then in a shell:

$ dot -Tpng -o /tmp/dotcode.png /tmp/dotcode.dot
$ xdg-open /tmp/dotcode.png
static load_format(path)[source]#

Load and return the symbols contained in the provided ZDL format file.

Parameters

path (str) – Path of the ZDL format file.

Returns

The list of symbols defined in the ZDL format file.

Return type

a dict where keys are symbol names and values are Symbol

>>> from netzob.all import *
>>> symbols = Protocol.load_format("test/resources/files/UDP_example/UDP_format.zdl")
>>> type(symbols["udp"])
<class 'netzob.Model.Vocabulary.Symbol.Symbol'>