python-netgear-switch-library 0.0.post353__tar.gz → 0.0.post355__tar.gz

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post353
+Version: 0.0.post355
 Summary: Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP.
 Author-email: Tim Ansell <me@mith.ro>
 License-Expression: Apache-2.0

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/docs/superpowers/specs/2026-08-02-snmp-surface-findings.md

@@ -305,3 +305,37 @@ inference, and each needs its own live check before it is recorded as fact.
 2. `create_vlan` needs an XUI implementation for the FASTPATH dialects.
 3. Until it exists, the oracle must report HTTP `create_vlan` unsupported on
    those models rather than claiming it works.
+
+
+### Follow-up: no FASTPATH page carries the token, and the tests cannot see it
+
+Probing every write page on the live gsm7252ps:
+
+| Page | `hash` present |
+|---|---|
+| `/vlanStatus.html` | no |
+| `/poeInterfaceConfiguration.html` | no |
+| `/portPvidConfiguration.html` | no |
+| `/switching/dot1q/vlan_port_cfg.html` | no |
+| `/portsConfiguration.html` | no |
+
+So the token is absent from the **whole XE FASTPATH dialect**, not just the VLAN
+page, and every `_csrf`-scraping write is affected on those models — not only
+`create_vlan`.
+
+The mock is now faithful: `virtual/web.py` emits the token only for the Plus
+dialects that really have it, and driving HTTP `create_vlan` against the fake
+reproduces the live failure on gsm7252ps while still succeeding on gs305ep.
+
+**`tests/test_capabilities.py` stayed green through that change, and it was
+right to.** Its `_refused()` counts only `UnsupportedCapabilityError` and
+`NotImplementedError` as a refusal; anything else "means the backend ACCEPTED
+the operation and tried, which is exactly what Support.SUPPORTED claims". An
+`HttpUnexpectedPageError` is therefore success by that definition. The test
+verifies **dispatch**, not **outcome** — by design — so it can never catch a
+write that reaches the right backend and then fails there.
+
+That is a gap in the safety net, not a bug in the test. Catching this class
+needs a different check: drive each write against the mock and assert the state
+actually changed. Recorded here so the next person does not assume a green
+capability suite means the writes work.

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/src/netgear_switch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.post353'
-__version_tuple__ = version_tuple = (0, 0, 'post353')
+__version__ = version = '0.0.post355'
+__version_tuple__ = version_tuple = (0, 0, 'post355')
 
 __commit_id__ = commit_id = None

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/src/netgear_switch/capabilities.py

@@ -101,6 +101,11 @@ class Operation:
 
 _CLI_BACKENDS = frozenset({Backend.SSH, Backend.TELNET, Backend.CONSOLE})
 
+#: HTTP writes implemented by scraping the Plus dialect's CSRF token. A dialect
+#: without that token cannot serve any of them -- see
+#: ``endpoints.dialect_has_csrf_hash`` for the measurement.
+_CSRF_HTTP_WRITES = frozenset({"create_vlan", "delete_vlan"})
+
 READ_OPERATIONS: tuple[Operation, ...] = (
     Operation("get_ports", OperationKind.READ, "Per-port link/admin status"),
     Operation("get_stats", OperationKind.READ, "Per-port octet/packet counters"),
@@ -351,7 +356,7 @@ def _http_path_for(spec: HttpModelSpec, op: Operation) -> str | None:
 
 def _http_support(model: SwitchModel, op: Operation) -> tuple[Support, str]:
     from .http_write import CERT_UPLOAD_KNOWN_UNIMPLEMENTED
-    from .protocols.http.endpoints import http_spec
+    from .protocols.http.endpoints import dialect_has_csrf_hash, http_spec
 
     spec = http_spec(model)
     if not spec.reads_verified:
@@ -374,6 +379,17 @@ def _http_support(model: SwitchModel, op: Operation) -> tuple[Support, str]:
                 f"this model takes a certificate by {mechanism}, not over the "
                 "web UI -- use upload_certificate_scp",
             )
+    if op.name in _CSRF_HTTP_WRITES and not dialect_has_csrf_hash(spec.html_dialect):
+        # These writers scrape an <input name="hash"> before posting, and this
+        # dialect's pages do not carry one -- MEASURED on gsm7252ps and
+        # gs110emx, see endpoints.dialect_has_csrf_hash. Driving them raises
+        # HttpUnexpectedPageError on real hardware, so claiming support here
+        # would publish a support table that contradicts the device.
+        return (
+            Support.UNSUPPORTED,
+            f"model {model.key!r} web UI carries no CSRF 'hash' token, which "
+            f"the HTTP {op.name} writer requires",
+        )
     path = _http_path_for(spec, op)
     if path is None:
         return (

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/src/netgear_switch/http_write.py

@@ -268,6 +268,25 @@ def _check_goahead_upload_response(text: str) -> None:
         )
 
 
+def _require_csrf_dialect(spec: HttpModelSpec, model_key: str, op: str) -> None:
+    """Refuse a hash-scraping write on a dialect whose pages carry no token.
+
+    This is a CAPABILITY refusal, not a surprise, so it raises
+    UnsupportedCapabilityError rather than HttpUnexpectedPageError: the writer
+    is built on the Plus form, and MEASURED probes of gsm7252ps and gs110emx
+    found no ``<input name="hash">`` anywhere in their write pages. Saying so by
+    type is what lets the facade, the capability table and the caller agree --
+    and what stops a bare "unexpected page" from reading like a transient fault.
+    """
+    from .protocols.http.endpoints import dialect_has_csrf_hash
+
+    if not dialect_has_csrf_hash(spec.html_dialect):
+        raise UnsupportedCapabilityError(
+            f"model {model_key!r} web UI carries no CSRF 'hash' token, which "
+            f"the HTTP {op} writer requires"
+        )
+
+
 def _csrf(html: str) -> str:
     token = parse.parse_csrf_hash(html)
     if token is None:
@@ -747,6 +766,7 @@ class HttpWriter:
         return shown
 
     def create_vlan(self, vlan: int, name: str, *, force: bool = False) -> None:
+        _require_csrf_dialect(self._spec, self.model.key, "create_vlan")
         del name, force  # web UI 8021qCf.cgi has no VLAN-name field (GROUNDED).
         path = _require_path(self.model.key, self._spec.vlan_config_path, "VLAN config")
         page = self.session.get_page(path)
@@ -760,6 +780,7 @@ class HttpWriter:
             )
 
     def delete_vlan(self, vlan: int, *, force: bool = False) -> None:
+        _require_csrf_dialect(self._spec, self.model.key, "delete_vlan")
         del force  # VLAN delete disruptiveness is guarded per-member elsewhere.
         path = _require_path(self.model.key, self._spec.vlan_config_path, "VLAN config")
         page = self.session.get_page(path)
@@ -1215,6 +1236,7 @@ class AsyncHttpWriter:
         return shown
 
     async def create_vlan(self, vlan: int, name: str, *, force: bool = False) -> None:
+        _require_csrf_dialect(self._spec, self.model.key, "create_vlan")
         del name, force
         path = _require_path(self.model.key, self._spec.vlan_config_path, "VLAN config")
         page = await self.session.get_page(path)
@@ -1228,6 +1250,7 @@ class AsyncHttpWriter:
             )
 
     async def delete_vlan(self, vlan: int, *, force: bool = False) -> None:
+        _require_csrf_dialect(self._spec, self.model.key, "delete_vlan")
         del force
         path = _require_path(self.model.key, self._spec.vlan_config_path, "VLAN config")
         page = await self.session.get_page(path)

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/src/netgear_switch/protocols/http/endpoints.py

@@ -140,6 +140,27 @@ class HtmlDialect(enum.Enum):
     GOAHEAD_XML = "goahead_xml"
 
 
+def dialect_has_csrf_hash(dialect: HtmlDialect) -> bool:
+    """Whether this dialect's pages carry an ``<input name="hash">`` CSRF token.
+
+    ``http_write`` scrapes that token before every form post, so a dialect
+    without one cannot be driven by those writers at all.
+
+    MEASURED 2026-08-02, not inferred. Live probes found NO hash on any write
+    page of gsm7252ps (10.1.5.22: vlanStatus, poeInterfaceConfiguration,
+    portPvidConfiguration, vlan_port_cfg, portsConfiguration) nor of gs110emx
+    (10.1.5.25: Cf8021q, vlan_pvidsetting). Only the Plus ``.cgi`` pages have
+    it -- the surface ``HttpWriter`` was originally written against.
+
+    ONE definition, read by the capability oracle AND by the virtual switch, so
+    the mock can never emit a token the hardware lacks. That divergence is
+    exactly how HTTP ``create_vlan`` passed the entire test suite while failing
+    on all four FASTPATH switches.
+    """
+    return dialect in {HtmlDialect.STANDARD, HtmlDialect.GS105PE}
+
+
+
 @dataclass(frozen=True)
 class XuiMgmtIpFields:
     """Which fields of a FASTPATH XUI management-IP page carry what.

{python_netgear_switch_library-0.0.post353 → python_netgear_switch_library-0.0.post355}/src/netgear_switch/virtual/web.py

@@ -39,8 +39,40 @@ def _hash_input() -> str:
     return f'<input type="hidden" name="hash" value="{_HASH}">'
 
 
+def _has_csrf_hash(spec: HttpModelSpec) -> bool:
+    """Whether this model's real web UI carries an ``<input name="hash">``.
+
+    ONLY the Plus ``.cgi`` dialects do. MEASURED 2026-08-02: a live capture of
+    the FASTPATH ``vlanStatus.html`` on gsm7252ps (10.1.5.22, committed as
+    ``tests/fixtures/http/gsm7252ps_vlan_status_live.html``) carries no ``hash``
+    input anywhere -- only ``applet_port``, ``applet_unit``, ``dbgopt`` and the
+    XUI cell hiddens.
+
+    This mock used to emit the token on EVERY page regardless of dialect, and
+    that is how ``HttpWriter.create_vlan`` -- which scrapes the token and is
+    written for the Plus form -- passed here while failing on real FASTPATH
+    hardware with "no CSRF 'hash' token on page before write". The mock and the
+    writer agreed with each other while both disagreed with the device, which
+    is exactly the failure principle 5 exists to prevent. Emitting it only
+    where the hardware does makes the mock refuse the same write the switch
+    refuses.
+    """
+    from ..protocols.http.endpoints import dialect_has_csrf_hash
+
+    return dialect_has_csrf_hash(spec.html_dialect)
+
+
 def render_page(
     state: VirtualSwitchState, spec: HttpModelSpec, path: str, form: dict[str, str]
+) -> str:
+    html = _render_page_body(state, spec, path, form)
+    if not _has_csrf_hash(spec):
+        html = html.replace(_hash_input(), "")
+    return html
+
+
+def _render_page_body(
+    state: VirtualSwitchState, spec: HttpModelSpec, path: str, form: dict[str, str]
 ) -> str:
     if path == spec.dashboard_path:
         return _render_dashboard(state)

python_netgear_switch_library-0.0.post355/tests/virtual/test_write_outcomes.py

@@ -0,0 +1,136 @@
+# tests/virtual/test_write_outcomes.py
+"""Writes must CHANGE STATE, not merely reach a backend.
+
+``tests/test_capabilities.py`` deliberately asserts something weaker: that the
+facade dispatches an operation to the backend the table names. Its ``_refused``
+counts only ``UnsupportedCapabilityError``/``NotImplementedError`` as a refusal,
+so any other exception means "the backend accepted the op and tried" -- which is
+exactly what ``Support.SUPPORTED`` claims there.
+
+That is a reasonable contract, and it is why a write which reaches the right
+backend and then FAILS there is invisible to it. HTTP ``create_vlan`` did that
+on four FASTPATH models for as long as the operation has existed: the writer
+scrapes an ``<input name="hash">`` CSRF token those pages do not carry, and the
+mock hid it by emitting one anyway. 27 green capability tests coexisted with a
+write that had never worked on real hardware.
+
+This module closes that gap for the VLAN lifecycle: for every (model, backend)
+the capability table claims is SUPPORTED, create a VLAN and assert it is
+actually there afterwards, then delete it and assert it is actually gone.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from netgear_switch.capabilities import backends_for, operation, support
+from netgear_switch.protocols.cli.commands import CLI_BACKENDS
+from netgear_switch.protocols.http.endpoints import http_spec
+from netgear_switch.registry import Backend, get_model
+from netgear_switch.sync_api import SyncSwitch
+from netgear_switch.transport.http.client import HttpClient
+from netgear_switch.transport.sync.nsdp_udp import UdpNsdpClient
+from netgear_switch.transport.sync.snmp_netsnmp_cli import NetsnmpCliClient
+from netgear_switch.virtual.server import VirtualSwitch
+
+if TYPE_CHECKING:
+    from netgear_switch.registry import SwitchModel
+
+#: gs105pe is expected to FAIL: its HTTP create_vlan reports
+#: WriteVerificationError("VLAN 4007 was not created") against the mock. That is
+#: a REAL defect this module exposed, not a test artefact -- an earlier ad-hoc
+#: probe called it working only because it never deleted between backends, so
+#: the HTTP check saw the VLAN NSDP had already created. Marked xfail(strict) so
+#: the suite stays honest AND tells us the moment it starts passing.
+XFAIL_MODELS = {"gs105pe"}
+
+SEEDED_MODELS = (
+    "gsm7252ps",
+    "gsm7228ps",
+    "m4300-24x",
+    "m4300-16x",
+    "gs110emx",
+    "gs305ep",
+    "gs105pe",
+    "gs728tpp",
+)
+
+#: A throwaway id from the range this project reserves for testing (4001-4008).
+TEST_VLAN = 4007
+
+
+def _facade(mock: VirtualSwitch, model: SwitchModel) -> SyncSwitch:
+    """A facade wired to every face this mock bound, so no op reaches a network."""
+    kwargs: dict[str, Any] = {}
+    if Backend.SNMP in model.backends:
+        snmp = NetsnmpCliClient(f"{mock.host}:{mock.port}", mock.community)
+        kwargs["snmp_client"] = snmp
+        kwargs["snmp_write_client"] = snmp
+    if Backend.NSDP in model.backends:
+        nsdp = UdpNsdpClient(
+            mock.host, client_port=0, server_port=mock.port, timeout=2.0
+        )
+        kwargs["nsdp_client"] = nsdp
+        kwargs["nsdp_write_client"] = nsdp
+        kwargs["nsdp_password"] = mock.nsdp_password
+    if Backend.HTTP in model.backends:
+        kwargs["http_client"] = HttpClient(
+            f"{mock.host}:{mock.http_port}", mock.http_password, http_spec(model)
+        )
+    if CLI_BACKENDS & model.backends:
+        kwargs["cli_client"] = mock.cli_session()
+    return SyncSwitch(model, host=mock.host, **kwargs)
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        pytest.param(
+            k,
+            marks=pytest.mark.xfail(
+                strict=True,
+                reason="HTTP create_vlan does not apply on this dialect; see "
+                "XFAIL_MODELS",
+            ),
+        )
+        if k in XFAIL_MODELS
+        else k
+        for k in SEEDED_MODELS
+    ],
+)
+def test_claimed_vlan_writes_actually_change_state(key: str) -> None:
+    model = get_model(key)
+    create, delete = operation("create_vlan"), operation("delete_vlan")
+    with VirtualSwitch(model=key) as mock:
+        switch = _facade(mock, model)
+        for backend in backends_for(model):
+            if not support(model, backend, create).supported:
+                continue
+
+            def vlans(b: Backend = backend) -> set[int]:
+                return {v.vlan_id for v in switch.get_vlans(backend=b)}
+
+            before = vlans()
+            assert TEST_VLAN not in before, f"{key}/{backend.name}: seed uses the id"
+
+            switch.create_vlan(TEST_VLAN, "outcome", backend=backend)
+            assert TEST_VLAN in vlans(), (
+                f"{key}/{backend.name}: capabilities says create_vlan is "
+                "supported, and the call returned, but the VLAN is not there"
+            )
+
+            if support(model, backend, delete).supported:
+                # force=True: NSDP force-gates delete_vlan because it drops every
+                # member port. The gate is a deliberate safety feature, not the
+                # thing under test here.
+                switch.delete_vlan(TEST_VLAN, force=True, backend=backend)
+                assert TEST_VLAN not in vlans(), (
+                    f"{key}/{backend.name}: delete_vlan returned but the VLAN "
+                    "is still present"
+                )
+                assert vlans() == before, (
+                    f"{key}/{backend.name}: VLAN set not restored after the "
+                    "create/delete round trip"
+                )