trishul-snmp

A modern SNMP runtime, manager, and simulator toolkit written in Python.

trishul-snmp (tsnmp) is a package-first SNMP runtime for manager-side use, notification handling, and narrow simulator-style responder flows. It keeps the protocol runtime independent from MIB compilation and uses compiled JSON artifacts only when symbolic enrichment is desired.

For the canonical tsnmp/tsmi split, tested version pairing, and current ecosystem status, see Ecosystem and Compatibility.

The split with trishul-smi (tsmi) is intentional:

• tsnmp Runtime, transport, manager API, thin CLI, optional enrichment consumer
• tsmi Parser/compiler that produces compiled JSON artifacts

The primary product is the importable Python package. The CLI is intentionally thin and secondary.

Features

• async-first Python API
• SNMPv2c manager runtime
• SNMPv3 USM manager runtime (V3Manager; noAuthNoPriv, authNoPriv, authPriv AES-128)
• read-only operations:
  • get
  • get_next
  • get_bulk
  • walk
  • bulkwalk
• outbound SNMPv2c trap and inform send
• outbound SNMPv3 USM trap and inform send (V3Notifier; traps require UsmLocalEngine)
• inbound SNMPv2c and SNMPv3 USM trap and inform listen (V3NotificationListener handles one configured user)
• offline SNMPv2c and strict SNMPv3 USM notification decode
• narrow read-only SNMPv2c responder / simulator
• simulation rules for dynamic OID values (counters, gauges, uptime, timestamps)
• bundle-backed auto-population of simulator object sets
• in-memory MIB bundle iteration and substring search
• JSON-safe notification event serialization
• in-tree BER / ASN.1 / SNMPv2c + SNMPv3 wire/security codec
• UDP transport and request dispatcher
• optional symbolic translation and display enrichment from compiled JSON MIB artifacts
• works with numeric OIDs and no MIB bundle loaded
• live CLI commands cover SNMPv2c plus SNMPv3 manager, notification send, notification listen, and offline decode

Scope

Current main-branch baseline:

• manager operations plus notification send/listen/decode
• narrow read-only responder / simulator support
• SNMPv2c and SNMPv3 USM (noAuthNoPriv, authNoPriv, authPriv AES-128)
• read-only operations only
• async-first Python API first, CLI second
• optional compiled-JSON enrichment via tsmi artifacts
• no runtime dependency on trishul-smi

Deliberately deferred:

• raw MIB file or raw MIB directory ingestion
• pysnmp API compatibility shims
• direct runtime dependency on the trishul-smi Python package
• sync wrapper
• SNMPv1
• set
• full agent framework
• writable responder support
• compiler workflows inside tsnmp

Installation

pip install trishul-snmp

For SNMPv3 auth/priv support (HMAC and AES-128-CFB encryption):

pip install "trishul-snmp[v3]"

The base package imports without [v3]; only calling auth or priv methods at runtime requires it.

For local development:

pip install -e ".[dev,v3]"

Requires Python >=3.10.

Quick Start

Numeric GET with no bundle:

import asyncio

from trishul_snmp import V2cManager


async def main() -> None:
    async with V2cManager(host="10.0.0.10", community="public") as manager:
        response = await manager.get("1.3.6.1.2.1.1.3.0")
        for varbind in response.varbinds:
            print(varbind.oid_str, varbind.value_type, varbind.display_value)


asyncio.run(main())

Symbolic GET with a compiled JSON bundle:

import asyncio

from trishul_snmp import V2cManager, load_bundle

bundle = load_bundle("./IF-MIB.json")


async def main() -> None:
    async with V2cManager(
        host="10.0.0.10",
        community="public",
        bundle=bundle,
    ) as manager:
        response = await manager.get("IF-MIB::ifDescr.1")
        for varbind in response.varbinds:
            print(varbind.display_name, "=", varbind.display_value)


asyncio.run(main())

SNMPv3 USM GET:

import asyncio

from trishul_snmp import AuthProtocol, UsmUser, V3Manager

user = UsmUser(
    username="monitor",
    auth_protocol=AuthProtocol.SHA256,
    auth_key=b"authpass123",
)


async def main() -> None:
    async with V3Manager(host="10.0.0.10", user=user) as manager:
        response = await manager.get("1.3.6.1.2.1.1.3.0")
        for varbind in response.varbinds:
            print(varbind.oid_str, varbind.value_type, varbind.display_value)


asyncio.run(main())

Current CLI coverage includes SNMPv2c plus SNMPv3 get, getnext, getbulk, walk, bulkwalk, trap, inform, listen, and decode-notification via explicit --snmp-version {2c,3} selection. SNMPv3 listen requires explicit --local-engine-id, --local-engine-boots, and --local-engine-time. SNMPv3 decode-notification requires explicit user/auth/priv inputs.

Documentation

• Documentation Index — entry point for package docs
• Getting Started — install, first requests, and runtime flows
• Ecosystem and Compatibility — tsnmp/tsmi split, tested pairing, bundle inputs, ecosystem status
• Python API — manager, notify, responder, and public runtime types
• CLI Reference — polling, notification, and offline decode commands
• Configuration — manager, notify, responder, and bundle/runtime knobs
• Architecture — layering, package structure, and call flows
• Bundle Contract — compiled JSON inputs, sidecars, validation, scope
• Roadmap — shipped scope and deferred work
• Contributing — dev setup and quality gates
• Changelog — version history
• v0.1.0 Release Notes — archived initial release notes
• v0.1 Design Plan — historical planning and design doc

Repository Layout

• trishul_snmp/ Package source
• tests/ Test suite
• docs/ Application and design documentation
• docs/archive/ Archived planning and historical release notes
• README.md Repository/GitHub landing page

Community

Canonical package docs live under docs/. GitHub/community entry points live under .github/.

• Contributing Guide
• Contributors
• Funding

Development

Checks used in this repo:

python3 -m pytest -q
python3 -m ruff check .
python3 -m ruff format --check trishul_snmp tests
python3 -m mypy

License

MIT — see LICENSE.