fh_tool-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh_tool-cli
-Version: 0.2.1
+Version: 0.2.3
 Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
 Author: Gxxk
 License-Expression: AGPL-3.0-or-later
@@ -9,8 +9,10 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.7.0
 
 # fh_tool-cli
 
@@ -38,6 +40,20 @@ uv run fh-tool --help
 
 下文示例中的 `fh-tool ...` 如果是在源码目录内运行，可以统一写成 `uv run fh-tool ...`。
 
+## CLI 输出和日志
+
+CLI 入口使用 Click，错误和日志输出使用 Rich。命令结果只写 stdout；错误、警告和日志写 stderr，便于脚本把 stdout 当作数据流处理。
+
+```bash
+fh-tool --verbose probe --json
+fh-tool --quiet config show
+fh-tool --log-file fh-tool.log dev-info
+```
+
+`--json` 输出稳定的 machine-readable JSON，不混入日志或样式。当前默认人类输出仍保持 pretty JSON，以兼容已有脚本；后续可以在不影响 `--json` 的前提下逐步增加表格化输出。
+
+`--log-file` 写入 JSON lines 结构化日志；`-v/-vv` 控制 info/debug 事件，`-q` 只保留 error 级别。日志只记录 command、HTTP method、状态码、cfg path、风险等级等元数据，密码、session、token、LOID、PPPoE 等字段会脱敏。
+
 ## 快速配置
 
 保存默认 IP/MAC：
@@ -135,7 +151,7 @@ fh-tool wan list --backend local-vm
 
 `local-vm` 只是在本机 proot VM 内执行厂商 `cfg_cmd`。`--vm-root` 必须指向 VM 工作区目录，也就是包含 `bin/proot-shell` 和 `rootfs-vm/fhrom/bin/cfg_cmd` 的目录；默认是 `/mnt/dev-cold/HG5143F-ONU-vm`。不要把它指到里面的 `rootfs-vm/`。
 
-Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
+Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；cfg 来源需要 Telnet 时会默认使用 HG5143F 派生 Telnet 凭据 fallback，可用 `--no-derived-credentials` 关闭。失败不会阻塞只读抓取，并会在结果里返回脱敏 login summary。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
 
@@ -160,13 +176,18 @@ fh-tool web services set --service telnet --enabled 0 --confirm
 
 常规 Web 写接口优先使用 typed 参数。`web ajax post` 和 `web ajax replay` 支持任意已知或未知 AJAX method，默认只输出计划，不发 POST；执行必须加 `--confirm`，且默认拒绝空 payload。`--json-payload` 和可重复的 `--param k=v` 仍保留为固件差异逃生口，合并顺序是 typed 参数、JSON、最后 `--param` 覆盖。旧的确认参数会直接报弃用错误。
 
-Telnet/cfg/诊断命令默认不会自动套用派生凭据。如果设备仍是 HG5143F 默认 Telnet 规则，并且已提供或保存 MAC，可以显式加 `--use-derived-credentials` 作为 fallback：
+Web AJAX 写命令 dry-run 不会登录；加 `--confirm` 后，如果没有显式 `--sessionid`，会要求自动登录成功后才发 POST。
+
+Telnet/cfg/诊断命令在未显式传 Telnet 密码时，会默认使用 HG5143F 派生 Telnet 凭据 fallback；显式传入的用户名/密码始终优先。如果设备不是该规则，或需要保留空凭据/自定义认证，可加 `--no-derived-credentials` 关闭。`--use-derived-credentials` 仍作为兼容参数接受：
 
 ```bash
-fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --use-derived-credentials
-fh-tool wan list --use-derived-credentials
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer
+fh-tool wan list
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --no-derived-credentials
 ```
 
+需要 root shell 的 Telnet 操作会自动执行 `su root`，当前 su 密码默认按 HG5143F 规则从 MAC 派生；如果 runtime su 密码已经被你改过，可显式传 `--su-password` 或 `--su-password-stdin`。例如 device restore、`cloud disable-cloudclt --confirm`、`account set-su-runtime-password --confirm` 会走 root runner。`account set-su-runtime-password` 写入的是 `/var/telsu` 的 passwd 格式 md5-crypt 行，不会把明文密码写入远端命令。
+
 诊断命令保持只读；`ip status` 这类依赖 VM/userspace 工具的命令会分别标记每个 probe 的 `ok/output/error`，工具缺失时输出 `partial_failure=true`，不会吞掉其它已成功字段。
 
 本地 VM 集成测试默认会跳过；需要显式指定 VM 目录才会运行：
@@ -211,6 +232,8 @@ fh-tool restore backup.tgz \
 
 当前 restore 只恢复 allowlist 内的配置文件，且会拒绝路径穿越、绝对路径逃逸和未知文件写入。`/proc/mtd`、runtime password 文件、restore/factory reset flag 等备份内容不会被恢复。恢复后会 read-back/hash verify；不会自动 reboot，也不会自动 factory reset。
 
+默认备份清单包含调研确认的 `/fhconf`、`/fhdata`、runtime password、CloudPlat/appframework 状态和 boot/app 信息等只读路径；这些新增调研路径不会自动加入 restore allowlist。
+
 ## CloudPlat / SmartSwitch
 
 CloudPlat 默认先做只读审计和计划：
@@ -229,6 +252,14 @@ fh-tool cloud disable-smartswitch --confirm
 
 该命令不会修改 LOID、PON、WAN VLAN、ServiceList 或 TR-069 VLAN。
 
+只停 CloudPlat 连接优先使用 SAF container 内的 `cloudclt` init 脚本：
+
+```bash
+fh-tool cloud disable-cloudclt --confirm
+```
+
+该命令通过 `lxc-attach -n saf -- /etc/init.d/cloudclt stop/disable` 执行，需要 root runner；仍然不会 patch 启动脚本或删除 package。
+
 ## 22 个 `/fh_tool/api` method 覆盖
 
 已提供 typed command：

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/README.md

@@ -24,6 +24,20 @@ uv run fh-tool --help
 
 下文示例中的 `fh-tool ...` 如果是在源码目录内运行，可以统一写成 `uv run fh-tool ...`。
 
+## CLI 输出和日志
+
+CLI 入口使用 Click，错误和日志输出使用 Rich。命令结果只写 stdout；错误、警告和日志写 stderr，便于脚本把 stdout 当作数据流处理。
+
+```bash
+fh-tool --verbose probe --json
+fh-tool --quiet config show
+fh-tool --log-file fh-tool.log dev-info
+```
+
+`--json` 输出稳定的 machine-readable JSON，不混入日志或样式。当前默认人类输出仍保持 pretty JSON，以兼容已有脚本；后续可以在不影响 `--json` 的前提下逐步增加表格化输出。
+
+`--log-file` 写入 JSON lines 结构化日志；`-v/-vv` 控制 info/debug 事件，`-q` 只保留 error 级别。日志只记录 command、HTTP method、状态码、cfg path、风险等级等元数据，密码、session、token、LOID、PPPoE 等字段会脱敏。
+
 ## 快速配置
 
 保存默认 IP/MAC：
@@ -121,7 +135,7 @@ fh-tool wan list --backend local-vm
 
 `local-vm` 只是在本机 proot VM 内执行厂商 `cfg_cmd`。`--vm-root` 必须指向 VM 工作区目录，也就是包含 `bin/proot-shell` 和 `rootfs-vm/fhrom/bin/cfg_cmd` 的目录；默认是 `/mnt/dev-cold/HG5143F-ONU-vm`。不要把它指到里面的 `rootfs-vm/`。
 
-Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
+Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；cfg 来源需要 Telnet 时会默认使用 HG5143F 派生 Telnet 凭据 fallback，可用 `--no-derived-credentials` 关闭。失败不会阻塞只读抓取，并会在结果里返回脱敏 login summary。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
 
@@ -146,13 +160,18 @@ fh-tool web services set --service telnet --enabled 0 --confirm
 
 常规 Web 写接口优先使用 typed 参数。`web ajax post` 和 `web ajax replay` 支持任意已知或未知 AJAX method，默认只输出计划，不发 POST；执行必须加 `--confirm`，且默认拒绝空 payload。`--json-payload` 和可重复的 `--param k=v` 仍保留为固件差异逃生口，合并顺序是 typed 参数、JSON、最后 `--param` 覆盖。旧的确认参数会直接报弃用错误。
 
-Telnet/cfg/诊断命令默认不会自动套用派生凭据。如果设备仍是 HG5143F 默认 Telnet 规则，并且已提供或保存 MAC，可以显式加 `--use-derived-credentials` 作为 fallback：
+Web AJAX 写命令 dry-run 不会登录；加 `--confirm` 后，如果没有显式 `--sessionid`，会要求自动登录成功后才发 POST。
+
+Telnet/cfg/诊断命令在未显式传 Telnet 密码时，会默认使用 HG5143F 派生 Telnet 凭据 fallback；显式传入的用户名/密码始终优先。如果设备不是该规则，或需要保留空凭据/自定义认证，可加 `--no-derived-credentials` 关闭。`--use-derived-credentials` 仍作为兼容参数接受：
 
 ```bash
-fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --use-derived-credentials
-fh-tool wan list --use-derived-credentials
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer
+fh-tool wan list
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --no-derived-credentials
 ```
 
+需要 root shell 的 Telnet 操作会自动执行 `su root`，当前 su 密码默认按 HG5143F 规则从 MAC 派生；如果 runtime su 密码已经被你改过，可显式传 `--su-password` 或 `--su-password-stdin`。例如 device restore、`cloud disable-cloudclt --confirm`、`account set-su-runtime-password --confirm` 会走 root runner。`account set-su-runtime-password` 写入的是 `/var/telsu` 的 passwd 格式 md5-crypt 行，不会把明文密码写入远端命令。
+
 诊断命令保持只读；`ip status` 这类依赖 VM/userspace 工具的命令会分别标记每个 probe 的 `ok/output/error`，工具缺失时输出 `partial_failure=true`，不会吞掉其它已成功字段。
 
 本地 VM 集成测试默认会跳过；需要显式指定 VM 目录才会运行：
@@ -197,6 +216,8 @@ fh-tool restore backup.tgz \
 
 当前 restore 只恢复 allowlist 内的配置文件，且会拒绝路径穿越、绝对路径逃逸和未知文件写入。`/proc/mtd`、runtime password 文件、restore/factory reset flag 等备份内容不会被恢复。恢复后会 read-back/hash verify；不会自动 reboot，也不会自动 factory reset。
 
+默认备份清单包含调研确认的 `/fhconf`、`/fhdata`、runtime password、CloudPlat/appframework 状态和 boot/app 信息等只读路径；这些新增调研路径不会自动加入 restore allowlist。
+
 ## CloudPlat / SmartSwitch
 
 CloudPlat 默认先做只读审计和计划：
@@ -215,6 +236,14 @@ fh-tool cloud disable-smartswitch --confirm
 
 该命令不会修改 LOID、PON、WAN VLAN、ServiceList 或 TR-069 VLAN。
 
+只停 CloudPlat 连接优先使用 SAF container 内的 `cloudclt` init 脚本：
+
+```bash
+fh-tool cloud disable-cloudclt --confirm
+```
+
+该命令通过 `lxc-attach -n saf -- /etc/init.d/cloudclt stop/disable` 执行，需要 root runner；仍然不会 patch 启动脚本或删除 package。
+
 ## 22 个 `/fh_tool/api` method 覆盖
 
 已提供 typed command：

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fh_tool-cli"
-version = "0.2.1"
+version = "0.2.3"
 description = "用于本地管理 FiberHome fh_tool 接口的 Python CLI"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,8 +18,10 @@ classifiers = [
     "Topic :: System :: Networking",
 ]
 dependencies = [
+    "click>=8.1.0",
     "cryptography>=42.0.0",
     "requests>=2.31.0",
+    "rich>=13.7.0",
 ]
 
 [project.scripts]

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/src/fh_tool_cli/account.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import shlex
 import sys
 from dataclasses import dataclass
+from hashlib import md5
 from secrets import token_urlsafe
 from typing import Any
 
@@ -13,6 +14,8 @@ WEB_ADMIN_PASSWORD_PATH = "InternetGatewayDevice.DeviceInfo.X_CT-COM_TeleComAcco
 TELNET_PASSWORD_PATH = "InternetGatewayDevice.DeviceInfo.X_CT-COM_ServiceManage.TelnetPassword"
 TELNET_USERNAME_PATH = "InternetGatewayDevice.DeviceInfo.X_CT-COM_ServiceManage.TelnetUserName"
 SU_RUNTIME_PASSWORD_FILE = "/var/telsu"
+_MD5_CRYPT_MAGIC = b"$1$"
+_MD5_CRYPT_ALPHABET = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
 
 
 @dataclass(frozen=True)
@@ -69,7 +72,9 @@ def set_telnet_username(backend: CfgCmdBackend, name: str) -> dict[str, Any]:
 
 
 def set_su_runtime_password(shell_runner: Any, password: str) -> dict[str, Any]:
-    command = f"printf %s {shlex.quote(password)} > {shlex.quote(SU_RUNTIME_PASSWORD_FILE)}"
+    hashed_password = _md5_crypt_empty_salt(password)
+    passwd_entry = f"root:{hashed_password}:0:0:Telnet user:/:/bin/ash"
+    command = f"printf '%s\\n' {shlex.quote(passwd_entry)} > {shlex.quote(SU_RUNTIME_PASSWORD_FILE)}"
     shell_runner(command)
     return {
         "path": SU_RUNTIME_PASSWORD_FILE,
@@ -80,6 +85,62 @@ def set_su_runtime_password(shell_runner: Any, password: str) -> dict[str, Any]:
     }
 
 
+def _md5_crypt_empty_salt(password: str) -> str:
+    return _md5_crypt(password.encode(), b"")
+
+
+def _md5_crypt(password: bytes, salt: bytes) -> str:
+    if len(salt) > 8:
+        salt = salt[:8]
+
+    digest = md5(password + _MD5_CRYPT_MAGIC + salt)
+    alternate = md5(password + salt + password).digest()
+    password_len = len(password)
+
+    remaining = password_len
+    while remaining > 0:
+        digest.update(alternate[: min(16, remaining)])
+        remaining -= 16
+
+    remaining = password_len
+    while remaining > 0:
+        if remaining & 1:
+            digest.update(b"\x00")
+        else:
+            digest.update(password[:1])
+        remaining >>= 1
+
+    final = digest.digest()
+    for index in range(1000):
+        digest = md5()
+        digest.update(password if index & 1 else final)
+        if index % 3:
+            digest.update(salt)
+        if index % 7:
+            digest.update(password)
+        digest.update(final if index & 1 else password)
+        final = digest.digest()
+
+    encoded = (
+        _md5_crypt_base64(final[0], final[6], final[12], 4)
+        + _md5_crypt_base64(final[1], final[7], final[13], 4)
+        + _md5_crypt_base64(final[2], final[8], final[14], 4)
+        + _md5_crypt_base64(final[3], final[9], final[15], 4)
+        + _md5_crypt_base64(final[4], final[10], final[5], 4)
+        + _md5_crypt_base64(0, 0, final[11], 2)
+    )
+    return f"$1${salt.decode()}${encoded}"
+
+
+def _md5_crypt_base64(byte2: int, byte1: int, byte0: int, length: int) -> str:
+    value = (byte2 << 16) | (byte1 << 8) | byte0
+    encoded = []
+    for _ in range(length):
+        encoded.append(_MD5_CRYPT_ALPHABET[value & 0x3F])
+        value >>= 6
+    return "".join(encoded)
+
+
 def _redact_write_result(result: dict[str, Any]) -> dict[str, Any]:
     redacted = dict(result)
     redacted["value"] = "[REDACTED]"

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/src/fh_tool_cli/backends/cfg_cmd.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import re
 import shlex
 from collections.abc import Callable
@@ -8,6 +9,7 @@ from pathlib import Path
 from typing import Any
 
 from ..errors import CliError
+from ..output import log_event
 
 DANGER_CFG_PATH_RE = re.compile(
     r"(tr-?069|wan|pon|loid|vlan|preconfig|servicelist|smartswitch|cloudplat)",
@@ -57,13 +59,23 @@ class CfgCmdBackend:
         self.expensive_missing_paths = expensive_missing_paths
 
     def get(self, path: str) -> str:
-        return parse_cfg_get_output(path, self._runner(_cfg_command("get", path)))
+        log_event(logging.DEBUG, "cfg.get.start", path=path, risk=cfg_read_risk(path))
+        output = self._runner(_cfg_command("get", path))
+        value = parse_cfg_get_output(path, output)
+        log_event(logging.DEBUG, "cfg.get.success", path=path, risk=cfg_read_risk(path), empty=not bool(value))
+        return value
 
     def set(self, path: str, value: str) -> str:
-        return self._runner(_cfg_command("set", path, value))
+        log_event(logging.INFO, "cfg.set.start", path=path, risk=cfg_path_risk(path))
+        result = self._runner(_cfg_command("set", path, value))
+        log_event(logging.INFO, "cfg.set.success", path=path, risk=cfg_path_risk(path))
+        return result
 
     def attr(self, path: str) -> str:
-        return self._runner(_cfg_command("attr", path)).strip()
+        log_event(logging.DEBUG, "cfg.attr.start", path=path, risk=cfg_read_risk(path))
+        result = self._runner(_cfg_command("attr", path)).strip()
+        log_event(logging.DEBUG, "cfg.attr.success", path=path, risk=cfg_read_risk(path), empty=not bool(result))
+        return result
 
 
 def cfg_set_with_verify(backend: CfgCmdBackend, path: str, value: str) -> dict[str, Any]:

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/src/fh_tool_cli/backends/fh_tool.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import logging
 from typing import Any
 
 import requests
@@ -8,6 +9,7 @@ import requests
 from ..config_store import format_mac, resolve_ip, resolve_mac
 from ..crypto import decrypt_payload, derive_crypto, encrypt_payload
 from ..errors import FHToolError
+from ..output import log_event
 
 FH_TOOL_API_PATH = "/fh_tool/api"
 FH_TOOL_UPLOAD_PATH = "/fh_tool/upload"
@@ -22,6 +24,8 @@ def fh_tool_call(
     crypto = derive_crypto(mac)
     encrypted = encrypt_payload(payload, crypto)
     url = f"http://{ip}:8080{FH_TOOL_API_PATH}"
+    func = str(payload.get("func", "unknown"))
+    log_event(logging.INFO, "fh_tool.api.request", ip=ip, path=FH_TOOL_API_PATH, func=func)
     try:
         response = requests.post(
             url,
@@ -34,15 +38,35 @@ def fh_tool_call(
             allow_redirects=False,
         )
     except requests.RequestException as exc:
+        log_event(logging.INFO, "fh_tool.api.error", ip=ip, path=FH_TOOL_API_PATH, func=func, error=str(exc))
         raise FHToolError(f"无法连接 {url}: {exc}") from exc
 
     if response.status_code != 200:
+        log_event(
+            logging.INFO,
+            "fh_tool.api.http_error",
+            ip=ip,
+            path=FH_TOOL_API_PATH,
+            func=func,
+            status_code=response.status_code,
+        )
         raise FHToolError(f"{FH_TOOL_API_PATH} 返回 HTTP {response.status_code}")
 
     try:
-        return decrypt_payload(response.text, crypto)
+        result = decrypt_payload(response.text, crypto)
     except Exception as exc:
+        log_event(logging.INFO, "fh_tool.api.decrypt_error", ip=ip, path=FH_TOOL_API_PATH, func=func)
         raise FHToolError("响应解密失败，MAC 可能不匹配或固件协议不同") from exc
+    log_event(
+        logging.INFO,
+        "fh_tool.api.response",
+        ip=ip,
+        path=FH_TOOL_API_PATH,
+        func=func,
+        status_code=response.status_code,
+        result=result.get("result") if isinstance(result, dict) else None,
+    )
+    return result
 
 
 def api_payload(func: str, params: dict[str, Any] | None = None, index: str = "1") -> dict[str, Any]:

fh_tool_cli-0.2.3/src/fh_tool_cli/backends/telnet.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import socket
+import logging
+from dataclasses import dataclass
+
+from ..config_store import decode_text
+from ..errors import FHToolError
+from ..output import log_event
+
+
+@dataclass(frozen=True)
+class TelnetCredentials:
+    host: str
+    port: int = 23
+    username: str | None = None
+    password: str | None = None
+    timeout: float = 5.0
+
+
+class TelnetShell:
+    def __init__(self, credentials: TelnetCredentials):
+        self.credentials = credentials
+
+    def run(self, command: str) -> str:
+        log_event(
+            logging.INFO,
+            "telnet.command.start",
+            host=self.credentials.host,
+            port=self.credentials.port,
+            username_present=bool(self.credentials.username),
+            password_present=bool(self.credentials.password),
+        )
+        try:
+            with socket.create_connection(
+                (self.credentials.host, self.credentials.port),
+                timeout=self.credentials.timeout,
+            ) as sock:
+                sock.settimeout(self.credentials.timeout)
+                if self.credentials.username:
+                    _read_until(sock, b"login:")
+                    sock.sendall(self.credentials.username.encode("utf-8") + b"\n")
+                if self.credentials.password:
+                    _read_until(sock, b"Password:")
+                    sock.sendall(self.credentials.password.encode("utf-8") + b"\n")
+                sock.sendall(command.encode("utf-8") + b"\n")
+                sock.sendall(b"exit\n")
+                output = decode_text(_read_all(sock))
+                log_event(
+                    logging.INFO,
+                    "telnet.command.success",
+                    host=self.credentials.host,
+                    port=self.credentials.port,
+                    output_bytes=len(output.encode("utf-8")),
+                )
+                return output
+        except OSError as exc:
+            log_event(
+                logging.INFO,
+                "telnet.command.error",
+                host=self.credentials.host,
+                port=self.credentials.port,
+                error=str(exc),
+            )
+            raise FHToolError(f"Telnet command failed: {exc}") from exc
+
+    def run_as_root(self, command: str, *, su_password: str) -> str:
+        log_event(
+            logging.INFO,
+            "telnet.root_command.start",
+            host=self.credentials.host,
+            port=self.credentials.port,
+            username_present=bool(self.credentials.username),
+            telnet_password_present=bool(self.credentials.password),
+            su_password_present=bool(su_password),
+        )
+        try:
+            with socket.create_connection(
+                (self.credentials.host, self.credentials.port),
+                timeout=self.credentials.timeout,
+            ) as sock:
+                sock.settimeout(self.credentials.timeout)
+                if self.credentials.username:
+                    _read_until(sock, b"login:")
+                    sock.sendall(self.credentials.username.encode("utf-8") + b"\n")
+                if self.credentials.password:
+                    _read_until(sock, b"Password:")
+                    sock.sendall(self.credentials.password.encode("utf-8") + b"\n")
+                sock.sendall(b"su root\n")
+                _read_until(sock, b"Password:")
+                sock.sendall(su_password.encode("utf-8") + b"\n")
+                sock.sendall(command.encode("utf-8") + b"\n")
+                sock.sendall(b"exit\n")
+                sock.sendall(b"exit\n")
+                output = decode_text(_read_all(sock))
+                log_event(
+                    logging.INFO,
+                    "telnet.root_command.success",
+                    host=self.credentials.host,
+                    port=self.credentials.port,
+                    output_bytes=len(output.encode("utf-8")),
+                )
+                return output
+        except OSError as exc:
+            log_event(
+                logging.INFO,
+                "telnet.root_command.error",
+                host=self.credentials.host,
+                port=self.credentials.port,
+                error=str(exc),
+            )
+            raise FHToolError(f"Telnet root command failed: {exc}") from exc
+
+
+def _read_until(sock: socket.socket, marker: bytes) -> bytes:
+    data = bytearray()
+    while marker not in data:
+        try:
+            chunk = sock.recv(4096)
+        except TimeoutError:
+            break
+        if not chunk:
+            break
+        data.extend(chunk)
+    return bytes(data)
+
+
+def _read_all(sock: socket.socket) -> bytes:
+    data = bytearray()
+    while True:
+        try:
+            chunk = sock.recv(4096)
+        except TimeoutError:
+            break
+        if not chunk:
+            break
+        data.extend(chunk)
+    return bytes(data)

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.3}/src/fh_tool_cli/backends/web_ajax.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import base64
 import hashlib
+import logging
 import re
 from typing import Any
 from urllib.parse import urljoin
@@ -11,6 +12,7 @@ from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 from cryptography.hazmat.primitives.padding import PKCS7
 
 from ..errors import FHToolError
+from ..output import log_event
 
 DEFAULT_AJAX_PATH = "/cgi-bin/ajax"
 DEFAULT_WEB_LOGIN_PORT = "0"
@@ -65,10 +67,13 @@ class WebAjaxClient:
 
     def login_check(self) -> dict[str, Any]:
         url = self.base_url
+        log_event(logging.INFO, "web.login_check.start", base_url=self.base_url)
         try:
             response = self.session.get(url, timeout=self.timeout, allow_redirects=False)
         except requests.RequestException as exc:
+            log_event(logging.INFO, "web.login_check.error", base_url=self.base_url, error=str(exc))
             raise FHToolError(f"Web login-check failed {url}: {exc}") from exc
+        log_event(logging.INFO, "web.login_check.response", base_url=self.base_url, status_code=response.status_code)
         result = {
             "url": url,
             "status_code": response.status_code,
@@ -112,6 +117,7 @@ class WebAjaxClient:
         *,
         port: str = DEFAULT_WEB_LOGIN_PORT,
     ) -> dict[str, Any]:
+        log_event(logging.INFO, "web.login.start", base_url=self.base_url, username=username)
         brmad = self._fetch_brmad()
         self.ajax_get("get_operator", use_session=False)
         loginpd = fiberhome_web_encrypt(
@@ -128,10 +134,21 @@ class WebAjaxClient:
         )
         response = result.get("response")
         login_result = response.get("login_result") if isinstance(response, dict) else None
+        ok = result["ok"] and str(login_result) == "0"
+        log_event(
+            logging.INFO,
+            "web.login.response",
+            base_url=self.base_url,
+            username=username,
+            status_code=result["status_code"],
+            ok=ok,
+            login_result=login_result,
+            sessionid_present=bool(self.sessionid),
+        )
         return {
             "method": "do_login",
             "status_code": result["status_code"],
-            "ok": result["ok"] and str(login_result) == "0",
+            "ok": ok,
             "login_result": login_result,
             "username": username,
             "sessionid_present": bool(self.sessionid),
@@ -151,6 +168,14 @@ class WebAjaxClient:
             request_params.update(params)
         if use_session and self.sessionid:
             request_params.setdefault("sessionid", self.sessionid)
+        log_event(
+            logging.DEBUG,
+            "web.ajax.request",
+            base_url=self.base_url,
+            http_method="GET",
+            method=method,
+            sessionid_present=bool(request_params.get("sessionid")),
+        )
         try:
             response = self.session.get(
                 url,
@@ -159,6 +184,14 @@ class WebAjaxClient:
                 allow_redirects=False,
             )
         except requests.RequestException as exc:
+            log_event(
+                logging.INFO,
+                "web.ajax.error",
+                base_url=self.base_url,
+                http_method="GET",
+                method=method,
+                error=str(exc),
+            )
             raise FHToolError(f"Web AJAX GET failed {url}: {exc}") from exc
         return self._response_result("GET", url, method, response)
 
@@ -168,6 +201,14 @@ class WebAjaxClient:
         request_data["ajaxmethod"] = method
         if self.sessionid:
             request_data.setdefault("sessionid", self.sessionid)
+        log_event(
+            logging.DEBUG,
+            "web.ajax.request",
+            base_url=self.base_url,
+            http_method="POST",
+            method=method,
+            sessionid_present=bool(request_data.get("sessionid")),
+        )
         try:
             response = self.session.post(
                 url,
@@ -176,6 +217,14 @@ class WebAjaxClient:
                 allow_redirects=False,
             )
         except requests.RequestException as exc:
+            log_event(
+                logging.INFO,
+                "web.ajax.error",
+                base_url=self.base_url,
+                http_method="POST",
+                method=method,
+                error=str(exc),
+            )
             raise FHToolError(f"Web AJAX POST failed {url}: {exc}") from exc
         return self._response_result("POST", url, method, response)
 
@@ -319,6 +368,16 @@ class WebAjaxClient:
             "content_type": response.headers.get("Content-Type"),
             "sessionid_present": bool(self.sessionid),
         }
+        log_event(
+            logging.DEBUG,
+            "web.ajax.response",
+            base_url=self.base_url,
+            http_method=http_method,
+            method=method,
+            status_code=response.status_code,
+            ok=result["ok"],
+            sessionid_present=bool(self.sessionid),
+        )
         try:
             payload = response.json()
         except ValueError: