Scanning modes

The mode controls collector choice, timeout budget, and concurrency

The definitions live in src/hostlens/config.py

Mode	Collectors	Default timeout	Concurrency cap
`fast`	reverse DNS and OUI	0.8 seconds	64
`normal`	fast collectors, mDNS, DNS-SD, LLMNR, NetBIOS, SSDP, and UPnP	2.5 seconds	48
`deep`	normal collectors and selected TCP services	5 seconds	24
`passive`	OUI for hosts already in the neighbor table	30 seconds	16

The constructor values are upper bounds

For example, a client configured with concurrency=12 will never use a mode cap higher than 12

Fast

Use fast mode for inventory work where quick discovery matters more than detailed identity

devices = await intel.scan_network(mode="fast")

Discovery still uses the neighbor table and ARP when available

Per-device enrichment is limited to reverse DNS and manufacturer lookup

Normal mode is the default

devices = await intel.scan_network()

It adds the common local naming and discovery protocols and applies the built-in fingerprint rules

mDNS, DNS-SD, and SSDP are scanned once for the network and their results are matched back to devices by address

They are not restarted for every IP in the subnet

If cloud enrichment is configured, normal mode can also query Fingerbank

Deep mode checks these TCP ports

device = await intel.scan_host("192.168.1.20", mode="deep")

This is a connection check, not a broad port scan and not a banner grabber

Passive observation reads the operating system neighbor table at an interval

async for event in intel.watch_network(interval=5):
    print(event.device.ip)

It does not send HostLens probes

The operating system may have learned its neighbor entries through traffic generated by other applications

scan_network(mode="passive") is rejected because passive work has no fixed completion point

Use watch_network instead

HostLens(timeout=...) sets the caller limit for collectors

The effective collector timeout is the smaller of the client timeout and the mode timeout

intel = HostLens(timeout=1.5)

A collector timeout or protocol failure is logged at debug level and does not normally fail the whole device scan

Completed host profiles are cached in memory for five minutes per HostLens instance

Create a new instance or call intel.cache.clear() when a fresh result is required immediately

The cache is process-local and is not written to disk