python-netgear-switch-library 0.0.post154__py3-none-any.whl

netgear_switch/protocols/snmp/write.py

@@ -0,0 +1,112 @@
+"""Pure SNMP write encoding: SET varbinds and Q-BRIDGE bitmap read-modify-write.
+
+No I/O and transport-agnostic. ``SetVarbind`` carries a net-snmp-style type
+letter (``i`` INTEGER, ``u`` Gauge32/unsigned, ``s`` string, ``x`` hex/octets,
+``a`` IpAddress) that both transports map onto their own SET call. The bitmap
+helpers do a read-modify-write so only the target port's bit changes, leaving
+trunks and other access ports untouched (design spec §6).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ...models import VlanMode
+from .parse import decode_port_bitmap
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from ...registry import SwitchModel
+
+SET_TYPE_LETTERS: frozenset[str] = frozenset({"i", "u", "s", "x", "a"})
+
+
+@dataclass(frozen=True)
+class SetVarbind:
+    """One SNMP SET varbind: full numeric OID, value, and net-snmp type letter."""
+
+    oid: str
+    value: int | str | bytes
+    type_letter: str
+
+    def __post_init__(self) -> None:
+        if self.type_letter not in SET_TYPE_LETTERS:
+            raise ValueError(
+                f"unknown SET type letter {self.type_letter!r}; "
+                f"expected one of {sorted(SET_TYPE_LETTERS)}"
+            )
+
+
+def encode_port_bitmap(ports: Iterable[int], width_bytes: int = 8) -> bytes:
+    """Inverse of ``parse.decode_port_bitmap``: a port set -> a wire bitmap.
+
+    Bit 7 (MSB) of byte 0 is port 1. The buffer grows past ``width_bytes`` if a
+    port number needs it, so callers never pre-size for the actual port count.
+    """
+    data = bytearray(width_bytes)
+    for p in ports:
+        byte_idx, bit = divmod(p - 1, 8)
+        while byte_idx >= len(data):
+            data.append(0)
+        data[byte_idx] |= 0x80 >> bit
+    return bytes(data)
+
+
+def set_port_bit(
+    current: bytes | str, port: int, present: bool, *, width_bytes: int | None = None
+) -> bytes:
+    """Read-modify-write one port's bit in a VLAN bitmap; all others preserved.
+
+    Preserves the input bitmap's byte width to avoid wire-length mismatches on
+    SET for >64-port switches. ``width_bytes``, if given (e.g. a model-derived
+    width from ``vlan_bitmap_width``), is honoured too: the result is at least
+    8 bytes, at least as wide as the input, and at least ``width_bytes`` wide.
+    """
+    # Compute the current bitmap's width in bytes
+    if isinstance(current, bytes):
+        current_width = len(current)
+    else:
+        current_width = len(current.encode("latin-1"))
+
+    ports = set(decode_port_bitmap(current))
+    if present:
+        ports.add(port)
+    else:
+        ports.discard(port)
+    target_width = max(8, current_width, width_bytes or 0)
+    return encode_port_bitmap(ports, width_bytes=target_width)
+
+
+def membership_bitmaps(
+    *,
+    mode: VlanMode,
+    port: int,
+    egress: bytes | str,
+    untagged: bytes | str,
+    width_bytes: int | None = None,
+) -> tuple[bytes, bytes]:
+    """Compute (new_egress, new_untagged) for one port's VLAN membership change.
+
+    UNTAGGED -> egress bit on + untagged bit on; TAGGED -> egress on, untagged
+    off; EXCLUDED -> both off. Read-modify-write on the current bitmaps, so
+    every other port's membership is preserved. ``width_bytes`` is forwarded to
+    ``set_port_bit`` for both columns (see ``vlan_bitmap_width``).
+    """
+    in_egress = mode in (VlanMode.UNTAGGED, VlanMode.TAGGED)
+    in_untagged = mode is VlanMode.UNTAGGED
+    return (
+        set_port_bit(egress, port, in_egress, width_bytes=width_bytes),
+        set_port_bit(untagged, port, in_untagged, width_bytes=width_bytes),
+    )
+
+
+def vlan_bitmap_width(model: SwitchModel) -> int:
+    """Wire byte-width of ``model``'s dot1q VLAN egress/untagged bitmaps.
+
+    ``dot1qVlanStaticEgressPorts``/``UntaggedPorts`` are packed 8 ports/byte,
+    MSB-first (port 1 = bit 7 of byte 0). The Q-BRIDGE MIB's own default
+    PortList width is 8 bytes (64 ports); a model with more ports needs a
+    wider bitmap or the SET's wire length won't match what the device expects.
+    """
+    return max(8, (model.port_count + 7) // 8)

netgear_switch/registry.py

@@ -0,0 +1,227 @@
+"""Declarative registry of known Netgear switch models."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from .errors import UnknownModelError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_FM = "1.3.6.1.4.1.4526.10"   # Fully Managed vendor subtree (M4300, GSM7252PS)
+_SMP = "1.3.6.1.4.1.4526.11"  # Smart Managed Pro vendor subtree (S3300/GSM7228PS)
+
+
+class Backend(enum.Enum):
+    SNMP = "snmp"
+    NSDP = "nsdp"
+    HTTP = "http"
+
+
+class SwitchClass(enum.Enum):
+    FULLY_MANAGED = "fully_managed"
+    SMART_MANAGED_PRO = "smart_managed_pro"
+    PLUS = "plus"
+
+
+@dataclass(frozen=True)
+class SwitchModel:
+    key: str
+    display_name: str
+    switch_class: SwitchClass
+    port_count: int
+    poe_port_count: int
+    backends: frozenset[Backend]
+    snmp_vendor_base: str | None
+    # True (the default) for every model with a real device capture or other
+    # hardware-validated prior art backing its fields. False marks a model
+    # registered from spec sheets/product briefs alone, with NO capture --
+    # its port/PoE counts and (for SNMP models) vendor OID family are a
+    # best-effort guess, and vendor-specific reads (get_sensors, vendor PoE
+    # power, etc.) are UNVERIFIED-pending-capture even though the
+    # model-agnostic standard-MIB/CGI reads should still work. See the
+    # UNVERIFIED-pending-capture entries below (m7300, xs748t, gs728tpp) for
+    # the honesty rationale; do NOT flip this to True without a real capture.
+    verified: bool = True
+
+    @property
+    def has_mac_table(self) -> bool:
+        # MAC/FDB table is only reachable via SNMP (managed switches).
+        return Backend.SNMP in self.backends
+
+
+def _model(
+    key: str,
+    display_name: str,
+    switch_class: SwitchClass,
+    port_count: int,
+    poe_port_count: int,
+    backends: set[Backend],
+    snmp_vendor_base: str | None,
+    *,
+    verified: bool = True,
+) -> SwitchModel:
+    return SwitchModel(
+        key=key,
+        display_name=display_name,
+        switch_class=switch_class,
+        port_count=port_count,
+        poe_port_count=poe_port_count,
+        backends=frozenset(backends),
+        snmp_vendor_base=snmp_vendor_base,
+        verified=verified,
+    )
+
+
+_MODELS: dict[str, SwitchModel] = {
+    m.key: m
+    for m in (
+        _model(
+            "m4300-24x",
+            "M4300-24X (XSM4324CS)",
+            SwitchClass.FULLY_MANAGED,
+            28,
+            0,
+            {Backend.SNMP},
+            _FM,
+        ),
+        _model(
+            "m4300-16x",
+            "M4300-16X (XSM4316)",
+            SwitchClass.FULLY_MANAGED,
+            16,
+            16,
+            {Backend.SNMP},
+            _FM,
+        ),
+        _model(
+            "gsm7252ps",
+            "GSM7252PS",
+            SwitchClass.FULLY_MANAGED,
+            52,
+            48,
+            {Backend.SNMP},
+            _FM,
+        ),
+        _model(
+            "gsm7228ps",
+            "GSM7228PS (S3300)",
+            SwitchClass.SMART_MANAGED_PRO,
+            52,
+            48,
+            {Backend.SNMP, Backend.HTTP},
+            _SMP,
+        ),
+        _model(
+            "gs110emx",
+            "GS110EMX",
+            SwitchClass.PLUS,
+            10,
+            0,
+            {Backend.NSDP, Backend.HTTP},
+            None,
+        ),
+        _model(
+            "gs305ep",
+            "GS305EP",
+            SwitchClass.PLUS,
+            5,
+            4,
+            {Backend.NSDP, Backend.HTTP},
+            None,
+        ),
+        # --- UNVERIFIED-pending-capture below: no device capture exists for
+        # any of these three models (gdoc2netcfg fleet models with no
+        # prior-art fixture). Registered from spec sheets/product briefs only
+        # so gdoc2netcfg can construct a SyncSwitch for them; see each
+        # entry's comment for what specifically is a guess. The
+        # model-agnostic standard-MIB SNMP reads (ports/vlans/lldp/PoE
+        # admin/stats/mgmt-IP) should work regardless of the vendor OID
+        # family guess below, but get_sensors() and vendor PoE-power
+        # readings are UNVERIFIED until a real capture confirms the
+        # 4526.10 vs 4526.11 subtree. Do NOT treat any of these three as a
+        # source of confirmed behaviour -- confirm via hardware
+        # verification before relying on anything beyond the standard MIBs.
+        _model(
+            "m7300",
+            # M7300-24XF (24x SFP+, 0 PoE) picked as the assumed/documented
+            # variant -- the M7300 family also ships non-XF and other port
+            # counts; which exact SKU gdoc2netcfg's fleet actually runs is
+            # UNVERIFIED. Same FASTPATH fully-managed lineage as M4300, so
+            # the 4526.10 ("_FM") vendor subtree is the best spec-guess, but
+            # that family assignment is itself UNVERIFIED-pending-capture.
+            "M7300-24XF",
+            SwitchClass.FULLY_MANAGED,
+            24,
+            0,
+            {Backend.SNMP},
+            _FM,
+            verified=False,
+        ),
+        _model(
+            "xs748t",
+            # XS748T: 48x 10G copper (+ SFP+ combo), non-PoE per the
+            # documented base spec -- UNVERIFIED-pending-capture. HTTP is
+            # plausible for a Smart Managed Pro switch but is deliberately
+            # OMITTED here (not just unverified): see gsm7228ps for the
+            # SNMP+HTTP shape once a login/read flow is actually captured.
+            # Until then SNMP-only avoids implying a web-UI integration that
+            # does not exist in this codebase.
+            "XS748T",
+            SwitchClass.SMART_MANAGED_PRO,
+            48,
+            0,
+            {Backend.SNMP},
+            _SMP,
+            verified=False,
+        ),
+        _model(
+            "gs728tpp",
+            # GS728TPP: 24x Gigabit PoE+ + 4x SFP combo = 28 total ports,
+            # 24 PoE+ -- UNVERIFIED-pending-capture (port split assumed from
+            # the product name's "28" port count and Gigabit PoE+ line
+            # convention, not a capture).
+            #
+            # HTTP backend deliberately OMITTED even though this model's
+            # web UI is real and reachable: certbot-hook-netgear-switches/
+            # netgear-updater.py's GS728TPPUpdater (grounded prior art) shows
+            # GS728TPP uses a THIRD, distinct login scheme -- a GET / redirect
+            # to a per-session path, then GET {path}/System.xml?action=login&
+            # user=...&password=... (not a POST), with userStatus/usernme/
+            # sessionID cookies set from the response rather than via a
+            # normal Set-Cookie login POST. That is neither MERGE_HASH_CGI,
+            # GAMBIT, nor CHEETAH_FORM (registry.protocols.http.endpoints
+            # .LoginScheme), and transport/http/client.py's login() only
+            # knows how to drive those three. Registering Backend.HTTP here
+            # without real scheme/transport support would either (a) fail
+            # tests/protocols/http/test_endpoints.py::
+            # test_every_http_model_has_a_spec, or (b) force picking an
+            # existing (wrong) LoginScheme and have login() attempt a
+            # garbage POST against a real switch -- both dishonest. Wiring
+            # in a real LoginScheme.XML_API is a dedicated future slice, not
+            # a registry-only change. SNMP-only here is sufficient for
+            # gdoc2netcfg's SyncSwitch construction; only the SNMP vendor
+            # OID family is UNVERIFIED-pending-capture.
+            "GS728TPP",
+            SwitchClass.SMART_MANAGED_PRO,
+            28,
+            24,
+            {Backend.SNMP},
+            _SMP,
+            verified=False,
+        ),
+    )
+}
+
+MODELS: Mapping[str, SwitchModel] = MappingProxyType(_MODELS)
+
+
+def get_model(key: str) -> SwitchModel:
+    try:
+        return _MODELS[key]
+    except KeyError:
+        raise UnknownModelError(f"unknown switch model: {key!r}") from None

netgear_switch/snmp_read.py

@@ -0,0 +1,226 @@
+# src/netgear_switch/snmp_read.py
+"""Model-driven SNMP read operations over a sync or async client."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .errors import UnsupportedCapabilityError
+from .models import DetectedModel
+from .protocols.snmp import oids, parse
+from .registry import MODELS, Backend
+
+if TYPE_CHECKING:
+    # Only used in type annotations (return types / parameter types), never
+    # instantiated or referenced at runtime here -- kept behind
+    # TYPE_CHECKING so ruff's TC rules stay clean (see oids.py for the same
+    # pattern).
+    from .models import (
+        LLDPNeighbor,
+        MacEntry,
+        MgmtIpConfig,
+        PoEStatus,
+        PortStats,
+        PortStatus,
+        Sensor,
+        VLANInfo,
+    )
+    from .protocols.snmp.client import AsyncSnmpClient, SnmpClient
+    from .registry import SwitchModel
+
+
+def _require_snmp(model: SwitchModel) -> None:
+    if Backend.SNMP not in model.backends:
+        raise UnsupportedCapabilityError(f"model {model.key!r} has no SNMP backend")
+
+
+def read_system_info(client: SnmpClient) -> DetectedModel:
+    """Identify a switch's model via SNMP sysDescr matching.
+
+    Deliberately NOT a method on ``SnmpReader``: every other read in this
+    module requires a already-known ``SwitchModel`` (``_require_snmp`` gates
+    the reader's construction), but model identification exists precisely
+    for the case where the caller does NOT yet know/trust the model -- so
+    this takes a bare, unbound ``SnmpClient`` instead. See
+    ``protocols.snmp.parse.detect_model_from_sysdescr`` for the honesty-
+    constrained matching rules (never guesses; ``key=None`` means genuinely
+    unidentified -- an unregistered model or a non-Netgear device).
+    """
+    rows = client.get([oids.SYS_DESCR, oids.SYS_OBJECT_ID])
+    sys_descr, sys_object_id = parse.parse_system_info(rows)
+    key = parse.detect_model_from_sysdescr(sys_descr, MODELS)
+    return DetectedModel(key=key, sys_descr=sys_descr, sys_object_id=sys_object_id)
+
+
+async def async_read_system_info(client: AsyncSnmpClient) -> DetectedModel:
+    """Async twin of ``read_system_info`` -- see there."""
+    rows = await client.get([oids.SYS_DESCR, oids.SYS_OBJECT_ID])
+    sys_descr, sys_object_id = parse.parse_system_info(rows)
+    key = parse.detect_model_from_sysdescr(sys_descr, MODELS)
+    return DetectedModel(key=key, sys_descr=sys_descr, sys_object_id=sys_object_id)
+
+
+class SnmpReader:
+    def __init__(self, client: SnmpClient, model: SwitchModel) -> None:
+        # _require_snmp is the single capability gate: it raises for any model
+        # without an SNMP backend (i.e. Plus). Vendor OIDs are resolved lazily,
+        # only in the ops that need the vendor subtree (get_poe/get_sensors/
+        # get_mgmt_ip), so constructing a reader never touches vendor_oids.
+        _require_snmp(model)
+        self.client = client
+        self.model = model
+
+    def get_ports(self) -> list[PortStatus]:
+        w = self.client.walk
+        return parse.parse_port_status(
+            w(oids.IF_ADMIN_STATUS), w(oids.IF_OPER_STATUS),
+            w(oids.IF_HIGH_SPEED), w(oids.IF_NAME), w(oids.IF_ALIAS),
+        )
+
+    def get_stats(self) -> list[PortStats]:
+        w = self.client.walk
+        return parse.parse_port_stats(
+            in_octets=w(oids.IF_HC_IN_OCTETS), out_octets=w(oids.IF_HC_OUT_OCTETS),
+            in_ucast=w(oids.IF_HC_IN_UCAST), out_ucast=w(oids.IF_HC_OUT_UCAST),
+            in_errors=w(oids.IF_IN_ERRORS), out_errors=w(oids.IF_OUT_ERRORS),
+        )
+
+    def get_vlans(self) -> list[VLANInfo]:
+        w = self.client.walk
+        return parse.parse_vlans(
+            w(oids.DOT1Q_VLAN_STATIC_NAME), w(oids.DOT1Q_VLAN_STATIC_EGRESS),
+            w(oids.DOT1Q_VLAN_STATIC_UNTAGGED),
+        )
+
+    def get_pvids(self) -> list[tuple[int, int]]:
+        return parse.parse_pvids(self.client.walk(oids.DOT1Q_PVID))
+
+    def get_lldp(self) -> list[LLDPNeighbor]:
+        return parse.parse_lldp(self.client.walk(oids.LLDP_REM_TABLE))
+
+    def get_macs(self) -> list[MacEntry]:
+        # No has_mac_table guard here: has_mac_table == (Backend.SNMP in
+        # backends), which __init__'s _require_snmp already enforced. (The
+        # registry.has_mac_table property stays for external callers.)
+        w = self.client.walk
+        return parse.parse_macs(
+            w(oids.DOT1Q_TP_FDB_PORT), w(oids.DOT1D_BASE_PORT_IF_INDEX)
+        )
+
+    def get_poe(self) -> list[PoEStatus]:
+        vendor = oids.vendor_oids(self.model)
+        w = self.client.walk
+        return parse.parse_poe(
+            w(oids.PETH_PSE_PORT_TABLE), w(vendor.poe_power_mw)
+        )
+
+    def get_sensors(self) -> list[Sensor]:
+        vendor = oids.vendor_oids(self.model)
+        w = self.client.walk
+        columns = [
+            ("fan", "RPM", w(vendor.box_fan)),
+            ("power", "W", w(vendor.box_psu_power)),
+            ("temperature", "C", w(vendor.box_temp)),
+        ]
+        return parse.parse_box_sensors(columns)
+
+    def get_mgmt_ip(self) -> MgmtIpConfig:
+        vendor = oids.vendor_oids(self.model)
+        w = self.client.walk
+        return parse.parse_mgmt_ip(
+            w(oids.IP_ADENT_ADDR), w(oids.IP_ADENT_NETMASK),
+            w(oids.IP_ROUTE_DEST), w(oids.IP_ROUTE_NEXTHOP),
+            w(vendor.dhcp_mode_unverified),  # single named UNVERIFIED OID (Task 4)
+            w(oids.DOT1D_BASE_BRIDGE_ADDRESS),  # standard BRIDGE-MIB scalar
+        )
+
+    def get_system_info(self) -> DetectedModel:
+        """Identify this switch's model via sysDescr (see ``read_system_info``).
+
+        Reuses this reader's already-connected client. Unlike every other
+        method here, the result does NOT depend on ``self.model`` matching
+        the real device -- useful to confirm/discover a switch's real model
+        via a reader that was (possibly wrongly) constructed against a
+        different model key.
+        """
+        return read_system_info(self.client)
+
+
+class AsyncSnmpReader:
+    def __init__(self, client: AsyncSnmpClient, model: SwitchModel) -> None:
+        # Same contract as SnmpReader: _require_snmp gates construction; vendor
+        # OIDs resolved lazily in get_poe/get_sensors/get_mgmt_ip only.
+        _require_snmp(model)
+        self.client = client
+        self.model = model
+
+    async def get_ports(self) -> list[PortStatus]:
+        w = self.client.walk
+        return parse.parse_port_status(
+            await w(oids.IF_ADMIN_STATUS), await w(oids.IF_OPER_STATUS),
+            await w(oids.IF_HIGH_SPEED), await w(oids.IF_NAME),
+            await w(oids.IF_ALIAS),
+        )
+
+    async def get_stats(self) -> list[PortStats]:
+        w = self.client.walk
+        return parse.parse_port_stats(
+            in_octets=await w(oids.IF_HC_IN_OCTETS),
+            out_octets=await w(oids.IF_HC_OUT_OCTETS),
+            in_ucast=await w(oids.IF_HC_IN_UCAST),
+            out_ucast=await w(oids.IF_HC_OUT_UCAST),
+            in_errors=await w(oids.IF_IN_ERRORS),
+            out_errors=await w(oids.IF_OUT_ERRORS),
+        )
+
+    async def get_vlans(self) -> list[VLANInfo]:
+        w = self.client.walk
+        return parse.parse_vlans(
+            await w(oids.DOT1Q_VLAN_STATIC_NAME),
+            await w(oids.DOT1Q_VLAN_STATIC_EGRESS),
+            await w(oids.DOT1Q_VLAN_STATIC_UNTAGGED),
+        )
+
+    async def get_pvids(self) -> list[tuple[int, int]]:
+        return parse.parse_pvids(await self.client.walk(oids.DOT1Q_PVID))
+
+    async def get_lldp(self) -> list[LLDPNeighbor]:
+        return parse.parse_lldp(await self.client.walk(oids.LLDP_REM_TABLE))
+
+    async def get_macs(self) -> list[MacEntry]:
+        # No has_mac_table guard: _require_snmp in __init__ already enforced it.
+        w = self.client.walk
+        return parse.parse_macs(
+            await w(oids.DOT1Q_TP_FDB_PORT),
+            await w(oids.DOT1D_BASE_PORT_IF_INDEX),
+        )
+
+    async def get_poe(self) -> list[PoEStatus]:
+        vendor = oids.vendor_oids(self.model)
+        w = self.client.walk
+        return parse.parse_poe(
+            await w(oids.PETH_PSE_PORT_TABLE), await w(vendor.poe_power_mw)
+        )
+
+    async def get_sensors(self) -> list[Sensor]:
+        vendor = oids.vendor_oids(self.model)
+        w = self.client.walk
+        columns = [
+            ("fan", "RPM", await w(vendor.box_fan)),
+            ("power", "W", await w(vendor.box_psu_power)),
+            ("temperature", "C", await w(vendor.box_temp)),
+        ]
+        return parse.parse_box_sensors(columns)
+
+    async def get_mgmt_ip(self) -> MgmtIpConfig:
+        vendor = oids.vendor_oids(self.model)
+        w = self.client.walk
+        return parse.parse_mgmt_ip(
+            await w(oids.IP_ADENT_ADDR), await w(oids.IP_ADENT_NETMASK),
+            await w(oids.IP_ROUTE_DEST), await w(oids.IP_ROUTE_NEXTHOP),
+            await w(vendor.dhcp_mode_unverified),  # single named UNVERIFIED OID
+            await w(oids.DOT1D_BASE_BRIDGE_ADDRESS),  # standard BRIDGE-MIB scalar
+        )
+
+    async def get_system_info(self) -> DetectedModel:
+        """Async twin of ``SnmpReader.get_system_info`` -- see there."""
+        return await async_read_system_info(self.client)