Skip to main content
emisar

SNMP (net-snmp)

v0.2.4

Read a network device over SNMP with the net-snmp CLI — system group, interface table, BGP peers (BGP4-MIB) and OSPF neighbors / general group (OSPF-MIB), plus a generic single-OID get and a bounded subtree walk. The routing reads exist to give operators visibility into BGP / OSPF state on devices this control plane can't reach by a native API — e.g. a pfSense + FRR edge firewall, where the REST API exposes no routing-protocol state. All read-only.

7 allowed by default
Pack ID
snmp
Vendor
emisar
OS
linux
Actions
7
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
snmpget snmpbulkwalk

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install snmp --hash sha256:b63c4b702fcfd4669ff8b7387693ea478a997cae6be0053b69b1dddd4dcdee08

Setup

Every action runs a net-snmp client (snmpget / snmpbulkwalk) against the {{ args.host }} you pass, after requiring that exact destination in SNMP_ALLOWED_HOSTS . Install net-snmp on the runner host (Debian: apt-get install snmp), enable SNMP on each target device, and set the credentials below.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • SNMP_ALLOWED_HOSTS required

    Comma-separated exact device hostnames, IP addresses, or host:port destinations that actions may target. Matching is ASCII case-insensitive; entries do not accept wildcards, CIDRs, URLs, or spaces.

  • SNMP_VERSION default 2c

    SNMP version — "1", "2c" (default), or "3". The table reads use GETBULK, so they need 2c or 3. Prefer 3 (authPriv) on any untrusted path: v1/v2c send the community in cleartext on the wire.

  • SNMP_COMMUNITY

    The read-only community string (SNMP v1/v2c). Written to a transient snmp.conf the tool reads via SNMPCONFPATH, so it never appears in the process arguments or the audit log. Use a least-privilege RO community.

  • SNMP_USER

    SNMPv3 security (user) name.

  • SNMP_LEVEL default authPriv

    SNMPv3 security level: noAuthNoPriv, authNoPriv, or authPriv (default).

  • SNMP_AUTH_PROTO default SHA

    SNMPv3 authentication protocol (e.g. SHA, SHA-256, MD5).

  • SNMP_AUTH_PASS

    SNMPv3 authentication passphrase. Streamed via snmp.conf, never in argv.

  • SNMP_PRIV_PROTO default AES

    SNMPv3 privacy (encryption) protocol (e.g. AES, AES-256, DES).

  • SNMP_PRIV_PASS

    SNMPv3 privacy passphrase. Streamed via snmp.conf, never in argv.

Notes

  • SNMP_ALLOWED_HOSTS and any SNMP credentials or protocol settings you set ( SNMP_COMMUNITY , SNMP_USER , SNMP_AUTH_PASS , SNMP_PRIV_PASS , SNMP_VERSION , SNMP_LEVEL , and the protocol choices) must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so a variable present on the host but not inherited is silently dropped and the call is refused or fails authentication.
  • Actions query by NUMERIC OID so they work without MIB files (Debian's snmp package ships none by default — mibs : is commented out). Output is therefore numeric too; each routing action's description maps the columns and decodes the state enums. Install snmp-mibs-downloader on the runner for symbolic names if you prefer.
  • Enable SNMP on the device first. pfSense: Services → SNMP (set an RO community, bind it to the management interface, not WAN). The host arg is the device address; an unreachable device or wrong community fails the action (non-zero exit), it is not reported as empty.
  • BGP4-MIB / OSPF-MIB are not served by the base snmpd — FRR exports them over AgentX. On the firewall/router, enable AgentX in FRR ( agentx in the daemon config) and run bgpd/ospfd with the SNMP module, and set master agentx in snmpd.conf. Without that, bgp_peers / ospf_* return nothing even though SNMP itself works (snmp.system will still answer).
  • This pack only reads. SNMP SET (writes) is intentionally not implemented — community-based SET is a notorious abuse surface, and emisar mutators belong in device-native, auditable packs.

Verify it works

Runs snmp.system, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify snmp

Install and configure a pack walks through the whole sequence on a host.

Actions 7 total

View on GitHub
  • snmp.bgp_peers script low Low — read-only or trivially reversible

    snmpwalk BGP4-MIB bgpPeerTable (1.3.6.1.2.1.15.3)

    List BGP peers from BGP4-MIB bgpPeerTable — per-peer bgpPeerState (.2: 1=idle 2=connect 3=active 4=opensent 5=openconfirm 6=established), bgpPeerAdminStatus (.3: 1=stop 2=start), bgpPeerRemoteAddr (.7), bgpPeerRemoteAs (.9), in/out updates (.10/.11), and bgpPeerFsmEstablishedTime (.16). The right read for "is the BGP session up?" on a router or firewall (e.g. pfSense + FRR) that this control plane can't reach by a native API. Walks 1.3.6.1.2.1.15.3.

    View source on GitHub
  • snmp.get script low Low — read-only or trivially reversible

    snmpget a single OID

    Get a single SNMP object by OID — one snmpget. Use for a specific scalar the curated reads don't cover (e.g. a vendor MIB value). Give a numeric OID like 1.3.6.1.2.1.1.5.0, or a symbolic one (SNMPv2-MIB::sysName.0) if the device's MIBs are installed on the runner.

    View source on GitHub
  • snmp.interfaces script low Low — read-only or trivially reversible

    snmpwalk IF-MIB ifTable (1.3.6.1.2.1.2.2)

    List a device's interfaces from IF-MIB ifTable — per-interface ifDescr (.2), ifType (.3), ifSpeed (.5), ifAdminStatus (.7: 1=up 2=down), ifOperStatus (.8: 1=up 2=down), and in/out octets (.10/.16) and errors (.14/.20). Use to spot a down or errored link. Walks 1.3.6.1.2.1.2.2.

    View source on GitHub
  • snmp.ospf_general script low Low — read-only or trivially reversible

    snmpwalk OSPF-MIB ospfGeneralGroup (1.3.6.1.2.1.14.1)

    Show the OSPF general group from OSPF-MIB — ospfRouterId (.1), ospfAdminStat (.2: 1=enabled 2=disabled), ospfVersionNumber (.3), and the area-border / AS-border router flags (.4/.5). Use to confirm OSPF is enabled and read the router id. Walks 1.3.6.1.2.1.14.1.

    View source on GitHub
  • snmp.ospf_neighbors script low Low — read-only or trivially reversible

    snmpwalk OSPF-MIB ospfNbrTable (1.3.6.1.2.1.14.10)

    List OSPF neighbors from OSPF-MIB ospfNbrTable — per-neighbor ospfNbrIpAddr (.1), ospfNbrRtrId (.3), and ospfNbrState (.6: 1=down 2=attempt 3=init 4=twoWay 5=exchangeStart 6=exchange 7=loading 8=full). A healthy adjacency is 8=full (or 4=twoWay on a DR-other). Use to confirm OSPFv2 adjacencies. Walks 1.3.6.1.2.1.14.10. (OSPFv3 lives in OSPFV3-MIB — use snmp.walk.)

    View source on GitHub
  • snmp.system script low Low — read-only or trivially reversible

    snmpwalk system group (1.3.6.1.2.1.1)

    Show the SNMP system group of a device — sysDescr (model/OS), sysObjectID, sysUpTime, sysContact, sysName, sysLocation. The first stop to confirm SNMP works and identify what the device is. Walks 1.3.6.1.2.1.1.

    View source on GitHub
  • snmp.walk script low Low — read-only or trivially reversible

    snmpwalk an OID subtree

    Walk an SNMP subtree by root OID — one snmpbulkwalk (requires SNMP v2c or v3). Use to read a table or MIB the curated reads don't cover (e.g. OSPFV3-MIB 1.3.6.1.2.1.191, or a vendor table). Output is capped, so a very large subtree is truncated; narrow the root OID. Give a numeric OID, or a symbolic one if the device's MIBs are installed on the runner.

    View source on GitHub
← Back to registry
Pack reference  Publish your own