ntrprtr 1.3.2

Interpret bytes through different customizable actions

Description

Interpret bytes through different customizable actions

Configuration

In order to interpet the given bytes, you need to provide a ´.json´ file with the following structure:

[
    {
        "name": "Enter the name here..",
        "description": "Provide description here..",
        "start": 0,  // The start byte from where you want to interpret
        "end": 10,   // The end byte where interpreting shall stop
        "action": {  // There a 3 different actions at the moment. 
                     // --> Do only specify one action per object here.
                     // --> The actions are specified below.
                     // --> You do not need to provide an action.
        }
    }
]

The following actions are available:

// Get the decimal value of the given bytes.
// Specify if you want to interpret it as little or big endian
{
    "type": "decimal",
    "endianess": "little|big"
}

// Get the binary value of the given bytes.
// Specify if you want to interpret it as little or big endian
{
    "type": "binary",
    "endianess": "little|big"
}

// Get the ascii representation of the given bytes.
{
    "type": "ascii",
    "nonAsciiPlaceholder": "."
}

// Get the unicode representation of the given bytes.
{
    "type": "unicode",
    "endianess": "little|big"
}

// Provides a hexdump for the given bytes
{
    "type": "hexdump",
    "nonAsciiPlaceholder": "."
}

// Compare the given bytes against your own values:
{
    "type": "equals",
    "endianess": "little|big",
    // Add as many objects as you want to the "cmp" list
    "cmp": [{
                // The value you want to compare with the given bytes
                "value": "1D1E", 
                // A description which will be added to the result, 
                // if the given bytes matches "value"         
                "description": "Compare 1"      
            },{
                "value": "1D1",
                "description": "Compare 2"
            }],
    // The result if there was no match 
    "noMatch": "No Match found!"
}

// Compare the bits of the given bytes against your own values
{
    "type": "bitequals",
    "endianess": "little|big",
    // Add as many objects as you want to the "cmp" list
    "cmp": [{
                // The bits you want to compare
                "value": "01110111",
                // Description to be added to the result,
                // if bits machtes "value"
                "description": "Bits are equal"
            }],
    // The result if there was no match 
    "noMatch": "Bits are not equal!"
}

// Interprets 2 Bytes as DOS time - format hour:minute:seconds
{
    "type": "dostime",
    "endianess": "little|big"
}

// Interprets 2 Bytes as DOS date - format day.month.year
{
    "type": "dosdate",
    "endianess": "little|big"
}

Just add as many interpreting objects as you want to the list. The output is a list of tuples. Look at the example section for an overview.

Installation

pip install ntrprtr

Example

Given bytes to interpret:

00 01 02 03 04 04 06 07 08 09 0A 0B 0C 0D 0E 0F 
68 61 6C 6C 6F 20 77 6F 72 6C 64 1B 1C 1D 1E 1F
43 B7 67 42 00 00 00 00 00 00 00 00 00 00 00 00
79 00 5F 00 30 00 31 00 2E 00 6A 00

Use the following config.json:

[
    {
        "name": "first-bytes",
        "description": "This are the first three bytes",
        "start": 0,
        "end": 2,
        "action": {
            "type": "decimal",
            "endianess": "little"
        }
    },
    {
        "name": "bin-bytes",
        "description": "Binary bytes",
        "start": 2,
        "end": 3,
        "action": {
            "type": "binary",
            "endianess": "little"
        }
    },
    {
        "name": "ascii-bytes",
        "description": "These are ascii values",
        "start": 16,
        "end": 26,
        "action": {
            "type": "ascii",
            "nonAsciiPlaceholder": "."
        }
    },
    {
        "name": "hexdump-bytes",
        "description": "Hexdump values",
        "start": 0,
        "end": 3,
        "action": {
            "type": "hexdump",
            "nonAsciiPlaceholder": "."
        }
    },
    {
        "name": "equals-bytes",
        "description": "Test if the given bytes equals my specified bytes",
        "start": 29,
        "end": 30,
        "action": {
            "type": "equals",
            "endianess": "big",
            "cmp": [{
                "value": "1D1E",
                "description": "Compare 1"
            },{
                "value": "1D1",
                "description": "Compare 2"
            }],
            "noMatch": "No Match found!"
        }
    },
    {
        "name": "bitEquals",
        "description": "Check bit equality",
        "start": 22,
        "end": 22,
        "action":{
            "type": "bitequals",
            "endianess": "big",
            "cmp": [
                {
                    "value": "01110111",
                    "description": "Bits are equal"
                }
            ],
            "noMatch": "Bits are not equal!"
        }
    },
      {
        "name": "dos-time-bytes",
        "description": "DOS time bytes",
        "start": 32,
        "end": 33,
        "action": {
            "type": "dostime",
            "endianess": "little"
        }
    },
    {
        "name": "dos-date-bytes",
        "description": "DOS date bytes",
        "start": 34,
        "end": 35,
        "action": {
            "type": "dosdate",
            "endianess": "little"
        }
    },
    {
        "name": "unicode-bytes",
        "description": "unicode repr.",
        "start": 48,
        "end": 59,
        "action": {
            "type": "unicode",
            "endianess": "big"
        }
    }
]

Use it programmatically:

import json

from ntrprtr.ByteInterpreter import ByteInterpreter
from ntrprtr.printer.Printer import Printer

configPath = "config.json"
pathToFile = "example.dd" # Contains the above bytes


fileHandle = open(pathToFile, "rb")
testBytes = fileHandle.read()

configHandle = open(configPath, encoding="utf8")
config = json.load(configHandle)

b = ByteInterpreter(testBytes, config)
result = b.interpret()

# If you want a standard output use Printer
p = Printer()
p.print(result)

The result is a list of tuples:

[
#     Name           Description          Action     Bytes                        ActionResult
    ('first-bytes', 'First three bytes', 'decimal',  bytearray(b'\x00\x01\x02'), '131328'), 
    ('bin-bytes',   'Binary bytes',      'binary',   bytearray(b'\x02\x03'),     '0000 0011 0000 0010'),
    ('ascii-bytes', 'Ascii values',      'ascii',    bytearray(b'hallo world'),  'hallo world'), 
    ('hexdump-bytes', 'Hexdump values', 'hexdump',   bytearray(b'\x00\x01\x02'), 'See below'),
    ('equals-bytes', 'Test equals',      'equals',   bytearray(b'\x1d\x1e'),     'Compare 1'),
    ('bitEquals',       'Bit equality', 'bitequals', bytearray(b'\x77'),         'Bits are equal'),
    ('dos-time-bytes', 'DOS time bytes', 'dostime',  bytearray(b'C\xb7'),        '22:58:6'),
    ('dos-date-bytes', 'DOS date bytes', 'dosdate',  bytearray(b'...'),          '7.3.2013')
    ('unicode-bytes', 'unicode repr.',   'unicode',  bytearray(b'...'),          '7.3.2013')
]

The output from printer looks like the following:

--> This are the first three bytes
    --------------
    00 01 02
    --------------
    131328

--> Binary bytes
    --------------
    02 03
    --------------
    0000 0011 0000 0010

--> These are ascii values
    --------------
    68 61 6C 6C 6F 20 77 6F 72 6C 64
    --------------
    hallo world

--> Hexdump values
    --------------
    Hexdump
    --------------

      Offset   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    ASCII           
    --------   -----------------------------------------------    ---------------- 
           0   00 01 02 03                                        ....             
    

--> Test if the given bytes equals my specified bytes
    --------------
    1D 1E
    --------------
    Compare 1

--> Check bit equality
    --------------
    77
    --------------
    0111 0111
    --------------
    Bits are equal

--> DOS time bytes
    --------------
    43 B7
    --------------
    22:58:6

--> DOS date bytes
    --------------
    67 42
    --------------
    7.3.2013

--> unicode repr.
    --------------
    79 00 5F 00 30 00 31 00 2E 00 6A 00
    --------------
    y_01.j

License

MIT