diff --git a/README.md b/README.md index 26b9460e53a..215eccff76a 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,14 @@ password=MY_PASSWORD Once tracking the `device_tracker` component will maintain a file in your config dir called `known_devices.csv`. Edit this file to adjust which devices have to be tracked. +As an alternative to the router-based device tracking, it is possible to directly scan the network for devices by using nmap. The IP addresses to scan can be specified in any format that nmap understands, including the network-prefix notation (`192.168.1.1/24`) and the range notation (`192.168.1.1-255`). + +``` +[device_tracker] +platform=nmap_tracker +hosts=192.168.1.1/24 +``` + ## Further customizing Home Assistant diff --git a/config/home-assistant.conf.example b/config/home-assistant.conf.example index e5f8db42a9b..0edd11e98f6 100644 --- a/config/home-assistant.conf.example +++ b/config/home-assistant.conf.example @@ -12,13 +12,16 @@ api_password=mypass platform=hue [device_tracker] -# The following types are available: netgear, tomato, luci +# The following types are available: netgear, tomato, luci, nmap_tracker platform=netgear host=192.168.1.1 username=admin password=PASSWORD # http_id is needed for Tomato routers only # http_id=ABCDEFGHH +# For nmap_tracker, only the IP addresses to scan are needed: +# hosts=192.168.1.1/24 # netmask prefix notation or +# hosts=192.168.1.1-255 # address range [chromecast] # Optional: hard code the hosts (comma seperated) to find chromecasts diff --git a/homeassistant/components/device_tracker/nmap_tracker.py b/homeassistant/components/device_tracker/nmap_tracker.py new file mode 100644 index 00000000000..d51f3b310cb --- /dev/null +++ b/homeassistant/components/device_tracker/nmap_tracker.py @@ -0,0 +1,123 @@ +""" Supports scanning using nmap. """ +import logging +from datetime import timedelta +import threading +from collections import namedtuple +import subprocess +import re + +from libnmap.process import NmapProcess +from libnmap.parser import NmapParser, NmapParserException + +from homeassistant.const import CONF_HOSTS +from homeassistant.helpers import validate_config +from homeassistant.util import Throttle +from homeassistant.components.device_tracker import DOMAIN + +# Return cached results if last scan was less then this time ago +MIN_TIME_BETWEEN_SCANS = timedelta(seconds=5) + +_LOGGER = logging.getLogger(__name__) + + +# pylint: disable=unused-argument +def get_scanner(hass, config): + """ Validates config and returns a Nmap scanner. """ + if not validate_config(config, {DOMAIN: [CONF_HOSTS]}, + _LOGGER): + return None + + scanner = NmapDeviceScanner(config[DOMAIN]) + + return scanner if scanner.success_init else None + +Device = namedtuple("Device", ["mac", "name"]) + + +def _arp(ip_address): + """ Get the MAC address for a given IP """ + cmd = ['arp', '-n', ip_address] + arp = subprocess.Popen(cmd, stdout=subprocess.PIPE) + out, _ = arp.communicate() + match = re.search('(([0-9A-Fa-f]{2}\\:){5}[0-9A-Fa-f]{2})', str(out)) + if match: + return match.group(0) + _LOGGER.info("No MAC address found for %s", ip_address) + return '' + + +class NmapDeviceScanner(object): + """ This class scans for devices using nmap """ + + def __init__(self, config): + self.last_results = [] + + self.lock = threading.Lock() + self.hosts = config[CONF_HOSTS] + + self.success_init = True + self._update_info() + _LOGGER.info("nmap scanner initialized") + + def scan_devices(self): + """ Scans for new devices and return a + list containing found device ids. """ + + self._update_info() + + return [device.mac for device in self.last_results] + + def get_device_name(self, mac): + """ Returns the name of the given device or None if we don't know. """ + + filter_named = [device.name for device in self.last_results + if device.mac == mac] + + if filter_named: + return filter_named[0] + else: + return None + + @Throttle(MIN_TIME_BETWEEN_SCANS) + def _update_info(self): + """ Scans the network for devices. + Returns boolean if scanning successful. """ + if not self.success_init: + return False + + with self.lock: + _LOGGER.info("Scanning") + + nmap = NmapProcess(targets=self.hosts, options="-F") + + nmap.run() + + if nmap.rc == 0: + try: + results = NmapParser.parse(nmap.stdout) + self.last_results = [] + for host in results.hosts: + if host.is_up(): + if host.hostnames: + name = host.hostnames[0] + else: + name = host.ipv4 + if host.mac: + mac = host.mac + else: + mac = _arp(host.ipv4) + if mac: + device = Device(mac, name) + self.last_results.append(device) + _LOGGER.info("nmap scan successful") + return True + except NmapParserException as parse_exc: + _LOGGER.error("failed to parse nmap results: %s", + parse_exc.msg) + self.last_results = [] + return False + + else: + self.last_results = [] + _LOGGER.error(nmap.stderr) + return False diff --git a/requirements.txt b/requirements.txt index c4885c361f5..f30b2304866 100644 --- a/requirements.txt +++ b/requirements.txt @@ -17,3 +17,6 @@ pyuserinput>=0.1.9 # switch.tellstick, tellstick_sensor tellcore-py>=1.0.4 + +# namp_tracker plugin +python-libnmap