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

netgear_switch/cli/resolve.py

@@ -0,0 +1,108 @@
+"""Resolve the target ``SyncSwitch`` from CLI args (inventory or host+model).
+
+Credential precedence (design spec Sec5.1): CLI flag -> environment variable ->
+config value -> interactive prompt.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from netgear_switch.config import load_inventory
+from netgear_switch.errors import ConfigError
+from netgear_switch.registry import get_model
+from netgear_switch.sync_api import SyncSwitch
+
+if TYPE_CHECKING:
+    import argparse
+    from collections.abc import Callable, Mapping
+
+    from netgear_switch.config import SwitchConfig
+
+
+def _read_community(
+    args: argparse.Namespace,
+    env: Mapping[str, str],
+    config_value: str | None,
+    prompt: Callable[[str], str] | None,
+) -> str | None:
+    if args.community:
+        return str(args.community)
+    if env.get("NGSW_COMMUNITY"):
+        return env["NGSW_COMMUNITY"]
+    if config_value:
+        return config_value
+    if prompt is not None:
+        typed = prompt("SNMP read community: ")
+        # A bare Enter at the prompt must NOT become a literal empty-string
+        # SNMP community; treat it as unresolved so the library's existing
+        # lazy CredentialError fires at SNMP-build time instead. (CLI/env/
+        # config tiers are out of scope here -- separate hardening later.)
+        return typed if typed.strip() else None
+    return None
+
+
+def _write_community_override(
+    args: argparse.Namespace, env: Mapping[str, str]
+) -> str | None:
+    if args.write_community:
+        return str(args.write_community)
+    return env.get("NGSW_WRITE_COMMUNITY")
+
+
+def _from_inventory(
+    args: argparse.Namespace,
+    env: Mapping[str, str],
+    prompt: Callable[[str], str] | None,
+) -> SyncSwitch:
+    if not args.config:
+        raise ConfigError("--switch requires --config <inventory.toml>")
+    inventory = load_inventory(args.config, env=env)
+    try:
+        cfg: SwitchConfig = inventory[args.switch]
+    except KeyError:
+        raise ConfigError(
+            f"switch {args.switch!r} not found in {args.config}"
+        ) from None
+    community = _read_community(args, env, cfg.snmp_community, prompt)
+    write_override = _write_community_override(args, env)
+    return SyncSwitch(
+        cfg.model,
+        cfg.host,
+        snmp_community=community,
+        snmp_write_community=write_override,
+        snmp_write_community_resolver=lambda: cfg.snmp_write_community(env=env),
+        protected_ports=cfg.protected_ports,
+    )
+
+
+def resolve_switch(
+    args: argparse.Namespace,
+    *,
+    env: Mapping[str, str] | None = None,
+    prompt: Callable[[str], str] | None = None,
+) -> SyncSwitch:
+    """Build a ``SyncSwitch`` from ``--config``/``--switch``/``--host``/``--model``.
+
+    Resolution: an inventory lookup (``--switch``, requires ``--config``) wins
+    when given; otherwise ``--host``/``--model`` build a switch directly.
+    Credential precedence for the SNMP read community is CLI flag ->
+    ``NGSW_COMMUNITY`` env var -> inventory config value -> ``prompt`` (if
+    supplied). The write community only ever comes from a CLI flag or
+    ``NGSW_WRITE_COMMUNITY``/inventory spec, resolved lazily by ``SyncSwitch``.
+    """
+    env = os.environ if env is None else env
+    if args.switch:
+        return _from_inventory(args, env, prompt)
+    if args.host and args.model:
+        community = _read_community(args, env, None, prompt)
+        return SyncSwitch(
+            get_model(args.model),
+            args.host,
+            snmp_community=community,
+            snmp_write_community=_write_community_override(args, env),
+        )
+    raise ConfigError(
+        "specify --switch <name> (with --config) or both --host and --model"
+    )

netgear_switch/cli/safety.py

@@ -0,0 +1,71 @@
+"""Write-safety gates for disruptive ngsw commands (design spec §6)."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .context import EXIT_ERROR, EXIT_OK
+
+if TYPE_CHECKING:
+    import argparse
+    from collections.abc import Callable
+
+    from .context import CliContext
+
+
+def add_write_args(parser: argparse.ArgumentParser) -> None:
+    """Attach the shared --dry-run / --yes / --force gates to a subparser."""
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print the operation that would be sent, then send nothing",
+    )
+    parser.add_argument(
+        "-y", "--yes", action="store_true", help="skip the confirmation prompt"
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="override protected_ports and other force-gates",
+    )
+
+
+def confirm(prompt: str, *, assume_yes: bool, ctx: CliContext) -> bool:
+    """Ask for confirmation on stderr; read one line from ctx.inp."""
+    if assume_yes:
+        return True
+    print(f"{prompt} [y/N]: ", end="", file=ctx.err)
+    ctx.err.flush()
+    reply = ctx.inp.readline().strip().lower()
+    return reply in {"y", "yes"}
+
+
+def do_write(
+    ctx: CliContext,
+    *,
+    dry_run: bool,
+    assume_yes: bool,
+    host: str,
+    description: str,
+    action: Callable[[], None],
+    warning: str | None = None,
+) -> int:
+    """The single disruptive-write gate: dry-run -> confirm -> execute -> report.
+
+    ``action`` is the verify-after-write facade call; any NetgearSwitchError it
+    raises propagates to main() for clean reporting. The CLI describes the
+    operation at facade granularity (method + args + host) rather than
+    re-encoding the SNMP SET / NSDP packet / HTTP form, so no library logic is
+    duplicated here.
+    """
+    if dry_run:
+        print(f"DRY-RUN: would {description} on {host} (nothing sent)", file=ctx.out)
+        return EXIT_OK
+    prompt = f"About to {description} on {host}."
+    if warning:
+        prompt = f"{warning}\n{prompt}"
+    if not confirm(prompt, assume_yes=assume_yes, ctx=ctx):
+        print("aborted: no changes made", file=ctx.err)
+        return EXIT_ERROR
+    action()
+    print(f"ok: {description}", file=ctx.out)
+    return EXIT_OK

netgear_switch/config.py

@@ -0,0 +1,184 @@
+"""TOML inventory loading and credential resolution."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import tomllib
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .errors import ConfigError, CredentialError
+from .registry import SwitchModel, get_model
+
+if TYPE_CHECKING:
+    from typing import TypeGuard
+
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+_SECRET_COMMAND_TIMEOUT = 10
+
+
+def resolve_secret(
+    spec: str | None,
+    *,
+    env: Mapping[str, str],
+    runner: Runner = subprocess.run,
+) -> str | None:
+    """Resolve one secret spec to its value (or None)."""
+    if spec is None:
+        return None
+    if spec.startswith("${") and spec.endswith("}"):
+        name = spec[2:-1]
+        try:
+            return env[name]
+        except KeyError:
+            raise CredentialError(f"environment variable {name!r} is not set") from None
+    if spec.startswith("!"):
+        args = shlex.split(spec[1:])
+        if not args:
+            raise CredentialError("empty command in secret spec")
+        try:
+            result = runner(
+                args, capture_output=True, text=True, timeout=_SECRET_COMMAND_TIMEOUT
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise CredentialError(
+                f"secret command {args!r} could not be run: {exc}"
+            ) from exc
+        if result.returncode != 0:
+            raise CredentialError(
+                f"secret command {args!r} failed "
+                f"(exit {result.returncode}): {result.stderr.strip()}"
+            )
+        return result.stdout.strip()
+    return spec
+
+
+def _is_literal(spec: str | None) -> TypeGuard[str]:
+    if spec is None:
+        return False
+    return not (spec.startswith("${") and spec.endswith("}")) and not spec.startswith(
+        "!"
+    )
+
+
+def ensure_secure_file(path: os.PathLike[str] | str) -> None:
+    """Raise if the file is readable/writable by group or other."""
+    mode = os.stat(path).st_mode
+    if mode & 0o077:
+        raise ConfigError(
+            f"{os.fspath(path)} has insecure permissions {oct(mode & 0o777)}; "
+            "chmod 600 it (contains a literal secret)"
+        )
+
+
+@dataclass(frozen=True)
+class SwitchConfig:
+    name: str
+    model: SwitchModel
+    host: str
+    snmp_community: str | None
+    snmp_write_community_spec: str | None
+    http_password_spec: str | None
+    nsdp_interface: str | None
+    protected_ports: frozenset[int]
+
+    def snmp_write_community(
+        self, *, env: Mapping[str, str], runner: Runner = subprocess.run
+    ) -> str | None:
+        return resolve_secret(self.snmp_write_community_spec, env=env, runner=runner)
+
+    def http_password(
+        self, *, env: Mapping[str, str], runner: Runner = subprocess.run
+    ) -> str | None:
+        return resolve_secret(self.http_password_spec, env=env, runner=runner)
+
+
+def _switch_from_table(
+    name: str, table: Mapping[str, object]
+) -> tuple[SwitchConfig, list[str]]:
+    try:
+        model_key = table["model"]
+        host = table["host"]
+    except KeyError as exc:
+        raise ConfigError(
+            f"switch {name!r} is missing required key {exc.args[0]!r}"
+        ) from None
+    if not isinstance(model_key, str) or not isinstance(host, str):
+        raise ConfigError(f"switch {name!r}: 'model' and 'host' must be strings")
+
+    snmp = table.get("snmp", {})
+    http = table.get("http", {})
+    nsdp = table.get("nsdp", {})
+    if (
+        not isinstance(snmp, Mapping)
+        or not isinstance(http, Mapping)
+        or not isinstance(nsdp, Mapping)
+    ):
+        raise ConfigError(f"switch {name!r}: snmp/http/nsdp must be tables")
+
+    ports = table.get("protected_ports", [])
+    if not isinstance(ports, list) or not all(
+        isinstance(p, int) and not isinstance(p, bool) for p in ports
+    ):
+        raise ConfigError(f"switch {name!r}: protected_ports must be a list of ints")
+
+    for label, value in (
+        ("snmp.community", snmp.get("community")),
+        ("snmp.write_community", snmp.get("write_community")),
+        ("http.password", http.get("password")),
+        ("nsdp.interface", nsdp.get("interface")),
+    ):
+        if value is not None and not isinstance(value, str):
+            raise ConfigError(f"switch {name!r}: {label} must be a string")
+
+    secret_specs = [
+        snmp.get("write_community"),
+        http.get("password"),
+    ]
+    literals = [s for s in secret_specs if _is_literal(s)]
+
+    cfg = SwitchConfig(
+        name=name,
+        model=get_model(model_key),
+        host=host,
+        snmp_community=snmp.get("community"),
+        snmp_write_community_spec=snmp.get("write_community"),
+        http_password_spec=http.get("password"),
+        nsdp_interface=nsdp.get("interface"),
+        protected_ports=frozenset(ports),
+    )
+    return cfg, literals
+
+
+def load_inventory(
+    path: os.PathLike[str] | str,
+    *,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, SwitchConfig]:
+    """Load a TOML inventory into a {name: SwitchConfig} dict."""
+    if env is None:
+        env = os.environ
+    with open(path, "rb") as fh:
+        data = tomllib.load(fh)
+
+    switches = data.get("switches", {})
+    if not isinstance(switches, Mapping):
+        raise ConfigError("top-level [switches] must be a table")
+
+    result: dict[str, SwitchConfig] = {}
+    any_literal = False
+    for name, table in switches.items():
+        if not isinstance(table, Mapping):
+            raise ConfigError(f"[switches.{name}] must be a table")
+        cfg, literals = _switch_from_table(name, table)
+        if literals:
+            any_literal = True
+        result[name] = cfg
+
+    if any_literal:
+        ensure_secure_file(path)
+    return result

netgear_switch/errors.py

@@ -0,0 +1,52 @@
+"""Exception hierarchy for netgear_switch."""
+
+from __future__ import annotations
+
+
+class NetgearSwitchError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ConfigError(NetgearSwitchError):
+    """The inventory/config file is malformed or invalid."""
+
+
+class CredentialError(NetgearSwitchError):
+    """A required secret could not be resolved from any source."""
+
+
+class UnknownModelError(NetgearSwitchError):
+    """A switch references a model key that is not in the registry."""
+
+
+class UnsupportedCapabilityError(NetgearSwitchError):
+    """The requested operation is not available on this model/backend."""
+
+
+class ProtectedPortError(NetgearSwitchError):
+    """A disruptive write targeted a protected port without force=True."""
+
+
+class WriteVerificationError(NetgearSwitchError):
+    """A write did not read back as expected.
+
+    Carries the observed state before and after the write attempt so callers
+    can report exactly what diverged.
+    """
+
+    def __init__(self, message: str, *, before: object, after: object) -> None:
+        super().__init__(message)
+        self.before = before
+        self.after = after
+
+
+class HttpError(NetgearSwitchError):
+    """An HTTP web-UI transport operation failed (connect, HTTP status, page shape)."""
+
+
+class HttpAuthError(HttpError):
+    """Web-UI login was rejected, or an authenticated session was lost."""
+
+
+class HttpUnexpectedPageError(HttpError):
+    """A web-UI page or token could not be parsed into the expected shape."""

netgear_switch/http_read.py

@@ -0,0 +1,174 @@
+"""Model-driven web-UI read operations over a sync or async ``HttpSession``.
+
+Parallel to ``snmp_read.py``/``nsdp_read.py``. Construction is gated on
+``HttpModelSpec.reads_verified``: a model whose web reads are still
+UNVERIFIED-pending-capture (gs110emx Gambit, gsm7228ps cheetah/S3300) refuses
+to construct rather than return fabricated data -- the facade never gets a
+plausible-but-wrong result from an unverified scrape. Web-UI-impossible ops
+(MAC/FDB, box sensors, LLDP, management-IP config) raise
+``UnsupportedCapabilityError`` honestly instead of silently returning ``[]``.
+
+All page-path selection and HTML-to-model conversion lives in the
+module-level helpers below (pure, I/O-free); ``HttpReader``/``AsyncHttpReader``
+differ only in whether ``session.get_page``/``post_form`` is awaited.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .errors import UnsupportedCapabilityError
+from .models import VLANInfo, VlanMode
+from .protocols.http import parse
+from .protocols.http.endpoints import http_spec
+
+if TYPE_CHECKING:
+    from .models import (
+        LLDPNeighbor,
+        MacEntry,
+        MgmtIpConfig,
+        PoEStatus,
+        PortStats,
+        PortStatus,
+        Sensor,
+    )
+    from .protocols.http.endpoints import HttpModelSpec
+    from .protocols.http.session import AsyncHttpSession, HttpSession
+    from .registry import SwitchModel
+
+
+def _require_verified_reads(spec: HttpModelSpec) -> None:
+    if not spec.reads_verified:
+        raise UnsupportedCapabilityError(
+            f"model {spec.model_key!r} HTTP reads are UNVERIFIED-pending-capture"
+        )
+
+
+def _unsupported(model_key: str, op: str) -> UnsupportedCapabilityError:
+    return UnsupportedCapabilityError(
+        f"model {model_key!r} web UI does not expose {op}"
+    )
+
+
+def _require_path(model_key: str, path: str | None, op: str) -> str:
+    """Return ``path`` or raise honestly if this model's spec has none for ``op``."""
+    if path is None:
+        raise _unsupported(model_key, op)
+    return path
+
+
+def _vlan_info(vid: int, membership_html: str, port_count: int) -> VLANInfo:
+    """Pure conversion of one 8021qMembe.cgi response into a ``VLANInfo``."""
+    states = parse.parse_membership(membership_html, port_count)
+    tagged = frozenset(p for p, m in states.items() if m is VlanMode.TAGGED)
+    untagged = frozenset(p for p, m in states.items() if m is VlanMode.UNTAGGED)
+    return VLANInfo(
+        vlan_id=vid,
+        name=None,
+        member_ports=tagged | untagged,
+        tagged_ports=tagged,
+        untagged_ports=untagged,
+    )
+
+
+class HttpReader:
+    """Synchronous web-UI read facade over one switch."""
+
+    def __init__(self, session: HttpSession, model: SwitchModel) -> None:
+        self._spec = http_spec(model)
+        _require_verified_reads(self._spec)
+        self.session = session
+        self.model = model
+
+    def get_ports(self) -> list[PortStatus]:
+        path = _require_path(self.model.key, self._spec.dashboard_path, "port status")
+        return parse.parse_port_status(self.session.get_page(path))
+
+    def get_stats(self) -> list[PortStats]:
+        path = _require_path(self.model.key, self._spec.stats_path, "port statistics")
+        return parse.parse_port_stats(self.session.get_page(path))
+
+    def get_poe(self) -> list[PoEStatus]:
+        path = _require_path(self.model.key, self._spec.poe_status_path, "PoE status")
+        return parse.parse_poe_status(self.session.get_page(path))
+
+    def get_pvids(self) -> list[tuple[int, int]]:
+        path = _require_path(self.model.key, self._spec.pvid_path, "port PVIDs")
+        return parse.parse_pvids(self.session.get_page(path))
+
+    def get_vlans(self) -> list[VLANInfo]:
+        cfg_path = _require_path(
+            self.model.key, self._spec.vlan_config_path, "VLAN configuration"
+        )
+        member_path = _require_path(
+            self.model.key, self._spec.vlan_membership_path, "VLAN membership"
+        )
+        cfg = self.session.get_page(cfg_path)
+        result: list[VLANInfo] = []
+        for vid in parse.parse_vlan_ids(cfg):
+            html = self.session.post_form(member_path, {"VLAN_ID": str(vid)})
+            result.append(_vlan_info(vid, html, self.model.port_count))
+        return result
+
+    def get_macs(self) -> list[MacEntry]:
+        raise _unsupported(self.model.key, "a MAC/FDB table")
+
+    def get_lldp(self) -> list[LLDPNeighbor]:
+        raise _unsupported(self.model.key, "LLDP neighbours")
+
+    def get_sensors(self) -> list[Sensor]:
+        raise _unsupported(self.model.key, "box sensors")
+
+    def get_mgmt_ip(self) -> MgmtIpConfig:
+        raise _unsupported(self.model.key, "management-IP config")
+
+
+class AsyncHttpReader:
+    """Asynchronous web-UI read facade (mirror of ``HttpReader``)."""
+
+    def __init__(self, session: AsyncHttpSession, model: SwitchModel) -> None:
+        self._spec = http_spec(model)
+        _require_verified_reads(self._spec)
+        self.session = session
+        self.model = model
+
+    async def get_ports(self) -> list[PortStatus]:
+        path = _require_path(self.model.key, self._spec.dashboard_path, "port status")
+        return parse.parse_port_status(await self.session.get_page(path))
+
+    async def get_stats(self) -> list[PortStats]:
+        path = _require_path(self.model.key, self._spec.stats_path, "port statistics")
+        return parse.parse_port_stats(await self.session.get_page(path))
+
+    async def get_poe(self) -> list[PoEStatus]:
+        path = _require_path(self.model.key, self._spec.poe_status_path, "PoE status")
+        return parse.parse_poe_status(await self.session.get_page(path))
+
+    async def get_pvids(self) -> list[tuple[int, int]]:
+        path = _require_path(self.model.key, self._spec.pvid_path, "port PVIDs")
+        return parse.parse_pvids(await self.session.get_page(path))
+
+    async def get_vlans(self) -> list[VLANInfo]:
+        cfg_path = _require_path(
+            self.model.key, self._spec.vlan_config_path, "VLAN configuration"
+        )
+        member_path = _require_path(
+            self.model.key, self._spec.vlan_membership_path, "VLAN membership"
+        )
+        cfg = await self.session.get_page(cfg_path)
+        result: list[VLANInfo] = []
+        for vid in parse.parse_vlan_ids(cfg):
+            html = await self.session.post_form(member_path, {"VLAN_ID": str(vid)})
+            result.append(_vlan_info(vid, html, self.model.port_count))
+        return result
+
+    async def get_macs(self) -> list[MacEntry]:
+        raise _unsupported(self.model.key, "a MAC/FDB table")
+
+    async def get_lldp(self) -> list[LLDPNeighbor]:
+        raise _unsupported(self.model.key, "LLDP neighbours")
+
+    async def get_sensors(self) -> list[Sensor]:
+        raise _unsupported(self.model.key, "box sensors")
+
+    async def get_mgmt_ip(self) -> MgmtIpConfig:
+        raise _unsupported(self.model.key, "management-IP config")