pip install hostlens

from hostlens import identify

device = identify("192.168.1.42")

print(device.best_name)
print(device.manufacturer)
print(device.device_type)
print(device.confidence)

Samsung QN90C
Samsung Electronics
smart_tv
0.94

HostLens uses the local neighbor table, ARP, reverse DNS, OUI data, mDNS, SSDP, UPnP, NetBIOS, and a short list of useful TCP services

Unknown values stay None

Cloud enrichment stays off unless the caller enables it

Why HostLens exists

Most LAN discovery code stops at an IP and MAC address or exposes protocol-specific dictionaries

HostLens gives callers one DeviceProfile with the evidence that produced it

Scan a network

Async is the main implementation

import asyncio

from hostlens import HostLens


async def main() -> None:
    intel = HostLens()
    devices = await intel.scan_network(mode="normal")

    for device in devices:
        print(f"{device.ip:15} {device.best_name}")


asyncio.run(main())

HostLens detects the preferred local IPv4 subnet when one is not supplied

Pass a CIDR range when you want an exact network

devices = await intel.scan_network("192.168.1.0/24", mode="fast")

Select an interface on machines with several active adapters

intel = HostLens(interface="Wi-Fi")

Scanning modes

Normal mode is the default

Deep mode checks ports 22, 80, 443, 445, 554, and 9100

It does not perform an unrestricted port scan

Read the scanning guide

Progressive results

A network scan can report a target before its enrichment collectors finish

from hostlens.models import DeviceFound, DeviceUpdated, ScanCompleted

async for event in intel.scan_stream("192.168.1.0/24", mode="normal"):
    if isinstance(event, DeviceFound):
        print("found", event.device.ip)
    elif isinstance(event, DeviceUpdated):
        print("updated", event.device.best_name)
    elif isinstance(event, ScanCompleted):
        print("done", event.summary.duration)

Ask for counts and duration without using the event stream

result = await intel.scan_network(mode="fast", return_result=True)

print(result.summary.targets_checked)
print(result.summary.devices_found)
print(result.summary.duration)

Device profiles

Every scanning path returns the same Pydantic model

device.ip
device.mac
device.hostname
device.friendly_name
device.manufacturer
device.device_type
device.model
device.os
device.services
device.confidence
device.fields
device.evidence
device.best_name

Serialize it without another conversion layer

data = device.model_dump()
json_data = device.model_dump_json(indent=2)

Inspect the facts behind a result

for item in device.evidence:
    print(item.source, item.field, item.value, item.confidence)

Or print the built-in explanation

print(device.explain())

Samsung QN90C
Confidence: 94%

Evidence:
- MAC prefix matches Samsung Electronics
- UPnP manufacturer reports Samsung Electronics
- UPnP modelName reports QN90C
- mDNS advertises _airplay._tcp.local

Confidence values are heuristics for choosing and ranking evidence

They are not calibrated probabilities

Read about profiles and evidence

Command line

The CLI calls the same Python API

hostlens identify 192.168.1.20
hostlens identify 192.168.1.20 --deep

hostlens scan
hostlens scan --fast
hostlens scan --deep
hostlens scan 192.168.1.0/24

hostlens discover
hostlens watch --passive

Read the CLI guide

Privacy and Fingerbank

Local scanning works without an account or API key

Fingerbank is opt in

import os

intel = HostLens(
    cloud=True,
    fingerbank_api_key=os.environ["FINGERBANK_API_KEY"],
)

Preview the values that would leave the machine

payload = intel.preview_cloud_payload(device)
print(payload)

API keys are not added to evidence or logs

Read the cloud and privacy guide

Platform notes

HostLens supports Python 3.11 and newer on Windows, Linux, and macOS

Active ARP discovery may need extra system access

Read all platform notes

Documentation

Full documentation lives at cyber0x3a.github.io/hostlens

Development

git clone https://github.com/Cyber0x3a/hostlens.git
cd hostlens
python -m venv .venv
python -m pip install -e ".[dev,docs]"

python -m ruff format --check .
python -m ruff check .
python -m pyright
python -m pytest
python -m build
python -m mkdocs build --strict

Normal unit tests do not use a live network

Live network tests must use the network marker

See CONTRIBUTING.md before changing protocol behavior or public models

License

HostLens is available under the MIT License