Add coverage-gap detection: ignored-hrefs registry, Repairs issue, redaction
Implements the first half of the device-capability-diagnostics spec: - registry/capabilities/ignored.py: known-noise hrefs (Bixby/voice provisioning, WiFi/BLE info, OTA/region housekeeping, and a couple of redundant hrefs) declared as no-entity Capability objects, so discover()'s existing unknown-resource reporting treats them as covered instead of flagging every device as having gaps. Folded into each by_type registry and into the global fallback CAPABILITIES set. - discovery.py: log() callback now passes the raw href instead of a formatted message, so callers can collect a clean unbound-hrefs list. - coordinator.py: wires that callback into self._unbound_hrefs, tracks device_type_name/one_ui_version, and raises (or clears) a Repairs issue when a device's type is unrecognized or it has genuinely unmodeled hrefs left over. - registry/redact.py: recursive, substring-keyed redaction for anything that looks like account/identity data, ahead of the diagnostics.py platform that will consume it. Verified against the real dishwasher/refrigerator fixtures: known-noise hrefs no longer show up as gaps, while genuine gaps (e.g. /bespoke/vs/0 on the fridge) still do.
This commit is contained in:
1 parent
b67e0e5cf5
commit
35b47d6b5a
14 files changed
+383
-11
No files matched your search
@@ -1,10 +1,11 @@
|
||||
"""Dishwasher device registry."""
|
||||
from ..capabilities import common, dishwasher, fridge, laundry, operational
|
||||
from ..capabilities import common, dishwasher, fridge, ignored, laundry, operational
|
||||
from ._base import DeviceRegistry, _build
|
||||
|
||||
REGISTRY = DeviceRegistry(
|
||||
name='dishwasher',
|
||||
capabilities=_build([
|
||||
*ignored.IGNORED,
|
||||
common.POWER,
|
||||
common.KIDS_LOCK,
|
||||
common.REMOTE_CONTROL,
|
||||
|
||||
@@ -3,12 +3,13 @@
|
||||
Note: dryer devices use port 49155 (not 49154). The config flow handles
|
||||
this automatically via port probing.
|
||||
"""
|
||||
from ..capabilities import common, dryer, fridge, laundry, operational
|
||||
from ..capabilities import common, dryer, fridge, ignored, laundry, operational
|
||||
from ._base import DeviceRegistry, _build
|
||||
|
||||
REGISTRY = DeviceRegistry(
|
||||
name='dryer',
|
||||
capabilities=_build([
|
||||
*ignored.IGNORED,
|
||||
common.POWER,
|
||||
common.KIDS_LOCK,
|
||||
common.REMOTE_CONTROL,
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
"""Oven device registry."""
|
||||
from ..capabilities import common, fridge, oven
|
||||
from ..capabilities import common, fridge, ignored, oven
|
||||
from ._base import DeviceRegistry, _build
|
||||
|
||||
REGISTRY = DeviceRegistry(
|
||||
name='oven',
|
||||
capabilities=_build([
|
||||
*ignored.IGNORED,
|
||||
common.POWER,
|
||||
common.KIDS_LOCK,
|
||||
common.REMOTE_CONTROL,
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
"""Refrigerator device registry."""
|
||||
from ..capabilities import common, fridge
|
||||
from ..capabilities import common, fridge, ignored
|
||||
from ._base import DeviceRegistry, _build
|
||||
|
||||
REGISTRY = DeviceRegistry(
|
||||
name='refrigerator',
|
||||
capabilities=_build([
|
||||
*ignored.IGNORED,
|
||||
common.POWER,
|
||||
fridge.STATUS_LOCK,
|
||||
fridge.DOOR_ALERT,
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
from . import common, dishwasher, fridge, laundry, operational, oven
|
||||
from . import common, dishwasher, fridge, ignored, laundry, operational, oven
|
||||
from ..capability import Capability
|
||||
|
||||
|
||||
@@ -16,4 +16,4 @@ _OVEN_GLOBAL_CAPS = [
|
||||
]
|
||||
|
||||
ALL = [v for mod in (common, operational, laundry, fridge)
|
||||
for v in vars(mod).values() if _is_capability(v)] + _OVEN_GLOBAL_CAPS
|
||||
for v in vars(mod).values() if _is_capability(v)] + _OVEN_GLOBAL_CAPS + ignored.IGNORED
|
||||
@@ -0,0 +1,67 @@
|
||||
"""Hrefs deliberately not modeled as capabilities.
|
||||
|
||||
Every entry here is either irrelevant plumbing (network/account/OTA
|
||||
housekeeping that will never be home-automation-relevant) or a duplicate of
|
||||
state we already expose through a friendlier href. Declaring them here,
|
||||
rather than leaving them unregistered, keeps discover()'s unknown-resource
|
||||
reporting limited to genuine coverage gaps.
|
||||
|
||||
Capability defaults entities=() and discover() treats any href that
|
||||
resolves to a capability at all as matched, even one with no entities, so
|
||||
this list uses the same declaration shape as a real capability with no
|
||||
extra machinery. Fold into by_type registries (per-family gap detection)
|
||||
and into the global ALL list (unknown-device-type fallback).
|
||||
|
||||
Deliberately exact hrefs only, no href_prefix/pattern capabilities: the
|
||||
unknown-device-type fallback path (coordinator's `discover(resources,
|
||||
CAPABILITIES)` call) doesn't pass pattern_caps, so a prefix-based entry
|
||||
here would silently do nothing on that path. Enumerate each known href
|
||||
instead; it's a short, stable list.
|
||||
|
||||
This list is maintainer-curated only; there is no per-installation
|
||||
override. Grow it as real /device/0 dumps surface more universal noise —
|
||||
do not add a href here on a guess. If a href's relevance is unclear, leave
|
||||
it unbound so it surfaces as a gap for a human to look at.
|
||||
"""
|
||||
from ..capability import Capability
|
||||
|
||||
IGNORED: list[Capability] = [
|
||||
# Device serial/model is read directly by the coordinator for HA device
|
||||
# identity, not modeled as an entity capability.
|
||||
Capability(href='/information/vs/0'),
|
||||
|
||||
# Bixby voice assistant: feature negotiation, account provisioning
|
||||
# (Samsung account email, access tokens), terms-of-service state, and
|
||||
# enable/disable status.
|
||||
Capability(href='/voice/feature/vs/0'),
|
||||
Capability(href='/voice/provisioning/vs/0'),
|
||||
Capability(href='/bixby/vs/0'),
|
||||
Capability(href='/bixby/status/vs/0'),
|
||||
Capability(href='/bixbyuservalidate/vs/0'),
|
||||
Capability(href='/bixbyterms/vs/0'),
|
||||
|
||||
# Network/WiFi housekeeping — MAC addresses, supported auth/crypto
|
||||
# types, no controllable or observable appliance state.
|
||||
Capability(href='/wirelessinfo/vs/0'),
|
||||
Capability(href='/connectionconfig/vs/0'),
|
||||
|
||||
# Static or internal-protocol metadata, not entity-worthy.
|
||||
Capability(href='/quickcontrol/info/vs/0'),
|
||||
Capability(href='/realtimenotiforclient/vs/0'),
|
||||
Capability(href='/file/information/vs/0'),
|
||||
Capability(href='/configuration/vs/0'), # region/countryCode
|
||||
Capability(href='/setting/vs/0'), # supported/selected UI language
|
||||
Capability(href='/timezone/vs/0'), # redundant with HA's own timezone
|
||||
Capability(href='/wm/setinfo/vs/0'), # model/manufacturing metadata
|
||||
|
||||
# Demand Response Load Control — utility-company grid signals; requires
|
||||
# cloud registration with a utility program we don't support locally.
|
||||
Capability(href='/drlc/vs/0'),
|
||||
|
||||
# Redundant with capabilities already declared elsewhere.
|
||||
# /speakersound/vs/0 duplicates /settings/sound/volume/vs/0 (laundry.SOUND_VOLUME).
|
||||
Capability(href='/speakersound/vs/0'),
|
||||
# /wm/editcourse/vs/0 is the raw encoded course-list byte string already
|
||||
# decoded and exposed via /course/vs/0 (dishwasher.CYCLE_OPTIONS).
|
||||
Capability(href='/wm/editcourse/vs/0'),
|
||||
]
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
A device advertises a set of OCF resources keyed by href. For every href
|
||||
present in the registry, emit the capability's entities bound to that resource.
|
||||
Unknown hrefs are a coverage gap, logged at debug and skipped.
|
||||
Unknown hrefs are a coverage gap; each one is passed to the optional `log`
|
||||
callback (as the raw href, not a formatted message) and otherwise skipped.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -79,6 +80,6 @@ def discover(
|
||||
break
|
||||
|
||||
if not matched and log is not None:
|
||||
log(f"unknown resource {href}")
|
||||
log(href)
|
||||
|
||||
return out
|
||||
@@ -0,0 +1,41 @@
|
||||
"""Redact account/identity data from a raw resource tree before it leaves
|
||||
the user's Home Assistant instance (diagnostics downloads, issue reports).
|
||||
|
||||
/device/0 dumps mix appliance state with genuinely sensitive data when
|
||||
Bixby/voice is set up on the device: a Samsung account email, a Bixby
|
||||
access token, a hashed device ID, WiFi/BLE MAC addresses, the serial
|
||||
number, and otnDUID. This walks the whole tree and redacts any value whose
|
||||
key matches a known-sensitive substring, regardless of which href it's
|
||||
under — new device types will have unknown-shaped data we can't fully
|
||||
enumerate in advance, so this errs on catching the field by name rather
|
||||
than only redacting inside hrefs we already recognize.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
REDACTED = "**REDACTED**"
|
||||
|
||||
_SENSITIVE_SUBSTRINGS = (
|
||||
'mac', 'serial', 'token', 'login', 'account', 'email',
|
||||
'userid', 'deviceid', 'uuid', 'duid', 'password', 'secret',
|
||||
)
|
||||
|
||||
|
||||
def _is_sensitive_key(key: str) -> bool:
|
||||
lowered = key.lower()
|
||||
return any(s in lowered for s in _SENSITIVE_SUBSTRINGS)
|
||||
|
||||
|
||||
def redact_resources(resources):
|
||||
"""Recursively redact dict values whose key matches a sensitive substring.
|
||||
|
||||
Works on the shape produced by parse_device0_batch (dict[href, rep]) or
|
||||
any nested dict/list structure within a rep.
|
||||
"""
|
||||
if isinstance(resources, dict):
|
||||
return {
|
||||
key: (REDACTED if _is_sensitive_key(key) else redact_resources(value))
|
||||
for key, value in resources.items()
|
||||
}
|
||||
if isinstance(resources, list):
|
||||
return [redact_resources(item) for item in resources]
|
||||
return resources
|
||||
Reference in new issue
Block a user