scapy_cbor package

This package provides an augmented interface of scapy.fields and scapy.packet to manage cbor-decoded structures and values.

Subpackages

• scapy_cbor.test package
  • Submodules
    • TestBoolField
      • TestBoolField.testEncode()
      • TestBoolField.testDecode()
      • TestBoolField.testGetfield()
      • TestBoolField.testAddfield()
    • TestUintField
      • TestUintField.testEncode()
      • TestUintField.testDecode()
    • TestOptionalField
      • TestOptionalField.testEncode()
      • TestOptionalField.testDecode()
      • TestOptionalField.testGetfield()
      • TestOptionalField.testAddfield()
    • TestFieldListField
      • TestFieldListField.testEncode()
      • TestFieldListField.testDecode()
      • TestFieldListField.testGetfield()
      • TestFieldListField.testAddfield()
    • MockItem
      • MockItem.fields_desc
      • MockItem.aliastypes
    • TestCborItem
      • TestCborItem.testEncode()
      • TestCborItem.testDecodeConstructor()
      • TestCborItem.testDecodeDissect()
      • TestCborItem.testDecodeBytes()
    • MockArray
      • MockArray.fields_desc
      • MockArray.aliastypes
    • TestCborArray
      • TestCborArray.testEncode()
      • TestCborArray.testDecodeConstructor()
      • TestCborArray.testDecodeDissect()
      • TestCborArray.testDecodeBytes()
    • MockValueHead
      • MockValueHead.aliastypes
      • MockValueHead.fields_desc
    • TestTypeValueHead
      • TestTypeValueHead.setUpClass()
      • TestTypeValueHead.testEncodeEmpty()
      • TestTypeValueHead.testDecodeEmpty()
      • TestTypeValueHead.testEncodeItem()
      • TestTypeValueHead.testDecodeItem()
      • TestTypeValueHead.testEncodeArray()
      • TestTypeValueHead.testDecodeArray()

Submodules

Extend SCAPY field interface for CBOR encoding.

exception scapy_cbor.fields.DecodeError

Bases: RuntimeError

Signal an error in CBOR decoding.

class scapy_cbor.fields.CborField(name, default=None)

Bases: Field

Abstract base type.

Parameters:

• name (str) – The unique field name.

• default – Default/initial value.

addfield(pkt, s, val)

Augmented signature for s as CBOR array instead of bytes.

getfield(pkt, s)

Augmented signature for s as CBOR array instead of bytes.

i2m(pkt, x)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, x)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

any2i(pkt, x)

Try to understand the most input values possible and make an internal value from them

class scapy_cbor.fields.OptionalField(fld, missing=None)

Bases: object

Optional based on the contents of the source data.

Parameters:

missing – Values which will be treated as non-values and omitted. The default is None and cbor2.undefined.

fld

missing

getfield(pkt, s)

addfield(pkt, s, val)

class scapy_cbor.fields.ArrayWrapField(fld)

Bases: CborField

Wrap a field with an array container.

fld

getfield(pkt, s)

Augmented signature for s as CBOR array instead of bytes.

addfield(pkt, s, val)

Augmented signature for s as CBOR array instead of bytes.

class scapy_cbor.fields.FieldListField(name, default, fld)

Bases: CborField

Similar to scapy.fields.FieldListField.

islist = 1

fld

i2m(pkt, x)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

any2i(pkt, x)

Try to understand the most input values possible and make an internal value from them

i2repr(pkt, x)

Convert internal value to a nice representation

addfield(pkt, s, val)

Augmented signature for s as CBOR array instead of bytes.

getfield(pkt, s)

Augmented signature for s as CBOR array instead of bytes.

class scapy_cbor.fields.PacketField(name, default, cls)

Bases: CborField

Similar to scapy.fields.PacketField but for CBOR encoding.

holds_packets = 1

cls

i2m(pkt, x)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, x)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

any2i(pkt, x)

Try to understand the most input values possible and make an internal value from them

class scapy_cbor.fields.PacketListField(name, default, cls)

Bases: PacketField

Similar to scapy.fields.PacketListField but for CBOR encoding.

islist = 1

getfield(pkt, s)

Augmented signature for s as CBOR array instead of bytes.

addfield(pkt, s, val)

Augmented signature for s as CBOR array instead of bytes.

class scapy_cbor.fields.BoolField(name, default=None)

Bases: CborField

A field which must be ‘bool’ type.

i2m(pkt, val)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, val)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

i2repr(pkt, x)

Convert internal value to a nice representation

randval()

Return a volatile object whose value is both random and suitable for this field

class scapy_cbor.fields.UintField(name, default=None, maxval=None)

Bases: CborField

A field which must be ‘uint’ type.

Parameters:

maxval – The maximum value allowed in this field. Warnings will be output if the actual value is above this limit

maxval

i2m(pkt, x)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, x)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

i2repr(pkt, x)

Convert internal value to a nice representation

randval()

Return a volatile object whose value is both random and suitable for this field

class scapy_cbor.fields.EnumField(name, default, enum)

Bases: UintField

An integer containing an enumerated value.

Parameters:

enum (enum.IntEnum) – Available values for the field.

enum

m2i(pkt, val)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

class scapy_cbor.fields.FlagsField(name, default, flags)

Bases: UintField

An integer containing enumerated flags.

Parameters:

flags (enum.IntFlag) – Available flags for the field.

flags

m2i(pkt, x)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

class scapy_cbor.fields.TstrField(name, default=None)

Bases: CborField

Allow only CBOR ‘tstr’ value.

i2m(pkt, x)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, x)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

i2repr(pkt, x)

Convert internal value to a nice representation

randval()

Return a volatile object whose value is both random and suitable for this field

class scapy_cbor.fields.BstrField(name, default=None)

Bases: CborField

Allow only CBOR ‘bstr’ value.

i2m(pkt, x)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, x)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

i2repr(pkt, x)

Convert internal value to a nice representation

randval()

Return a volatile object whose value is both random and suitable for this field

class scapy_cbor.fields.CborEncodedField(name, default=None)

Bases: BstrField

An encoded CBOR data item within a ‘bstr’.

i2m(pkt, val)

Encode this field to a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The internal data value.

Returns:

The CBOR item.

Return type:

A value or IGNORE.

m2i(pkt, val)

Decode this field from a CBOR item.

Parameters:

• pkt – The packet (container) context.

• x – The CBOR item value.

Returns:

The internal data value.

Return type:

A value or IGNORE.

i2repr(pkt, x)

Convert internal value to a nice representation

Extend SCAPY packet interface for CBOR structure encoding.

class scapy_cbor.packets.AbstractCborStruct(_pkt=b'', post_transform=None, _internal=0, _underlayer=None, _parent=None, stop_dissection_after=None, **fields)

Bases: Packet

An abstract data packet, which encodes as a CBOR item of arbitrary value.

Complex inner types mean this packet is never iterable for multiple values.

dissect(s)

Decode the whole bundle from a bytestring. :param data: The encoded bundle.

aliastypes = [<class 'scapy_cbor.packets.AbstractCborStruct'>, <class 'scapy.packet.Packet'>]

class scapy_cbor.packets.CborArray(_pkt=b'', post_transform=None, _internal=0, _underlayer=None, _parent=None, stop_dissection_after=None, **fields)

Bases: AbstractCborStruct

An abstract data layer, which encodes a packet as a CBOR array. Any payload of this packet will be appended to the array, so it must itself build to an array struct.

self_build(*_args, **_kwargs)

Create the default layer regarding fields_desc dict

post_build(pkt, pay)

Interpret payload as extra array items.

do_dissect(s)

aliastypes = [<class 'scapy_cbor.packets.CborArray'>, <class 'scapy_cbor.packets.AbstractCborStruct'>, <class 'scapy.packet.Packet'>]

class scapy_cbor.packets.CborItem(_pkt=b'', post_transform=None, _internal=0, _underlayer=None, _parent=None, stop_dissection_after=None, **fields)

Bases: AbstractCborStruct

A special case layer which is undecoded CBOR item storage. There is no packet framing (i.e. array) on this item and no payload or padding is allowed.

Only one field is allowed with an arbitrary name. The base class field name is ‘item’.

fields_desc: List[AnyField] = [<CborField (CborItem).item>]

self_build(*_args, **_kwargs)

Create the default layer regarding fields_desc dict

post_build(pkt, pay)

DEV: called right after the current layer is build.

Parameters:

• pkt (str) – the current packet (build by self_build function)

• pay (str) – the packet payload (build by do_build_payload function)

Returns:

a string of the packet with the payload

build()

Create the current layer

Returns:

string of the packet with the payload

do_dissect(s)

aliastypes = [<class 'scapy_cbor.packets.CborItem'>, <class 'scapy_cbor.packets.AbstractCborStruct'>, <class 'scapy.packet.Packet'>]

class scapy_cbor.packets.TypeValueHead(_pkt=b'', post_transform=None, _internal=0, _underlayer=None, _parent=None, stop_dissection_after=None, **fields)

Bases: CborArray

A pattern for an array encoding which contains exactly two values. This is analogous to a type-length-value (TLV) encoding for CBOR. The type is a field and the value is captured in the payload of this packet. The default payload for unknown types is a CborItem.

fields_desc: List[AnyField] = [<UintField (TypeValueHead,AdminRecord).type_code>]

do_build_payload()

Create the default version of the payload layer

Returns:

a string of payload layer

do_dissect_payload(s)

Perform the dissection of the layer’s payload

Parameters:

s (str) – the raw layer

default_payload_class(payload)

DEV: Returns the default payload class if nothing has been found by the guess_payload_class() method.

Parameters:

payload (str) – the layer’s payload

Returns:

the default payload class define inside the configuration file

classmethod bind_type(type_code)

Bind a block-type-specific packet-class handler.

Parameters:

type_code (int) – The type to bind to the payload class.

aliastypes = [<class 'scapy_cbor.packets.TypeValueHead'>, <class 'scapy_cbor.packets.CborArray'>, <class 'scapy_cbor.packets.AbstractCborStruct'>, <class 'scapy.packet.Packet'>]

class scapy_cbor.packets.CborSequence(_pkt=b'', post_transform=None, _internal=0, _underlayer=None, _parent=None, stop_dissection_after=None, **fields)

Bases: CborArray

Internally handled as an array but encoded without the array framing.

dissect(s)

Synthesize an indefinite-length array frame. :param data: The CBOR array.

aliastypes = [<class 'scapy_cbor.packets.CborSequence'>, <class 'scapy_cbor.packets.CborArray'>, <class 'scapy_cbor.packets.AbstractCborStruct'>, <class 'scapy.packet.Packet'>]

Conversion and output utilites.

scapy_cbor.util.encode_diagnostic(obj, **kwargs)

Encode a Python object as a CBOR Extended Diagnostic Notation string.

Parameters:

kwargs – Special options: indent: if provided, indent this many spaces bstr_as: either ‘hex’ (default) or ‘base64’

Throw TypeError:

If there is an unencodable part.