puresnmp.plugins.security module

This module provides a plugin architecture for security methods.

Each security plugin can be distributed as separate package by providing modules inside the namespace-package “puresnmp_plugins.security”. Note that in order to be a valid namespace-package, such a package must not have a __init__.py file!

Example folder-structure for a privacy plugin:

my-security-plugin/
 +- setup.py (or pyproject.toml)
 +- puresnmp/
     +- security/
         +- mymodule.py
         +- myothermodule.py

Note that there is no __init__.py file!

In order for modules to be detected as plugin, they must follow the following rules:

Have a no-arg function create returning a instance of the class (or subclass) of puresnmp.security.SecurityModel.
Contain a int-variable IDENTIFIER. This variable should map to the security model identifiers as defined in the SNMPv3 standard. See https://www.iana.org/assignments/snmp-number-spaces/snmp-number-spaces.xhtml and RFC 3411

class puresnmp.plugins.security.SecurityModel

Bases: Generic[TPureSNMPType, TX690Type]

Each Security Model defines the applied protecion on SNMP PDUs

generate_request_message(message: TPureSNMPType, security_engine_id: bytes, credentials: Credentials) → TX690Type

Take a plain unprocessed message and applies security to the message as defined by the concrete security model.

It returns the processed message including security modifications. Further processing is provided by the “message-processing-model” to prepare it for sending out to the network.

The kind of processing applied to the message depends on the credential type.

Parameters:

message – The original message
security_engine_id – The engine-id of the receiving SNMP engine
credentials – A credential object giving information on what kind of operations are needed on the message.

local_config: Dict[bytes, Dict[str, Any]]: The “Local Configuration Datastore” (LCD). This contains contextual information which may be needed for some security models (as defined by the SNMPv3 architecture.)

process_incoming_message(message: TX690Type, credentials: Credentials) → TPureSNMPType

Takes a message which included potential security modifications (like encryption) and “undoes” these modifications in order to make the message usable again.

Returns an unprocessed message.

The kind of processing applied to the message depends on the credential type.

Parameters:

message – The original message
credentials – A credential object giving information on what kind of operations are needed on the message.

async send_discovery_message(transport_handler: Callable[[bytes], Awaitable[bytes]]) → Any

Send a discovery message to the remote engine.

Parameters:: handler – A callable that is responsible to send data to the remote engine. This callable should already be aware of how to connect. It takes the bytes to be sent to the remote and should return the response bytes without any processing.

set_engine_timing(engine_id: bytes, engine_boots: int, engine_time: int) → None

Update the security model with timing information of the remote-engine.

The timing information is required by SNMPv3 to authenticat/encrypt messages.boots

class puresnmp.plugins.security.TPureSNMPType

The type of an unsecured message inside of “puresnmp”

alias of TypeVar(‘TPureSNMPType’, bound=Any)

class puresnmp.plugins.security.TSecurityPlugin(*args, **kwargs)

Bases: Protocol

Protocol for security plugins

create() → SecurityModel[TPureSNMPType, TX690Type]: Create a new instance of a security model

class puresnmp.plugins.security.TX690Type

The type of a secured message outside of “puresnmp”

alias of TypeVar(‘TX690Type’, bound=Any)

puresnmp.plugins.security.create(identifier: int) → SecurityModel[TPureSNMPType, TX690Type]

Return an instance of the given security module by identifier.

This looks up the module by “IDENTIFIER” as specified in the given plugin.

If no plugin with the given identifier is found, a KeyError is raised

puresnmp.plugins.security.is_valid_sec_plugin(mod: ModuleType) → bool