Implement MAC address exclude list in nmap_tracker (home-assistant#142724)

Co-authored-by: Erik <[email protected]>

Author: tedvdb

homeassistant/components/nmap_tracker/__init__.py

@@ -29,6 +29,7 @@
 
 from .const import (
     CONF_HOME_INTERVAL,
+    CONF_MAC_EXCLUDE,
     CONF_OPTIONS,
     DOMAIN,
     NMAP_TRACKED_DEVICES,
@@ -145,6 +146,7 @@ def __init__(
         self._hosts = None
         self._options = None
         self._exclude = None
+        self._mac_exclude = None
         self._scan_interval = None
 
         self._known_mac_addresses: dict[str, str] = {}
@@ -161,6 +163,7 @@ async def async_setup(self):
         self._hosts = [host for host in hosts_list if host != ""]
         excludes_list = cv.ensure_list_csv(config[CONF_EXCLUDE])
         self._exclude = [exclude for exclude in excludes_list if exclude != ""]
+        self._mac_exclude = config.get(CONF_MAC_EXCLUDE, [])
         self._options = config[CONF_OPTIONS]
         self.home_interval = timedelta(
             minutes=cv.positive_int(config[CONF_HOME_INTERVAL])
@@ -377,6 +380,11 @@ async def _async_run_nmap_scan(self):
                 continue
 
             formatted_mac = format_mac(mac)
+
+            if formatted_mac in self._mac_exclude:
+                _LOGGER.debug("MAC address %s is excluded from tracking", formatted_mac)
+                continue
+
             if (
                 devices.config_entry_owner.setdefault(formatted_mac, entry_id)
                 != entry_id

homeassistant/components/nmap_tracker/config_flow.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from ipaddress import ip_address, ip_network, summarize_address_range
+import re
 from typing import Any
 
 import voluptuous as vol
@@ -23,10 +24,13 @@
 from homeassistant.const import CONF_EXCLUDE, CONF_HOSTS
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers import config_validation as cv
+from homeassistant.helpers.device_registry import format_mac
+from homeassistant.helpers.selector import TextSelector, TextSelectorConfig
 from homeassistant.helpers.typing import VolDictType
 
 from .const import (
     CONF_HOME_INTERVAL,
+    CONF_MAC_EXCLUDE,
     CONF_OPTIONS,
     DEFAULT_OPTIONS,
     DOMAIN,
@@ -86,6 +90,31 @@ def _normalize_ips_and_network(hosts_str: str) -> list[str] | None:
     return normalized_hosts
 
 
+def _is_valid_mac(mac_address: str) -> bool:
+    """Check if a mac address is valid."""
+    is_valid_mac = re.fullmatch(
+        r"[0-9A-F]{12}", string=mac_address, flags=re.IGNORECASE
+    )
+    if is_valid_mac is not None:
+        return True
+    return False
+
+
+def _normalize_mac_addresses(mac_addresses: list[str]) -> list[str] | None:
+    """Check if a list of mac addresses are all valid."""
+    normalized_mac_addresses = []
+
+    for mac_address in sorted(mac_addresses):
+        mac_address = mac_address.replace(":", "").replace("-", "").upper().strip()
+        if not _is_valid_mac(mac_address):
+            return None
+
+        formatted_mac_address = format_mac(mac_address)
+        normalized_mac_addresses.append(formatted_mac_address)
+
+    return normalized_mac_addresses
+
+
 def normalize_input(user_input: dict[str, Any]) -> dict[str, str]:
     """Validate hosts and exclude are valid."""
     errors = {}
@@ -101,6 +130,12 @@ def normalize_input(user_input: dict[str, Any]) -> dict[str, str]:
     else:
         user_input[CONF_EXCLUDE] = ",".join(normalized_exclude)
 
+    normalized_mac_exclude = _normalize_mac_addresses(user_input[CONF_MAC_EXCLUDE])
+    if normalized_mac_exclude is None:
+        errors[CONF_MAC_EXCLUDE] = "invalid_hosts"
+    else:
+        user_input[CONF_MAC_EXCLUDE] = normalized_mac_exclude
+
     return errors
 
 
@@ -111,12 +146,17 @@ async def _async_build_schema_with_user_input(
     exclude = user_input.get(
         CONF_EXCLUDE, await network.async_get_source_ip(hass, MDNS_TARGET_IP)
     )
+    mac_exclude = user_input.get(CONF_MAC_EXCLUDE, [])
+
     schema: VolDictType = {
         vol.Required(CONF_HOSTS, default=hosts): str,
         vol.Required(
             CONF_HOME_INTERVAL, default=user_input.get(CONF_HOME_INTERVAL, 0)
         ): int,
         vol.Optional(CONF_EXCLUDE, default=exclude): str,
+        vol.Optional(CONF_MAC_EXCLUDE, default=mac_exclude): TextSelector(
+            TextSelectorConfig(multiple=True)
+        ),
         vol.Optional(
             CONF_OPTIONS, default=user_input.get(CONF_OPTIONS, DEFAULT_OPTIONS)
         ): str,

homeassistant/components/nmap_tracker/const.py

@@ -13,6 +13,7 @@
 # Interval in minutes to exclude devices from a scan while they are home
 CONF_HOME_INTERVAL: Final = "home_interval"
 CONF_OPTIONS: Final = "scan_options"
+CONF_MAC_EXCLUDE: Final = "mac_exclude"
 DEFAULT_OPTIONS: Final = "-n -sn -PR -T4 --min-rate 10 --host-timeout 5s"
 
 TRACKER_SCAN_INTERVAL: Final = 120

homeassistant/components/nmap_tracker/strings.json

@@ -9,6 +9,7 @@
           "home_interval": "[%key:component::nmap_tracker::config::step::user::data::home_interval%]",
           "consider_home": "Seconds to wait till marking a device tracker as not home after not being seen.",
           "exclude": "[%key:component::nmap_tracker::config::step::user::data::exclude%]",
+          "mac_exclude": "[%key:component::nmap_tracker::config::step::user::data::mac_exclude%]",
           "scan_options": "[%key:component::nmap_tracker::config::step::user::data::scan_options%]",
           "interval_seconds": "Scan interval"
         }
@@ -21,11 +22,12 @@
   "config": {
     "step": {
       "user": {
-        "description": "Configure hosts to be scanned by Nmap. Network address and excludes can be IP addresses (192.168.1.1), IP networks (192.168.0.0/24) or IP ranges (192.168.1.0-32).",
+        "description": "Configure hosts to be scanned by Nmap. IP address and excludes can be addresses (192.168.1.1), networks (192.168.0.0/24) or ranges (192.168.1.0-32).",
         "data": {
-          "hosts": "Network addresses (comma-separated) to scan",
+          "hosts": "IP addresses or ranges (comma-separated) to scan",
           "home_interval": "Minimum number of minutes between scans of active devices (preserve battery)",
-          "exclude": "Network addresses (comma-separated) to exclude from scanning",
+          "exclude": "IP addresses (comma-separated) to exclude from tracking",
+          "mac_exclude": "MAC address to exclude from tracking",
           "scan_options": "Raw configurable scan options for Nmap"
         }
       }

tests/components/nmap_tracker/test_config_flow.py

@@ -11,6 +11,7 @@
 )
 from homeassistant.components.nmap_tracker.const import (
     CONF_HOME_INTERVAL,
+    CONF_MAC_EXCLUDE,
     CONF_OPTIONS,
     DEFAULT_OPTIONS,
     DOMAIN,
@@ -48,6 +49,7 @@ async def test_form(hass: HomeAssistant, hosts: str) -> None:
                 CONF_HOME_INTERVAL: 3,
                 CONF_OPTIONS: DEFAULT_OPTIONS,
                 CONF_EXCLUDE: "4.4.4.4",
+                CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
             },
         )
         await hass.async_block_till_done()
@@ -60,6 +62,7 @@ async def test_form(hass: HomeAssistant, hosts: str) -> None:
         CONF_HOME_INTERVAL: 3,
         CONF_OPTIONS: DEFAULT_OPTIONS,
         CONF_EXCLUDE: "4.4.4.4",
+        CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
     }
     assert len(mock_setup_entry.mock_calls) == 1
 
@@ -84,6 +87,7 @@ async def test_form_range(hass: HomeAssistant) -> None:
                 CONF_HOME_INTERVAL: 3,
                 CONF_OPTIONS: DEFAULT_OPTIONS,
                 CONF_EXCLUDE: "4.4.4.4",
+                CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
             },
         )
         await hass.async_block_till_done()
@@ -96,6 +100,7 @@ async def test_form_range(hass: HomeAssistant) -> None:
         CONF_HOME_INTERVAL: 3,
         CONF_OPTIONS: DEFAULT_OPTIONS,
         CONF_EXCLUDE: "4.4.4.4",
+        CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
     }
     assert len(mock_setup_entry.mock_calls) == 1
 
@@ -116,6 +121,7 @@ async def test_form_invalid_hosts(hass: HomeAssistant) -> None:
             CONF_HOME_INTERVAL: 3,
             CONF_OPTIONS: DEFAULT_OPTIONS,
             CONF_EXCLUDE: "",
+            CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
         },
     )
     await hass.async_block_till_done()
@@ -135,6 +141,7 @@ async def test_form_already_configured(hass: HomeAssistant) -> None:
             CONF_HOME_INTERVAL: 3,
             CONF_OPTIONS: DEFAULT_OPTIONS,
             CONF_EXCLUDE: "4.4.4.4",
+            CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
         },
     )
     config_entry.add_to_hass(hass)
@@ -151,6 +158,7 @@ async def test_form_already_configured(hass: HomeAssistant) -> None:
             CONF_HOME_INTERVAL: 3,
             CONF_OPTIONS: DEFAULT_OPTIONS,
             CONF_EXCLUDE: "",
+            CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
         },
     )
     await hass.async_block_till_done()
@@ -159,8 +167,8 @@ async def test_form_already_configured(hass: HomeAssistant) -> None:
     assert result2["reason"] == "already_configured"
 
 
-async def test_form_invalid_excludes(hass: HomeAssistant) -> None:
-    """Test invalid excludes passed in."""
+async def test_form_invalid_ip_excludes(hass: HomeAssistant) -> None:
+    """Test invalid ip excludes passed in."""
 
     result = await hass.config_entries.flow.async_init(
         DOMAIN, context={"source": config_entries.SOURCE_USER}
@@ -175,6 +183,7 @@ async def test_form_invalid_excludes(hass: HomeAssistant) -> None:
             CONF_HOME_INTERVAL: 3,
             CONF_OPTIONS: DEFAULT_OPTIONS,
             CONF_EXCLUDE: "not an exclude",
+            CONF_MAC_EXCLUDE: ["00:00:00:00:00:00"],
         },
     )
     await hass.async_block_till_done()
@@ -183,6 +192,37 @@ async def test_form_invalid_excludes(hass: HomeAssistant) -> None:
     assert result2["errors"] == {CONF_EXCLUDE: "invalid_hosts"}
 
 
+@pytest.mark.parametrize(
+    "mac_excludes",
+    [["1234567890"], ["1234567890", "11:22:33:44:55:66"], ["ABCDEFGHIJK"]],
+)
+async def test_form_invalid_mac_excludes(
+    hass: HomeAssistant, mac_excludes: str
+) -> None:
+    """Test invalid mac excludes passed in."""
+
+    result = await hass.config_entries.flow.async_init(
+        DOMAIN, context={"source": config_entries.SOURCE_USER}
+    )
+    assert result["type"] is FlowResultType.FORM
+    assert result["errors"] == {}
+
+    result2 = await hass.config_entries.flow.async_configure(
+        result["flow_id"],
+        {
+            CONF_HOSTS: "3.3.3.3",
+            CONF_HOME_INTERVAL: 3,
+            CONF_OPTIONS: DEFAULT_OPTIONS,
+            CONF_EXCLUDE: "4.4.4.4",
+            CONF_MAC_EXCLUDE: mac_excludes,
+        },
+    )
+    await hass.async_block_till_done()
+
+    assert result2["type"] is FlowResultType.FORM
+    assert result2["errors"] == {CONF_MAC_EXCLUDE: "invalid_hosts"}
+
+
 async def test_options_flow(hass: HomeAssistant) -> None:
     """Test we can edit options."""
 
@@ -194,6 +234,7 @@ async def test_options_flow(hass: HomeAssistant) -> None:
             CONF_HOME_INTERVAL: 3,
             CONF_OPTIONS: DEFAULT_OPTIONS,
             CONF_EXCLUDE: "4.4.4.4",
+            CONF_MAC_EXCLUDE: ["00:00:00:00:00:00", "11:22:33:44:55:66"],
         },
     )
     config_entry.add_to_hass(hass)
@@ -214,6 +255,7 @@ async def test_options_flow(hass: HomeAssistant) -> None:
         CONF_CONSIDER_HOME: 180,
         CONF_SCAN_INTERVAL: 120,
         CONF_OPTIONS: "-n -sn -PR -T4 --min-rate 10 --host-timeout 5s",
+        CONF_MAC_EXCLUDE: ["00:00:00:00:00:00", "11:22:33:44:55:66"],
     }
 
     with patch(
@@ -229,6 +271,7 @@ async def test_options_flow(hass: HomeAssistant) -> None:
                 CONF_OPTIONS: "-sn",
                 CONF_EXCLUDE: "4.4.4.4, 5.5.5.5",
                 CONF_SCAN_INTERVAL: 10,
+                CONF_MAC_EXCLUDE: ["00:00:00:00:00:00", "11:22:33:44:55:66"],
             },
         )
         await hass.async_block_till_done()
@@ -241,5 +284,6 @@ async def test_options_flow(hass: HomeAssistant) -> None:
         CONF_OPTIONS: "-sn",
         CONF_EXCLUDE: "4.4.4.4,5.5.5.5",
         CONF_SCAN_INTERVAL: 10,
+        CONF_MAC_EXCLUDE: ["00:00:00:00:00:00", "11:22:33:44:55:66"],
     }
     assert len(mock_setup_entry.mock_calls) == 1