ipscout 2.0.0__tar.gz → 2.3.0__tar.gz

{ipscout-2.0.0 → ipscout-2.3.0}/CHANGELOG.md

@@ -5,6 +5,260 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [2.3.0] 2026-10-26 12:19:25
+
+### Added
+
+- `lookup_mac(ip, active=True, fallback_to_cache=True)` (and the same on `get_mac_address`, plus
+  `ipscout mac --active --fallback-to-cache`): ask actively, and read the neighbour cache instead
+  only when this host cannot ask, meaning no privilege (`IPScoutPermissionError`), or no interface
+  or route that can carry the request, or a send or read that failed (`IPScoutUnsupportedError`). An active ask nobody answered stays an
+  active answer and is never replaced by a cache entry; a host name and a zone naming no interface
+  still raise. `fallback_to_cache=True` without `active=True` raises `ValueError`.
+- `MacMethod` (`ACTIVE`, `CACHE`) and `MacLookup.method`: every MAC answer says whether it was asked
+  for or read from the cache, and `ipscout mac` prints and emits it. `--strict` keeps it too, and now
+  also carries the interface of a direct answer.
+
+### Fixed
+
+- An active MAC lookup no longer reports a request it could not make as "nobody answered":
+  - On Windows, a `SendARP` or `ResolveIpNetEntry2` failure other than no reply (no route to the
+    address, among others) and a missing `iphlpapi.dll` now raise `IPScoutUnsupportedError`.
+    They used to return `None`. Only `ERROR_BAD_NET_NAME` reads as no reply.
+  - On Linux and macOS, a send or receive that fails after the socket opens (the interface went
+    away, the link is down) now raises `IPScoutUnsupportedError` too, instead of returning `None`.
+- `lookup_mac(..., active=True)` resolves a zone before anything is sent on every platform, by
+  index or by either Windows name (the friendly one `local_interfaces()` reports, or the
+  `if_nametoindex` one), and raises `IPScoutResolutionError` when it names no interface. Before,
+  the routed branch and Windows never looked at the zone, so a typo passed unseen. The cache read
+  now matches on the interface the zone resolves to, so a numeric zone such as `%2` finds the
+  entry on that link rather than whichever link holds the address.
+- On Windows, an active lookup of an address with no route raises `IPScoutUnsupportedError`
+  instead of reporting nobody answered: `SendARP` gives the same status for both.
+
+## [2.2.0] 2026-10-26 11:06:07
+
+### Added
+
+- `read_snmp_system` / `aread_snmp_system` and the `ipscout snmp-system` command: the SNMP system
+  group (sysUpTime, sysName, sysDescr, sysObjectID) of many hosts, one GET each, SNMPv1 or v2c as the
+  caller chooses. Each host gets an `SnmpSystem` record with an `SnmpState` (ANSWERED, SILENT,
+  REFUSED, ERROR, UNREACHABLE) instead of an exception; under v1 a value the agent lacks is asked
+  around and reported as `None`. The uptime tells a restart (it fell) from mere reachability.
+- `ipscout.deadline`: the per-host deadline helpers, shared by the banner grab and the SNMP read.
+- `packet.max_payload_size(family)` and `packet.require_payload_size(payload_size, family)`: the
+  one per-family payload bound, which `ping` and `build_echo_request` both apply.
+- `models.RoundTrip` (a finite round trip of 0 or more milliseconds), `api.HostNames` /
+  `api.require_host_names` (a collection of host names, refusing one bare string),
+  `traceroute.TracerouteSettings` and `traceroute.DEFAULT_MAX_HOPS`, `bpf.MAX_BPF_DEVICES`, and a
+  `method` field on `portscan.PortScanSettings`.
+- `ipscout.models.require_port`, `Port`, `MIN_PORT` and `MAX_PORT`: the one port-range check
+  (1-65535) every entry point and record taking a port number now applies.
+- `ipscout.packet.MAX_PAYLOAD_SIZE_IPV4` (65507) and `MAX_PAYLOAD_SIZE_IPV6` (65527): the most ICMP
+  payload one echo can carry.
+- `AddressFamily.ip_version` and `AddressFamily.of_version()`.
+- `ipscout.portscan.DEFAULT_TIMEOUT` (1.0 s per port), and `DEFAULT_CONCURRENCY` exported from
+  `ipscout.api` and `ipscout.scan`; the CLI options take their defaults from these.
+- Argument models and checks every entry point shares: `banner.BannerSettings`,
+  `portscan.PortScanSettings`, `scan.SweepSettings`; `models.Timeout` / `require_timeout` (above 0,
+  at most 2147483 s, finite), `models.MAX_TIMES` (65535, the 16-bit echo sequence),
+  `models.MAX_HOP_LIMIT` (255), `models.parse_address` / `require_address`, `models.needs_zone`,
+  `pool.Concurrency` / `require_concurrency` (at least 1), and `errors.validation_problems` /
+  `refused_arguments`, which word every argument refusal the same way.
+- `models.DEFAULT_TIMEOUT` (2.0 s, re-exported by `service`), `models.DISCARD_PORT`,
+  `AddressFamily.unspecified_address`, `packet.MAX_IP_LENGTH`, `packet.UDP_HEADER_SIZE`,
+  `packet.IPV4_MIN_HEADER_SIZE`, `arp.normalise_mac` (where `neighbours.normalise_mac` now comes
+  from), `arp.format_hardware_address`, `arp.FRAME_RECEIVE_SIZE`, `ports.CAPTURE_RECEIVE_BUFFER`,
+  `ports.MIN_CAPTURE_WAIT`, `wol.DEFAULT_BROADCAST`, `scan.refuse_a_partial_scope`,
+  `scan.sweep_argument_refusal`.
+- Windows backend helpers: `winapi.IpStatus` (an `IntEnum` of the IP_STATUS codes with their text),
+  `win_family` / `family_from_win`, `sockaddr_in6`, `sockaddr_inet_address`, `address_text`,
+  `reply_buffer_size`, `DEFAULT_TTL`, `ICMP_REPLY_HEADROOM`, `MAX_ADAPTER_ADDRESS_LENGTH`,
+  `NO_ERROR`, `MS_LAYOUT`; `transport_windows.ipv6_destination` and `echo_outcome`;
+  `neighbours_windows.declared_mac`. macOS route-socket helpers in `bsdroute`: `RTM_GET`,
+  `NO_METRICS`, `pack_sockaddr_in6`, `open_route_socket`.
+
+### Changed
+
+- Every argument refusal reads `<operation> refused its arguments: <argument>: <reason>` (one part
+  per bad argument) and is a plain `ValueError` with pydantic's report kept as `__cause__`. `ping`
+  raised the `pydantic.ValidationError` itself, and with `raise_on_error=False` its `.error` held
+  pydantic's text, error-type tags and a docs URL; the CLI printed the same text.
+- Arguments that were accepted and then misreported are refused before anything is sent:
+  `concurrency` below 1 (silently run as 1); a `timeout` of zero, below zero, infinite or above
+  2147483 s in `ping`, `traceroute`, `scan_ports`, `syn_scan`, `arp_scan` and `grab_banners` (a zero
+  timeout reported open ports as `FILTERED`, a sweep returned the cache as its result, a traceroute
+  walked 30 silent hops, and 1e12 raised `OverflowError` mid-probe); `times` above 65535; a negative
+  `payload_size`; `max_hops` above 255; a sweep `limit` below 1; an empty `farewell` (silently not
+  sent); a NaN or infinite `DhcpSession` window.
+- Address arguments are parsed at entry: `query_route` and `lookup_mac` refuse a host name, a
+  malformed literal, a literal of the other family or a zone on an IPv4 address with `ValueError`
+  (they returned `None` / `UNKNOWN`, the same as "no route"); `wake_on_lan` refuses a broadcast that
+  is empty, `0.0.0.0`, a name or not IPv4 (an empty one sent the packet to this host and reported it
+  sent); `scan_ports` resolves the host once and uses that address for every port (a name was
+  resolved per port, and the SYN path passed the name to `inet_aton`); an unresolvable host raises
+  `IPScoutResolutionError` instead of reporting every port `FILTERED`.
+- Records refuse values no producer makes: `ResponseObject` (counts 0-65535, received at most sent
+  and matching the answered round trips, `reached` exactly when something answered, `ip` of its
+  `family`, a non-empty `error`), `TraceHop.ttl` 1-255, `InterfaceAddress` / `SubnetInfo` prefix
+  length within the family, `mtu` above 0, `Interface.index` at least 1, `SweepScope.limit` at least
+  1, `ObserveDhcpReport` windows, `JsonEnvelope` (`ok` exactly when `error` is absent),
+  `ParsedReply` field widths, `EchoPayload.token` exactly 8 bytes, and `DhcpReply` (canonical MAC,
+  a non-zero IPv4 offer, a 32-bit transaction id). `build_echo_request` refuses a token of the wrong
+  length and a sequence or identifier outside 0-65535.
+- A `ping` that fails before sending reports what it knew: the resolved address and family when
+  resolution succeeded (it reported `0.0.0.0` / IPv4 for an IPv6 target), and 0 pings sent.
+- `bootp.offers_from_frames(mac=...)` accepts any written form of the address; another spelling
+  than lowercase-colon silently matched nothing.
+- CLI: a bad option value is a usage error (exit 2, naming the option) before any probe, checked
+  through the library's own argument types; `ping-many -c 0` exited 1 with every row failed.
+  `wake`, `gateway --to` and `mac` with a bad argument exit 2 naming the command (they escaped with
+  exit 1 or 22 and `command: null`). `traceroute --max-hops` is limited to 1-255. In human mode a
+  usage error shows Click's usage text instead of a traceback.
+
+- Every port number is held to 1-65535 the same way, with the message
+  `port out of range 1-65535: N`. `scan_ports` / `ascan_ports` / `syn_scan` refuse a port LIST
+  holding an out-of-range port with `ValueError` (only a specification string was checked);
+  `grab_banners` / `agrab_banners` keep refusing a bad port, now in that wording; and
+  `PortResult`, `Banner` and `WakeReport` refuse one at construction, where pydantic's
+  `greater than or equal to 1` wording used to appear.
+- `ping` / `aping` / `ping_many` check `tcp_port` on every call, also when no TCP fallback is
+  used: out of range it raises, or with `raise_on_error=False` is reported on `.error`. It used
+  to be ignored unless the fallback engaged.
+- On Windows, `path_mtu()` sends its don't-fragment probes with TTL 128, Windows' own default, as
+  `ping` does. It used 64, so a target more than 64 hops away could not be probed.
+- `Banner` requires `error` exactly when the state is `UNREACHABLE` and refuses an empty one. It
+  used to forbid `error` on the other states but allowed an `UNREACHABLE` banner without a reason.
+
+- More arguments are checked strictly before anything is sent, in the
+  `<operation> refused its arguments: <argument>: <reason>` shape:
+  - `ping` / `aping` / `ping_many` / `is_reachable`: `times=True` sent one echo and `timeout="1"`
+    waited a second; both are refused now (`is_reachable`, which never raises, answers `False`).
+  - `ping_many` / `aping_many` and `grab_banners` / `agrab_banners`: one string passed as the host
+    collection (`ping_many("printer.lan")`) probed each character as a host; it is refused, and so
+    is a host that is not a string (a raw pydantic error from `Banner` before). `ping_many` checks
+    `concurrency` before it takes anything from the targets; the refusal used to come after the
+    targets iterable was consumed, as `concurrency must be at least 1, got 0`.
+  - `traceroute` / `atraceroute` / `trace_path` / `atrace_path`: `max_hops=True` walked one hop and
+    `3.0` or `"5"` raised `TypeError`; a non-bool `resolve_names` (`"no"` switched lookups on) and a
+    `timeout` of the wrong type are refused. The messages change from
+    `max_hops must be 1-255, got 256` (and `max_hops must be at least 1, got 0` in 2.1.0) to
+    `traceroute refused its arguments: max_hops: Input should be less than or equal to 255`. The
+    arguments are checked before the name is resolved, so a bad `max_hops` with an unresolvable
+    name is a `ValueError`, no longer `IPScoutResolutionError`.
+  - `scan_ports` / `ascan_ports` / `syn_scan` with a port LIST: `[True]` and `[80.5]` scanned port
+    1 and 80 and keyed the result `True` / `80.5`; they are refused, and a list port out of range
+    now reads `port scan refused its arguments: ports.0: port out of range 1-65535: 0` (a
+    specification string keeps the bare `port out of range 1-65535: 0`).
+    `scan_ports(method="syn")` with a plain string silently ran a connect scan; it is refused.
+  - `observe_dhcp_first_reachable`: a `probe_timeout` of 0, negative, NaN or text, or a `tcp_port`
+    outside 1-65535, watched the whole window and returned `None` (port 0 silently dropped the TCP
+    attempt); they are refused before the capture opens.
+  - `DhcpSession` / `observe_dhcp`: a `settle` above 2147483 s is refused. A `timeout` of 0 reads
+    `timeout must be above 0 and at most 2147483 seconds, got 0` (2.1.0:
+    `timeout must be positive, got 0: a window of zero could never see anything`).
+  - `get_mac_address`, `lookup_mac` and `resolve_active`: text that is not an address literal
+    raises `ValueError`. In 2.1.0 `get_mac_address("nonsense")` returned `None`, and with
+    `active=True` raised `IPScoutUnsupportedError` (no route). `resolve_active` checks its
+    `timeout` (0 returned `None` without waiting, -1 raised a raw `Timeout value out of range`).
+  - `SweepScope.from_networks("192.0.2.0/24", ...)` (one network as text) is refused instead of
+    being split into characters.
+- `resolve_active` and `lookup_mac(active=True)` on Linux and macOS honour an RFC 4007 zone
+  (`fe80::1%eth0`, by name or index): the request goes out on that interface. The zoned text used to
+  make the backend's `inet_pton` fail, and `None` came back with nothing sent. A zone naming no
+  interface raises `IPScoutResolutionError`. On Windows the zone is still not used.
+- `build_echo_request` refuses a `payload_size` its family cannot carry with the same message
+  `ping` uses (`10**12` raised `MemoryError`, 70000 a raw pydantic error, and IPv4 65508-65527 was
+  built). `build_arp_request` / `build_neighbour_solicitation` refuse a sender address that is not
+  six bytes (`"aa:bb"` was zero-padded into the frame).
+- Records refuse more values no producer makes: `EchoResult.rtt_ms` NaN, infinite or negative, a
+  round trip without a source (or the reverse), `ttl_expired` without an answer; `TraceHop` reached
+  or named without an address, a round trip without an address, an empty `hostname`;
+  `Interface` with an empty name, an address filed under the other family, a hardware address not
+  in lowercase colon form or all zero, an MTU above 0xFFFFFFFF; `Neighbour` whose `ip` is not a
+  bare literal of its `family` or whose `mac` is not `aa:bb:cc:dd:ee:ff`; `MacLookup` whose
+  `via_ip` and `NEXT_HOP` scope disagree, `DIRECT` without a MAC or `UNKNOWN` with one;
+  `SubnetInfo` whose network is not the one its address sits on, whose broadcast is not that
+  network's, or whose gateway is not of its family; `SweepScope` networks covering more than its
+  limit; `FindIpReport` with `scanned` and `scope` disagreeing; `ObserveDhcpReport` and
+  `WakeReport` with a non-canonical MAC, unbounded windows, or a broadcast that is not a usable
+  IPv4 address.
+- `SubnetInfo.network` is an `IPv4Network` / `IPv6Network` instead of text. JSON output is
+  unchanged; Python callers reading it as a string need `str(...)`.
+- CLI: `wake`, `find-ip` and `observe-dhcp` report the MAC as `aa:bb:cc:dd:ee:ff` whatever spelling
+  was typed (they echoed the input).
+
+### Fixed
+
+- TCP fallback probes over IPv6 (`TcpEchoTransport`, `AsyncTcpEchoTransport`) could reach an IPv4
+  listener: an IPv4-mapped target (`::ffff:a.b.c.d`) connected through IPv4 on Linux and macOS,
+  and on macOS with Python 3.15 a plain IPv4 literal did too, so the host read as reachable over
+  IPv6. The probe socket now sets `IPV6_V6ONLY`, and such a target reads as unanswered.
+- Windows `local_interfaces()`: an adapter with no friendly name was named `b'{GUID}'` (the repr
+  of the bytes) and one with no name at all `''`; it is now `{GUID}`, or `ifindex-<n>` /
+  `adapter-<position>` when even that is missing.
+- macOS `dhcp_capture_available()`: a busy `/dev/bpf0` answered `False` although a capture would
+  claim the next free device; it now tries the same pool a capture does.
+- `reverse_dns` answers `None` for an empty PTR name, which a traceroute with `resolve_names=True`
+  would otherwise have failed on.
+- `aping`, `aping_many`, `ais_reachable` and `atraceroute` resolve their target in a worker
+  thread, and `atrace_path(resolve_names=True)` looks up each hop's name there too. They called
+  `getaddrinfo` / `gethostbyaddr` on the event-loop thread, so one slow name server stalled every
+  other task in the loop: in `aping_many`, one slow name held up the whole sweep.
+- `is_reachable` / `ais_reachable` resolve the target once and probe that one address on both the
+  ICMP and the TCP attempt; they resolved twice, so round-robin DNS could make the two attempts
+  probe different hosts. ICMP versus TCP is now chosen for the family the target resolved to, not
+  for IPv4, and a socket error from either attempt answers `False` instead of escaping. A
+  `tcp_port` outside 1-65535 raised an uncaught `OverflowError` from the connect; it now makes only
+  the TCP attempt answer `False`, so a host that answers ICMP still reads as reachable.
+- `ping` / `aping` / `ping_many` refuse a `payload_size` above 65507 bytes for an IPv4 target or
+  65527 for IPv6 (raised, or on `.error` with `raise_on_error=False`). Such an echo cannot be sent,
+  and the failed send was reported as a live host that never answered.
+- `wake_on_lan` refuses a port outside 1-65535 with `ValueError`. It raised an uncaught
+  `OverflowError` from the socket layer, which the CLI printed as a traceback.
+- An interface whose sysfs MTU reads 0 is listed with no MTU instead of failing the listing.
+
+### Removed
+
+Backend-module names replaced by the shared definitions above. Nothing in the top-level `ipscout`
+namespace is removed or changed.
+
+- `winapi.IP_SUCCESS`, `IP_DEST_NET_UNREACHABLE`, `IP_DEST_HOST_UNREACHABLE`, `IP_REQ_TIMED_OUT`,
+  `IP_TTL_EXPIRED_TRANSIT`: use `winapi.IpStatus` members, which compare equal to the same numbers.
+- `neighbours_linux`, `neighbours_windows`, `bsdroute` and `tcpsyn` no longer define their own
+  `format_mac`, `MAC_LENGTH` and `checksum`; they import `arp.format_mac`, `arp.MAC_LENGTH` and
+  `packet.checksum` (the same RFC 1071 sum) and drop them from `__all__`. An old import still
+  resolves, except that `neighbours_windows.format_mac` now takes one argument: for a
+  length-prefixed buffer use `neighbours_windows.declared_mac(raw, length)`.
+- `neighbours_windows.resolve_active(ip)` takes the family as a second argument; an IPv4 address in
+  a non-dotted-quad form such as `192.0.2` resolves to nothing instead of being read as `192.0.0.2`.
+
+## [2.1.0] 2026-10-24 17:18:42
+
+### Added
+
+- `grab_banners` / `agrab_banners`: read the first line each of many hosts sends on one TCP port,
+  connecting, reading, optionally sending a `farewell` such as `b"QUIT\r\n"`, and closing on ONE
+  connection per host, so a device that refuses a second connect right after a session is still
+  read. Each host gets a `Banner` whose `BannerState` is `GREETED` (with `line`), `SILENT`,
+  `REFUSED` or `UNREACHABLE` (with `error`); a name that does not resolve is a result, not an
+  exception. One `timeout` per host covers resolution, connect and read; results keep input order.
+- `ipscout banners HOSTS... --port N`, the 22nd subcommand. A `HOSTS` item written as a network
+  expands to its hosts within the sweep bound; `--farewell` decodes `\r`, `\n`, `\t` and `\\`.
+  Exits 1 when no host greeted.
+
+### Fixed
+
+- `ping_many` / `aping_many` return their mapping in the order the targets were given, as documented.
+  It was in completion order, so a target that timed out ahead of one that answered came after it.
+- The TCP fallback (`allow_tcp_fallback`, `is_reachable`) counts a refused connection as an answer
+  in every spelling a platform uses for it. It recognised only `ConnectionRefusedError`, so a refusal
+  arriving as a bare `OSError` with `ECONNREFUSED`, or with the Windows numbering 10061 / 1225,
+  reported a live host as unanswered.
+- In `--json` and `--json-bare` modes, an invalid option value is reported with the option's name
+  (`Invalid value for '--timeout': ...`). The JSON error message carried only Click's bare text,
+  which did not say which option was wrong.
+
 ## [2.0.0] 2026-10-24 12:32:19
 
 ### Changed

{ipscout-2.0.0 → ipscout-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipscout
-Version: 2.0.0
+Version: 2.3.0
 Summary: Ping, traceroute and local-network inspection in pure Python - no subprocess, and no admin rights on the default paths
 Project-URL: Homepage, https://github.com/bitranox/ipscout
 Project-URL: Repository, https://github.com/bitranox/ipscout.git
@@ -29,7 +29,7 @@ Requires-Dist: rtoml>=0.14.0
 Provides-Extra: dev
 Requires-Dist: bandit>=1.9.4; extra == 'dev'
 Requires-Dist: build>=1.6.1; extra == 'dev'
-Requires-Dist: certifi>=2026.10.19; extra == 'dev'
+Requires-Dist: certifi>=2026.10.23; extra == 'dev'
 Requires-Dist: click>=8.5.0; extra == 'dev'
 Requires-Dist: hatchling>=1.32.4; extra == 'dev'
 Requires-Dist: import-linter>=2.15; extra == 'dev'
@@ -201,6 +201,8 @@ ipscout ping-many 127.0.0.1 ::1 -c 1
 ipscout reachable example.com
 ipscout traceroute 1.1.1.1 --max-hops 10
 ipscout scan-ports 192.168.1.10 --ports 22,80,443,8000-8100
+ipscout banners 192.0.2.0/24 --port 21 --farewell 'QUIT\r\n'   # what each host says first
+ipscout snmp-system 192.0.2.0/28        # uptime, name and model over SNMP
 ipscout mac 8.8.8.8                     # the gateway's, labelled NEXT_HOP
 ipscout find-ip dc:b2:2f:44:34:59 --scan
 ipscout arp-scan --network 192.168.1.0/24
@@ -234,6 +236,8 @@ ipscout.sweep_scope()  # what a default sweep covers, and what is too wide for i
 ipscout.default_gateway()  # and query_route() for any destination
 ipscout.subnet_info()  # addressing, gateway, stored DHCP facts
 ipscout.scan_ports(host, "22,80,8000-8100")
+ipscout.grab_banners(hosts, 21, farewell=b"QUIT\r\n")  # each host's first line, on one connection
+ipscout.read_snmp_system(hosts)  # uptime, sysName, sysDescr, sysObjectID; a falling uptime is a restart
 ipscout.path_mtu("8.8.8.8")
 ipscout.wake_on_lan(mac, broadcast="192.168.1.255")
 ipscout.observe_dhcp(mac, interface="br0")  # a machine that has no address yet (needs elevation)
@@ -242,7 +246,9 @@ ipscout.remove_neighbour(ip, interface="eth0")  # and out again
 ```
 
 A MAC address does not survive a router hop, so `lookup_mac` puts the scope in the answer and
-`get_mac_address` returns `None` for anything routed rather than passing off the gateway's as the host's. A
+`get_mac_address` returns `None` for anything routed rather than passing off the gateway's as the host's. Every
+answer also says in `method` whether it was asked for (`active=True`) or read from the cache, and
+`fallback_to_cache=True` reads the cache only when this host cannot ask actively. A
 sweep with no network given covers the subnets this host is attached to that fit inside one sweep's
 4096-address budget, and names the ones left out - a container bridge on a `/16` is skipped rather than
 cancelling the sweep, and a search that matched nothing while a network went uncovered says so instead of

{ipscout-2.0.0 → ipscout-2.3.0}/README.md

@@ -155,6 +155,8 @@ ipscout ping-many 127.0.0.1 ::1 -c 1
 ipscout reachable example.com
 ipscout traceroute 1.1.1.1 --max-hops 10
 ipscout scan-ports 192.168.1.10 --ports 22,80,443,8000-8100
+ipscout banners 192.0.2.0/24 --port 21 --farewell 'QUIT\r\n'   # what each host says first
+ipscout snmp-system 192.0.2.0/28        # uptime, name and model over SNMP
 ipscout mac 8.8.8.8                     # the gateway's, labelled NEXT_HOP
 ipscout find-ip dc:b2:2f:44:34:59 --scan
 ipscout arp-scan --network 192.168.1.0/24
@@ -188,6 +190,8 @@ ipscout.sweep_scope()  # what a default sweep covers, and what is too wide for i
 ipscout.default_gateway()  # and query_route() for any destination
 ipscout.subnet_info()  # addressing, gateway, stored DHCP facts
 ipscout.scan_ports(host, "22,80,8000-8100")
+ipscout.grab_banners(hosts, 21, farewell=b"QUIT\r\n")  # each host's first line, on one connection
+ipscout.read_snmp_system(hosts)  # uptime, sysName, sysDescr, sysObjectID; a falling uptime is a restart
 ipscout.path_mtu("8.8.8.8")
 ipscout.wake_on_lan(mac, broadcast="192.168.1.255")
 ipscout.observe_dhcp(mac, interface="br0")  # a machine that has no address yet (needs elevation)
@@ -196,7 +200,9 @@ ipscout.remove_neighbour(ip, interface="eth0")  # and out again
 ```
 
 A MAC address does not survive a router hop, so `lookup_mac` puts the scope in the answer and
-`get_mac_address` returns `None` for anything routed rather than passing off the gateway's as the host's. A
+`get_mac_address` returns `None` for anything routed rather than passing off the gateway's as the host's. Every
+answer also says in `method` whether it was asked for (`active=True`) or read from the cache, and
+`fallback_to_cache=True` reads the cache only when this host cannot ask actively. A
 sweep with no network given covers the subnets this host is attached to that fit inside one sweep's
 4096-address budget, and names the ones left out - a container bridge on a `/16` is skipped rather than
 cancelling the sweep, and a search that matched nothing while a network went uncovered says so instead of

{ipscout-2.0.0 → ipscout-2.3.0}/docs/systemdesign/module_reference.md

@@ -58,7 +58,7 @@ The import-linter contract `Layered dependencies point one way only` is enforced
 listed highest first; each may import only from those below it.
 
 ```
-scan : subnet : portscan : mtu : wol   sweeps and single-purpose probes
+scan : subnet : portscan : banner : snmp : mtu : wol : dhcp   sweeps and single-purpose probes
 api          ping / aping / ping_many / aping_many / is_reachable / ais_reachable
 traceroute   traceroute / atraceroute / trace_path / atrace_path
 static_neighbours  set_neighbour / remove_neighbour
@@ -71,7 +71,9 @@ transport_posix : transport_windows : transport_tcp
   : interfaces_posix : interfaces_windows
   : routes_linux : routes_macos : routes_windows
   : neighbours_linux : neighbours_macos : neighbours_windows
-packet : resolve : ports : winapi : netlink : bsdroute : arp : tcpsyn
+  : dhcp_linux : dhcp_windows : dhcp_macos
+packet : deadline : resolve : ports : winapi : netlink : bsdroute : arp : tcpsyn
+  : pool : sockerr : unixio : bootp : bpf : snmpber
 models
 errors
 ```
@@ -102,8 +104,11 @@ caller asked for and what the machine could do. A transport reports what happene
 ### Data flow, one ping
 
 1. `api.ping` resolves the target once through `resolve.resolve_one`, which fixes the address
-   family up front rather than guessing it later.
-2. `api._prepare` builds a `service.PingRequest`. Pydantic field bounds reject a bad `times`,
+   family up front rather than guessing it later. The async entry points (`aping`,
+   `ais_reachable`, `atraceroute`, and the hop names of `atrace_path`) run that lookup in a worker
+   thread, because `getaddrinfo` blocks for as long as the name server takes and one slow name on
+   the loop thread would stall every other probe in a sweep.
+2. `api._request` builds a `service.PingRequest`. Pydantic field bounds reject a bad `times`,
    `timeout` or `interval` here, before any packet moves, identically for every caller path.
 3. `factory.make_transport` picks the backend.
 4. `service.run_ping` sends the echoes, paced against the run's start so a slow reply does not push
@@ -196,39 +201,45 @@ own value only as a fallback, which keeps loopback and LAN timings meaningful.
 
 ### Public surface
 
-| Module                 | Role                                                                                                                              |
-|------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `__init__.py`          | Re-exports the public API so importers depend on the package, not its layout.                                                     |
-| `api.py`               | `ping`, `aping`, `ping_many`, `aping_many`, `is_reachable`, `ais_reachable`. Owns the error contract.                             |
-| `traceroute.py`        | `traceroute`, `atraceroute`, `trace_path`, `atrace_path`, and the capability refusal.                                             |
-| `interfaces.py`        | `local_interfaces`, dispatching to the per-OS backend.                                                                            |
-| `routes.py`            | `query_route`, `default_gateway`, dispatching to the per-OS backend.                                                              |
-| `neighbours.py`        | `neighbours`, `lookup_mac`, `get_mac_address`, `resolve_active`, `normalise_mac`.                                                 |
-| `static_neighbours.py` | `set_neighbour`, `remove_neighbour`: write and delete a permanent IPv4 entry, choosing the interface and reading the result back. |
-| `scan.py`              | `arp_scan`, `find_ip_by_mac`, `local_networks`, `sweep_scope`. Sweep, then read what the kernel learned.                          |
-| `subnet.py`            | `subnet_info`, composing interfaces, routes and the stored lease.                                                                 |
-| `portscan.py`          | `scan_ports`, `ascan_ports`, `syn_scan`, `parse_ports`.                                                                           |
-| `mtu.py`               | `path_mtu`, by kernel query on Linux and by bisection elsewhere.                                                                  |
-| `wol.py`               | `wake_on_lan` and the magic packet it builds.                                                                                     |
-| `dhcp.py`              | `observe_dhcp` and its session: the capture loop, the quiet window and the platform dispatch.                                     |
-| `resolve.py`           | `resolve`, `resolve_one` (returns a `ResolvedTarget` named tuple), `reverse_dns`, `family_of`.                                    |
-| `factory.py`           | `make_transport`, `make_async_transport`, `icmp_available`. The only `sys.platform` branch in the probing path.                   |
+| Module                 | Role                                                                                                                                                                      |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `__init__.py`          | Re-exports the public API so importers depend on the package, not its layout.                                                                                             |
+| `api.py`               | `ping`, `aping`, `ping_many`, `aping_many`, `is_reachable`, `ais_reachable`. Owns the error contract.                                                                     |
+| `traceroute.py`        | `traceroute`, `atraceroute`, `trace_path`, `atrace_path`, and the capability refusal.                                                                                     |
+| `interfaces.py`        | `local_interfaces`, dispatching to the per-OS backend.                                                                                                                    |
+| `routes.py`            | `query_route`, `default_gateway`, dispatching to the per-OS backend.                                                                                                      |
+| `neighbours.py`        | `neighbours`, `lookup_mac`, `get_mac_address`, `resolve_active`, `normalise_mac`, and `ask_or_read_cache`, the one rule for falling back from an active ask to the cache. |
+| `static_neighbours.py` | `set_neighbour`, `remove_neighbour`: write and delete a permanent IPv4 entry, choosing the interface and reading the result back.                                         |
+| `scan.py`              | `arp_scan`, `find_ip_by_mac`, `local_networks`, `sweep_scope`. Sweep, then read what the kernel learned.                                                                  |
+| `subnet.py`            | `subnet_info`, composing interfaces, routes and the stored lease.                                                                                                         |
+| `portscan.py`          | `scan_ports`, `ascan_ports`, `syn_scan`, `parse_ports`.                                                                                                                   |
+| `banner.py`            | `grab_banners`, `agrab_banners`: connect, read the first line, say goodbye and close, all on one connection per host.                                                     |
+| `snmp.py`              | `read_snmp_system`, `aread_snmp_system`: one SNMP GET of the system group per host on a connected UDP socket, re-asking under v1 without a value the agent lacks.         |
+| `mtu.py`               | `path_mtu`, by kernel query on Linux and by bisection elsewhere.                                                                                                          |
+| `wol.py`               | `wake_on_lan` and the magic packet it builds.                                                                                                                             |
+| `dhcp.py`              | `observe_dhcp` and its session: the capture loop, the quiet window and the platform dispatch.                                                                             |
+| `resolve.py`           | `resolve`, `resolve_one` (returns a `ResolvedTarget` named tuple), `reverse_dns`, `family_of`.                                                                            |
+| `factory.py`           | `make_transport`, `make_async_transport`, `icmp_available`. The only `sys.platform` branch in the probing path.                                                           |
 
 ### Core
 
-| Module        | Role                                                                                                                    |
-|---------------|-------------------------------------------------------------------------------------------------------------------------|
-| `errors.py`   | `IPScoutError` and its subclasses, sweep refusals included. No dependencies.                                            |
-| `models.py`   | Frozen result models and the `str`-subclass enums.                                                                      |
-| `ports.py`    | `EchoResult`, `EchoTransport`, `AsyncEchoTransport`. The seams.                                                         |
-| `packet.py`   | ICMP encode and decode. Total functions over bytes: no sockets, no clock, no I/O.                                       |
-| `service.py`  | `PingRequest`, `run_ping`, `arun_ping`. Probe sequencing and aggregation.                                               |
-| `netlink.py`  | Message and attribute walkers and encoders, and the acknowledgement reader, for the Linux route and neighbour backends. |
-| `bsdroute.py` | Routing-message and `sockaddr` walkers and encoders for the macOS backends, plus `sysctl`.                              |
-| `arp.py`      | ARP and NDP codecs. Testable without the privilege the sockets need.                                                    |
-| `bootp.py`    | BOOTP/DHCP reply codec, separate from the capture for the same reason.                                                  |
-| `bpf.py`      | BSD packet filter ioctl encoding and record splitting, shared by two backends.                                          |
-| `tcpsyn.py`   | TCP SYN codec and its pseudo-header checksum, for the half-open scan.                                                   |
+| Module        | Role                                                                                                                                              |
+|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| `errors.py`   | `IPScoutError` and its subclasses, sweep refusals included, and `could_not_ask` for a resolution request that could not be sent. No dependencies. |
+| `models.py`   | Frozen result models and the `str`-subclass enums.                                                                                                |
+| `ports.py`    | `EchoResult`, `EchoTransport`, `AsyncEchoTransport`. The seams.                                                                                   |
+| `packet.py`   | ICMP encode and decode. Total functions over bytes: no sockets, no clock, no I/O.                                                                 |
+| `service.py`  | `PingRequest`, `run_ping`, `arun_ping`. Probe sequencing and aggregation.                                                                         |
+| `netlink.py`  | Message and attribute walkers and encoders, and the acknowledgement reader, for the Linux route and neighbour backends.                           |
+| `bsdroute.py` | Routing-message and `sockaddr` walkers and encoders for the macOS backends, plus `sysctl`.                                                        |
+| `arp.py`      | ARP and NDP codecs. Testable without the privilege the sockets need.                                                                              |
+| `bootp.py`    | BOOTP/DHCP reply codec, separate from the capture for the same reason.                                                                            |
+| `bpf.py`      | BSD packet filter ioctl encoding and record splitting, shared by two backends.                                                                    |
+| `tcpsyn.py`   | TCP SYN codec and its pseudo-header checksum, for the half-open scan.                                                                             |
+| `deadline.py` | `within` and `failure_reason`: one deadline across several awaits, shared by the banner grab and the SNMP read.                                   |
+| `snmpber.py`  | BER encode of an SNMP GET and a structural parse of the reply. Total functions over bytes, like `packet.py`.                                      |
+| `pool.py`     | `gather_bounded`: a fixed worker pool, so a long work list never becomes one Task per item.                                                       |
+| `sockerr.py`  | `is_refusal`: one reading of a refused connect across every platform's spelling, shared by every module that connects.                            |
 
 ### Platform backends
 
@@ -253,13 +264,13 @@ own value only as a fallback, which keeps loopback and LAN timings meaningful.
 
 ### CLI adapter
 
-| Module              | Role                                                                       |
-|---------------------|----------------------------------------------------------------------------|
-| `cli.py`            | The rich-click group, twenty-one subcommands, `_emit` and `_fail`, `main`. |
-| `serialize.py`      | `to_jsonable` and `dumps` at the output boundary.                          |
-| `typed_click.py`    | Typed facade over rich-click's partially-typed decorators.                 |
-| `__main__.py`       | `python -m ipscout`.                                                       |
-| `__init__conf__.py` | Static package metadata, kept in sync with `pyproject.toml` by automation. |
+| Module              | Role                                                                         |
+|---------------------|------------------------------------------------------------------------------|
+| `cli.py`            | The rich-click group, twenty-three subcommands, `_emit` and `_fail`, `main`. |
+| `serialize.py`      | `to_jsonable` and `dumps` at the output boundary.                            |
+| `typed_click.py`    | Typed facade over rich-click's partially-typed decorators.                   |
+| `__main__.py`       | `python -m ipscout`.                                                         |
+| `__init__conf__.py` | Static package metadata, kept in sync with `pyproject.toml` by automation.   |
 
 ---
 
@@ -276,6 +287,8 @@ and mutating it can only make it disagree with reality.
 | `InterfaceAddress`   | `address`, `prefix_len`                                                                                                                                                                                                                                         |
 | `MacLookup`          | `ip`, `mac`, `scope`, `via_ip`, `interface`                                                                                                                                                                                                                     |
 | `SubnetInfo`         | `interface`, `address`, `prefix_len`, `network`, `family`, `broadcast`, `gateway`, `dns_servers`, `domain`, `dhcp_server`, `lease_obtained`, `lease_expires`, `mtu`                                                                                             |
+| `Banner`             | `host`, `port`, `state`, `line`, `error`                                                                                                                                                                                                                        |
+| `SnmpSystem`         | `host`, `state`, `uptime_seconds`, `name`, `description`, `object_id`, `error`                                                                                                                                                                                  |
 | `CapabilityReport`   | `icmp_ipv4`, `icmp_ipv6`, `traceroute`                                                                                                                                                                                                                          |
 | `ReachabilityReport` | `target`, `reachable`                                                                                                                                                                                                                                           |
 | `ResolveReport`      | `target`, `addresses`                                                                                                                                                                                                                                           |