From 6f9b91ae9b1e0578c86affec8f142dcd519e9537 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Mon, 2 Nov 2026 08:47:46 +0100 Subject: [PATCH] fix(fingerprint): tell a DAL gateway from other Zyxel devices The driver's evidence was all vendor-wide: Zyxel's enterprise OID, Zyxel OUIs and "zyxel" on the web page. Every managed Zyxel device has all three, and they were the driver's whole maximum, so discovery named any Zyxel switch this gateway with high confidence. Discovery now also fetches /getRSAPublickKey on ports 80 and 443, the DAL key exchange the driver logs in with, without counting the port. Its "RSAPublicKey" answer weighs 24: vendor-wide evidence alone is 28 of 52 (medium), a gateway 52 of 52, or 37 of 52 without SNMP. Closes #13 --- CHANGELOG.md | 7 +++ napalm_zyxel/zyxel_driver.py | 24 +++++--- tests/test_fingerprint.py | 109 +++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+), 7 deletions(-) create mode 100644 tests/test_fingerprint.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 574cb1b..2667cc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,13 @@ All notable changes to this driver. The format follows - The HTTP fingerprint no longer counts `gs1920` and `gs2210` as evidence for this driver: they are Zyxel switches, and discovery offered this gateway driver for them (#4). +- Discovery tells a DAL gateway from any other Zyxel device (#13). The Zyxel + enterprise OID, a Zyxel OUI and "zyxel" on the web page fit every Zyxel switch, + firewall or NAS, and together they were this driver's whole maximum score. Discovery + now also fetches `/getRSAPublickKey` on ports 80 and 443 (the key exchange the + driver logs in with, answered without a login), and its `"RSAPublicKey"` answer + weighs 24. Vendor-wide evidence alone comes to 28 of 52, below "high"; a gateway + with SNMP scores 52 of 52, one without SNMP 37 of 52. - Every HTTP request to the gateway carries the driver's `timeout`. It was set on the session, where requests ignores it, so an unresponsive gateway could hang a call indefinitely (#3). diff --git a/napalm_zyxel/zyxel_driver.py b/napalm_zyxel/zyxel_driver.py index 80fb9b6..a3132f3 100644 --- a/napalm_zyxel/zyxel_driver.py +++ b/napalm_zyxel/zyxel_driver.py @@ -21,7 +21,7 @@ from cryptography.hazmat.primitives.asymmetric import padding as asym_padding from cryptography.hazmat.primitives.asymmetric import rsa from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from napalm.base.exceptions import ConnectionClosedException, ConnectionException -from napalm_device_types import FingerprintRule, ResidentialGatewayDriver +from napalm_device_types import FingerprintRule, PortSpec, ResidentialGatewayDriver from napalm_device_types.models import ( HostDict, NATTranslationDict, @@ -95,12 +95,6 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): DRIVER_NAME = "zyxel" SNMP_OBJECT_ID_PREFIX = "1.3.6.1.4.1.890" OUI_PREFIXES = ["00:13:49", "1C:74:0D", "C8:6C:87", "B0:B2:DC", "28:28:5D"] - HTTP_FINGERPRINT = [ - FingerprintRule("zyxel", weight=7.0, mandatory=True), - ] - #: The DAL accepts a PINGTEST request but its answer carries no reply count or - #: round-trip time, so this driver cannot tell an answering host from a silent one. - SUPPORTS_PING = False _LOGIN_PATH = "UserLogin" _LOGOUT_PATH = "cgi-bin/UserLogout" @@ -108,6 +102,22 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): _BASIC_INFO_PATH = "getBasicInformation" _DAL_PATH = "cgi-bin/DAL" + #: Discovery also fetches the DAL's key exchange, which answers without a login + #: (``open()`` needs it). The port answering is no evidence; the answer is (#13). + PORT_SPECS = [ + PortSpec("http", 80, (f"/{_RSA_KEY_PATH}",), weight=0.0), + PortSpec("https", 443, (f"/{_RSA_KEY_PATH}",), weight=0.0), + ] + #: OID, OUI and "zyxel" fit every Zyxel product and stay below "high" together; + #: only a DAL gateway answers with an ``RSAPublicKey`` (#13). + HTTP_FINGERPRINT = [ + FingerprintRule("zyxel", weight=7.0, mandatory=True), + FingerprintRule('"rsapublickey"', weight=24.0), + ] + #: The DAL accepts a PINGTEST request but its answer carries no reply count or + #: round-trip time, so this driver cannot tell an answering host from a silent one. + SUPPORTS_PING = False + def __init__( self, hostname: str, diff --git a/tests/test_fingerprint.py b/tests/test_fingerprint.py new file mode 100644 index 0000000..5af2ee4 --- /dev/null +++ b/tests/test_fingerprint.py @@ -0,0 +1,109 @@ +"""Discovery tells a DAL gateway from any other Zyxel device (#13). + +The driver's evidence was all vendor-wide: Zyxel's enterprise OID, Zyxel OUIs and the +word "zyxel" on the web page. Every managed Zyxel device (switch, firewall, NAS, access +point) has all three, and under discovery's normalisation they made up the driver's +whole maximum: 28 of 28, confidence "high". + +What only a gateway this driver can talk to has is the DAL's key exchange: an +unauthenticated ``GET /getRSAPublickKey`` that answers ``{"RSAPublicKey": ...}``. The +driver cannot log in without it (``ZyxelVMGDriver.open``). + +``_netork_confidence`` mirrors how netOrk scores a driver +(``netork/jobs/tasks/discovery_fingerprint.py``: ``_score_driver``, +``_max_possible_score``, ``norm = score / max``, "high" from 0.7, "medium" from 0.4). +""" + +from __future__ import annotations + +import re + +import pytest +from napalm_device_types import rules_max_weight + +from napalm_zyxel import ZyxelVMGDriver + +#: What netOrk adds for a matching sysObjectID prefix and for a matching OUI. +OID_WEIGHT = 15.0 +OUI_WEIGHT = 6.0 + +ZYXEL_OID = "1.3.6.1.4.1.890.1.5.8.20" +ZYXEL_MAC = "00:13:49:aa:bb:cc" +OTHER_MAC = "00:00:5e:00:53:01" + +SWITCH_PAGE = "ZyXEL GS1920-24HP zyxel web configurator" +#: The gateway's landing page and its answer to ``GET /getRSAPublickKey``, as the +#: probe accumulates them (it fetches every path of a scheme into one body). +GATEWAY_PAGE = ( + "Zyxel VMG4005-B50A zyxel " + '{"RSAPublicKey": "-----BEGIN PUBLIC KEY-----\\nMIIBIjANBgkq...\\n-----END PUBLIC KEY-----\\n"}' +) + + +def _netork_score(cls: type[ZyxelVMGDriver], oid: str | None, mac: str | None, page: str) -> float: + score = 0.0 + if mac and mac[:8].upper() in (p.upper() for p in cls.OUI_PREFIXES): + score += OUI_WEIGHT + if oid: + if not oid.startswith(cls.SNMP_OBJECT_ID_PREFIX): + return 0.0 + score += OID_WEIGHT + combined = re.sub(r"\s+", " ", page.lower()) + for rule in cls.HTTP_FINGERPRINT: + matched = rule.pattern in combined + if rule.mandatory and not matched: + return 0.0 + if matched: + score += -rule.weight if rule.negative else rule.weight + return score + + +def _netork_max(cls: type[ZyxelVMGDriver]) -> float: + total = sum(spec.weight for spec in cls.PORT_SPECS or []) + total += OID_WEIGHT if cls.SNMP_OBJECT_ID_PREFIX else 0.0 + total += OUI_WEIGHT if cls.OUI_PREFIXES else 0.0 + rules = (*cls.SNMP_FINGERPRINT, *cls.SSH_FINGERPRINT, *cls.HTTP_FINGERPRINT) + return total + rules_max_weight(rules) or 1.0 + + +def _netork_confidence(oid: str | None, mac: str | None, page: str) -> tuple[float, str]: + norm = _netork_score(ZyxelVMGDriver, oid, mac, page) / _netork_max(ZyxelVMGDriver) + return norm, "high" if norm >= 0.7 else "medium" if norm >= 0.4 else "low" + + +def test_vendor_wide_evidence_alone_stays_below_high(): + """A Zyxel switch: Zyxel OID, Zyxel OUI, "zyxel" on its page.""" + norm, confidence = _netork_confidence(ZYXEL_OID, ZYXEL_MAC, SWITCH_PAGE) + + assert norm < 0.7 + assert confidence != "high" + + +def test_a_gateway_with_snmp_scores_the_maximum(): + assert _netork_confidence(ZYXEL_OID, ZYXEL_MAC, GATEWAY_PAGE) == (1.0, "high") + + +def test_a_gateway_without_snmp_is_still_high(): + """Residential gateways often answer no SNMP; the DAL answer carries them.""" + assert _netork_confidence(None, ZYXEL_MAC, GATEWAY_PAGE)[1] == "high" + + +def test_the_dal_answer_outweighs_snmp_and_oui_together(): + """A gateway behind a router (no OUI) without SNMP beats a switch with both.""" + gateway, _ = _netork_confidence(None, OTHER_MAC, GATEWAY_PAGE) + switch, _ = _netork_confidence(ZYXEL_OID, ZYXEL_MAC, SWITCH_PAGE) + + assert gateway > switch + + +@pytest.mark.parametrize(("scheme", "port"), [("http", 80), ("https", 443)]) +def test_discovery_fetches_the_dal_key_exchange_without_counting_the_port(scheme, port): + specs = [s for s in ZyxelVMGDriver.PORT_SPECS or [] if (s.scheme, s.port) == (scheme, port)] + + assert [(s.paths, s.weight, s.mandatory) for s in specs] == [ + (("/getRSAPublickKey",), 0.0, False) + ] + + +def test_the_probed_path_is_the_one_the_driver_logs_in_with(): + assert ZyxelVMGDriver._RSA_KEY_PATH == "getRSAPublickKey" -- 2.54.0