trishul-smi

A clean, modern SNMP MIB compiler written in Python.

trishul-smi fetches, parses, and compiles SNMP MIB definitions (SMIv1 and SMIv2) into structured JSON or pysnmp-compatible Python modules. It resolves transitive imports automatically, caches compiled modules on disk, and ships a CLI that works out-of-the-box with no SNMP toolchain required.

Features

• Full import closure — resolves every transitive dependency automatically
• Full OID resolution — all objects carry absolute numeric OID paths after compile
• Two output formats — structured JSON and pysnmp-compatible Python
• Atomic JSON modules + optional sidecars — each module JSON is usable on its own; manifest.json and oid_index.json are additive when enabled via CompilerConfig or the CLI flags --emit-manifest / --emit-oid-index
• Versioned JSON IR metadata — module JSON and optional sidecars carry schema_version, producer_version, generated_by, and generated_at
• Deterministic sidecars — optional manifest.json and oid_index.json describe the final emitted JSON file set, so overlapping alias inputs do not duplicate or self-poison bundle metadata
• Real-world parser compatibility — wrapped inline comment continuations, SNMPv2-PDU compatibility forms, preserved-source SNMPv2-TC variants that import built-in ASN.1 symbols such as OCTET STRING and OBJECT IDENTIFIER, Juniper AGENT-CAPABILITIES clauses with ACCESS not-implemented, and vendor MIBs that use lowercase local type references now compile cleanly through the standard parser path
• Tagged ASN.1 type support — explicit base MIBs such as SNMPv2-SMI compile correctly, including application-tagged types like IpAddress and Counter32
• pysmi-parity pysnmp output — MibTableColumn detection, full TC subtypeSpec, setIndexNames, setOrganization, setRevisions, inline constraint wrappers
• Reverse conversion — tsmi convert FILE.py converts a compiled PySNMP module back to JSON
• Directory compile mode — tsmi compile -d /path/to/mibs auto-discovers and compiles every MIB file
• Concurrent fetching — parallel async HTTP with retry and timeout; parse waves stay deterministic on real MIB corpora
• Pluggable readers — FileReader, HttpReader, ZipReader, composable via ReaderChain
• Disk cache — compiled modules cached with mtime-based TTL; atomic writes
• Cycle detection — Kahn's algorithm with actionable error messages
• SMIv1 + SMIv2 — separate Lark grammars, auto-detected per MIB

Installation

pip install trishul-smi

Requires Python ≥ 3.10.

Quick Start

# Compile from a local MIB directory
tsmi compile IF-MIB --mib-dir /usr/share/snmp/mibs

# Fetch from the internet and compile to JSON + pysnmp
tsmi compile IF-MIB IP-MIB -f json -f pysnmp --online -o ./out

# Emit optional bundle sidecars for downstream JSON consumers
tsmi compile IF-MIB --online --emit-manifest --emit-oid-index -o ./out

Python API:

import asyncio
from pathlib import Path
from trishul_smi.compiler import MibCompiler
from trishul_smi.config import CompilerConfig
from trishul_smi.reader import FileReader, HttpReader

async def main():
    config = CompilerConfig(output_dir=Path("./out"))
    compiler = MibCompiler(config).add_reader(FileReader("/usr/share/snmp/mibs"))
    # optionally add HTTP: async with HttpReader(*config.sources) as http: compiler.add_reader(http)
    results = await compiler.compile("IF-MIB", "IP-MIB")
    for r in results:
        print(r.name, r.status, r.output_paths)

asyncio.run(main())

Each emitted MODULE.json is a valid standalone artifact. For downstream bundle metadata, set emit_manifest=True and/or emit_oid_index=True on CompilerConfig, or use the CLI flags --emit-manifest and --emit-oid-index. When enabled, sidecars describe the final emitted JSON file set for that compile run.

Documentation

• CLI Reference — all commands, options, and output format examples
• Python API — embedding trishul-smi as a library
• Configuration — CompilerConfig fields and defaults
• JSON Bundle Contract — atomic module JSON, optional sidecars, and runtime guarantees
• Architecture — package structure, data flow, design principles
• Roadmap — planned features and known limitations
• Changelog — version history

Repository

• Contributing — dev setup, quality gates, and repo conventions
• Contributors — maintainer and contributor credits
• Release Checklist — maintainer release process

License

MIT — see LICENSE.