hostlens 0.1.0__py3-none-any.whl

hostlens/__init__.py

@@ -0,0 +1,18 @@
+"""High-level LAN device discovery and identification"""
+
+from hostlens.api import discover, discover_async, identify, identify_async
+from hostlens.client import HostLens
+from hostlens.config import ScanMode
+from hostlens.models import DeviceProfile
+
+__all__ = [
+    "DeviceProfile",
+    "HostLens",
+    "ScanMode",
+    "discover",
+    "discover_async",
+    "identify",
+    "identify_async",
+]
+
+__version__ = "0.1.0"

hostlens/api.py

@@ -0,0 +1,28 @@
+"""Convenient module-level sync and async APIs"""
+
+from __future__ import annotations
+
+import asyncio
+
+from hostlens.client import HostLens
+from hostlens.models import DeviceProfile
+
+
+async def identify_async(target: str) -> DeviceProfile:
+    """Identify one network device asynchronously"""
+    return await HostLens().identify(target)
+
+
+def identify(target: str) -> DeviceProfile:
+    """Identify one network device from synchronous code"""
+    return asyncio.run(identify_async(target))
+
+
+async def discover_async(subnet: str | None = None) -> list[DeviceProfile]:
+    """Discover devices on a subnet asynchronously"""
+    return await HostLens().discover(subnet)
+
+
+def discover(subnet: str | None = None) -> list[DeviceProfile]:
+    """Discover devices on a subnet from synchronous code"""
+    return asyncio.run(discover_async(subnet))

hostlens/cache.py

@@ -0,0 +1,30 @@
+"""Small in-memory TTL cache"""
+
+import time
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class MemoryCache(Generic[T]):
+    def __init__(self, ttl: float = 300.0) -> None:
+        self.ttl = ttl
+        self.entries: dict[str, tuple[T, float]] = {}
+
+    def get(self, key: str) -> T | None:
+        entry = self.entries.get(key)
+        if entry is None:
+            return None
+
+        value, expires_at = entry
+        if expires_at <= time.monotonic():
+            del self.entries[key]
+            return None
+
+        return value
+
+    def set(self, key: str, value: T) -> None:
+        self.entries[key] = (value, time.monotonic() + self.ttl)
+
+    def clear(self) -> None:
+        self.entries.clear()

hostlens/cli/__init__.py

@@ -0,0 +1,5 @@
+"""HostLens command line interface"""
+
+from hostlens.cli.app import app
+
+__all__ = ["app"]

hostlens/cli/__main__.py

@@ -0,0 +1,3 @@
+from hostlens.cli.app import app
+
+app()

hostlens/cli/app.py

@@ -0,0 +1,88 @@
+"""HostLens command-line interface"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+from typing import Annotated
+
+import typer
+
+from hostlens.cli.output import show_device, show_found, show_summary
+from hostlens.client import HostLens
+from hostlens.config import ScanMode
+from hostlens.models import DeviceFound, DeviceIdentified, ScanCompleted
+
+app = typer.Typer(no_args_is_help=True, help="Discover and identify devices on a local network")
+
+
+def _mode(fast: bool, deep: bool) -> ScanMode:
+    if fast and deep:
+        raise typer.BadParameter("Choose either --fast or --deep")
+    if fast:
+        return ScanMode.FAST
+    if deep:
+        return ScanMode.DEEP
+    return ScanMode.NORMAL
+
+
+@app.command()
+def identify(
+    target: str,
+    deep: Annotated[bool, typer.Option("--deep", help="Use deeper service probes")] = False,
+) -> None:
+    """Identify one device"""
+    device = asyncio.run(
+        HostLens().scan_host(target, mode=ScanMode.DEEP if deep else ScanMode.NORMAL)
+    )
+    show_device(device)
+
+
+@app.command()
+def scan(
+    subnet: str | None = None,
+    fast: Annotated[bool, typer.Option("--fast", help="Favor discovery speed")] = False,
+    deep: Annotated[bool, typer.Option("--deep", help="Use deeper service probes")] = False,
+) -> None:
+    """Discover and identify a local subnet"""
+
+    async def run() -> None:
+        async for event in HostLens().scan_stream(subnet, mode=_mode(fast, deep)):
+            if isinstance(event, DeviceFound):
+                show_found(event.device.ip)
+            elif isinstance(event, DeviceIdentified):
+                show_device(event.device)
+            elif isinstance(event, ScanCompleted):
+                show_summary(event.summary.devices_found, event.summary.duration)
+
+    asyncio.run(run())
+
+
+@app.command()
+def discover(subnet: str | None = None) -> None:
+    """Run a fast discovery scan"""
+    devices = asyncio.run(HostLens().discover(subnet))
+    for device in devices:
+        show_device(device)
+
+
+@app.command()
+def watch(
+    subnet: str | None = None,
+    passive: Annotated[bool, typer.Option("--passive", help="Do not probe devices")] = True,
+) -> None:
+    """Watch for devices observed by the operating system"""
+    if not passive:
+        raise typer.BadParameter("watch currently supports passive observation only")
+
+    async def run() -> None:
+        async for event in HostLens().watch_network(subnet):
+            if isinstance(event, DeviceFound):
+                show_device(event.device)
+
+    with suppress(KeyboardInterrupt):
+        asyncio.run(run())
+
+
+if __name__ == "__main__":
+    app()

hostlens/cli/output.py

@@ -0,0 +1,39 @@
+"""Terminal output for the HostLens CLI"""
+
+from rich.console import Console
+from rich.table import Table
+
+from hostlens.models import DeviceProfile
+
+console = Console()
+
+
+def show_device(device: DeviceProfile) -> None:
+    table = Table(title=device.best_name, show_header=False, box=None)
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+
+    rows = (
+        ("IP", device.ip),
+        ("MAC", device.mac),
+        ("Hostname", device.hostname),
+        ("Manufacturer", device.manufacturer),
+        ("Type", device.device_type),
+        ("Model", device.model),
+        ("OS", device.os),
+        ("Confidence", f"{device.confidence:.0%}"),
+    )
+
+    for label, value in rows:
+        if value is not None:
+            table.add_row(label, str(value))
+
+    console.print(table)
+
+
+def show_found(ip: str) -> None:
+    console.print(f"Found {ip}")
+
+
+def show_summary(devices_found: int, duration: float) -> None:
+    console.print(f"Found {devices_found} devices in {duration:.2f}s")

hostlens/client.py

@@ -0,0 +1,271 @@
+"""The public async HostLens client"""
+
+import asyncio
+import ipaddress
+import logging
+import time
+from collections.abc import AsyncIterator, Sequence
+
+from hostlens.cache import MemoryCache
+from hostlens.collectors import (
+    Collector,
+    HostnameCollector,
+    MdnsCollector,
+    NetbiosCollector,
+    OuiCollector,
+    ServiceCollector,
+    SsdpCollector,
+    UpnpCollector,
+    collect_evidence,
+)
+from hostlens.config import (
+    ScanMode,
+    parse_scan_mode,
+    scan_collectors,
+    scan_concurrency,
+    scan_timeout,
+    validate_options,
+)
+from hostlens.identity.fingerbank import FingerbankClient
+from hostlens.identity.fingerprints import apply_local_rules
+from hostlens.identity.fusion import build_profile
+from hostlens.models import (
+    DeviceFound,
+    DeviceIdentified,
+    DeviceProfile,
+    DeviceUpdated,
+    ScanCompleted,
+    ScanEvent,
+    ScanResult,
+    ScanSummary,
+    Target,
+)
+from hostlens.network.addressing import local_subnet, normalize_ip, validate_subnet
+from hostlens.network.discovery import discover_targets, known_neighbors
+
+logger = logging.getLogger(__name__)
+
+
+def _built_in_collectors() -> tuple[Collector, ...]:
+    return (
+        HostnameCollector(),
+        OuiCollector(),
+        MdnsCollector(),
+        SsdpCollector(),
+        UpnpCollector(),
+        NetbiosCollector(),
+        ServiceCollector(),
+    )
+
+
+class HostLens:
+    """Discover and identify devices through one async API"""
+
+    def __init__(
+        self,
+        *,
+        interface: str | None = None,
+        timeout: float = 3.0,
+        concurrency: int = 64,
+        cloud: bool = False,
+        fingerbank_api_key: str | None = None,
+        collectors: Sequence[Collector] | None = None,
+    ) -> None:
+        validate_options(timeout, concurrency, cloud, fingerbank_api_key)
+
+        self.interface = interface
+        self.timeout = timeout
+        self.concurrency = concurrency
+        self.cache: MemoryCache[DeviceProfile] = MemoryCache(ttl=300)
+
+        available = collectors if collectors is not None else _built_in_collectors()
+        self.collectors = {collector.name: collector for collector in available}
+
+        self.fingerbank = None
+        if cloud and fingerbank_api_key:
+            self.fingerbank = FingerbankClient(fingerbank_api_key, timeout)
+
+    async def identify(
+        self,
+        target: str,
+        *,
+        mode: ScanMode | str = ScanMode.NORMAL,
+    ) -> DeviceProfile:
+        """Identify one IP address"""
+        return await self.scan_host(target, mode=mode)
+
+    async def scan_host(
+        self,
+        target: str,
+        *,
+        mode: ScanMode | str = ScanMode.NORMAL,
+    ) -> DeviceProfile:
+        """Scan and identify one host"""
+        ip = normalize_ip(target)
+        cached = self.cache.get(ip)
+        if cached:
+            return cached
+
+        resolved_target = await self._find_neighbor(ip)
+        device = await self._identify_target(resolved_target, parse_scan_mode(mode))
+        self.cache.set(ip, device)
+        return device
+
+    async def scan_hosts(
+        self,
+        targets: Sequence[str],
+        *,
+        mode: ScanMode | str = ScanMode.NORMAL,
+    ) -> list[DeviceProfile]:
+        """Identify several hosts with bounded concurrency"""
+        scan_mode = parse_scan_mode(mode)
+        limit = min(self.concurrency, scan_concurrency(scan_mode))
+        semaphore = asyncio.Semaphore(limit)
+
+        async def scan_one(target: str) -> DeviceProfile:
+            async with semaphore:
+                return await self.scan_host(target, mode=scan_mode)
+
+        tasks = [scan_one(target) for target in targets]
+        return list(await asyncio.gather(*tasks))
+
+    async def scan_network(
+        self,
+        subnet: str | None = None,
+        *,
+        mode: ScanMode | str = ScanMode.NORMAL,
+        return_result: bool = False,
+    ) -> list[DeviceProfile] | ScanResult:
+        """Discover and identify devices on one subnet"""
+        devices: dict[str, DeviceProfile] = {}
+        summary = None
+
+        async for event in self.scan_stream(subnet, mode=mode):
+            if isinstance(event, (DeviceFound, DeviceUpdated, DeviceIdentified)):
+                key = event.device.mac or event.device.ip
+                devices[key] = event.device
+            if isinstance(event, ScanCompleted):
+                summary = event.summary
+
+        found = list(devices.values())
+        if return_result:
+            if summary is None:
+                raise RuntimeError("Scan finished without a summary")
+            return ScanResult(devices=found, summary=summary)
+        return found
+
+    async def discover(self, subnet: str | None = None) -> list[DeviceProfile]:
+        """Run a fast network scan"""
+        result = await self.scan_network(subnet, mode=ScanMode.FAST)
+        if isinstance(result, ScanResult):
+            return result.devices
+        return result
+
+    async def scan(self, subnet: str | None = None) -> AsyncIterator[ScanEvent]:
+        """Stream a normal network scan"""
+        async for event in self.scan_stream(subnet):
+            yield event
+
+    async def scan_stream(
+        self,
+        subnet: str | None = None,
+        *,
+        mode: ScanMode | str = ScanMode.NORMAL,
+    ) -> AsyncIterator[ScanEvent]:
+        """Yield devices early and enrich them as the scan continues"""
+        started = time.monotonic()
+        scan_mode = parse_scan_mode(mode)
+        if scan_mode is ScanMode.PASSIVE:
+            raise ValueError("Use watch_network for passive observation")
+
+        network = self._network(subnet)
+        targets: list[Target] = []
+        arp_timeout = min(scan_timeout(scan_mode), 1.5)
+
+        async for target in discover_targets(network, self.interface, arp_timeout):
+            targets.append(target)
+            yield DeviceFound(device=build_profile(target, []))
+
+        limit = min(self.concurrency, scan_concurrency(scan_mode))
+        semaphore = asyncio.Semaphore(limit)
+
+        async def enrich(target: Target) -> DeviceProfile:
+            async with semaphore:
+                return await self._identify_target(target, scan_mode)
+
+        tasks = [asyncio.create_task(enrich(target)) for target in targets]
+        for task in asyncio.as_completed(tasks):
+            device = await task
+            self.cache.set(device.ip, device)
+            yield DeviceUpdated(device=device)
+            yield DeviceIdentified(device=device)
+
+        duration = time.monotonic() - started
+        checked = max(0, ipaddress.ip_network(network).num_addresses - 2)
+        summary = ScanSummary(
+            duration=duration,
+            targets_checked=checked,
+            devices_found=len(targets),
+            mode=scan_mode.value,
+        )
+        yield ScanCompleted(summary=summary)
+
+    async def watch_network(
+        self,
+        subnet: str | None = None,
+        *,
+        mode: ScanMode | str = ScanMode.PASSIVE,
+        interval: float = 2.0,
+    ) -> AsyncIterator[ScanEvent]:
+        """Watch the OS neighbor table without sending probes"""
+        if parse_scan_mode(mode) is not ScanMode.PASSIVE:
+            raise ValueError("watch_network only supports passive mode")
+
+        network = self._network(subnet)
+        seen: set[str] = set()
+
+        while True:
+            async for target in known_neighbors(network):
+                key = target.mac or target.ip
+                if key in seen:
+                    continue
+
+                seen.add(key)
+                device = await self._identify_target(target, ScanMode.PASSIVE)
+                yield DeviceFound(device=device)
+
+            await asyncio.sleep(interval)
+
+    def preview_cloud_payload(self, device: DeviceProfile) -> dict[str, str]:
+        """Show the data that cloud enrichment would receive"""
+        if self.fingerbank is None:
+            return {}
+
+        target = Target(ip=device.ip, mac=device.mac)
+        return self.fingerbank.preview_payload(target, device.evidence)
+
+    async def _identify_target(self, target: Target, mode: ScanMode) -> DeviceProfile:
+        names = scan_collectors(mode)
+        collectors = [self.collectors[name] for name in names if name in self.collectors]
+        timeout = min(self.timeout, scan_timeout(mode))
+        evidence = await collect_evidence(collectors, target, timeout)
+
+        if mode in {ScanMode.NORMAL, ScanMode.DEEP, ScanMode.PASSIVE}:
+            evidence.extend(apply_local_rules(evidence))
+
+        if self.fingerbank and mode is not ScanMode.FAST:
+            try:
+                evidence.extend(await self.fingerbank.resolve(target, evidence))
+            except Exception as error:
+                logger.debug("Fingerbank enrichment failed: %s", error)
+
+        return build_profile(target, evidence)
+
+    async def _find_neighbor(self, ip: str) -> Target:
+        subnet = str(ipaddress.ip_network(f"{ip}/32", strict=False))
+        async for target in known_neighbors(subnet):
+            return target
+        return Target(ip=ip)
+
+    def _network(self, subnet: str | None) -> str:
+        return validate_subnet(subnet or local_subnet(self.interface))

hostlens/collectors/__init__.py

@@ -0,0 +1,21 @@
+"""Built-in evidence collectors"""
+
+from hostlens.collectors.base import Collector, collect_evidence
+from hostlens.collectors.basic import HostnameCollector, OuiCollector
+from hostlens.collectors.mdns import MdnsCollector
+from hostlens.collectors.netbios import NetbiosCollector
+from hostlens.collectors.services import ServiceCollector
+from hostlens.collectors.ssdp import SsdpCollector
+from hostlens.collectors.upnp import UpnpCollector
+
+__all__ = [
+    "Collector",
+    "HostnameCollector",
+    "MdnsCollector",
+    "NetbiosCollector",
+    "OuiCollector",
+    "ServiceCollector",
+    "SsdpCollector",
+    "UpnpCollector",
+    "collect_evidence",
+]

hostlens/collectors/base.py

@@ -0,0 +1,41 @@
+"""Shared collector runner"""
+
+import asyncio
+import logging
+from collections.abc import Sequence
+from typing import Protocol
+
+from hostlens.models import Evidence, Target
+
+logger = logging.getLogger(__name__)
+
+
+class Collector(Protocol):
+    name: str
+
+    async def collect(self, target: Target, timeout: float) -> list[Evidence]: ...
+
+
+async def collect_evidence(
+    collectors: Sequence[Collector],
+    target: Target,
+    timeout: float,
+) -> list[Evidence]:
+    """Run independent collectors together and isolate their failures"""
+    results = await asyncio.gather(
+        *(_collect_safely(collector, target, timeout) for collector in collectors)
+    )
+    return [item for result in results for item in result]
+
+
+async def _collect_safely(
+    collector: Collector,
+    target: Target,
+    timeout: float,
+) -> list[Evidence]:
+    try:
+        async with asyncio.timeout(timeout):
+            return await collector.collect(target, timeout)
+    except Exception as error:
+        logger.debug("Collector %s failed for %s: %s", collector.name, target.ip, error)
+        return []

hostlens/collectors/basic.py

@@ -0,0 +1,65 @@
+"""Fast hostname and manufacturer collectors"""
+
+import asyncio
+import socket
+
+from hostlens.models import Evidence, Target
+
+
+class HostnameCollector:
+    name = "hostname"
+
+    async def collect(self, target: Target, timeout: float) -> list[Evidence]:
+        try:
+            result = await asyncio.wait_for(
+                asyncio.to_thread(socket.gethostbyaddr, target.ip),
+                timeout=timeout,
+            )
+        except (TimeoutError, OSError):
+            return []
+
+        hostname = result[0].rstrip(".")
+        return [
+            Evidence(
+                source=self.name,
+                field="hostname",
+                value=hostname,
+                confidence=0.75,
+                description=f"Reverse DNS reports hostname {hostname}",
+            )
+        ]
+
+
+class OuiCollector:
+    name = "oui"
+
+    def __init__(self) -> None:
+        self.parser: object | None = None
+
+    async def collect(self, target: Target, timeout: float) -> list[Evidence]:
+        del timeout
+        if not target.mac:
+            return []
+
+        manufacturer = await asyncio.to_thread(self._lookup, target.mac)
+        if not manufacturer:
+            return []
+
+        return [
+            Evidence(
+                source=self.name,
+                field="manufacturer",
+                value=manufacturer,
+                confidence=0.78,
+                description=f"MAC prefix matches {manufacturer}",
+            )
+        ]
+
+    def _lookup(self, mac: str) -> str | None:
+        from manuf import manuf  # type: ignore[import-untyped]
+
+        if self.parser is None:
+            self.parser = manuf.MacParser(update=False)
+
+        manufacturer = self.parser.get_manuf_long(mac) or self.parser.get_manuf(mac)  # type: ignore[attr-defined]
+        return str(manufacturer).strip() if manufacturer else None