payloadinspector 1.0.1

Inspect byte strings as bit fields

payloadinspector

Inspect byte strings as bit fields.

payloadinspector takes a bit field (an ordered list of name-bitlength tuples) and a payload (a string of bytes) as arguments. It maps the data contents of the payload to the bit field and outputs one, several or all of the values.

Install

Install payloadinspector with pip

$ pip install payloadinspector

payloadinspector can also be installed from a local copy with

# Clone the repo one of:
#   - [e-mail]:fredrikh/payloadinspector.git
#   - https://gitlab.com/fredrikh/payloadinspector.git
$ git clone <repo-url>
$ cd payloadinspector

# Set up virtual environment, for example with
$ python3 -m venv .venv

# Install PayloadInspector
$ pip install $(pwd)

Usage

After installation payloadinspector can be called from the command line. Try running it with the -h flag to see the help text with formatting rules.

Reading bitfield format from argument

As an example, let's say we have a bitfield that looks like this:

             -------------------------------------------------------
element name | address | padding | priority | padding | data | CRC |
             -------------------------------------------------------
# of bits    |   16    |    8    |     4    |    4    |  64  |  16 |
             -------------------------------------------------------

Note that there are two sections with the name 'padding'. They must be given unique names in the bitfield specification.

The data we have from our debugger or similar is:

0x00 0x03 0x00 0x50 0x43 0xc1 0xac 0x6f 0x90 0xaa 0x43 0xdf 0x43 0xd6

To inspect the value of each bitfield element, we would run

$ payloadinspector --bitfield "(address, 16), (padding1, 8), (priority, 4), (padding2, 4), (data, 64), (crc, 16)" --payload "0x00 0x03 0x00 0x50 0x43 0xc1 0xac 0x6f 0x90 0xaa 0x43 0xdf 0x43 0xd6"

Which would output:

address: 3, padding1: 0, priority: 5, padding2: 0, data: 4882373066214753247, crc: 17366

The output format can be configured using the -f, --format argument. It can either be used to specify the encoding as dec (default) bin or hex:

$ payloadinspector --bitfield "(address, 16), (padding1, 8), (priority, 4), (padding2, 4), (data, 64), (crc, 16)" --payload "0x00 0x03 0x00 0x50 0x43 0xc1 0xac 0x6f 0x90 0xaa 0x43 0xdf 0x43 0xd6" --format hex

Which gives:

address: 0x3, padding1: 0x0, priority: 0x5, padding2: 0x0, data: 0x43c1ac6f90aa43df, crc: 0x43d6

It can also be used to specify a subset of the bitfield elements:

$ payloadinspector --bitfield "(address, 16), (padding1, 8), (priority, 4), (padding2, 4), (data, 64), (crc, 16)" --payload "0x00 0x03 0x00 0x50 0x43 0xc1 0xac 0x6f 0x90 0xaa 0x43 0xdf 0x43 0xd6" --format "address, priority"

Which gives the output:

address: 3, priority: 5

Finally, the format string can be used to specify individual encodings for each element:

$ payloadinspector --bitfield "(address, 16), (padding1, 8), (priority, 4), (padding2, 4), (data, 64), (crc, 16)" --payload "0x00 0x03 0x00 0x50 0x43 0xc1 0xac 0x6f 0x90 0xaa 0x43 0xdf 0x43 0xd6" --format "address,  data:hex, priority:bin"

Which gives the output:

address: 3, data: 0x43c1ac6f90aa43df, priority: 0b101

The example above also shows that the order of the elements can be rearranged with the format string.

Reading bitfield format from C file

The bitfield structure can also be read by parsing a C bitfiled. If you have a C header file header.h which contains the struct

/* ... */

struct bitfield1
{
    uint8_t element1 : 3;
    uint8_t element2 : 5;
    uint16_t element3 : 14;
    uint8_t padding : 2
};

typedef struct
{
    uint8_t element4 : 4;
    uint8_t element5 : 4;
    uint16_t element6 : 10;
    uint8_t padding 6
} bitfield2;

/* ... */

You can load each struct directly from the file by giving the --source-structargument like this:

$ payloadinspector --source-struct "header.h:bitfield1" --payload "0xdf 0x43 0xd6"

Which would give the output:

element1: 6, element2: 31, element3: 4341, padding: 2

It is also possible to only print the format of the bitfield by omitting the --payload argument:

$ payloadinspector --source-struct "header.h:bitfield1"

gives the output:

element1: 3
element2: 5
element3: 14
padding: 2

Several formats of struct definitions are supported, both typedefed and non-typedefed, as well as with attributes like "packed".

However, all elements must be given a name and a bit size as an integer. #define-d constants are not supported. The following structs will not work

struct incompatible_bitfield1
{
    uint8_t element1 : 3;
    uint8_t element2; // ERROR: Cannot parse bit size
    uint16_t element3 : 14;
};

struct incompatible_bitfield2
{
    uint8_t element1 : 4;
    uint8_t : 4; // ERROR: No element name
    uint16_t element2 : 16;
};

#define N_BITS_ELEMENT1 3
#define N_BITS_ELEMENT2 5

struct incompatible_bitfield3
{
    uint8_t element1 : N_BITS_ELEMENT1; // ERROR: Cannot parse bit size
    uint8_t element2 : N_BITS_ELEMENT2;
}