SNMP Trap Provider is a API that is used to receive trap events from EMS SNMP Agent or any other trap events matching format. It's a linked provider no need to install.

SNMP Trap Provider ¶

How EMS Translate OID with Varbinds to Human-readable Event ¶

SNMP Trap Provider translate the message from SNMP Agent to human readable event by searches OID codebook from Redis firstly, and then search from Git Repo if not found and cache to Redis as key: codebook:{oid} and value: codebook.json file content.

In the repo Stores all event OID severity rule which sets mapping current OID and alert severity and codebooks which are used to translate SNMP trap OID to event name and translate sub varbinds to specific message.

Request API ¶

/alerts/event/snmptrap

Request Method ¶

POST

Request Body ¶

single event

{
    "trap": {
        "fields": {
            "date_time": "2025-07-23 14:44:39.140",
            "source": {
                "host": "10.225.4.133",
                "ip": "10.225.4.133",
                "port": 36560
            },
            "type": "snmpv2trap",
            "version": "3",
            "request_id": 156363869,
            "error_status": 0,
            "error_index": 0,
            "snmp_trap_oid": ".1.3.6.1.6.3.1.1.5.4",
            "security_model": "snmpV3",
            "v3message_id": 1408213830,
            "v3context_name": "",
            "v3context_engine_id": "\ufffd\u0000\u001f\ufffd\ufffdiG\ufffdIׄ\ufffdh\u0000\u0000\u0000\u0000",
            "v3security_level": "AuthPriv",
            "v3security_username": "example_user",
            "v3security_privacy_protocol": "AES",
            "v3security_privacy_passphrase": "example_priv_pass",
            "v3security_authentication_protocol": "SHA",
            "v3security_authentication_passphrase": "example_auth_pass"
        }
    },
    "varbinds": [
        {
            "fields": {
                "oid": ".1.3.6.1.2.1.1.3.0",
                "type": "TimeTicks",
                "value": "(628578507) 72 days, 18:03:05.07"
            }
        },
        {
            "fields": {
                "oid": ".1.3.6.1.6.3.1.1.4.1.0",
                "type": "ObjectIdentifier",
                "value": ".1.3.6.1.6.3.1.1.5.4"
            }
        },
        {
            "fields": {
                "oid": ".1.3.6.1.2.1.2.2.1.7",
                "type": "Integer",
                "value": "0"
            }
        },
        {
            "fields": {
                "oid": ".1.3.6.1.2.1.2.2.1.1",
                "type": "Integer",
                "value": "2"
            }
        }
    ]
}

Body validation - trap.fields.source.host: Event source, required, cannot be empty. - trap.fields.snmp_trap_oid: Event OID, required, cannot be empty. - varbinds: Event detail informations, required, cannot be empty.

Fields:

EMS Field	Request Body Field and Description
name	the name in codebook ({snmp_trap_oid}.codebook.json)
service	trap.fields.source.host
host	trap.fields.source.host
message	host + converted content based on varbinds and codebook (name:value)
status	always firing
severity	"severity" in codebook, "low" by default

bulk events

[
    {
        "trap": {
            "fields": {
                "date_time": "2025-07-23 14:44:39.140",
                "source": {
                    "host": "10.225.4.133",
                    "ip": "10.225.4.133",
                    "port": 36560
                },
                "type": "snmpv2trap",
                "...": "..."
            }
        },
        "varbinds": [
            {
                "fields": {
                    "oid": ".1.3.6.1.2.1.2.2.1.1",
                    "type": "Integer",
                    "value": "2"
                }
            }
        ]
    },
    {
        "trap": {
            "fields": {
                "date_time": "2025-07-23 14:44:39.140",
                "source": {
                    "host": "10.225.4.133",
                    "ip": "10.225.4.133",
                    "port": 36560
                },
                "type": "snmpv2trap",
                "...": "..."
            }
        },
        "varbinds": [
            {
                "fields": {
                    "oid": ".1.3.6.1.2.1.2.2.1.1",
                    "type": "Integer",
                    "value": "2"
                }
            }
        ]
    }
]

Default Deduplicate Rule ¶

trap.fields.source.host + trap.fields.snmp_trap_oid

SNMP Agent ¶

SNMP Agent is a Go program for receiving SNMP traps and forwarding them to EMS Event Management System via SNMP Trap Provider API.
It supports SNMP v1, v2c, and v3. The agent listens on UDP port 162 by default.
SNMP Agent will cache the traps and send out aggregated trpas in 1 min interval incase too many calls to SNMP Trap Provider API.

SNMP Agent Configuration ¶

Configure security parameters:

[root@mttx3etr002 ~]#
  145  2025-05-07 02:36:09 docker ps
  146  2025-08-28 07:57:02 docker exec -it 154c8fbe2d58 bash

[root@mttx3etr002 conf]# cat /opt/webex/ems/service/snmp/conf/snmp_conf.yaml 

...
...
snmp:
  version: "v3"
  listenPort: 162
  securities:
    - username: "xxxx"
      authProtocol: "SHA"
      ems_snmp_auth_passphrase: "xxx"
      privProtocol: "AES"
      ems_snmp_priv_passphrase: "xxx"

ems:
  api: "https://csgems.stage.webex.com/v2/alerts/event/snmptrap"
  username: "X-API-KEY"
  password: "xxxxxxxxx"
  apiTimeout: 5
...
...

Generate coodebook based on MIB file and severity mapping file ¶

Git clone the repo keephq-snmp-mibs to local.
Go to folder /ci.

Run the main.py to generate codebook file.

  python3.11 main.py -m {mib_file_name}

The codebook file will be generated in folder /codebooks with file name: {oid}.codebook.json.

Tips: 1. Make sure you have pysmi and pysnmp lib installed and use python3.10+.
2. When run the script, you may get error: AttributeError: module pysnmp.debug has no attribute setLogger. Did you mean: 'set_logger'?, this is because of local pysnmp version issue, you can modify the view.py line 18 from "debug.setLogger" to "debug.set_logger" to fix it.