puresnmp.adt module

This module contains simple “abstract data types” which are used for both type-hinting and to keep the code more expressive & readable.

class puresnmp.adt.EncryptedMessage(version: Integer, header: HeaderData, security_parameters: bytes, scoped_pdu: OctetString | ScopedPDU)

Bases: Message

A message whose PDU is encrypted

header: HeaderData: Additional information wrapping the old-style PDU

scoped_pdu: OctetString: The “old-style” PDU (either plain or encrypted)

security_parameters: bytes: Additional data needed to authenticate & en/decrypt the message

version: Integer: The IANA version identifier

class puresnmp.adt.HeaderData(message_id: int, message_max_size: int, flags: V3Flags, security_model: int)

Bases: object

Header information for an SNMPv3 message

as_snmp_type() → Sequence: Convert this header-data object into an x.690 Sequence

flags: V3Flags: Additional boolean flags about the message

message_id: int: ID to match responses with requests

message_max_size: int: Maximum number of bytes accepted by the SNMP engine

pretty(depth: int = 0) → str

Return a prettyfied string of this object.

This prettyfied string is useful for debugging and introspection.

Parameters:: depth – How many levels of indentation to apply. This is used internally for nested structures.

security_model: int: The security model required to process this message (identified by a IANA registered ID). See puresnmp.security

class puresnmp.adt.Message(version: Integer, header: HeaderData, security_parameters: bytes, scoped_pdu: OctetString | ScopedPDU)

Bases: object

A complete SNMP message including all information needed by RFC 3411

Such a message contains an “old-style” PDU (as was defined in SNMPv2) plus some meta-data. The meta-data consists of a version identifier to identify the proper “message-processing-model” using a IANA registered value.

See also

RFC definition: The MIB definition of an SNMPv3 message
Example Message Format: A simple visual representation of the byte-structure of an SNMPv3 message
IANA Message Processing Models: Oficially registered message “version” identifiers

static decode(data: bytes) → PlainMessage | EncryptedMessage

Construct a new SNMPv3 message from a bytes object

>>> from puresnmp.pdu import GetRequest, PDUContent
>>> from x690.types import ObjectIdentifier as OID
>>> pdu = ScopedPDU(
...     OctetString(b"engine"),
...     OctetString(b"context"),
...     GetRequest(PDUContent(42, [])),
... )
>>> msg = PlainMessage(
...     version=Integer(3),
...     header=HeaderData(42, 65000, V3Flags(False, False, False), 3),
...     security_parameters=b"",
...     scoped_pdu=pdu
... )
>>> result = Message.decode(bytes(msg))
>>> result == msg
True

classmethod from_sequence(seq: Sequence) → TMessageType: Construct a Message instance from an X.690 Sequence

header: HeaderData: Additional information wrapping the old-style PDU

pretty(depth: int = 0) → str

Return a prettyfied string of this object.

This prettyfied string is useful for debugging and introspection.

Parameters:: depth – How many levels of indentation to apply. This is used internally for nested structures.

scoped_pdu: OctetString | ScopedPDU: The “old-style” PDU (either plain or encrypted)

security_parameters: bytes: Additional data needed to authenticate & en/decrypt the message

version: Integer: The IANA version identifier

class puresnmp.adt.PlainMessage(version: Integer, header: HeaderData, security_parameters: bytes, scoped_pdu: OctetString | ScopedPDU)

Bases: Message

A message whose PDU is not encrypted

header: HeaderData: Additional information wrapping the old-style PDU

scoped_pdu: ScopedPDU: The “old-style” PDU (either plain or encrypted)

security_parameters: bytes: Additional data needed to authenticate & en/decrypt the message

version: Integer: The IANA version identifier

class puresnmp.adt.ScopedPDU(context_engine_id: OctetString, context_name: OctetString, data: PDU)

Bases: object

A data-structure wrapping the different values from a SNMPv3 “Scoped PDU”

as_snmp_type() → Sequence: Convert this message into an x.690 Sequence

context_engine_id: OctetString

context_name: OctetString

data: PDU: A PDU-structure as defined in SNMPv2

static decode(data: bytes, slc: slice = slice(None, None, None)) → ScopedPDU

Create a ScopedPDU instance from an x.690 bytes object

Parameters:

bytes – the bytes object which contains the PDU.
slc – The slice at which the object is located. If left to the default, it will assume that the object is located in the beginning of the bytes object.

>>> from puresnmp.pdu import GetRequest, PDUContent, VarBind
>>> from x690.types import ObjectIdentifier as OID
>>> pdu = ScopedPDU(
...     OctetString(b"engine"),
...     OctetString(b"context"),
...     GetRequest(PDUContent(42, [])),
... )
>>> result = ScopedPDU.decode(bytes(pdu))
>>> pdu == result
True

pretty(depth: int = 0) → str

Return a prettyfied string of this object.

This prettyfied string is useful for debugging and introspection.

Parameters:: depth – How many levels of indentation to apply. This is used internally for nested structures.

class puresnmp.adt.V3Flags(auth: bool = False, priv: bool = False, reportable: bool = False)

Bases: object

This class represents the SNMP message flags.

At the time of this writing, this only contains the flags auth, priv and reportable. The remaining bytes are (as of this state) reserved by the SNMP standard.

auth: bool = False: Whether the PDU exchange requires authentication

static decode(blob: OctetString) → V3Flags

Converts an OctetString instance into a more pythonic instance

>>> V3Flags.decode(OctetString(b"\x00"))
V3Flags(auth=False, priv=False, reportable=False)
>>> V3Flags.decode(OctetString(b"\x07"))
V3Flags(auth=True, priv=True, reportable=True)

priv: bool = False: Whether the PDU exchange requires privacy (encryption)

reportable: bool = False: Whether the exchanged PDU expects a response