lanname

Address to hostname lookup on a local network: reverse DNS, mDNS and NetBIOS, cached and never blocking the caller. Standard library only, no dependencies, Python 3.9 and up.

from lanname import Resolver

with Resolver(mode="dns", workers=4) as resolver:
    name = resolver.lookup("192.168.1.10")     # None until it is known

An IP address in a log line, a database row or a dashboard is much less useful a year later than the name of the thing it was. The three ways to find that name on a local network are all short, all standard library, and all annoying enough to get right that nobody wants to write them twice.

Two things are worth stating before anything else. The first is why you would reach for this rather than call socket.gethostbyaddr yourself. The second is the one place it will do something you did not ask for if you let it.

It never blocks. lookup() reads a cache and returns, always. Misses are queued for background workers. A caller draining a socket cannot afford to wait on a DNS round trip, and UDP in particular has no backpressure, so anything that stalls the read loop loses packets silently.

The widest mode probes the LAN, and is not the default. Installing this says you want names. It does not say you want multicast queries and NetBIOS requests going to hosts you happened to see an address for, on a network you may not own. The default asks the resolver your machine already uses and nothing more. "all" is a switch you throw deliberately.

Contents

• Installing
• Modes
• Resolver
• What gets looked up
• Where probes are allowed to go
• Static hosts files
• What answered, over a session
• Counters
• Ceilings
• Logging
• The three methods on their own
• Crafting replies to test against
• Watching a resolver work
• Limitations
• Licence

Installing

pip install lanname

Or from a checkout with pip install ., or by copying the lanname/ directory somewhere on the path. There is nothing to build and nothing to install alongside it.

import lanname
lanname.__version__          # "0.5.0"

Modes

The order matters and is not configurable: reverse DNS answers for anything with a real record, mDNS catches the Apple and Linux hosts that publish over multicast, and NetBIOS catches the Windows machines that answer to nothing else. Each step only runs because the one before it came back empty.

mode can be changed on a running resolver with set_mode(), which starts the worker threads if the resolver was constructed "off" and never had any. Going back to "off" stops new work being queued and drops what was already queued, unresolved, so nothing is sent for it; a probe in flight is the last one. The threads stay parked on an empty queue; shutdown() is what retires them, and after it the resolver is not restartable: set_mode() still changes the mode but starts nothing.

MODE_DESC is exported with the rest: a dict from each mode name to the one line description of it used above, so a program that offers the choice can say what it is offering without writing its own account of the three.

Resolver

Resolver(mode="dns", hosts_files=(), workers=4, resolve_public=False,
         fqdn=False, positive_ttl=3600, negative_ttl=300, timeout=1.0,
         local_networks=None)

lookup() returning None means "not known yet", never "has no name". Ask again the next time the address turns up; the answer appears once a worker has been round. The first sighting of any address is always a miss, by design.

shutdown() is a courtesy rather than a requirement, since the workers are daemon threads and the interpreter will not wait for them. What it buys is that probes stop going out at the point the caller thinks it has stopped: queued addresses are dropped unresolved, a probe in flight is the last one, and lookup() answers from static entries and the cache only, queueing nothing. A resolver is not restartable; build another.

What gets looked up

Not everything is worth a query, and two of the categories are worth refusing outright.

private means 10/8, 172.16/12, 192.168/16 and fc00::/7, and nothing else. ipaddress's is_private would also say yes to the documentation ranges (192.0.2.0/24 and its two siblings, 2001:db8::/32), the benchmarking range (198.18.0.0/15) and a few more, and its answer has changed between Python versions; none of those is a LAN, and since this class is the gate on what "all" mode probes, it is drawn tightly. Those ranges, and carrier-grade NAT space (100.64.0.0/10), count as public: left alone unless resolve_public is set, and never probed.

Public addresses are skipped by default because a busy link produces thousands of them, most resolve to something uninformative like a cloud provider's generic reverse record, and every one is a query somebody else can see. Turn them on when the public side is the interesting half.

mDNS and NetBIOS are only ever tried for private addresses, whatever resolve_public says. Both are link-local methods, and sending either to an address off the local network is at best pointless and at worst rude. Private is a weaker guarantee than on-link, though, so read the next section before turning "all" on anywhere that matters.

addr_kind(addr) is exported if the same classification is useful elsewhere. It returns one of ADDR_KINDS.

Where probes are allowed to go

Private is not the same as on-link. 10/8, 172.16/12 and 192.168/16 are three very large blocks, and an address out of one of them says only that some network somewhere uses it, not that it is on a network this machine is attached to. The addresses handed to lookup() typically come off a wire, which makes them somebody else's choice: a host that can put a packet in front of the caller, with a source address it picked, decides which addresses "all" mode probes. The mDNS query goes to the multicast group with a TTL of 1 and stays on the link whatever the address in it, but the NetBIOS query goes to the address itself, so it leaves by whatever route the machine has, over a VPN or a WAN link included.

local_networks is the answer to that. Given some networks, "all" mode probes only addresses inside one of them:

Resolver(mode="all", local_networks=["192.168.1.0/24", "10.2.0.0/16"])
Resolver(mode="all", local_networks="192.168.1.0/24")     # one needs no list

The default is None, which is no restriction and what every version before this one did. An address turned away is counted in stats["off_link"], and is otherwise treated as a miss: reverse DNS was still tried for it, and the failure is cached for negative_ttl like any other.

There is no automatic discovery of the machine's own networks. Nothing in socket or ipaddress reports an interface prefix, and the calls that do, getifaddrs and GetAdaptersAddresses, are per-platform and would each need their own ctypes struct layout, right on every platform or the gate is wrong in one direction or the other. That is a decision to take on its own rather than in passing, so for now the networks have to be given, and until they are, "all" mode behaves as it always has.

Static hosts files

Resolver(mode="off", hosts_files=["/etc/hosts", "static.hosts"])

Standard hosts format: an address, whitespace, a name, and # starts a comment. The first entry for an address wins, and files are read in the order given. Lines that do not parse are skipped rather than raising, and a file that cannot be read at all is logged as a warning, on the grounds that a missing optional file should not stop the program that asked for it.

Static entries answer even in "off" mode, and they answer without a cache lookup or a queue round trip. A resolver constructed "off" with a hosts file is a pure static mapping that starts no threads and sends no traffic, which is a reasonable way to run this in an environment where active lookups are not welcome.

What answered, over a session

for addr, names in resolver.local_hosts():
    print(addr, names[0], names[1:] or "")

Every private address that has ever resolved to a name, sorted by address, each with its names most recent first. This is kept separately from the cache and outlives it: the cache expires and evicts, and this is meant to answer "what did you see all session" long after either has happened.

A host whose name changes keeps both, newest first, up to MAX_NAMES_PER_HOST. That is usually a DHCP lease moving or a machine being renamed, and the last few changes are the interesting part.

Counters

resolver.stats is a collections.Counter, safe to read at any time.

dropped climbing means addresses are arriving faster than workers threads can resolve them, and those addresses simply go unresolved for now. Raise workers, or accept it: the queue is bounded on purpose, because the alternative to dropping work is growing memory without limit.

What a lookup can cost sets the rate those threads work at, and an address that answers nothing costs the most. In "all" mode the probes add at most timeout to it, for the pair rather than for each, so four threads spend at worst four seconds a second of wall clock on probing and the rest on reverse DNS, which the system resolver bounds and this package does not. Whoever is sending the addresses decides how many of them go unanswered, which is why the two probes share one deadline: taking timeout each doubled the cost of exactly the address an attacker supplies for free.

Ceilings

Everything keyed by address has a bound. The addresses reaching this package come off a network, so anything keyed by one and never evicted is a memory leak that other hosts can pull on.

The work queue holds 4,096 addresses and drops rather than blocking, counted in stats["dropped"].

The cache drops its oldest entry rather than emptying itself, and that distinction is the whole reason it is an OrderedDict. Clearing it wholesale would send every active host back through resolution at the same moment, which in "all" mode is a burst of mDNS and NetBIOS probes onto the LAN, from a program that was supposed to be quiet.

Logging

Everything goes to the lanname logger. The package installs a NullHandler and nothing else, so records go nowhere until you configure a handler.

import logging
logging.basicConfig(level=logging.INFO)

Nothing here is logged per address at INFO or above. A resolver watching a busy link would drown any log it shared.

DEBUG is the other extreme, and is meant for watching one resolver rather than for a log anything shares. It has a line for each thing a resolver does: the resolver built and the arguments it was built with, the workers starting and stopping, a hosts file read, an address queued or dropped for a full queue, a cache entry expiring, a worker taking an address and what it cached for it, an eviction, a mode or fqdn change, a shutdown and what it abandoned, the reason an address was not probed, and each query sent and reply read by the two probes, with the reason a reply was refused.

Two things are deliberately not there. A cache hit is not logged, since it is the same line every time a caller asks about an address it already knows, and it is what stats["hits"] counts; nor is an address the mode or its kind was never going to ask about, for the same reason. So a caller draining a busy socket writes a line per address resolved rather than per address seen.

Every name and every address a record carries is written as a repr. A name is whatever the answering host chose, _checked_name is what keeps a cursor move or a forged second line out of it, and the names most worth logging are the ones it refused. An address is no safer, since it is a key read off a network: ipaddress accepts any byte but % inside an IPv6 scope id, so an address carrying a newline is classed private and looked up like any other. Both are escaped rather than filtered, so what a record shows is what arrived.

The worker threads are named lanname-resolver-1 upwards, so a format with %(threadName)s in it tells four concurrent lookups apart:

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s %(levelname)s %(threadName)s %(name)s: %(message)s")

The three methods on their own

The scheduling and the asking are separable, and the asking is exported:

from lanname import mdns_reverse, netbios_name

mdns_reverse("192.168.1.10", timeout=1.0)    # str or None
netbios_name("192.168.1.10", timeout=1.0)    # str or None

Both send one packet and wait for one answer, both block for up to timeout, and both answer None rather than raising when a probe goes unanswered or a reply does not parse, and likewise when no socket can be opened or the send itself fails, as it does on a host with no route to the multicast group. A failure in one method is never a reason for "all" mode to skip the next. Reverse DNS has no wrapper here, because socket.gethostbyaddr already is one.

mdns_reverse sends a PTR query to 224.0.0.251:5353 with the unicast-response bit set and a multicast TTL of 1, so it stays on the link and there is no group to join. netbios_name sends a NBSTAT query straight to the host's port 137 and prefers the unique workstation name out of the answer.

Each takes only the reply to the query it sent. mdns_reverse ignores a datagram from any port but 5353 or carrying another transaction id, and keeps waiting; netbios_name connects to the host so that nothing else can answer, then checks the id and the response bit. A sixteen bit id is a filter for strays and stale replies, not authentication; see Limitations for what is and is not checked about the name itself.

Crafting replies to test against

A name from mDNS or NetBIOS is whatever the answering host chose, so the behaviour worth testing in anything downstream is what it does with a name that is not a tidy label: a control sequence, a newline, an embedded NUL, bytes that are not UTF-8, a lookalike, or a name far longer than a real host would send.

The repository carries a small tool for producing exactly those, under tools/poker. It builds the two replies with the hostname chosen byte for byte, shows what this package reads out of them, and can answer a live resolver's queries on the link so that a whole application sees the name you picked. It is a separate program beside the package, with a window that needs PySide6; the package itself keeps no dependencies. Its README says how to run it and, since it puts spoofed traffic on a network, where not to.

Watching a resolver work

Most of what this package does is a schedule rather than a value. A miss followed by a name two sightings later, an entry ageing out of the cache, a counter climbing, a queue dropping work: none of that shows up in a single call, and reading a Counter at a prompt is a poor way to watch it happen.

There is a second tool beside the first for that, under tools/harness. It builds a resolver from every argument the constructor takes, shows the equivalent Resolver(...) call as you change them, asks about the addresses you give it on a tick, and puts the counters, local_hosts(), the ceilings, the two probe functions and this package's log records on one window. It is a separate program with the same PySide6 dependency and none of its own; the package still has none. Its README says how to run it, and what each mode will send while it is open.

Limitations

• The first answer is always None. That is the design, not a bug. A caller that genuinely needs the name before it can proceed wants socket.gethostbyaddr and the blocking that comes with it.
• mDNS and NetBIOS are IPv4 only. Both open an AF_INET socket. Reverse DNS works for either family, so an IPv6 address gets one method rather than three.
• NetBIOS is a Windows convention and a fading one. Recent Windows can have it disabled, and non-Windows hosts answer only if they run Samba. It is the last method tried for exactly that reason.
• Names are checked, not verified. A host answering NetBIOS or mDNS says what it likes, and nothing here checks the claim against a forward lookup. Treat a name from "all" mode as a label a host chose for itself, not as identity. What is checked is that the name is fit to print: one holding any character below 0x21 (a space is allowed inside a NetBIOS name) or equal to 0x7f is refused, since those move a cursor, forge a second log line or hide the rest of a name; so is a label over 63 bytes or a name over 253, the DNS limits; and a name is abandoned past 255 bytes on the wire, so a reply built to loop its compression pointers cannot inflate one. Everything above 0x7f passes: a lookalike or a right-to-left override is legal in a name and yours to judge. A reverse DNS result goes through the same check, and a refused name is cached as a miss like any other.
• One resolver, one cache. Two resolvers in a process do not share anything, including the worker threads and the queue.

lookup() is safe to call from any thread; the cache and the observed-host table are both behind a lock.

Licence

MIT. See LICENSE.