Quick Start

This part of the documentation shows how to use the most important parts of Binalyzer.

Usually, everything starts out with a template that describes the layout of some binary data. Templates use XML, but other description languages could be used as well. Let’s look at an example. The following XML describes a 64 Byte piece of binary data. The from_str() method parses it using the XMLTemplateParser in order to create a Template object model that can be accessed using the Binalyzer object. There is no data bound to the template so the value property returns an empty byte sequence.

>>> from binalyzer import Binalyzer
>>> binalyzer = Binalyzer().xml.from_str("""
...     <template name="binary-data-64">
...         <field name="data-field-1" size="32"></field>
...         <field name="data-field-2" size="16"></field>
...         <field name="data-field-3" size="8"></field>
...         <field name="data-field-4" size="8"></field>
...     </template>
... """)
>>> binalyzer.template.name
'binary-data-64'
>>> binalyzer.template.value
b''
>>> binalyzer.template.size
64

Binding the template to a data stream allows for read or write access through named fields. In the example below the Binalyzer instance knows the total size of the data and binds a zeroized default stream (that fully resides in memory) to the template. The memory stream is accessed using named fields such as template.data_field_1. It is notable that the template itself represents the root node of the XML description.

>>> binalyzer.template.data_field_1.value = bytes([0xAA] * 32)
>>> binalyzer.template.data_field_2.value = bytes([0xBB] * 16)
>>> binalyzer.template.data_field_3.value = bytes([0xCC] * 8)
>>> binalyzer.template.data_field_4.value = bytes([0xDD] * 8)

Using the data property of the Binalyzer instance, the binary data can be written to a file.

>>> with open('simple-example-64.bin', 'wb') as binary_file:
...     binary_file.write(binalyzer.data.read())
...
64

Let’s have a look at the created file.

~$ binalyzer dump simple-example-64.bin

00000000: AA AA AA AA AA AA AA AA  AA AA AA AA AA AA AA AA  ................
00000010: AA AA AA AA AA AA AA AA  AA AA AA AA AA AA AA AA  ................
00000020: BB BB BB BB BB BB BB BB  BB BB BB BB BB BB BB BB  ................
00000030: CC CC CC CC CC CC CC CC  DD DD DD DD DD DD DD DD  ................

It’s also possible to read from the binary file and inspect it. Therefore, the file stream must be assigned to the Binalyzer.data field.

>>> binary_file = open('simple-example-64.bin', 'rb')
>>> binalyzer.data = binary_file
>>> for byte in binalyzer.template.data_field_4.value:
...     print(f"0x{byte:2x}")
...
0xdd
0xdd
0xdd
0xdd
0xdd
0xdd
0xdd
0xdd
>>>

That’s it. Now, you know how to use templates and acceess binary data for read and write access. Check out what Templates make possible.