qnap-nas-cli 0.2.0__py3-none-any.whl

qnap_nas_cli/__init__.py

@@ -0,0 +1,3 @@
+"""QNAP QTS diagnostics CLI."""
+
+__version__ = "0.2.0"

qnap_nas_cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

qnap_nas_cli/cli.py

@@ -0,0 +1,327 @@
+import argparse
+import getpass
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from . import __version__
+from .client import QtsClient
+from .commands import disks_ssh, dump, health, incident_report, network, raid, services, smart_details, storage, sysinfo, tailscale, validate_dump
+from .config import Config, default_config_path, load_config, password_from_environment, save_config
+from .errors import QtsError, TwoFactorRequired
+from .mcp import serve
+from .incident import DEFAULT_MAX_ITEMS, MAX_MAX_ITEMS, response_plan, write_evidence_bundle
+from .remediation import apply_plan, unavailable_plan
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="qts", description="QNAP QTS safety-first diagnostics CLI")
+    root.add_argument("--version", action="version", version="%(prog)s {}".format(__version__))
+    root.add_argument("--config", type=Path, help="設定檔路徑（也可使用 QTS_CONFIG）")
+    root.add_argument("--json", action="store_true", help="輸出 JSON")
+    root.add_argument("--insecure", action="store_true", help="停用 TLS 憑證驗證（僅限受信任區網暫時使用）")
+    subs = root.add_subparsers(dest="command", required=True)
+
+    setup = subs.add_parser("setup", help="寫入連線設定；不儲存密碼")
+    setup.add_argument("--origin", required=True)
+    setup.add_argument("--user", required=True)
+    setup.add_argument("--ssh-host")
+    setup.add_argument("--ssh-user")
+    setup.add_argument("--ssh-identity-file")
+    setup.add_argument("--timeout", type=int, default=15)
+
+    subs.add_parser("doctor", help="檢查本機設定與連線前置條件")
+    subs.add_parser("whoami", help="登入並顯示目前帳號與 NAS")
+    subs.add_parser("status", help="系統型號、韌體、負載、溫度與 uptime")
+    health_parser = subs.add_parser("health", help="唯讀磁碟與儲存健康稽核")
+    health_parser.add_argument("--volume-index", type=int, action="append", help="額外查詢指定 volume index，可重複指定；預設 1")
+    storage_parser = subs.add_parser("storage", aliases=["disks", "volumes"], help="磁碟與儲存空間")
+    storage_parser.add_argument("--volume-index", type=int, action="append", help="額外查詢指定 volume index，可重複指定；預設 1")
+    subs.add_parser("network", help="網路介面與 DNS")
+    subs.add_parser("tailscale", help="透過設定的免密 SSH 讀取 Tailscale")
+    subs.add_parser("raid", help="透過免密 SSH 唯讀解析 /proc/mdstat")
+    smart_parser = subs.add_parser("smart-details", help="透過免密 SSH 讀取指定 bay 的 SMART attributes")
+    smart_parser.add_argument("disk", type=int)
+    subs.add_parser("disk-topology", help="透過唯讀 SSH 讀取實體磁碟 bay、角色與型號")
+    subs.add_parser("services", help="唯讀檢查 Container Station 與 Tailscale QPKG 狀態")
+    dump_parser = subs.add_parser("dump", help="匯出已遮蔽敏感資料的相容性樣本")
+    dump_parser.add_argument("directory", nargs="?", type=Path, default=Path("qts-dump"))
+    fixture_parser = subs.add_parser("fixture", help="驗證 dump/fixture 是否能安全解析")
+    fixture_subs = fixture_parser.add_subparsers(dest="fixture_command", required=True)
+    fixture_validate = fixture_subs.add_parser("validate", help="離線驗證已遮蔽的 dump")
+    fixture_validate.add_argument("directory", type=Path)
+    fixture_validate.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    subs.add_parser("mcp", help="啟動唯讀 stdio MCP server")
+    incident_parser = subs.add_parser("incident", help="勒索事件唯讀盤點、人工 containment/evidence/rescue 工作流")
+    incident_subs = incident_parser.add_subparsers(dest="incident_command", required=True)
+    incident_scan = incident_subs.add_parser("scan", help="掃描有限、已知勒索指標並彙整健康/RAID evidence")
+    incident_scan.add_argument("--max-items", type=int, default=DEFAULT_MAX_ITEMS, help="最多掃描的檔案/資料夾項目數，1..{}".format(MAX_MAX_ITEMS))
+    incident_scan.add_argument("--evidence-dir", type=Path, help="可選：建立新的本機 evidence bundle 目錄")
+    incident_contain = incident_subs.add_parser("contain", help="從 incident report 產生人工 containment 清單；不修改 NAS")
+    incident_contain.add_argument("report", type=Path)
+    incident_evidence = incident_subs.add_parser("evidence", help="將既有 incident report 封存並建立 SHA-256 manifest")
+    incident_evidence.add_argument("report", type=Path)
+    incident_evidence.add_argument("directory", type=Path)
+    incident_rescue = incident_subs.add_parser("rescue", help="從 incident report 產生離線備份復原計畫；不覆寫 NAS")
+    incident_rescue.add_argument("report", type=Path)
+    incident_rescue.add_argument("--candidate-path", help="僅可指定本次 report 已列出的 indicator 範例，匯出一份唯讀本機樣本")
+    incident_rescue.add_argument("--directory", type=Path, help="建立新的本機隔離 evidence 目錄；搭配 --candidate-path 使用")
+    incident_rescue.add_argument("--max-bytes", type=int, default=100 * 1024 * 1024)
+    repair = subs.add_parser("repair", help="一般修復的 plan/apply 閘門；尚無已驗證的 NAS 寫入 adapter")
+    repair_subs = repair.add_subparsers(dest="repair_command", required=True)
+    repair_plan = repair_subs.add_parser("plan", help="讀取設備身分並輸出明確拒絕執行的 dry-run plan")
+    repair_plan.add_argument("--action", required=True, choices=["service-start", "service-stop", "notification-change", "firmware-update", "raid-rebuild", "smart-repair"])
+    repair_plan.add_argument("--output", type=Path, default=Path("qts-repair-plan.json"))
+    repair_apply = repair_subs.add_parser("apply", help="驗證 plan 與確認碼；未註冊的 mutation adapter 一律拒絕")
+    repair_apply.add_argument("plan_file", type=Path)
+    repair_apply.add_argument("--confirm", required=True, help="逐字輸入 plan_id；拒絕未驗證操作")
+    nested_parsers = (incident_scan, incident_contain, incident_evidence, incident_rescue, repair_plan, repair_apply)
+    for command_parser in nested_parsers:
+        command_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+        command_parser.add_argument("--insecure", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+        command_parser.add_argument("--config", type=Path, default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    seen = set()
+    for command_parser in subs.choices.values():
+        if id(command_parser) in seen:
+            continue
+        seen.add(id(command_parser))
+        command_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+        command_parser.add_argument("--insecure", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+        command_parser.add_argument("--config", type=Path, default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    return root
+
+
+def _config(args: argparse.Namespace) -> Config:
+    config = load_config(args.config)
+    if args.insecure:
+        config.insecure = True
+    return config
+
+
+def _password() -> str:
+    password = password_from_environment()
+    if password is not None:
+        return password
+    if not sys.stdin.isatty():
+        value = sys.stdin.readline().rstrip("\r\n")
+        if value:
+            return value
+    return getpass.getpass("QTS password: ")
+
+
+def _security_code() -> Optional[str]:
+    value = os.environ.get("QTS_SECURITY_CODE")
+    if value is None:
+        return None
+    value = value.replace(" ", "").strip()
+    return value or None
+
+
+def _prompt_security_code() -> str:
+    if not sys.stdin.isatty():
+        raise TwoFactorRequired("QTS 帳號需要 2FA；非互動模式請設定當下的 QTS_SECURITY_CODE")
+    value = getpass.getpass("QTS security code: ").replace(" ", "").strip()
+    if not value:
+        raise TwoFactorRequired("QTS 2FA 驗證碼不可為空")
+    return value
+
+
+def _login(client: QtsClient) -> None:
+    password = _password()
+    try:
+        client.login(password, _security_code())
+    except TwoFactorRequired:
+        client.login(password, _prompt_security_code())
+
+
+def _read_json(path: Path) -> Dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise QtsError("無法讀取 JSON 檔案：{}".format(exc)) from exc
+    if not isinstance(value, dict):
+        raise QtsError("JSON 根節點必須是 object")
+    return value
+
+
+def _save_new_json(path: Path, value: Dict[str, Any]) -> None:
+    try:
+        with path.open("x", encoding="utf-8") as stream:
+            json.dump(value, stream, ensure_ascii=False, indent=2)
+            stream.write("\n")
+    except FileExistsError as exc:
+        raise QtsError("輸出檔已存在，為避免覆寫 evidence/plan 已拒絕：{}".format(path)) from exc
+
+
+def _print(value: Any, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(value, ensure_ascii=False, indent=2))
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                print("{}:".format(key))
+                rendered = json.dumps(item, ensure_ascii=False, indent=2)
+                print("\n".join("  " + line for line in rendered.splitlines()))
+            elif item is not None:
+                print("{:<20} {}".format(key, item))
+    else:
+        print(value)
+
+
+def _doctor(config: Config, config_path: Optional[Path] = None) -> Dict[str, Any]:
+    import shutil
+    from urllib.parse import urlparse
+    parsed = urlparse(config.origin)
+    local_http = parsed.scheme == "http" and parsed.hostname in ("127.0.0.1", "localhost")
+    return {
+        "config": str(config_path or default_config_path()),
+        "origin": config.origin,
+        "username": config.username,
+        "tls_verification": not config.insecure,
+        "password_available": bool(password_from_environment()),
+        "ssh_configured": bool(config.ssh_host and config.ssh_user),
+        "ssh_executable": shutil.which("ssh") is not None,
+        "safe": (config.origin.startswith("https://") and not config.insecure) or local_http,
+    }
+
+
+def main(argv: Optional[list] = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "setup":
+            target = save_config(Config(args.origin, args.user, args.insecure, args.ssh_host, args.ssh_user, args.timeout, args.ssh_identity_file), args.config)
+            _print({"saved": str(target), "password_saved": False}, args.json)
+            return 0
+        if args.command == "fixture":
+            result = validate_dump(args.directory)
+            _print(result, args.json)
+            return 0 if result["valid"] else 2
+        offline_incident = args.command == "incident" and args.incident_command in ("contain", "evidence", "rescue")
+        if offline_incident and not (args.incident_command == "rescue" and args.candidate_path):
+            report = _read_json(args.report)
+            if args.incident_command == "evidence":
+                value = write_evidence_bundle(args.directory, report)
+            else:
+                scan = report.get("ransomware_scan")
+                if not isinstance(scan, dict):
+                    raise QtsError("report 缺少 ransomware_scan")
+                if args.incident_command == "contain":
+                    value = response_plan(scan)
+                else:
+                    value = {
+                        "status": "manual_rescue_plan_only",
+                        "actions_applied": [],
+                        "steps": [
+                            "在隔離的復原環境使用已驗證的離線／不可變備份；不要把備份直接覆寫到疑似受感染的 NAS。",
+                            "先完成遏止、可信任重建與漏洞修補；再抽樣驗證檔案雜湊、權限、時間戳及應用可讀性。",
+                            "分批恢復至新位置並保留原始加密資料與證據；由資料擁有者簽核後才切換服務。",
+                        ],
+                        "why": "本工具不會對原 NAS 寫檔、解密、刪除或覆寫；恢復來源與完整性需由管理者確認。",
+                    }
+            _print(value, args.json)
+            return 0
+        if args.command == "repair" and args.repair_command == "apply":
+            plan = _read_json(args.plan_file)
+            result = apply_plan(plan, args.confirm, handlers={})
+            _print(result, args.json)
+            return 2 if result["status"] == "refused" else 0
+        config = _config(args)
+        if args.command == "doctor":
+            _print(_doctor(config, args.config), args.json)
+            return 0
+        if args.command == "mcp":
+            return serve(config)
+        if args.command == "incident":
+            if args.incident_command == "rescue":
+                report = _read_json(args.report)
+                scan = report.get("ransomware_scan")
+                if not isinstance(scan, dict):
+                    raise QtsError("report 缺少 ransomware_scan")
+                if not args.candidate_path:
+                    raise QtsError("請提供 --candidate-path，或只產生離線 rescue plan")
+                candidates = [example for indicator in scan.get("indicators", []) for example in indicator.get("examples", [])]
+                if args.candidate_path not in candidates:
+                    raise QtsError("只能匯出本 report 列出的 indicator 範例路徑")
+                if not args.directory:
+                    raise QtsError("匯出本機樣本時必須指定新的 --directory")
+                if not 1 <= args.max_bytes <= 1024 * 1024 * 1024:
+                    raise QtsError("max-bytes 必須介於 1 byte 與 1 GiB")
+                source_path, _, filename = args.candidate_path.rpartition("/")
+                if not source_path or not filename:
+                    raise QtsError("candidate-path 格式無效")
+                report_manifest = write_evidence_bundle(args.directory, report)
+                with QtsClient(config) as client:
+                    _login(client)
+                    sample = client.download_file(source_path, filename, args.directory / filename, args.max_bytes)
+                value = {
+                    "status": "sample_exported_not_restored",
+                    "actions_applied": [],
+                    "source": args.candidate_path,
+                    "sample": sample,
+                    "report_manifest": report_manifest,
+                    "note": "已唯讀匯出到新本機目錄；這不是 NAS 復原，也不會執行或解密樣本。",
+                }
+                _save_new_json(args.directory / "rescue-manifest.json", value)
+                _print(value, args.json)
+                return 0
+            if not 1 <= args.max_items <= MAX_MAX_ITEMS:
+                raise QtsError("max-items 必須介於 1 到 {}".format(MAX_MAX_ITEMS))
+            with QtsClient(config) as client:
+                _login(client)
+                value = incident_report(client, config, args.max_items)
+            if args.evidence_dir:
+                value["evidence_bundle"] = write_evidence_bundle(args.evidence_dir, value)
+            _print(value, args.json)
+            return 0
+        if args.command == "repair":
+            with QtsClient(config) as client:
+                _login(client)
+                identity = sysinfo(client)
+            device = {"origin": config.origin, "model": identity.get("model"), "firmware": identity.get("firmware"), "build": identity.get("build")}
+            plan = unavailable_plan(device, args.action)
+            _save_new_json(args.output, plan)
+            _print({"plan": str(args.output), "plan_id": plan["plan_id"], "status": plan["status"], "refusal_reason": plan["refusal_reason"]}, args.json)
+            return 2
+        if args.command in ("tailscale", "raid", "disk-topology", "smart-details", "services"):
+            ssh_operations = {
+                "tailscale": lambda: tailscale(config),
+                "raid": lambda: raid(config),
+                "disk-topology": lambda: disks_ssh(config),
+                "smart-details": lambda: smart_details(config, args.disk),
+                "services": lambda: services(config),
+            }
+            _print(ssh_operations[args.command](), args.json)
+            return 0
+        operations = {
+            "status": sysinfo,
+            "health": health,
+            "storage": storage,
+            "disks": storage,
+            "volumes": storage,
+            "network": network,
+        }
+        with QtsClient(config) as client:
+            _login(client)
+            if args.command == "whoami":
+                data = sysinfo(client)
+                value = {"username": config.username, "hostname": data.get("hostname"), "model": data.get("model"), "origin": config.origin}
+            elif args.command == "dump":
+                value = dump(client, args.directory)
+            else:
+                if args.command in ("storage", "disks", "volumes", "health"):
+                    indices = getattr(args, "volume_index", None)
+                    value = health(client, indices) if args.command == "health" else storage(client, indices)
+                else:
+                    value = operations[args.command](client)
+        _print(value, args.json)
+        return 0
+    except (QtsError, OSError) as exc:
+        print("error: {}".format(exc), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qnap_nas_cli/client.py

@@ -0,0 +1,201 @@
+import base64
+import hashlib
+import json
+import posixpath
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Dict, Optional
+
+from .config import Config
+from .errors import AuthenticationError, CompatibilityError, QtsError, TwoFactorRequired
+
+
+AUTH_PATH = "/cgi-bin/authLogin.cgi"
+LOGOUT_PATH = "/cgi-bin/authLogout.cgi"
+
+
+def _xml_text(root: ET.Element, tag: str) -> Optional[str]:
+    node = root.find(".//{}".format(tag))
+    return None if node is None else (node.text or "").strip()
+
+
+class QtsClient:
+    def __init__(self, config: Config):
+        self.config = config.validate()
+        self.sid = None  # type: Optional[str]
+        self._ssl_context = ssl.create_default_context()
+        if config.insecure:
+            self._ssl_context.check_hostname = False
+            self._ssl_context.verify_mode = ssl.CERT_NONE
+
+    def _open(self, request: urllib.request.Request) -> bytes:
+        try:
+            with urllib.request.urlopen(request, timeout=self.config.timeout, context=self._ssl_context) as response:
+                return response.read()
+        except urllib.error.HTTPError as exc:
+            body = exc.read(512).decode("utf-8", "replace").replace("\n", " ")
+            raise QtsError("QTS 回傳 HTTP {}：{}".format(exc.code, body or "空白回應")) from exc
+        except urllib.error.URLError as exc:
+            reason = str(exc.reason)
+            if "CERTIFICATE_VERIFY_FAILED" in reason:
+                reason += "（請安裝可信憑證；僅在受信任區網暫時使用 --insecure）"
+            raise QtsError("無法連線至 NAS：{}".format(reason)) from exc
+
+    def login(self, password: str, security_code: Optional[str] = None) -> str:
+        if not password:
+            raise AuthenticationError("密碼不可為空")
+        fields = {
+            "user": self.config.username,
+            "pwd": base64.b64encode(password.encode("utf-8")).decode("ascii"),
+            "serviceKey": "1",
+            "client_app": "qnap-nas-cli",
+        }
+        if security_code:
+            fields["security_code"] = security_code
+            fields["dont_verify_2sv_again"] = "0"
+        body = urllib.parse.urlencode(fields).encode("ascii")
+        request = urllib.request.Request(
+            self.config.origin + AUTH_PATH,
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded", "User-Agent": "qnap-nas-cli/0.1"},
+        )
+        raw = self._open(request)
+        try:
+            root = ET.fromstring(raw)
+        except ET.ParseError as exc:
+            raise CompatibilityError("QTS 登入回應不是預期的 XML") from exc
+        if _xml_text(root, "authPassed") != "1":
+            needs_2fa = _xml_text(root, "need_2_step_verification") == "1" or _xml_text(root, "need_2sv") == "1"
+            if needs_2fa and not security_code:
+                raise TwoFactorRequired("QTS 帳號需要 2FA")
+            if needs_2fa and security_code:
+                raise AuthenticationError("QTS 2FA 驗證失敗；請確認驗證碼與 NAS 時間")
+            code = _xml_text(root, "errorValue") or "unknown"
+            raise AuthenticationError("QTS 登入失敗（errorValue={}）".format(code))
+        sid = _xml_text(root, "authSid")
+        if not sid:
+            raise CompatibilityError("QTS 表示登入成功，但沒有回傳 authSid")
+        self.sid = sid
+        return sid
+
+    def logout(self) -> None:
+        if not self.sid:
+            return
+        try:
+            self.get(LOGOUT_PATH, {}, include_sid=True)
+        except QtsError:
+            pass
+        finally:
+            self.sid = None
+
+    def get(self, path: str, params: Dict[str, str], include_sid: bool = True) -> bytes:
+        request = self._get_request(path, params, include_sid)
+        return self._open(request)
+
+    def _get_request(self, path: str, params: Dict[str, str], include_sid: bool = True) -> urllib.request.Request:
+        query = dict(params)
+        if include_sid:
+            if not self.sid:
+                raise AuthenticationError("尚未登入 QTS")
+            query["sid"] = self.sid
+        url = self.config.origin + path + "?" + urllib.parse.urlencode(query)
+        return urllib.request.Request(url, headers={"User-Agent": "qnap-nas-cli/0.1"})
+
+    def download_file(self, source_path: str, filename: str, target: Path,
+                      max_bytes: int = 100 * 1024 * 1024) -> Dict[str, object]:
+        """Stream one selected File Station file to a new local file, bounded by max_bytes."""
+        if not self.sid:
+            raise AuthenticationError("尚未登入 QTS")
+        if not isinstance(source_path, str) or not source_path.startswith("/") or "\x00" in source_path:
+            raise QtsError("NAS 檔案路徑格式不安全")
+        if any(part in (".", "..") for part in source_path.replace("\\", "/").split("/")):
+            raise QtsError("NAS 檔案路徑不得包含 dot segment")
+        if not isinstance(filename, str) or filename in ("", ".", "..") or "/" in filename or "\\" in filename or "\x00" in filename:
+            raise QtsError("檔名必須是單一安全路徑元件")
+        if type(max_bytes) is not int or not 1 <= max_bytes <= 1024 * 1024 * 1024:
+            raise QtsError("max_bytes 必須介於 1 byte 與 1 GiB")
+
+        target = Path(target)
+        request = self._get_request("/cgi-bin/filemanager/utilRequest.cgi", {
+            "func": "download", "isfolder": "0", "compress": "0",
+            "source_path": posixpath.normpath(source_path), "source_file": filename,
+            "source_total": "1",
+        })
+        digest = hashlib.sha256()
+        byte_count = 0
+        created = False
+        try:
+            with urllib.request.urlopen(request, timeout=self.config.timeout, context=self._ssl_context) as response:
+                content_length = response.headers.get("Content-Length")
+                if content_length and int(content_length) > max_bytes:
+                    raise QtsError("指定檔案超過 rescue 匯出上限 {} bytes".format(max_bytes))
+                content_type = (response.headers.get("Content-Type") or "").lower()
+                if "text/html" in content_type or "application/json" in content_type:
+                    raise QtsError("File Station download 回傳登入頁或 JSON 錯誤，不保存為檔案")
+                with target.open("xb") as output:
+                    created = True
+                    while True:
+                        chunk = response.read(min(1024 * 1024, max_bytes - byte_count + 1))
+                        if not chunk:
+                            break
+                        byte_count += len(chunk)
+                        if byte_count > max_bytes:
+                            raise QtsError("指定檔案超過 rescue 匯出上限 {} bytes".format(max_bytes))
+                        output.write(chunk)
+                        digest.update(chunk)
+        except FileExistsError as exc:
+            raise QtsError("本機 rescue 目標已存在；拒絕覆寫：{}".format(target)) from exc
+        except urllib.error.HTTPError as exc:
+            if created:
+                target.unlink(missing_ok=True)
+            raise QtsError("File Station download 回傳 HTTP {}".format(exc.code)) from exc
+        except urllib.error.URLError as exc:
+            if created:
+                target.unlink(missing_ok=True)
+            raise QtsError("File Station download 連線失敗：{}".format(exc.reason)) from exc
+        except (OSError, ValueError) as exc:
+            if created:
+                try:
+                    target.unlink()
+                except OSError:
+                    pass
+            raise QtsError("File Station download 寫入失敗：{}".format(exc)) from exc
+        except QtsError:
+            if created:
+                try:
+                    target.unlink()
+                except OSError:
+                    pass
+            raise
+        except Exception:
+            if created:
+                try:
+                    target.unlink()
+                except OSError:
+                    pass
+            raise
+        return {"path": str(target), "size_bytes": byte_count, "sha256": digest.hexdigest(), "max_bytes": max_bytes}
+
+    def get_xml(self, path: str, params: Dict[str, str]) -> ET.Element:
+        raw = self.get(path, params)
+        try:
+            return ET.fromstring(raw)
+        except ET.ParseError as exc:
+            raise CompatibilityError("{} 回應不是預期的 XML".format(path)) from exc
+
+    def get_json(self, path: str, params: Dict[str, str]):
+        raw = self.get(path, params)
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, ValueError) as exc:
+            raise CompatibilityError("{} 回應不是預期的 JSON".format(path)) from exc
+
+    def __enter__(self) -> "QtsClient":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.logout()