From a47f9c39706b1f9230aa9673827cdb8650450162 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Thu, 12 Nov 2026 19:03:40 +0100 Subject: [PATCH] fix(dal): decrypt the DAL's answer before reading it (#25) A GET of the DAL answers sealed ({"content", "iv"}), like a PUT does. _read_dal_or_page parsed the envelope as it came, so hosts, the ARP table, port forwards and the Wi-Fi getters found nothing on every gateway, and since nothing raised the HTML fallback never ran either. Every DAL GET now goes through one helper that decrypts the answer, checks for ZCFG_SUCCESS and returns its Object list; the status page and the System page share the decryption. Hosts are read from lanhosts and port forwards from nat, the names the gateway's web interface uses: LAN_HOSTS and NAT_PORTMAP are answered like any unknown name, with an empty Object. The new parsers live in napalm_zyxel/parsers.py, under strict mypy. Tests seal recorded, anonymised answers of a VMG4005-B50A (V5.17(ABQA.3.1)C0) with a real ZyxelCrypto, so the driver decrypts them. The Wi-Fi DAL names stay unverified: that gateway has no Wi-Fi. Closes #25 --- CHANGELOG.md | 11 + README.md | 9 +- napalm_zyxel/parsers.py | 62 +++++ napalm_zyxel/zyxel_driver.py | 163 +++++-------- .../vmg4005-b50a-ABQA.3.1-LAN_HOSTS.json | 6 + ...005-b50a-ABQA.3.1-getBasicInformation.json | 9 + .../vmg4005-b50a-ABQA.3.1-lanhosts.json | 167 +++++++++++++ tests/fixtures/vmg4005-b50a-ABQA.3.1-nat.json | 6 + tests/gateway.py | 82 +++++++ tests/quality_baseline.json | 4 +- tests/test_dal_reads.py | 229 ++++++++++++++++++ tests/test_failed_reads.py | 18 +- tests/test_zyxel.py | 89 ++----- 13 files changed, 675 insertions(+), 180 deletions(-) create mode 100644 napalm_zyxel/parsers.py create mode 100644 tests/fixtures/vmg4005-b50a-ABQA.3.1-LAN_HOSTS.json create mode 100644 tests/fixtures/vmg4005-b50a-ABQA.3.1-getBasicInformation.json create mode 100644 tests/fixtures/vmg4005-b50a-ABQA.3.1-lanhosts.json create mode 100644 tests/fixtures/vmg4005-b50a-ABQA.3.1-nat.json create mode 100644 tests/gateway.py create mode 100644 tests/test_dal_reads.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ca838b..9f331bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,17 @@ All notable changes to this driver. The format follows 3.12 venv no longer has. ### Fixed +- `get_hosts()`, `get_arp_table()` and `get_port_forwards()` report what the gateway + has (#25). They parsed the DAL's answer without decrypting it, found none of their + keys in the sealed envelope and reported nothing, on every gateway; the Wi-Fi + getters did the same. Every DAL answer is now decrypted and read from its `Object`. + Hosts come from `lanhosts` and port forwards from `nat`, the names the gateway's own + web interface reads them by: the gateway answers the names the driver used + (`LAN_HOSTS`, `NAT_PORTMAP`) like any name it does not know, with nothing. A host + the gateway has no name for (`"Unknown"`) has the host name `""`, a host's + interface type is `LAN` or `WLAN`, only a DHCP host reports the time left on its + lease, a TCP-and-UDP forward is reported once per protocol, and a forward limited + to one source address reports it as `remote_host`. - `get_facts()` reports the gateway's serial number and uptime (#27). It read them from `getBasicInformation`, which a VMG4005-B50A does not send them in, and reported `""` and `0`. They now come from `DeviceInfo` in the DAL's `cardpage_status`, the diff --git a/README.md b/README.md index 0ddb1d1..8d10057 100644 --- a/README.md +++ b/README.md @@ -39,14 +39,19 @@ with driver("192.0.2.1", "admin", "secret", optional_args={"use_tls": True}) as | `get_interfaces`, `get_interfaces_ip` | basic device information (WAN, LAN, Wi-Fi) | | `get_arp_table` | derived from the active LAN hosts | | `get_wan_status` | basic device information | -| `get_hosts` | DAL `LAN_HOSTS`, else the DHCP page | -| `get_port_forwards`, `get_nat_translations` | DAL `NAT_PORTMAP`, else the status page | +| `get_hosts` | DAL `lanhosts`, else the DHCP page | +| `get_port_forwards`, `get_nat_translations` | DAL `nat`, else the status page | | `get_wireless_clients`, `get_ssids`, `get_radio_status` | DAL, else the wireless page | | `get_diagnostics` | DAL `DIAGNOSTICS` | | `is_alive` | the session is open and the web port answers; without a session `False`, no connection | | `reboot_host` | DAL `REBOOT` | | `restart_wifi` | DAL `WIFI_RESTART` | +Every DAL answer is read the way the gateway sends it: AES-encrypted, with its data +under `Object`. The Wi-Fi getters read `WIFI_CLIENTS`, `WIFI_SSIDS` and `WIFI_RADIO`, +names that have not been checked against a gateway with Wi-Fi yet; a VMG4005-B50A +has no Wi-Fi. + ## Not supported Configuration changes (`load_merge_candidate` and `load_replace_candidate` raise diff --git a/napalm_zyxel/parsers.py b/napalm_zyxel/parsers.py new file mode 100644 index 0000000..a54faea --- /dev/null +++ b/napalm_zyxel/parsers.py @@ -0,0 +1,62 @@ +"""Pure parsers: the gateway's decrypted DAL answers in, NAPALM's typed dicts out.""" + +from __future__ import annotations + +from typing import Any + +from napalm_device_types.models import HostDict, PortForwardDict + +#: The name ``lanhosts`` gives a host the gateway has no name for. +_UNKNOWN_HOST = "Unknown" + +#: ``Protocol`` of a ``nat`` rule, as the protocols it forwards. +_FORWARD_PROTOCOLS = {"TCP": ("TCP",), "UDP": ("UDP",), "ALL": ("TCP", "UDP")} + + +def _host(entry: dict[str, Any]) -> HostDict: + """One host of the DAL's ``lanhosts`` answer.""" + name = str(entry.get("HostName") or "") + connection = str(entry.get("X_ZYXEL_ConnectionType") or "") + host: HostDict = { + "mac": str(entry.get("PhysAddress") or "").lower(), + "ip": str(entry.get("IPAddress") or ""), + "hostname": "" if name == _UNKNOWN_HOST else name, + "interface_type": "WLAN" if "Wi-Fi" in connection else "LAN", + "is_active": bool(entry.get("Active")), + } + if entry.get("AddressSource") == "DHCP": + host["lease_time_remaining"] = int(entry.get("LeaseTimeRemaining") or 0) + return host + + +def hosts(objects: list[dict[str, Any]]) -> list[HostDict]: + """The hosts of the DAL's ``lanhosts`` answer (``Object[].lanhosts[]``).""" + return [ + _host(entry) + for obj in objects + for entry in obj.get("lanhosts") or [] + if isinstance(entry, dict) + ] + + +def port_forwards(objects: list[dict[str, Any]]) -> list[PortForwardDict]: + """The rules of the DAL's ``nat`` answer, one per protocol they forward. + + A port range is reported by its first port. + """ + forwards: list[PortForwardDict] = [] + for rule in objects: + protocol = str(rule.get("Protocol") or "").upper() + for proto in _FORWARD_PROTOCOLS.get(protocol, (protocol,)): + forward: PortForwardDict = { + "name": str(rule.get("Description") or ""), + "protocol": proto, + "external_port": int(rule.get("ExternalPortStart") or 0), + "internal_ip": str(rule.get("InternalClient") or ""), + "internal_port": int(rule.get("InternalPortStart") or 0), + "enabled": bool(rule.get("Enable")), + } + if rule.get("SetOriginatingIP") and rule.get("OriginatingIpAddress"): + forward["remote_host"] = str(rule["OriginatingIpAddress"]) + forwards.append(forward) + return forwards diff --git a/napalm_zyxel/zyxel_driver.py b/napalm_zyxel/zyxel_driver.py index 92700d1..eff1988 100644 --- a/napalm_zyxel/zyxel_driver.py +++ b/napalm_zyxel/zyxel_driver.py @@ -36,6 +36,8 @@ from napalm_device_types.models import ( WirelessClientDict, ) +from napalm_zyxel import parsers + logger = logging.getLogger(__name__) #: Answers that mean the session is not (or no longer) accepted. @@ -171,6 +173,10 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): _BASIC_INFO_PATH = "getBasicInformation" _DAL_PATH = "cgi-bin/DAL" _SYSTEM_PATH = "cgi-bin/System?oid=snmp" + _STATUS_OID = "cardpage_status" + #: The DAL names the gateway's own web interface reads hosts and port forwards by. + _HOSTS_OID = "lanhosts" + _NAT_OID = "nat" #: 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). @@ -359,12 +365,46 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): return ConnectionException(detail) return RuntimeError(detail) + def _unseal(self, text: str, what: str) -> Any: + """*text* as JSON, decrypted when the gateway sealed it as ``{"content", "iv"}``. + + A GET of the DAL or the System page answers sealed, like a DAL PUT does (#25). + """ + if self._crypto is None: + raise ConnectionClosedException("Not connected") + try: + answer = json.loads(text) + if isinstance(answer, dict) and {"content", "iv"} <= answer.keys(): + answer = self._crypto.decrypt_response(answer) + except (ValueError, TypeError, KeyError) as exc: + raise RuntimeError(f"{what} on {self._base_url}: {exc}") from exc + return answer + + def _dal_get(self, oid: str) -> list[dict[str, Any]]: + """The ``Object`` list of the DAL's answer to a GET of *oid*, decrypted. + + Raises when the request fails or the gateway does not answer ``ZCFG_SUCCESS`` + with an ``Object`` list. A name the gateway does not know is answered with an + empty ``Object``, like a known one with nothing in it. + """ + what = f"DAL {oid}" + answer = self._unseal(self._fetch_page(f"{self._DAL_PATH}?oid={oid}"), what) + result = answer.get("result") if isinstance(answer, dict) else None + objects = answer.get("Object") if result == "ZCFG_SUCCESS" else None + if not isinstance(objects, list): + raise RuntimeError(f"{what} on {self._base_url} answered {result!r}") + return [obj for obj in objects if isinstance(obj, dict)] + def _read_dal_or_page( - self, oid: str, page: str, parse_dal: Callable[[Any], _T], parse_page: Callable[[str], _T] + self, + oid: str, + page: str, + parse_dal: Callable[[list[dict[str, Any]]], _T], + parse_page: Callable[[str], _T], ) -> _T: """The DAL's answer to *oid*, else the HTML *page*; raises when neither can be read.""" try: - return parse_dal(json.loads(self._fetch_page(f"cgi-bin/DAL?oid={oid}"))) + return parse_dal(self._dal_get(oid)) except (ConnectionException, RuntimeError, ValueError, TypeError) as exc: logger.debug("DAL %s not read (%s), reading %s", oid, exc, page) return parse_page(self._fetch_page(page)) @@ -397,15 +437,7 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): The answer is a one-entry list, sealed ``{"content", "iv"}`` like a DAL answer. """ - text = self._fetch_page(self._SYSTEM_PATH) - if self._crypto is None: - raise ConnectionClosedException("Not connected") - try: - answer = json.loads(text) - if isinstance(answer, dict) and {"content", "iv"} <= answer.keys(): - answer = self._crypto.decrypt_response(answer) - except (ValueError, TypeError, KeyError) as exc: - raise RuntimeError(f"{self._SYSTEM_PATH} on {self._base_url}: {exc}") from exc + answer = self._unseal(self._fetch_page(self._SYSTEM_PATH), self._SYSTEM_PATH) if not isinstance(answer, list) or not answer or not isinstance(answer[0], dict): raise RuntimeError(f"{self._SYSTEM_PATH} on {self._base_url} answered {answer!r}") hostname, domain = ( @@ -414,23 +446,10 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): return hostname, domain def _status_page(self) -> dict[str, Any]: - """The DAL's ``cardpage_status``, decrypted; raises when it cannot be read. - - A GET of the DAL answers sealed, ``{"content", "iv"}``, like the PUT does. - """ - text = self._fetch_page("cgi-bin/DAL?oid=cardpage_status") - if self._crypto is None: - raise ConnectionClosedException("Not connected") - try: - answer = json.loads(text) - if isinstance(answer, dict) and {"content", "iv"} <= answer.keys(): - answer = self._crypto.decrypt_response(answer) - except (ValueError, TypeError, KeyError) as exc: - raise RuntimeError(f"DAL cardpage_status on {self._base_url}: {exc}") from exc - result = answer.get("result") if isinstance(answer, dict) else None - objects = answer.get("Object") if result == "ZCFG_SUCCESS" else None - if not objects or not isinstance(objects[0], dict): - raise RuntimeError(f"DAL cardpage_status on {self._base_url} answered {result!r}") + """The DAL's ``cardpage_status``, decrypted; raises when it cannot be read.""" + objects = self._dal_get(self._STATUS_OID) + if not objects: + raise RuntimeError(f"DAL {self._STATUS_OID} on {self._base_url} answered no object") return objects[0] def get_interfaces(self) -> dict[str, dict[str, Any]]: @@ -626,35 +645,11 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): } def get_port_forwards(self) -> list[PortForwardDict]: - """Return port forwarding rules from DAL or HTML fallback.""" + """The gateway's port forwards (DAL ``nat``), else the status page's.""" return self._read_dal_or_page( - "NAT_PORTMAP", - "Status.htm", - self._parse_port_forwards_dal, - self._parse_port_forwards_html, + self._NAT_OID, "Status.htm", parsers.port_forwards, self._parse_port_forwards_html ) - def _parse_port_forwards_dal(self, data: dict) -> list[PortForwardDict]: - forwards: list[PortForwardDict] = [] - rules = data.get("rules", data.get("NATPortMap", data.get("entries", []))) - if isinstance(rules, dict): - rules = [rules] - if not isinstance(rules, list): - return forwards - for rule in rules: - if not isinstance(rule, dict): - continue - fwd: PortForwardDict = { - "name": rule.get("Description", rule.get("name", "")), - "protocol": rule.get("Protocol", rule.get("protocol", "TCP")), - "external_port": int(rule.get("ExternalPort", rule.get("external_port", 0)) or 0), - "internal_ip": rule.get("InternalIP", rule.get("internal_ip", "")), - "internal_port": int(rule.get("InternalPort", rule.get("internal_port", 0)) or 0), - "enabled": bool(rule.get("Enabled", rule.get("enabled", True))), - } - forwards.append(fwd) - return forwards - _PORT_FORWARD_RE = re.compile( r"(?P[^|]+?)\s*\|\s*(?PTCP|UDP|BOTH)\s*\|\s*" r"(?P\d+)\s*\|\s*(?P[0-9.]+)\s*\|\s*" @@ -678,33 +673,14 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): return forwards def get_hosts(self) -> list[HostDict]: - """Return DHCP host entries from DAL or HTML fallback.""" - return self._read_dal_or_page( - "LAN_HOSTS", "dhcp.htm", self._parse_hosts_dal, self._parse_hosts_html - ) + """The hosts the gateway knows on its LAN (DAL ``lanhosts``), else the DHCP page's. - def _parse_hosts_dal(self, data: dict) -> list[HostDict]: - hosts: list[HostDict] = [] - entries = data.get("hosts", data.get("LANHosts", data.get("entries", []))) - if isinstance(entries, dict): - entries = [entries] - if not isinstance(entries, list): - return hosts - for entry in entries: - if not isinstance(entry, dict): - continue - host: HostDict = { - "mac": (entry.get("MACAddress", entry.get("mac", "")) or "").lower(), - "ip": entry.get("IPAddress", entry.get("ip", "")), - "hostname": entry.get("HostName", entry.get("hostname", "")), - "interface_type": entry.get("InterfaceType", entry.get("interface_type", "lan")), - "is_active": bool(entry.get("Active", entry.get("active", True))), - } - lease = entry.get("LeaseTime", entry.get("lease_time")) - if lease is not None: - host["lease_time_remaining"] = int(lease) - hosts.append(host) - return hosts + A host the gateway has no name for (``"Unknown"``) has ``hostname`` ``""``; only a + host that got its address by DHCP has ``lease_time_remaining``. + """ + return self._read_dal_or_page( + self._HOSTS_OID, "dhcp.htm", parsers.hosts, self._parse_hosts_html + ) _HOST_RE = re.compile( r"(?P[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)" @@ -760,16 +736,11 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): self._parse_wireless_clients_html, ) - def _parse_wireless_clients_dal(self, data: dict) -> list[WirelessClientDict]: + def _parse_wireless_clients_dal( + self, entries: list[dict[str, Any]] + ) -> list[WirelessClientDict]: clients: list[WirelessClientDict] = [] - entries = data.get("clients", data.get("assoc", data.get("entries", []))) - if isinstance(entries, dict): - entries = [entries] - if not isinstance(entries, list): - return clients for entry in entries: - if not isinstance(entry, dict): - continue client: WirelessClientDict = { "mac": (entry.get("MACAddress", entry.get("mac", "")) or "").lower(), "ssid": entry.get("SSID", entry.get("ssid", "")), @@ -818,16 +789,9 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): "WIFI_SSIDS", "wireless.htm", self._parse_ssids_dal, self._parse_ssids_html ) - def _parse_ssids_dal(self, data: dict) -> dict[str, SSIDDict]: + def _parse_ssids_dal(self, entries: list[dict[str, Any]]) -> dict[str, SSIDDict]: ssids: dict[str, SSIDDict] = {} - entries = data.get("ssids", data.get("entries", [])) - if isinstance(entries, dict): - entries = [entries] - if not isinstance(entries, list): - return ssids for entry in entries: - if not isinstance(entry, dict): - continue ssid_name = (entry.get("SSID", entry.get("ssid", "")) or "").strip() if not ssid_name: continue @@ -866,12 +830,9 @@ class ZyxelVMGDriver(ResidentialGatewayDriver): self._parse_radio_status_html, ) - def _parse_radio_status_dal(self, data: dict) -> dict[str, RadioStatusDict]: + def _parse_radio_status_dal(self, entries: list[dict[str, Any]]) -> dict[str, RadioStatusDict]: radios: dict[str, RadioStatusDict] = {} - entries = data.get("radios", data.get("entries", [])) - if isinstance(entries, dict): - entries = [entries] - for entry in entries if isinstance(entries, list) else []: + for entry in entries: name = entry.get("Name", entry.get("name", "")) channel = int(entry.get("Channel", entry.get("channel", 0)) or 0) radios[name] = { diff --git a/tests/fixtures/vmg4005-b50a-ABQA.3.1-LAN_HOSTS.json b/tests/fixtures/vmg4005-b50a-ABQA.3.1-LAN_HOSTS.json new file mode 100644 index 0000000..fad2ba3 --- /dev/null +++ b/tests/fixtures/vmg4005-b50a-ABQA.3.1-LAN_HOSTS.json @@ -0,0 +1,6 @@ +{ + "result": "ZCFG_SUCCESS", + "ReplyMsg": "", + "ReplyMsgMultiLang": "", + "Object": [] +} diff --git a/tests/fixtures/vmg4005-b50a-ABQA.3.1-getBasicInformation.json b/tests/fixtures/vmg4005-b50a-ABQA.3.1-getBasicInformation.json new file mode 100644 index 0000000..a161222 --- /dev/null +++ b/tests/fixtures/vmg4005-b50a-ABQA.3.1-getBasicInformation.json @@ -0,0 +1,9 @@ +{ + "result": "ZCFG_SUCCESS", + "ModelName": "VMG4005-B50A", + "SoftwareVersion": "V5.17(ABQA.3.1)C0", + "CurrentLanguage": "de", + "AvailableLanguages": "en,cz,it,nl,pt,ru,tr,fr,de,es", + "RememberPassword": 0, + "FWUpgradeProgressST": 0 +} diff --git a/tests/fixtures/vmg4005-b50a-ABQA.3.1-lanhosts.json b/tests/fixtures/vmg4005-b50a-ABQA.3.1-lanhosts.json new file mode 100644 index 0000000..ac0746a --- /dev/null +++ b/tests/fixtures/vmg4005-b50a-ABQA.3.1-lanhosts.json @@ -0,0 +1,167 @@ +{ + "result": "ZCFG_SUCCESS", + "ReplyMsg": "DeviceSource", + "ReplyMsgMultiLang": "", + "Object": [ + { + "wanInfo": { + "wanStatus": 0, + "wanIfaceExist": 1, + "wanType": "" + }, + "lanhosts": [ + { + "Alias": "", + "PhysAddress": "02:00:00:00:00:02", + "IPAddress": "192.0.2.2", + "IPAddress6": "", + "IPLinkLocalAddress6": "N/A", + "AddressSource": "Static", + "DHCPClient": "", + "LeaseTimeRemaining": 0, + "AssociatedDevice": "", + "Layer1Interface": "Device.Ethernet.Interface.1", + "Layer3Interface": "Device.IP.Interface.1", + "VendorClassID": "", + "ClientID": "", + "UserClassID": "", + "HostName": "Unknown", + "Active": true, + "X_ZYXEL_DeleteLease": false, + "X_ZYXEL_ConnectionType": "Ethernet", + "X_ZYXEL_ConnectedAP": "", + "X_ZYXEL_HostType": "", + "X_ZYXEL_CapabilityType": "", + "X_ZYXEL_PhyRate": 1000, + "X_ZYXEL_WiFiStatus": false, + "X_ZYXEL_SignalStrength": 0, + "X_ZYXEL_SNR": 0, + "X_ZYXEL_RSSI": 0, + "X_ZYXEL_SoftwareVersion": "", + "X_ZYXEL_LastUpdate": 1769202204, + "X_ZYXEL_Address6Source": "", + "X_ZYXEL_DHCP6Client": "", + "X_ZYXEL_BytesSent": 0, + "X_ZYXEL_BytesReceived": 0, + "X_ZYXEL_OperatingStandard": "", + "X_ZYXEL_LastDataDownlinkRate": 0, + "X_ZYXEL_LastDataUplinkRate": 0, + "IPv4AddressNumberOfEntries": 0, + "IPv6AddressNumberOfEntries": 0, + "ClientDuid": "", + "ExpireTime": "", + "SupportedFrequencyBands": "", + "WiFiname": "", + "DeviceSource": "HOSTS_HOST", + "DeviceIcon": "", + "Internet_Blocking_Enable": false, + "DeviceName": "Unknown", + "curHostName": "", + "dhcp4PoolExist": true, + "dhcp4PoolIid": [ + 1, + 0, + 0, + 0, + 0, + 0 + ], + "dhcp4StaticAddrExist": false, + "dhcp4StaticAddrIid": [ + 0, + 0, + 0, + 0, + 0, + 0 + ], + "dhcp4StaticAddrEnable": false, + "dhcp4StaticAddr": "", + "dhcp4StaticAddrNum": 0, + "dhcp4StaticAddrUsedByOtherHost": false, + "icon": "ipc", + "staticIP": "" + }, + { + "Alias": "", + "PhysAddress": "02:00:00:00:00:03", + "IPAddress": "192.0.2.3", + "IPAddress6": "", + "IPLinkLocalAddress6": "N/A", + "AddressSource": "Static", + "DHCPClient": "", + "LeaseTimeRemaining": 0, + "AssociatedDevice": "", + "Layer1Interface": "", + "Layer3Interface": "Device.IP.Interface.1", + "VendorClassID": "", + "ClientID": "", + "UserClassID": "", + "HostName": "Unknown", + "Active": true, + "X_ZYXEL_DeleteLease": false, + "X_ZYXEL_ConnectionType": "Ethernet", + "X_ZYXEL_ConnectedAP": "", + "X_ZYXEL_HostType": "", + "X_ZYXEL_CapabilityType": "", + "X_ZYXEL_PhyRate": 0, + "X_ZYXEL_WiFiStatus": false, + "X_ZYXEL_SignalStrength": 0, + "X_ZYXEL_SNR": 0, + "X_ZYXEL_RSSI": 0, + "X_ZYXEL_SoftwareVersion": "", + "X_ZYXEL_LastUpdate": 1769202204, + "X_ZYXEL_Address6Source": "", + "X_ZYXEL_DHCP6Client": "", + "X_ZYXEL_BytesSent": 0, + "X_ZYXEL_BytesReceived": 0, + "X_ZYXEL_OperatingStandard": "", + "X_ZYXEL_LastDataDownlinkRate": 0, + "X_ZYXEL_LastDataUplinkRate": 0, + "IPv4AddressNumberOfEntries": 0, + "IPv6AddressNumberOfEntries": 0, + "ClientDuid": "", + "ExpireTime": "", + "SupportedFrequencyBands": "", + "WiFiname": "", + "DeviceSource": "HOSTS_HOST", + "DeviceIcon": "", + "Internet_Blocking_Enable": false, + "DeviceName": "Unknown", + "curHostName": "", + "dhcp4PoolExist": true, + "dhcp4PoolIid": [ + 1, + 0, + 0, + 0, + 0, + 0 + ], + "dhcp4StaticAddrExist": false, + "dhcp4StaticAddrIid": [ + 0, + 0, + 0, + 0, + 0, + 0 + ], + "dhcp4StaticAddrEnable": false, + "dhcp4StaticAddr": "", + "dhcp4StaticAddrNum": 0, + "dhcp4StaticAddrUsedByOtherHost": false, + "icon": "ipc", + "staticIP": "" + } + ], + "STBVendorID": { + "STBVendorID1": "", + "STBVendorID2": "", + "STBVendorID3": "", + "STBVendorID4": "", + "STBVendorID5": "" + } + } + ] +} diff --git a/tests/fixtures/vmg4005-b50a-ABQA.3.1-nat.json b/tests/fixtures/vmg4005-b50a-ABQA.3.1-nat.json new file mode 100644 index 0000000..08e3a9f --- /dev/null +++ b/tests/fixtures/vmg4005-b50a-ABQA.3.1-nat.json @@ -0,0 +1,6 @@ +{ + "result": "ZCFG_SUCCESS", + "ReplyMsg": "InternalClient", + "ReplyMsgMultiLang": "", + "Object": [] +} diff --git a/tests/gateway.py b/tests/gateway.py new file mode 100644 index 0000000..aac5703 --- /dev/null +++ b/tests/gateway.py @@ -0,0 +1,82 @@ +"""A logged-in driver whose gateway answers GETs from recorded fixtures, sealed. + +The fixtures in ``fixtures/`` are a VMG4005-B50A's (firmware V5.17(ABQA.3.1)C0) +answers, anonymised: addresses under 192.0.2.0/24, MAC addresses replaced by +placeholders, the serial number replaced, the provisioning key and PLOAM password +emptied. The gateway seals a DAL answer as ``{"content", "iv"}``; :func:`driver` +seals each fixture with a real :class:`ZyxelCrypto` and the driver's own key, so +what the driver reads has gone through the decryption. +""" + +from __future__ import annotations + +import json +from pathlib import Path +from typing import Any +from unittest.mock import MagicMock + +import requests + +from napalm_zyxel import ZyxelVMGDriver +from napalm_zyxel.zyxel_driver import ZyxelCrypto + +FIXTURES = Path(__file__).parent / "fixtures" +FIRMWARE = "vmg4005-b50a-ABQA.3.1" +AES_KEY = bytes(range(32)) + + +def fixture(name: str) -> Any: + """The recorded answer *name* (``cardpage_status``, ``lanhosts``, ...).""" + return json.loads((FIXTURES / f"{FIRMWARE}-{name}.json").read_text()) + + +def dal(oid: str) -> str: + """The path a DAL GET of *oid* is sent to.""" + return f"cgi-bin/DAL?oid={oid}" + + +def response(status: int, text: str = "") -> requests.Response: + resp = requests.Response() + resp.status_code = status + resp._content = text.encode() + resp.url = "http://192.0.2.1/" + return resp + + +def _crypto() -> ZyxelCrypto: + crypto = ZyxelCrypto() + crypto.aes_key = AES_KEY + return crypto + + +def sealed(answer: Any) -> requests.Response: + """*answer* the way the gateway sends it: AES-encrypted, ``{"content", "iv"}``.""" + envelope = _crypto().encrypt_json(answer) + return response(200, json.dumps({"content": envelope["content"], "iv": envelope["iv"]})) + + +def driver(answers: dict[str, Any]) -> ZyxelVMGDriver: + """A logged-in driver whose gateway answers a GET of each path in *answers*: + a response as it is, anything else sealed. Any other path answers 404.""" + drv = ZyxelVMGDriver("192.0.2.1", "admin", "password") + # NAPALM's __del__ asks is_alive(), which opens a TCP connection: not in a test. + drv.is_alive = lambda: {"is_alive": False} # type: ignore[method-assign] + + def get(url: str, params: dict[str, Any] | None = None, **_: Any) -> requests.Response: + for path, answer in answers.items(): + if url.endswith(f"/{path}"): + return answer if isinstance(answer, requests.Response) else sealed(answer) + return response(404) + + session = MagicMock(spec=requests.Session) + session.get.side_effect = get + drv._session = session + drv._sessionkey = "1" + drv._crypto = _crypto() + drv._device_info = fixture("getBasicInformation") + return drv + + +def requested(drv: ZyxelVMGDriver) -> list[str]: + """The URLs the driver sent a GET to, in order.""" + return [call.args[0] for call in drv._session.get.call_args_list] # type: ignore[union-attr] diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 2206f2a..87b710c 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -1,8 +1,6 @@ { "coverage_floor": 68.0, - "function_complexity": { - "napalm_zyxel/zyxel_driver.py::ZyxelVMGDriver._parse_wireless_clients_dal": 12 - }, + "function_complexity": {}, "function_lines": {}, "mypy_relaxed": [ "napalm_zyxel.zyxel_driver" diff --git a/tests/test_dal_reads.py b/tests/test_dal_reads.py new file mode 100644 index 0000000..a5e557f --- /dev/null +++ b/tests/test_dal_reads.py @@ -0,0 +1,229 @@ +"""A DAL GET is read the way the gateway sends it: sealed, with its data under ``Object`` (#25). + +``_read_dal_or_page`` parsed the answer to ``GET /cgi-bin/DAL?oid=...`` as it came, +but the gateway seals it (``{"content", "iv"}``) like the answer to a PUT. The +parsers found none of their keys in the envelope and reported no hosts, ARP +entries, port forwards, SSIDs, radios or Wi-Fi clients, and since nothing raised, +the HTML fallback never ran either. + +Decrypted, the answer is ``{"result": "ZCFG_SUCCESS", "Object": [...]}``. The host +list is the one the gateway's own web interface reads, ``oid=lanhosts``: the +driver asked for ``LAN_HOSTS``, a name the gateway does not know and answers, like +any unknown name, with an empty ``Object``. Port forwards are ``oid=nat`` (the +driver asked for ``NAT_PORTMAP``). +""" + +from __future__ import annotations + +import copy +import json +from typing import Any + +import pytest +import requests +from napalm.base.exceptions import ConnectionException + +from tests.gateway import dal, driver, fixture, requested, response + +LANHOSTS = fixture("lanhosts") + + +def _with_host(**changes: Any) -> dict[str, Any]: + """The recorded host list, its first host changed by *changes*.""" + answer = copy.deepcopy(LANHOSTS) + answer["Object"][0]["lanhosts"][0].update(changes) + return answer + + +#: A port forward as the gateway's web interface edits it (the rule object its NAT +#: page sends to ``oid=nat``). The recorded gateway is a bridge and has none, so the +#: values are placeholders; the field names are the gateway's. +RULE: dict[str, Any] = { + "Index": 1, + "Enable": True, + "Protocol": "TCP", + "Description": "web", + "Interface": "IP.Interface.3", + "ExternalPortStart": 8443, + "ExternalPortEnd": 8443, + "InternalPortStart": 443, + "InternalPortEnd": 443, + "InternalClient": "192.0.2.3", + "SetOriginatingIP": False, + "OriginatingIpAddress": "", + "OriginatingSubnetMask": "255.255.255.255", + "WANIP": "", + "X_ZYXEL_AutoDetectWanStatus": False, +} + + +def _nat(*rules: dict[str, Any]) -> dict[str, Any]: + return {**fixture("nat"), "Object": list(rules)} + + +# --- the sealed answer ------------------------------------------------------------------ + + +def test_the_sealed_host_list_is_decrypted_and_read(): + hosts = driver({dal("lanhosts"): LANHOSTS}).get_hosts() + assert [(h["mac"], h["ip"]) for h in hosts] == [ + ("02:00:00:00:00:02", "192.0.2.2"), + ("02:00:00:00:00:03", "192.0.2.3"), + ] + + +def test_the_host_list_is_the_one_the_web_interface_reads(): + drv = driver({dal("lanhosts"): LANHOSTS}) + drv.get_hosts() + assert requested(drv) == ["http://192.0.2.1:80/cgi-bin/DAL?oid=lanhosts"] + + +def test_an_unsealed_answer_is_read_as_it_is(): + hosts = driver({dal("lanhosts"): response(200, json.dumps(LANHOSTS))}).get_hosts() + assert len(hosts) == 2 + + +def test_an_answer_the_gateway_refused_falls_back_to_the_page(): + refused = {"result": "ZCFG_NO_SUCH_OBJECT", "Object": []} + page = response(200, "192.0.2.4 02:00:00:00:00:04 tablet") + hosts = driver({dal("lanhosts"): refused, "dhcp.htm": page}).get_hosts() + assert [h["ip"] for h in hosts] == ["192.0.2.4"] + + +def test_an_answer_that_cannot_be_decrypted_falls_back_to_the_page(): + garbled = response( + 200, json.dumps({"content": "bm90IHNlYWxlZA==", "iv": "AAAAAAAAAAAAAAAAAAAAAA=="}) + ) + page = response(200, "192.0.2.4 02:00:00:00:00:04 tablet") + hosts = driver({dal("lanhosts"): garbled, "dhcp.htm": page}).get_hosts() + assert [h["ip"] for h in hosts] == ["192.0.2.4"] + + +def test_a_gateway_with_no_hosts_has_none(): + empty = copy.deepcopy(LANHOSTS) + empty["Object"][0]["lanhosts"] = [] + assert driver({dal("lanhosts"): empty}).get_hosts() == [] + + +# --- the hosts -------------------------------------------------------------------------- + + +def test_a_recorded_host_reads_as_it_is_on_the_gateway(): + host = driver({dal("lanhosts"): LANHOSTS}).get_hosts()[0] + assert host == { + "mac": "02:00:00:00:00:02", + "ip": "192.0.2.2", + "hostname": "", # the gateway says "Unknown" + "interface_type": "LAN", + "is_active": True, + } + + +def test_a_host_name_the_gateway_knows_is_reported(): + hosts = driver({dal("lanhosts"): _with_host(HostName="printer")}).get_hosts() + assert hosts[0]["hostname"] == "printer" + + +def test_a_wifi_host_is_on_the_wlan(): + answer = _with_host(X_ZYXEL_ConnectionType="Wi-Fi 2.4GHz") + assert driver({dal("lanhosts"): answer}).get_hosts()[0]["interface_type"] == "WLAN" + + +def test_only_a_dhcp_host_has_a_lease(): + answer = _with_host(AddressSource="DHCP", LeaseTimeRemaining=3600) + hosts = driver({dal("lanhosts"): answer}).get_hosts() + assert hosts[0]["lease_time_remaining"] == 3600 + assert "lease_time_remaining" not in hosts[1] # AddressSource "Static" + + +def test_an_inactive_host_is_reported_inactive(): + hosts = driver({dal("lanhosts"): _with_host(Active=False)}).get_hosts() + assert hosts[0]["is_active"] is False + + +def test_the_arp_table_holds_the_active_hosts(): + drv = driver({dal("lanhosts"): _with_host(Active=False)}) + assert drv.get_arp_table() == [ + {"interface": "LAN", "mac": "02:00:00:00:00:03", "ip": "192.0.2.3", "age": -1.0} + ] + + +# --- port forwards ---------------------------------------------------------------------- + + +def test_the_recorded_bridge_has_no_port_forwards(): + assert driver({dal("nat"): fixture("nat")}).get_port_forwards() == [] + + +def test_a_port_forward_reads_as_the_gateway_lists_it(): + forwards = driver({dal("nat"): _nat(RULE)}).get_port_forwards() + assert forwards == [ + { + "name": "web", + "protocol": "TCP", + "external_port": 8443, + "internal_ip": "192.0.2.3", + "internal_port": 443, + "enabled": True, + } + ] + + +def test_a_forward_for_tcp_and_udp_is_one_per_protocol(): + forwards = driver({dal("nat"): _nat({**RULE, "Protocol": "ALL"})}).get_port_forwards() + assert [f["protocol"] for f in forwards] == ["TCP", "UDP"] + + +def test_a_disabled_forward_is_reported_disabled(): + forwards = driver({dal("nat"): _nat({**RULE, "Enable": False})}).get_port_forwards() + assert forwards[0]["enabled"] is False + + +def test_a_forward_limited_to_one_source_names_it(): + rule = {**RULE, "SetOriginatingIP": True, "OriginatingIpAddress": "198.51.100.7"} + forwards = driver({dal("nat"): _nat(rule)}).get_port_forwards() + assert forwards[0]["remote_host"] == "198.51.100.7" + + +def test_port_forwards_are_read_from_the_nat_oid(): + drv = driver({dal("nat"): fixture("nat")}) + drv.get_port_forwards() + assert requested(drv) == ["http://192.0.2.1:80/cgi-bin/DAL?oid=nat"] + + +# --- Wi-Fi ------------------------------------------------------------------------------ + + +@pytest.mark.parametrize( + ("getter", "oid", "empty"), + [ + ("get_wireless_clients", "WIFI_CLIENTS", []), + ("get_ssids", "WIFI_SSIDS", {}), + ("get_radio_status", "WIFI_RADIO", {}), + ], +) +def test_a_sealed_wifi_answer_is_decrypted(getter, oid, empty): + """The recorded gateway has no Wi-Fi: it answers these with an empty ``Object``.""" + assert getattr(driver({dal(oid): fixture("LAN_HOSTS")}), getter)() == empty + + +def test_a_wifi_answer_without_object_falls_back_to_the_page(): + answer = {"result": "ZCFG_SUCCESS"} + drv = driver({dal("WIFI_SSIDS"): answer, "wireless.htm": response(200, "")}) + drv.get_ssids() + assert requested(drv)[-1].endswith("/wireless.htm") + + +def test_a_wifi_client_under_object_is_read(): + """Not recorded: the field names are the parser's, not yet checked against a gateway.""" + client = {"MACAddress": "02:00:00:00:00:05", "SSID": "guest", "Signal": -61} + answer = {"result": "ZCFG_SUCCESS", "Object": [client]} + clients = driver({dal("WIFI_CLIENTS"): answer}).get_wireless_clients() + assert [(c["mac"], c["signal"]) for c in clients] == [("02:00:00:00:00:05", -61)] + + +def test_a_failed_request_still_raises(): + drv = driver({dal("lanhosts"): requests.Response()}) + drv._session.get.side_effect = requests.ConnectTimeout("timed out") # type: ignore[union-attr] + with pytest.raises(ConnectionException, match="timed out"): + drv.get_hosts() diff --git a/tests/test_failed_reads.py b/tests/test_failed_reads.py index d973e44..1b32d14 100644 --- a/tests/test_failed_reads.py +++ b/tests/test_failed_reads.py @@ -18,8 +18,9 @@ import requests from napalm.base.exceptions import ConnectionException from napalm_zyxel import ZyxelVMGDriver +from tests.gateway import fixture -HOSTS_DAL = {"hosts": [{"MACAddress": "AA:BB:CC:DD:EE:01", "IPAddress": "192.168.1.33"}]} +HOSTS_DAL = fixture("lanhosts") # tests/gateway.py HOSTS_PAGE = "192.168.1.34 aa:bb:cc:dd:ee:02 tablet" @@ -102,8 +103,8 @@ def test_a_reboot_that_fails_to_reach_the_gateway_raises(): @pytest.mark.parametrize( ("getter", "oid", "page"), [ - ("get_hosts", "LAN_HOSTS", "dhcp.htm"), - ("get_port_forwards", "NAT_PORTMAP", "Status.htm"), + ("get_hosts", "lanhosts", "dhcp.htm"), + ("get_port_forwards", "nat", "Status.htm"), ("get_wireless_clients", "WIFI_CLIENTS", "wireless.htm"), ("get_ssids", "WIFI_SSIDS", "wireless.htm"), ("get_radio_status", "WIFI_RADIO", "wireless.htm"), @@ -118,25 +119,26 @@ def test_a_getter_raises_when_neither_the_dal_nor_the_page_can_be_read(getter, o def test_get_arp_table_raises_when_the_hosts_cannot_be_read(): - driver = _driver({"cgi-bin/DAL?oid=LAN_HOSTS": _response(500), "dhcp.htm": _response(500)}) + driver = _driver({"cgi-bin/DAL?oid=lanhosts": _response(500), "dhcp.htm": _response(500)}) with pytest.raises(RuntimeError): driver.get_arp_table() def test_a_failed_dal_request_falls_back_to_the_page(): driver = _driver( - {"cgi-bin/DAL?oid=LAN_HOSTS": _response(500), "dhcp.htm": _response(200, HOSTS_PAGE)} + {"cgi-bin/DAL?oid=lanhosts": _response(500), "dhcp.htm": _response(200, HOSTS_PAGE)} ) assert [h["ip"] for h in driver.get_hosts()] == ["192.168.1.34"] def test_the_dal_answer_is_used_when_there_is_one(): - driver = _driver({"cgi-bin/DAL?oid=LAN_HOSTS": _response(200, json.dumps(HOSTS_DAL))}) - assert [h["ip"] for h in driver.get_hosts()] == ["192.168.1.33"] + driver = _driver({"cgi-bin/DAL?oid=lanhosts": _response(200, json.dumps(HOSTS_DAL))}) + assert [h["ip"] for h in driver.get_hosts()] == ["192.0.2.2", "192.0.2.3"] def test_a_gateway_that_lists_no_hosts_has_none(): - driver = _driver({"cgi-bin/DAL?oid=LAN_HOSTS": _response(200, '{"hosts": []}')}) + answer = {"result": "ZCFG_SUCCESS", "Object": [{"lanhosts": []}]} + driver = _driver({"cgi-bin/DAL?oid=lanhosts": _response(200, json.dumps(answer))}) assert driver.get_hosts() == [] diff --git a/tests/test_zyxel.py b/tests/test_zyxel.py index cbb15d0..a5caf7a 100644 --- a/tests/test_zyxel.py +++ b/tests/test_zyxel.py @@ -333,61 +333,20 @@ class TestZyxelVMGDriver: with pytest.raises(ConnectionClosedException): self.driver._dal_query("PINGTEST", {}) - def test_parse_port_forwards_dal(self): - self._setup_mocked_http() - data = { - "NATPortMap": [ - { - "Description": "Web Server", - "Protocol": "TCP", - "ExternalPort": 80, - "InternalIP": "192.168.1.10", - "InternalPort": 8080, - "Enabled": True, - } - ] - } - result = self.driver._parse_port_forwards_dal(data) - assert len(result) == 1 - assert result[0]["name"] == "Web Server" - assert result[0]["external_port"] == 80 - assert result[0]["internal_ip"] == "192.168.1.10" - - def test_parse_hosts_dal(self): - self._setup_mocked_http() - data = { - "LANHosts": [ - { - "MACAddress": "aa:bb:cc:dd:ee:ff", - "IPAddress": "192.168.1.100", - "HostName": "laptop", - "InterfaceType": "lan", - "Active": True, - } - ] - } - result = self.driver._parse_hosts_dal(data) - assert len(result) == 1 - assert result[0]["mac"] == "aa:bb:cc:dd:ee:ff" - assert result[0]["ip"] == "192.168.1.100" - assert result[0]["hostname"] == "laptop" - def test_parse_wireless_clients_dal(self): self._setup_mocked_http() - data = { - "assoc": [ - { - "MACAddress": "11:22:33:44:55:66", - "SSID": "MyWiFi", - "Radio": "wlan0", - "Signal": -45, - "TxRate": 300.0, - "RxRate": 150.0, - "Uptime": 3600, - "IPAddress": "192.168.1.50", - } - ] - } + data = [ + { + "MACAddress": "11:22:33:44:55:66", + "SSID": "MyWiFi", + "Radio": "wlan0", + "Signal": -45, + "TxRate": 300.0, + "RxRate": 150.0, + "Uptime": 3600, + "IPAddress": "192.168.1.50", + } + ] result = self.driver._parse_wireless_clients_dal(data) assert len(result) == 1 assert result[0]["mac"] == "11:22:33:44:55:66" @@ -396,19 +355,17 @@ class TestZyxelVMGDriver: def test_parse_ssids_dal(self): self._setup_mocked_http() - data = { - "ssids": [ - { - "SSID": "MyWiFi", - "Radio": "wlan0", - "BSSID": "00:1a:2b:3c:4d:5e", - "Encryption": "WPA2", - "Enabled": True, - "Hidden": False, - "Clients": 3, - } - ] - } + data = [ + { + "SSID": "MyWiFi", + "Radio": "wlan0", + "BSSID": "00:1a:2b:3c:4d:5e", + "Encryption": "WPA2", + "Enabled": True, + "Hidden": False, + "Clients": 3, + } + ] result = self.driver._parse_ssids_dal(data) assert "MyWiFi" in result assert result["MyWiFi"]["encryption"] == "WPA2"