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"