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"