trishul-smi

A clean, modern SNMP MIB compiler written in Python.

trishul-smi fetches, parses, and compiles SNMP MIB definitions (SMIv1 and SMIv2) into portable JSON (module files plus optional bundle sidecars). 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
• 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
• 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
tsmi compile IF-MIB IP-MIB -f json --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.