fix: traps add engine contextId (#1230)

omrozowicz-splunk · ajasnosz · web-flow · commit 3dff9cdb1cb6 · 2025-08-14T14:43:01.000+02:00
* fix: add decode method security engine ID

* chore: add missing import

* fix: unit tests

* fix: run pre-commit

* fix: update docker env file, docs and changelog

* fix: update method description

---------

Co-authored-by: ajasnosz &lt;ajasnosz@splunk.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@
 - introduce `splunkMetricNameHyphenToUnderscore` parameter to make metric names follow Splunk schema
 - change default walk to get only SNMPv2-MIB
 - add `disableMongoDebugLogging` parameter to disable extensive pymnogo logs while `logLevel` is set to `DEBUG`
+- add `includeSecurityContextId` parameter to control whether to add the `context_engine_id` field to v3 trap events
 
 ### Fixed
 - fix text SNMP values with numbers and 'E' being interpreted as scientific notation
diff --git a/charts/splunk-connect-for-snmp/templates/traps/deployment.yaml b/charts/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -79,6 +79,8 @@ spec:
             {{- end}}
             - name: SPLUNK_HEC_INSECURESSL
               value: {{ .Values.splunk.insecureSSL | default "false" | quote }}
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: {{ .Values.traps.includeSecurityContextId | default "false" | quote }}
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: {{ join "," .Values.traps.securityEngineId }}
             - name: SPLUNK_HEC_TOKEN
diff --git a/charts/splunk-connect-for-snmp/values.schema.json b/charts/splunk-connect-for-snmp/values.schema.json
@@ -746,6 +746,9 @@
         "aggregateTrapsEvents": {
           "type": ["string", "boolean"]
         },
+        "includeSecurityContextId": {
+          "type": ["string", "boolean"]
+        },
         "communities": {
           "type": "object"
         },
diff --git a/charts/splunk-connect-for-snmp/values.yaml b/charts/splunk-connect-for-snmp/values.yaml
@@ -438,6 +438,8 @@ traps:
     - "80003a8c04"
   # aggregateTrapsEvents flag set to true makes traps events collected as one event inside splunk
   aggregateTrapsEvents: "false"
+  # controls whether to add the context_engine_id field to v3 trap events
+  includeSecurityContextId: "false"
 
   # communities define a version of SNMP protocol and SNMP community string, which should be used
   communities: {}
diff --git a/docker_compose/.env b/docker_compose/.env
@@ -94,6 +94,7 @@ SNMP_V3_SECURITY_ENGINE_ID=80003a8c04
 TRAPS_PORT=162
 TRAP_LOG_LEVEL=INFO
 TRAP_DISABLE_MONGO_DEBUG_LOGGING=true
+INCLUDE_SECURITY_CONTEXT_ID=false
 
 # Scheduler configuration
 SCHEDULER_LOG_LEVEL=INFO
diff --git a/docs/dockercompose/6-env-file-configuration.md b/docs/dockercompose/6-env-file-configuration.md
@@ -125,6 +125,7 @@ Inside the directory with the docker compose files, there is a `.env`. Variables
 | Variable                     | Description                                                                                                                                                                                                                     |
 |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
 | `SNMP_V3_SECURITY_ENGINE_ID` | SNMPv3 TRAPs require the configuration SNMP Engine ID of the TRAP sending application for the USM users table of the TRAP receiving application for each USM user, for example: SNMP_V3_SECURITY_ENGINE_ID=80003a8c04,aab123456 |
+| `INCLUDE_SECURITY_CONTEXT_ID` | Controls whether to add the context_engine_id field to v3 trap events                                                                                                                                                           |
 | `TRAPS_PORT`                 | External port exposed for traps server                                                                                                                                                                                          |
 ## Scheduler
 
diff --git a/docs/microk8s/configuration/trap-configuration.md b/docs/microk8s/configuration/trap-configuration.md
@@ -24,6 +24,8 @@ traps:
   logLevel: "WARN"
   # disableMongoDebugLogging is used to disable extensive debug logging for MongoDB+pymongo while logLevel is set to DEBUG.
   disableMongoDebugLogging: true
+  # controls whether to add the context_engine_id field to v3 trap events
+  includeSecurityContextId: false
   # replicas: Number of replicas for trap container should be 2x number of nodes
   replicas: 2
   #loadBalancerIP: The IP address in the metallb pool
diff --git a/docs/microk8s/configuration/values-params-description.md b/docs/microk8s/configuration/values-params-description.md
@@ -164,6 +164,7 @@ Detailed documentation about configuring traps can be found in [Traps](trap-conf
 | `usernameSecrets`                               | Defines SNMPv3 secrets for trap messages sent by SNMP device                                                                    |                  |
 | `securityEngineId`                              | SNMP Engine ID of the TRAP sending application                                                                                  | `80003a8c04`     |
 | `aggregateTrapsEvents`                          | Enables collecting traps events as one event inside Splunk                                                                      | `false`          |
+| `includeSecurityContextId`                      | Controls whether to add the context_engine_id field to v3 trap events                                                           | `false`          |
 | `communities`                                   | Defines a version of SNMP protocol and SNMP community string                                                                    |                  |
 | `service.annotations`                           | Annotations to append under traps service                                                                                       |                  |
 | `service.usemetallb`                            | Enables using metallb                                                                                                           | `true`           |
diff --git a/rendered/manifests/tests/splunk-connect-for-snmp/templates/traps/deployment.yaml b/rendered/manifests/tests/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -68,6 +68,8 @@ spec:
               value: "8088"
             - name: SPLUNK_HEC_INSECURESSL
               value: "true"
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: "false"
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: 80003a8c04
             - name: SPLUNK_HEC_TOKEN
diff --git a/rendered/manifests/tests_autoscaling_enabled/splunk-connect-for-snmp/templates/traps/deployment.yaml b/rendered/manifests/tests_autoscaling_enabled/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -67,6 +67,8 @@ spec:
               value: "8088"
             - name: SPLUNK_HEC_INSECURESSL
               value: "true"
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: "false"
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: 80003a8c04
             - name: SPLUNK_HEC_TOKEN
diff --git a/rendered/manifests/tests_autoscaling_enabled_deprecated/splunk-connect-for-snmp/templates/traps/deployment.yaml b/rendered/manifests/tests_autoscaling_enabled_deprecated/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -67,6 +67,8 @@ spec:
               value: "8088"
             - name: SPLUNK_HEC_INSECURESSL
               value: "true"
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: "false"
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: 80003a8c04
             - name: SPLUNK_HEC_TOKEN
diff --git a/rendered/manifests/tests_enable_ui/splunk-connect-for-snmp/templates/traps/deployment.yaml b/rendered/manifests/tests_enable_ui/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -68,6 +68,8 @@ spec:
               value: "8088"
             - name: SPLUNK_HEC_INSECURESSL
               value: "true"
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: "false"
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: 80003a8c04
             - name: SPLUNK_HEC_TOKEN
diff --git a/rendered/manifests/tests_only_traps/splunk-connect-for-snmp/templates/traps/deployment.yaml b/rendered/manifests/tests_only_traps/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -68,6 +68,8 @@ spec:
               value: "8088"
             - name: SPLUNK_HEC_INSECURESSL
               value: "true"
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: "false"
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: 80003a8c04
             - name: SPLUNK_HEC_TOKEN
diff --git a/rendered/manifests/tests_probes_enabled/splunk-connect-for-snmp/templates/traps/deployment.yaml b/rendered/manifests/tests_probes_enabled/splunk-connect-for-snmp/templates/traps/deployment.yaml
@@ -68,6 +68,8 @@ spec:
               value: "8088"
             - name: SPLUNK_HEC_INSECURESSL
               value: "true"
+            - name: INCLUDE_SECURITY_CONTEXT_ID
+              value: "false"
             - name: SNMP_V3_SECURITY_ENGINE_ID
               value: 80003a8c04
             - name: SPLUNK_HEC_TOKEN
diff --git a/splunk_connect_for_snmp/snmp/tasks.py b/splunk_connect_for_snmp/snmp/tasks.py
@@ -164,8 +164,9 @@ def trap(self, work):
     _, _, result = self.process_snmp_data(varbind_table, metrics, work["host"])
     if human_bool(RESOLVE_TRAP_ADDRESS):
         work["host"] = resolve_address(work["host"])
+    fields = work.get("fields", None)
 
-    return _build_result(result, work["host"])
+    return _build_result(result, work["host"], fields)
 
 
 def _process_work_data(self, work, varbind_table, not_translated_oids):
@@ -222,15 +223,18 @@ def _resolve_remaining_oids(self, remaining_oids, varbind_table):
             logger.warning(f"No translation found for {w[0]}")
 
 
-def _build_result(result, host):
+def _build_result(result, host, fields=None):
     """Build the final result dictionary."""
-    return {
+    result = {
         "time": time.time(),
         "result": result,
         "address": host,
         "detectchange": False,
         "sourcetype": SPLUNK_SOURCETYPE_TRAPS,
     }
+    if fields:
+        result["fields"] = fields
+    return result
 
 
 def format_ipv4_address(host: str) -> str:
diff --git a/splunk_connect_for_snmp/splunk/tasks.py b/splunk_connect_for_snmp/splunk/tasks.py
@@ -283,6 +283,8 @@ def prepare_trap_data(work):
             "host": work["address"],
             "index": SPLUNK_HEC_INDEX_EVENTS,
         }
+        if "fields" in work:
+            event["fields"] = work["fields"]
         events.append(event)
     if SPLUNK_AGGREGATE_TRAPS_EVENTS:
         events = aggregate_traps(events)
diff --git a/splunk_connect_for_snmp/traps.py b/splunk_connect_for_snmp/traps.py
@@ -16,6 +16,9 @@
 import logging
 from contextlib import suppress
 
+from pyasn1.codec.ber import decoder
+from pyasn1.error import PyAsn1Error
+from pyasn1.type import univ
 from pysnmp.proto.api import v2c
 
 from splunk_connect_for_snmp.common.hummanbool import disable_mongo_logging, human_bool
@@ -50,13 +53,17 @@
 SECURITY_ENGINE_ID_LIST = os.getenv("SNMP_V3_SECURITY_ENGINE_ID", "80003a8c04").split(
     ","
 )
+INCLUDE_SECURITY_CONTEXT_ID = human_bool(
+    os.getenv("INCLUDE_SECURITY_CONTEXT_ID", "false")
+)
 IPv6_ENABLED = human_bool(os.getenv("IPv6_ENABLED", "false").lower())
 LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
 PYSNMP_DEBUG = os.getenv("PYSNMP_DEBUG", "")
 DISABLE_MONGO_DEBUG_LOGGING = human_bool(
     os.getenv("DISABLE_MONGO_DEBUG_LOGGING", "true")
 )
 
+# Now create the module logger
 logging.basicConfig(
     format="[%(asctime)s: %(levelname)s/%(name)s] %(message)s",
     level=getattr(logging, LOG_LEVEL),
@@ -99,6 +106,35 @@
 send_task_signature = send.s
 
 
+def decode_security_context(hexstr: bytes) -> str | None:
+    """
+    Decodes SNMPv3 security context from ASN.1 bytes and returns the engineID as a hex string.
+    Sometimes (for example in ERICSSON devices) the engineID is the only place where device IP is stored.
+    """
+    try:
+        decoded_message, _ = decoder.decode(hexstr, asn1Spec=univ.Sequence())
+        msg_version = decoded_message.getComponentByPosition(0)
+        if msg_version._value != 3:
+            logger.warning(
+                "SNMP message version is not 3, skipping security context decoding."
+            )
+            return None
+        msg_security_parameters_raw = decoded_message.getComponentByPosition(
+            2
+        ).asOctets()
+        usm_message, _ = decoder.decode(
+            msg_security_parameters_raw, asn1Spec=univ.Sequence()
+        )
+        usm_engine_id_obj = usm_message.getComponentByPosition(0)
+        usm_engine_id_bytes = usm_engine_id_obj.asOctets()
+        return usm_engine_id_bytes.hex()
+    except PyAsn1Error as e:
+        logger.error(f"ASN.1 decoding error: {e}")
+    except Exception as e:
+        logger.error(f"Error decoding SNMPv3 engineID: {e}")
+    return None
+
+
 # Callback function for receiving notifications
 # noinspection PyUnusedLocal
 def cb_fun(
@@ -108,18 +144,23 @@ def cb_fun(
         'Notification from ContextEngineId "%s", ContextName "%s"'
         % (context_engine_id.prettyPrint(), context_name.prettyPrint())
     )
-
     exec_context = snmp_engine.observer.getExecutionContext(
         "rfc3412.receiveMessage:request"
     )
 
     data = []
     device_ip = exec_context["transportAddress"][0]
 
+    logger.debug("Device IP is %s", device_ip)
+
     for name, val in varbinds:
         data.append((name.prettyPrint(), val.prettyPrint()))
 
     work = {"data": data, "host": device_ip}
+    if INCLUDE_SECURITY_CONTEXT_ID:
+        context_engine_id = decode_security_context(exec_context.get("wholeMsg"))
+        if context_engine_id:
+            work["fields"] = {"context_engine_id": context_engine_id}
     my_chain = chain(
         trap_task_signature(work).set(queue="traps").set(priority=5),
         prepare_task_signature().set(queue="send").set(priority=1),
diff --git a/test/snmp/test_tasks.py b/test/snmp/test_tasks.py
@@ -154,6 +154,48 @@ def test_trap(
             result,
         )
 
+    @patch("pysnmp.smi.rfc1902.ObjectType.resolveWithMib")
+    @patch("splunk_connect_for_snmp.snmp.manager.Poller.process_snmp_data")
+    @patch("splunk_connect_for_snmp.snmp.manager.Poller.__init__")
+    @patch("time.time")
+    def test_trap_with_context_engine_id(
+        self,
+        m_time,
+        m_poller,
+        m_process_data,
+        m_resolved,
+        m_mongo_client,
+    ):
+        m_poller.return_value = None
+        from splunk_connect_for_snmp.snmp.tasks import trap
+
+        m_time.return_value = 1640692955.365186
+
+        m_resolved.return_value = None
+
+        work = {
+            "data": [("asd", "tre")],
+            "host": "192.168.0.1",
+            "fields": {"context_engine_id": "80003a8c04"},
+        }
+        m_process_data.return_value = (False, [], {"test": "value1"})
+        m_poller.builder = MagicMock()
+        m_poller.trap = trap
+        m_poller.trap.mib_view_controller = MagicMock()
+        result = trap(work)
+
+        self.assertEqual(
+            {
+                "address": "192.168.0.1",
+                "detectchange": False,
+                "result": {"test": "value1"},
+                "sourcetype": "sc4snmp:traps",
+                "time": 1640692955.365186,
+                "fields": {"context_engine_id": "80003a8c04"},
+            },
+            result,
+        )
+
     @patch("pysnmp.smi.rfc1902.ObjectType.resolveWithMib")
     @patch("splunk_connect_for_snmp.snmp.manager.Poller.process_snmp_data")
     @patch("splunk_connect_for_snmp.snmp.manager.Poller.is_mib_known")
diff --git a/test/splunk/test_prepare.py b/test/splunk/test_prepare.py
@@ -2,7 +2,11 @@
 from unittest import TestCase
 from unittest.mock import patch
 
-from splunk_connect_for_snmp.splunk.tasks import apply_custom_translations, prepare
+from splunk_connect_for_snmp.splunk.tasks import (
+    apply_custom_translations,
+    prepare,
+    prepare_trap_data,
+)
 
 
 @patch("splunk_connect_for_snmp.splunk.tasks.SPLUNK_HEC_INDEX_EVENTS", "test_index")
@@ -601,3 +605,57 @@ def test_apply_custom_translation(self):
             },
             result,
         )
+
+
+@patch("splunk_connect_for_snmp.splunk.tasks.SPLUNK_SOURCETYPE_TRAPS", "sc4snmp:traps")
+@patch("splunk_connect_for_snmp.splunk.tasks.SPLUNK_HEC_INDEX_EVENTS", "netops")
+class TestPrepareTrapData(TestCase):
+    def test_prepare_trap_data_basic(self):
+        work = {
+            "time": 1640609779.473053,
+            "address": "192.168.0.1",
+            "result": {
+                "GROUP1": {
+                    "metrics": {
+                        "metric_one": {"value": 23},
+                        "metric_two": {"value": 26},
+                    },
+                    "fields": {
+                        "field_one": {"value": "on"},
+                        "field_two": {"value": "listening"},
+                    },
+                }
+            },
+        }
+        events = prepare_trap_data(work)
+        self.assertEqual(len(events), 1)
+        event = json.loads(events[0])
+        self.assertEqual(event["time"], 1640609779.473053)
+        self.assertEqual(event["source"], "sc4snmp")
+        self.assertEqual(event["sourcetype"], "sc4snmp:traps")
+        self.assertEqual(event["host"], "192.168.0.1")
+        self.assertEqual(event["index"], "netops")
+        event_data = json.loads(event["event"])
+        self.assertEqual(event_data["field_one"]["value"], "on")
+        self.assertEqual(event_data["field_two"]["value"], "listening")
+        self.assertEqual(event_data["metric_one"]["value"], 23.0)
+        self.assertEqual(event_data["metric_two"]["value"], 26.0)
+
+    def test_prepare_trap_data_with_extra_fields(self):
+        work = {
+            "time": 1640609779.473053,
+            "address": "192.168.0.1",
+            "fields": {"context_engine_id": "800000c1010a010fc4"},
+            "result": {
+                "GROUP1": {
+                    "metrics": {},
+                    "fields": {
+                        "context_engine_id": "800000c1010a010fc4",
+                    },
+                }
+            },
+        }
+        events = prepare_trap_data(work)
+        event = json.loads(events[0])
+        self.assertIn("fields", event)
+        self.assertEqual(event["fields"], {"context_engine_id": "800000c1010a010fc4"})
diff --git a/test/test_traps.py b/test/test_traps.py
