ha-mcp-dev 9.1.0.dev3265__tar.gz → 9.1.0.dev3267__tar.gz

{ha_mcp_dev-9.1.0.dev3265 → ha_mcp_dev-9.1.0.dev3267}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3265
+Version: 9.1.0.dev3267
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3265 → ha_mcp_dev-9.1.0.dev3267}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3265"
+version = "9.1.0.dev3267"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3265 → ha_mcp_dev-9.1.0.dev3267}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3265"
+version = "9.1.0.dev3267"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.1.0.dev3265 → ha_mcp_dev-9.1.0.dev3267}/src/ha_mcp/client/rest_client.py

@@ -1308,7 +1308,7 @@ class HomeAssistantClient:
     ) -> str:
         """Fetch app (add-on) container logs directly from Supervisor REST.
 
-        Distinct from ``tools_bug_report._fetch_addon_logs``: that auxiliary
+        Distinct from ``bug_report_sources._fetch_addon_logs``: that auxiliary
         helper uses the app self-service path ``/addons/self/logs`` and may skip
         failures. This helper takes arbitrary slugs and surfaces failures because
         callers (``ha_get_logs(source="supervisor", slug=...)``) need them.

ha_mcp_dev-9.1.0.dev3267/src/ha_mcp/tools/bug_report_redaction.py

@@ -0,0 +1,243 @@
+"""Secret and identifier scrubbing for ha_report_issue output.
+
+Dependency-free on purpose: only the standard library, so the rules can be
+exercised in isolation.
+"""
+
+import ipaddress
+import os
+import re
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from functools import lru_cache
+
+
+@dataclass(frozen=True)
+class KnownIdentifiers:
+    """This instance's own hostnames and addresses, read from Home Assistant."""
+
+    hosts: frozenset[str] = frozenset()
+    addresses: frozenset[str] = frozenset()
+
+
+_NO_IDENTIFIERS = KnownIdentifiers()
+
+# A ContextVar rather than a parameter: the scrubber is called from a dozen
+# synchronous sites while one report is assembled.
+_known_identifiers: ContextVar[KnownIdentifiers] = ContextVar(
+    "bug_report_known_identifiers", default=_NO_IDENTIFIERS
+)
+
+
+@contextmanager
+def known_identifiers_scope(identifiers: KnownIdentifiers) -> Iterator[None]:
+    """Make ``_sanitize_log_text`` redact ``identifiers`` within the block."""
+    token = _known_identifiers.set(identifiers)
+    try:
+        yield
+    finally:
+        _known_identifiers.reset(token)
+
+
+# Two or more colon-separated hex groups, optionally ending in a dotted quad
+# (``::ffff:192.0.2.1``); ``hh:mm:ss`` and other non-addresses fail to parse in
+# the callback and are left alone. A preceding label colon (``address:``) is
+# allowed: the leftmost match always consumes a whole address, so a candidate
+# never starts inside a longer one.
+_IPV6_CANDIDATE_RE = re.compile(
+    r"(?<![\w.])(?:[0-9A-Fa-f]{0,4}:){2,7}"
+    r"(?:\d{1,3}(?:\.\d{1,3}){3}|[0-9A-Fa-f]{0,4})(?![\w:]|\.\d)"
+)
+
+
+def _parse_v6(value: str) -> ipaddress.IPv6Address | None:
+    try:
+        return ipaddress.IPv6Address(value)
+    except ValueError:
+        return None
+
+
+def _alternation(values: frozenset[str]) -> str:
+    # Longest first, so an alternative never stops short inside a longer one.
+    return "|".join(re.escape(v) for v in sorted(values, key=len, reverse=True))
+
+
+@lru_cache(maxsize=8)
+def _known_identifier_rules(
+    identifiers: KnownIdentifiers,
+) -> tuple[tuple[re.Pattern[str], str | Callable[[re.Match[str]], str]], ...]:
+    """Whole-token patterns: a known value never matches inside a longer
+    address or hostname, but does match before ``:port``, ``/``, a quote,
+    a bracket, a comma or a sentence-ending dot."""
+    rules: list[tuple[re.Pattern[str], str | Callable[[re.Match[str]], str]]] = []
+    ipv4 = frozenset(a for a in identifiers.addresses if ":" not in a)
+    ipv6 = identifiers.addresses - ipv4
+    if ipv4:
+        rules.append(
+            (
+                re.compile(rf"(?<![\w.-])(?:{_alternation(ipv4)})(?![\w-]|\.[\w-])"),
+                "[IP]",
+            )
+        )
+    if ipv6:
+        # An IPv6 address has many spellings (``::`` vs zero groups, leading
+        # zeros), so candidates are parsed and compared, not matched as text.
+        known_v6 = frozenset(_parse_v6(a) for a in ipv6) - {None}
+
+        def _redact_v6(match: re.Match[str]) -> str:
+            try:
+                parsed = ipaddress.IPv6Address(match.group(0))
+            except ValueError:
+                return match.group(0)
+            return "[IP]" if parsed in known_v6 else match.group(0)
+
+        if known_v6:
+            rules.append((_IPV6_CANDIDATE_RE, _redact_v6))
+    if identifiers.hosts:
+        rules.append(
+            (
+                re.compile(
+                    rf"(?<![\w.-])(?:{_alternation(identifiers.hosts)})(?![\w-]|\.[\w-])",
+                    re.IGNORECASE,
+                ),
+                "[HA_HOST]",
+            )
+        )
+    return tuple(rules)
+
+
+# IPv4 sanitization: only redact addresses with strong network context so that
+# four-segment version strings (e.g. "ha-mcp version 1.2.3.4") are preserved.
+_IPV4_OCTET = r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)"
+
+_IPV4 = rf"(?:{_IPV4_OCTET}\.){{3}}{_IPV4_OCTET}"
+
+# IP followed by :port or /CIDR — always a network address, never a version.
+_IPV4_WITH_PORT_OR_CIDR_RE = re.compile(rf"\b{_IPV4}(?::\d+|/\d{{1,2}})\b(?!\.\d)")
+
+# IP preceded by a network keyword (from, to, host=, host='...', addr=, etc.).
+_IPV4_AFTER_KEYWORD_RE = re.compile(
+    rf"\b((?:from|to|host|hostname|addr|address|ip|src|dst|server|client|peer|via)\b\s*[=:]?\s*['\"]?){_IPV4}\b(?!\.\d)",
+    re.IGNORECASE,
+)
+
+# IP appearing inside a URL (`scheme://1.2.3.4...`).
+_IPV4_IN_URL_RE = re.compile(rf"(://){_IPV4}\b(?!\.\d)")
+
+# Plex wildcard DNS puts the server address in ``1-2-3-4.<hex>.plex.direct``.
+_PLEX_DIRECT_DASHED_IPV4_RE = re.compile(
+    rf"\b(?:{_IPV4_OCTET}-){{3}}{_IPV4_OCTET}(?=\.[^\s.]+\.plex\.direct\b)",
+    re.IGNORECASE,
+)
+# Internal hostnames. A match starts only where a name starts, so a long dotted
+# run stays linear instead of being rescanned from every label.
+_LAN_HOST_RE = re.compile(
+    r"(?<![\w.-])(?:[A-Za-z0-9-]+\.)+lan(?![\w-]|\.[\w-])", re.IGNORECASE
+)
+_TAILNET_HOST_RE = re.compile(
+    r"(?<![\w.-])(?:[A-Za-z0-9-]+\.)+ts\.net(?![\w-]|\.[\w-])", re.IGNORECASE
+)
+# Microsoft Graph calendar ID in a URL path.
+_GRAPH_CALENDAR_ID_RE = re.compile(r"(/me/calendars/)[^/?#\s'\"]+", re.IGNORECASE)
+
+
+# URL userinfo, anchored on "://" rather than on the scheme: a match that began
+# at the scheme made every character of a long unbroken word a candidate start,
+# quadratic in its length (about a minute for a 200 kB base64 blob).
+_URL_USERINFO_RE = re.compile(r"(://)([^:/?#\s@]+):([^@/\s]+)@")
+
+
+def _sanitize_log_text(text: str) -> str:
+    """Best-effort secret scrubber for log text.
+
+    Defense-in-depth, not exhaustive — bug reports still pass through human
+    review (see ``_generate_anonymization_guide``). Rules cover the most common
+    leak shapes seen in HA add-on logs:
+    JWTs, bearer tokens, long hex tokens, ``key=value`` style credentials,
+    URL userinfo, IPv4 addresses with network context (including quoted and
+    ``*.plex.direct`` dashed forms), ``.lan`` and tailnet ``.ts.net`` hostnames,
+    Microsoft Graph calendar IDs, and the MCP connect-URL secret path (the
+    add-on's LAN auth). Inside known_identifiers_scope this instance's own
+    hostnames and addresses are redacted first, wherever they appear.
+    """
+    for pattern, replacement in _known_identifier_rules(_known_identifiers.get()):
+        text = pattern.sub(replacement, text)
+    # JWT tokens (header.payload.signature)
+    text = re.sub(
+        r"eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+",
+        "[REDACTED_JWT]",
+        text,
+    )
+    # Bearer tokens — match any casing (BEARER, Bearer, bearer, BeArEr, …)
+    # via re.IGNORECASE, but preserve the original casing in the output by
+    # echoing m.group(1) back through the lambda.
+    text = re.sub(
+        r"\b(bearer)\s+\S+",
+        lambda m: f"{m.group(1)} [REDACTED]",
+        text,
+        flags=re.IGNORECASE,
+    )
+    # Authorization values in any other scheme (Basic, Digest, ...). The
+    # Bearer rule above has already handled Bearer, so it is skipped here.
+    text = re.sub(
+        r"\b(authorization['\"]?\s*[:=]\s*['\"]?)(?!bearer\b)(?:[A-Za-z]+\s+)?[^\s'\",}]+",
+        r"\1[REDACTED]",
+        text,
+        flags=re.IGNORECASE,
+    )
+    # Generic key=value credentials (api_key, token, secret, password, etc.).
+    # Negative lookbehind for a letter so OPENAI_API_KEY=... still matches
+    # (underscore is a word-char, so \b doesn't fire there).
+    # "authorization" has its own rule above.
+    # A quoted key and value, as in JSON or a Python dict repr, are covered
+    # too: {"token": "a b"} and {'password': 'x'}.
+    text = re.sub(
+        r"(?<![A-Za-z])(api[_-]?key|access[_-]?key|secret[_-]?key|token|secret|password|passwd)\b"
+        r"(['\"]?\s*[:=]\s*)(?:\"[^\"]*\"|'[^']*'|[^\s,}]+)",
+        r"\1\2[REDACTED]",
+        text,
+        flags=re.IGNORECASE,
+    )
+    # URL userinfo: scheme://user:password@host -> scheme://user:[REDACTED]@host
+    text = _URL_USERINFO_RE.sub(r"\1\2:[REDACTED]@", text)
+    # Long hex strings (API keys, tokens) - 32+ contiguous hex chars
+    text = re.sub(
+        r"(?<![a-fA-F0-9])[a-fA-F0-9]{32,}(?![a-fA-F0-9])",
+        "[REDACTED_HEX]",
+        text,
+    )
+    # IPv4 addresses — only when there's strong network context, so that
+    # four-segment version strings (e.g. "version 1.2.3.4") survive intact.
+    text = _IPV4_WITH_PORT_OR_CIDR_RE.sub("[IP]", text)
+    text = _IPV4_IN_URL_RE.sub(r"\1[IP]", text)
+    text = _IPV4_AFTER_KEYWORD_RE.sub(r"\1[IP]", text)
+    text = _PLEX_DIRECT_DASHED_IPV4_RE.sub("[IP]", text)
+    text = _TAILNET_HOST_RE.sub("[TAILNET_HOST]", text)
+    text = _LAN_HOST_RE.sub("[HOST]", text)
+    text = _GRAPH_CALENDAR_ID_RE.sub(r"\1[CALENDAR_ID]", text)
+    # MCP connect-URL secret path — the add-on's LAN auth. Redact by the
+    # configured value (catches custom paths) and the generated
+    # ``/private_<token>`` convention. Only bug-report output is scrubbed here;
+    # the raw logs this text is copied from are left intact.
+    # The dedicated settings-UI secret path (OAuth/OIDC) is a second secret whose
+    # leak grants the same unauthenticated settings access, so redact a custom
+    # value the same way. The auto-generated /private_<token> form is caught by
+    # the generic pattern below.
+    for env_name in ("MCP_SECRET_PATH", "MCP_SETTINGS_SECRET_PATH"):
+        # Strip before rstrip: the resolver strips MCP_SETTINGS_SECRET_PATH before
+        # mounting, so a whitespace-bearing value mounts at the stripped path — the
+        # redaction pattern must match that, not the raw value (GHSA-mx64-982r-65vg).
+        configured = os.getenv(env_name, "").strip().rstrip("/")
+        if configured and configured != "/mcp":
+            # Anchor on a path-segment boundary so a short/substring-prone
+            # configured value (e.g. "/ha") cannot corrupt unrelated text
+            # (e.g. "/happy").
+            text = re.sub(
+                re.escape(configured) + r"(?![A-Za-z0-9_-])",
+                "[REDACTED_SECRET_PATH]",
+                text,
+            )
+    text = re.sub(r"/private_[A-Za-z0-9_-]+", "[REDACTED_SECRET_PATH]", text)
+    return text

ha_mcp_dev-9.1.0.dev3267/src/ha_mcp/tools/bug_report_sources.py

@@ -0,0 +1,284 @@
+"""Best-effort collectors for ha_report_issue: logs, this instance's own
+identifiers, and Home Assistant's install facts. None of them raises."""
+
+import asyncio
+import contextlib
+import ipaddress
+import logging
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from .._version import is_running_in_addon
+from ..client.supervisor_client import make_supervisor_httpx_client
+from ..config import get_global_settings
+from .bug_report_redaction import KnownIdentifiers, _sanitize_log_text
+from .coercion import ANSI_ESCAPE_RE
+from .helpers import get_connected_ws_client
+
+logger = logging.getLogger(__name__)
+
+# Max characters to include from addon container logs.
+# 3000 chars ≈ 750 LLM tokens — keeps the tool response well below context budgets
+# while still capturing enough recent output to diagnose most issues.
+_ADDON_LOG_MAX_CHARS = 3000
+
+# Max characters to include from the Home Assistant error log (home-assistant.log).
+# Slightly larger than the addon cap: this log carries the highest-value
+# diagnostic lines (auth failures, integration tracebacks) and the recent tail
+# is where they land. ~5000 chars ≈ 1250 LLM tokens.
+_CORE_LOG_MAX_CHARS = 5000
+
+# Log window requested from the install for that tail. Only the last
+# _CORE_LOG_MAX_CHARS survive into the report — a few dozen lines of typical
+# HA log text — so anything deeper is fetched and then thrown away, which on
+# Supervisor-backed installs is exactly the cost that made the unconditional
+# 20,000-line fetch hang (#2279). 500 keeps an order of magnitude of headroom
+# for short lines.
+_CORE_LOG_WINDOW_LINES = 500
+
+
+async def _fetch_addon_logs() -> str:
+    """Fetch ha-mcp addon container logs via the Supervisor REST API.
+
+    Only works when running as a Home Assistant add-on (SUPERVISOR_TOKEN set).
+    Uses /addons/self/logs which resolves to the calling addon's own logs via
+    the Supervisor's per-addon token binding — no slug interpolation needed.
+
+    Direct httpx against ``http://supervisor`` is the documented add-on access
+    pattern: it uses the Supervisor token directly (no extra HA hop) and
+    preserves the ``self`` shortcut, which the WebSocket ``supervisor/api``
+    proxy used by other tools may not.
+
+    Returns sanitized log text (last _ADDON_LOG_MAX_CHARS chars, with a
+    truncation marker prepended when truncation occurs), or empty string on
+    failure.
+    """
+    # Redundant with the caller's `install_method == "addon"` gate, but kept
+    # as a defensive guard for any direct callers added later.
+    if not is_running_in_addon():
+        return ""
+
+    try:
+        async with make_supervisor_httpx_client(
+            timeout=10.0, verify=get_global_settings().verify_ssl
+        ) as http_client:
+            resp = await http_client.get("/addons/self/logs")
+            if resp.status_code != 200:
+                logger.info("Addon log fetch returned HTTP %s", resp.status_code)
+                return ""
+
+            # Strip ANSI escape codes first, then sanitize, then truncate.
+            # Sanitizing before truncating prevents secrets that straddle the
+            # truncation boundary from leaking through.
+            cleaned = ANSI_ESCAPE_RE.sub("", resp.text)
+            sanitized = _sanitize_log_text(cleaned)
+            if len(sanitized) > _ADDON_LOG_MAX_CHARS:
+                marker = (
+                    f"[...truncated, showing last {_ADDON_LOG_MAX_CHARS} of "
+                    f"{len(sanitized)} chars...]\n"
+                )
+                return marker + sanitized[-_ADDON_LOG_MAX_CHARS:]
+            return sanitized
+    except httpx.RequestError as e:
+        logger.warning(f"Failed to fetch addon logs: {e}")
+
+    return ""
+
+
+async def _fetch_core_error_log(client: Any) -> str:
+    """Fetch the Home Assistant error log (home-assistant.log) via the client.
+
+    Works on every install type — ``HomeAssistantClient.get_error_log`` routes
+    add-on installs to the Supervisor, supervised/HAOS to the hassio proxy, and
+    container/pip to ``/api/error_log``. Captured over REST, which stays up even
+    when the WebSocket path is failing; that is exactly the failure mode in
+    issue #1694, where the high-value auth lines
+    (``InsecureKeyLengthWarning``, "invalid authentication") only appeared in
+    home-assistant.log, not in the add-on log this tool already captured.
+
+    Best-effort: returns sanitized text (last ``_CORE_LOG_MAX_CHARS`` chars of a
+    ``_CORE_LOG_WINDOW_LINES`` window, with a truncation marker prepended) or an
+    empty string on any failure, so a log-fetch problem never breaks the
+    bug-report path.
+    """
+    try:
+        page = await client.get_error_log(lines=_CORE_LOG_WINDOW_LINES)
+    except Exception as e:  # noqa: BLE001
+        # Broad by design — the bug-report path must stay robust whatever the
+        # client raises (auth, role, connection, transport). Logged at INFO so
+        # a missing error log is visible without alarming on a routine 403.
+        logger.info(
+            "Could not fetch HA error log for bug report: %s (%s)",
+            e,
+            type(e).__name__,
+        )
+        return ""
+
+    if not page.text:
+        return ""
+
+    # Strip ANSI, then sanitize, then truncate — sanitizing before truncating
+    # keeps a secret straddling the cut boundary from leaking through.
+    sanitized = _sanitize_log_text(ANSI_ESCAPE_RE.sub("", page.text))
+    if len(sanitized) > _CORE_LOG_MAX_CHARS:
+        marker = (
+            f"[...truncated, showing last {_CORE_LOG_MAX_CHARS} of "
+            f"{len(sanitized)} chars...]\n"
+        )
+        return marker + sanitized[-_CORE_LOG_MAX_CHARS:]
+    return sanitized
+
+
+# Kept from system_health's ``homeassistant`` block. The rest (user,
+# config_dir, timezone) describes the person's setup rather than the install.
+_HA_INSTALL_KEYS = (
+    "installation_type",
+    "os_name",
+    "os_version",
+    "arch",
+    "python_version",
+    "container_arch",
+    "docker",
+    "hassio",
+    "dev",
+)
+
+
+def _add_host(host: str, hosts: set[str], addresses: set[str]) -> None:
+    # A configured URL may spell the name as an absolute FQDN (trailing dot);
+    # logs never do, so the stored name must not carry it.
+    host = host.rstrip(".")
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        # A single-label name (``supervisor`` for the app's proxy URL,
+        # ``homeassistant``, ``localhost``) is generic, and redacting it would
+        # blank every ordinary use of the word in the logs.
+        if "." in host:
+            hosts.add(host.lower())
+        return
+    if not address.is_loopback:
+        addresses.add(host.lower())
+
+
+def _add_url_host(url: Any, hosts: set[str], addresses: set[str]) -> None:
+    try:
+        host = urlparse(url).hostname if isinstance(url, str) else None
+    except ValueError:
+        # A malformed URL has no usable host; the report is still built.
+        return
+    if host:
+        _add_host(host, hosts, addresses)
+
+
+class _UnsuccessfulReply(Exception):
+    """A WebSocket command Home Assistant answered with an error."""
+
+
+# Each read gets its own short deadline: a silent socket must not add the
+# default 30 s command wait, twice, before the report is assembled. The reply
+# wait is the command's own; the outer deadline also covers connecting, which
+# the pooled client bounds separately at about 20 s.
+_IDENTIFIER_READ_TIMEOUT_S = 10.0
+_IDENTIFIER_READ_DEADLINE_S = 15.0
+
+
+async def _ws_result(client: Any, command: str) -> Any:
+    reply = await client.send_websocket_message(
+        {"type": command, "_wait_timeout": _IDENTIFIER_READ_TIMEOUT_S}
+    )
+    if not reply.get("success"):
+        raise _UnsuccessfulReply(reply.get("error_code") or "unsuccessful reply")
+    return reply.get("result")
+
+
+async def _read_identifiers(
+    client: Any, command: str, consume: Callable[[Any], None]
+) -> str | None:
+    """Run one read and hand its result to ``consume``; a failure becomes the
+    reason text for the caller's warning instead of an exception."""
+    try:
+        consume(
+            await asyncio.wait_for(
+                _ws_result(client, command), timeout=_IDENTIFIER_READ_DEADLINE_S
+            )
+        )
+    except Exception as e:  # noqa: BLE001
+        # The error text could carry the very hostnames being collected, so
+        # only Home Assistant's error code or the exception type is reported.
+        reason = str(e) if isinstance(e, _UnsuccessfulReply) else type(e).__name__
+        logger.info("Known-identifier read failed at %s: %s", command, reason)
+        return f"{command}: {reason}"
+    return None
+
+
+async def collect_known_identifiers(
+    client: Any,
+) -> tuple[KnownIdentifiers, str | None]:
+    """Read this instance's URLs and interface addresses for redaction.
+
+    Returns the identifiers and, when a read failed, one warning for the
+    caller. The reads are independent and whatever was collected is kept: the
+    server's own Home Assistant host needs no read at all, ``network/url``
+    answers a non-admin token while ``network`` (``require_admin`` in Core)
+    does not, and a transient failure of one read must not drop the other.
+    Loopback addresses are left out: they identify nobody.
+    """
+    hosts: set[str] = set()
+    addresses: set[str] = set()
+    _add_url_host(getattr(client, "base_url", None), hosts, addresses)
+
+    def _urls(urls: Any) -> None:
+        for key in ("internal", "external", "cloud"):
+            _add_url_host(urls.get(key), hosts, addresses)
+
+    def _adapters(network: Any) -> None:
+        for adapter in network.get("adapters") or []:
+            for entry in (adapter.get("ipv4") or []) + (adapter.get("ipv6") or []):
+                if entry.get("address"):
+                    _add_host(str(entry["address"]), hosts, addresses)
+
+    failures = [
+        failure
+        for failure in (
+            await _read_identifiers(client, "network/url", _urls),
+            await _read_identifiers(client, "network", _adapters),
+        )
+        if failure
+    ]
+    warning = (
+        f"Known-identifier redaction is partial ({'; '.join(failures)}); "
+        "review hostnames and addresses by hand."
+        if failures
+        else None
+    )
+    return KnownIdentifiers(frozenset(hosts), frozenset(addresses)), warning
+
+
+async def fetch_ha_install(client: Any) -> dict[str, Any] | None:
+    """Read Home Assistant's install facts from ``system_health/info``.
+
+    ``None`` when the WebSocket cannot be opened or the reply does not arrive.
+    """
+    ws_client = None
+    try:
+        ws_client, _ = await get_connected_ws_client(
+            client.base_url, client.token, verify_ssl=client.verify_ssl
+        )
+        if ws_client is None:
+            return None
+        _, event_response = await ws_client.send_command_with_event(
+            "system_health/info", wait_timeout=10.0
+        )
+        info = event_response["event"]["data"]["homeassistant"]["info"]
+        return {key: info[key] for key in _HA_INSTALL_KEYS if key in info}
+    except Exception as e:  # noqa: BLE001
+        logger.info("system_health read for the report failed: %s", e)
+        return None
+    finally:
+        if ws_client is not None:
+            with contextlib.suppress(Exception):
+                await ws_client.disconnect()