hvac-network-scanner 2.14.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,763 @@
1
+ Metadata-Version: 2.4
2
+ Name: hvac-network-scanner
3
+ Version: 2.14.1
4
+ Summary: Multi-protocol HVAC / building automation network scanner (BACnet/IP, MSTP, Modbus TCP, Niagara Fox, OPC UA, SNMP, and more)
5
+ Author: James Cupps
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/jamesccupps/HVAC-Network-Scanner
8
+ Project-URL: Issues, https://github.com/jamesccupps/HVAC-Network-Scanner/issues
9
+ Project-URL: Changelog, https://github.com/jamesccupps/HVAC-Network-Scanner/blob/main/CHANGELOG.md
10
+ Keywords: bacnet,modbus,hvac,building-automation,niagara,siemens,trane,network-scanner
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Environment :: Win32 (MS Windows)
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: Intended Audience :: Information Technology
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: System :: Networking :: Monitoring
24
+ Classifier: Topic :: System :: Hardware
25
+ Requires-Python: >=3.10
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=7.4; extra == "dev"
30
+ Requires-Dist: pytest-cov>=4.1; extra == "dev"
31
+ Provides-Extra: build
32
+ Requires-Dist: pyinstaller>=6.0; extra == "build"
33
+ Dynamic: license-file
34
+
35
+ # HVAC Network Scanner
36
+
37
+ [![CI](https://github.com/jamesccupps/HVAC-Network-Scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/jamesccupps/HVAC-Network-Scanner/actions/workflows/ci.yml)
38
+ [![Latest release](https://img.shields.io/github/v/release/jamesccupps/HVAC-Network-Scanner?label=release)](https://github.com/jamesccupps/HVAC-Network-Scanner/releases/latest)
39
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/LICENSE)
40
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
41
+
42
+ A multi-protocol discovery and audit tool for HVAC and building automation networks. Zero third-party dependencies — everything runs on the Python 3.10+ standard library.
43
+
44
+ **Website: [jamesccupps.github.io/HVAC-Network-Scanner](https://jamesccupps.github.io/HVAC-Network-Scanner/)** · [Download for Windows](https://github.com/jamesccupps/HVAC-Network-Scanner/releases/latest/download/HVACNetworkScanner.exe) · [All releases](https://github.com/jamesccupps/HVAC-Network-Scanner/releases)
45
+
46
+ ![HVAC Network Scanner](https://raw.githubusercontent.com/jamesccupps/HVAC-Network-Scanner/v2.14.1/docs/screenshots/main-window.png)
47
+
48
+ Working with Siemens APOGEE P2? The [APOGEE P2 toolkit](https://github.com/jamesccupps/P2_Wireshark_Dissector_And_P2_Scanner) has a Wireshark dissector, a read-only P2 scanner and the [protocol reference](https://jamesccupps.github.io/p2/).
49
+
50
+ ## What it does
51
+
52
+ Scans a network and tells you what building-automation gear lives on it. For each device found it tries to identify the exact model, pull readable points or registers, and surface the factory-default credentials that ship with that product so you can confirm they've been changed. The report also checks the firmware each controller reports against published CISA ICS advisories (Trane Tracer SC+, Siemens APOGEE PXC and TALON TC, Desigo PX, PXC and DXR2, Desigo CC), and says which to update and which to check by hand.
53
+
54
+ Works against:
55
+
56
+ - **BACnet/IP** — raw UDP `Who-Is` / `I-Am`, `ReadProperty`, and `ReadPropertyMultiple`. No BAC0 dependency, works on newer python versions. Reaches other subnets and VLANs by unicast discovery or through a BBMD. Reads BBMDs' broadcast and foreign-device tables, and each controller's trend logs, schedules and calendars as metadata.
57
+ - **BACnet MSTP** — device enumeration behind BACnet routers via `Who-Is-Router-To-Network` and targeted `Who-Is` to remote DNETs, including routers on other subnets with no BBMD.
58
+ - **BACnet/SC** — detects BACnet Secure Connect hubs (including ones devices name on nonstandard ports), and reports any that let a connection in without a client certificate.
59
+ - **KNXnet/IP** — finds KNX IP interfaces and routers on UDP 3671 and flags the ones offering tunneling or routing without KNX Secure.
60
+ - **LonWorks/IP (IP-852)** — finds IP-852 routers and nodes on UDP 1628 (i.LON and SmartServer, LOYTEC L-IP, and controllers with an IP-852 channel of their own) and reads what each says about itself: node type, the name it was given, Neuron IDs, configuration server, and whether IP-852 authentication is on.
61
+ - **Serial gateways** — finds Moxa NPort, MGate and OnCell devices with Moxa's identify request on UDP 4800 (never its credential functions). These are often where P1, N2, MS/TP and Modbus RTU buses reach the network.
62
+ - **Modbus TCP** — port sweep, device identification (FC 43 / MEI 14), holding/input register reads, and coil reads.
63
+ - **HVAC services** — Niagara Fox (station name, Niagara version, OS, host ID, brand; AX stations flagged as end of life) and the Niagara platform ports, OPC UA (the server's own name and product, and whether it allows unsecured endpoints or anonymous sessions, on 4840 and KEPServerEX's 49320), Siemens S7, EtherNet/IP CIP, MQTT, WebCTRL, Metasys, plus HTTP/HTTPS banner grabs.
64
+ - **SNMP v1/v2c** — raw UDP `sysDescr` probe, no pysnmp dependency.
65
+ - **Siemens APOGEE P2** — detects firmware 2.x APOGEE field panels and P2
66
+ supervisors on TCP/5033 without registering on them (see below).
67
+
68
+ Model identification combines signals from multiple protocols:
69
+
70
+ - Trane Tracer SC / SC+ / UC600 / UC400, Symbio, Tracer Ensemble, TR200 drives
71
+ - Siemens PXC Modular / Compact field panels, Desigo PXC4 / PXC5 / PXC7, DXR2 room controllers, Desigo CC, Insight
72
+ - Johnson Controls FEC / Metasys NAE
73
+ - Honeywell / Tridium Niagara
74
+ - Schneider EcoStruxure / SmartX
75
+ - Contemporary Controls BASRT-B routers
76
+ - Carrier i-Vu, Automated Logic WebCTRL, Alerton, Distech, Delta, KMC, Reliable, Carel, Belimo, Daikin, Mitsubishi (MelcoBEMS MINI), LG, Yaskawa HV600 drives, Moxa, and more
77
+
78
+ ## Tested against (verified hardware)
79
+
80
+ The scanner has been verified against real hardware in live
81
+ installations. These devices have known-good classification profiles:
82
+
83
+ - **Trane Tracer SC+** — supervisory controller (5,000+ objects)
84
+ - **Trane Symbio 400-500** — field controller (MSTP)
85
+ - **Trane Tracer Ensemble (TES Workstation)** — supervisor
86
+ (handles RPM rejection via fallback to single ReadProperty)
87
+ - **Siemens PXC Compact** (EPXC V3.5.x firmware) — field panel
88
+ - **Siemens PXC Modular** (PXME V3.5.x firmware) — field panel
89
+ (verified with 1,960-object program)
90
+ - **Siemens DXR2.E10PL-1, .E12P-1, .E18-1** — room controllers
91
+ - **Siemens Desigo CC / Insight** — supervisors
92
+
93
+ Across these, the scanner has been tested with ~13,000 points read
94
+ and ~30,000 paired BACnet exchanges at zero wire-level errors.
95
+
96
+ **For hardware not on this list**, the scanner uses a size-based
97
+ heuristic that sets an appropriate object enumeration cap from the
98
+ device's own reported object count. This is expected to work
99
+ correctly for any BACnet-compliant device. If you scan a device that
100
+ isn't on this list, please consider [contributing a profile](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CONTRIBUTING.md)
101
+ so future users can benefit from verified classification.
102
+
103
+ **Known out-of-scope:**
104
+
105
+ - Devices on serial buses: Siemens P1/FLN, Johnson Controls N2, LonTalk on
106
+ twisted pair, MS/TP without a router, DALI, M-Bus. They are not on IP, so
107
+ no network scanner sees them directly. The scanner finds the gateways
108
+ that carry them: BACnet routers (and the MS/TP devices behind them),
109
+ IP-852 routers, Moxa serial gateways, KNX IP interfaces.
110
+ - Reading points from panels running proprietary firmware without
111
+ BACnet/IP. Siemens APOGEE PXC panels on firmware revision 2.x speak P2
112
+ rather than BACnet/IP: the scanner **detects** them (and P2 supervisors)
113
+ and tells you so, but does not read their points — that needs a P2
114
+ session with the site's BLN name, which registers the client on the
115
+ panel. For that, use the
116
+ [P2 scanner](https://github.com/jamesccupps/P2_Wireshark_Dissector_And_P2_Scanner),
117
+ a commercial gateway such as PurpleSwift BACnetP2, or upgrade the panels
118
+ to firmware 3.x, which speaks BACnet/IP.
119
+
120
+ How detection works: each host with TCP/5033 open gets one well-formed P2
121
+ identify frame carrying a BLN name no site uses. A field panel resets the
122
+ connection at its access gate, a supervisor listener closes it, both
123
+ before any processing and without writing to the node table. One
124
+ attempt, one fixed name — not a handshake and not BLN-name guessing.
125
+ - Proprietary BMS protocols that are not BACnet or Modbus TCP
126
+ (JCI N2, LonTalk, Honeywell C-Bus, various others).
127
+
128
+ ## Install
129
+
130
+ ```bash
131
+ git clone https://github.com/jamesccupps/HVAC-Network-Scanner.git
132
+ cd HVAC-Network-Scanner
133
+ pip install -e .
134
+ ```
135
+
136
+ Or run straight from the source tree without installing:
137
+
138
+ ```bash
139
+ python -m hvac_scanner # launches the GUI
140
+ python -m hvac_scanner.cli --help
141
+ ```
142
+
143
+ Requires Python 3.10 or newer. No extra packages.
144
+
145
+ ### Try it without a building
146
+
147
+ `tools/sim_site.py` stands up a small simulated site on loopback addresses —
148
+ a Trane SC+, Siemens PXC and DXR2 controllers, an MS/TP router with three
149
+ JCI field controllers behind it, a workstation that rejects
150
+ ReadPropertyMultiple, Modbus meters and a gateway, an APOGEE P2 panel and
151
+ supervisor, a Niagara JACE with SNMP
152
+ and Fox, and web UIs. Real sockets on the real ports, so the whole scanner
153
+ runs against it:
154
+
155
+ ```bash
156
+ python tools/sim_site.py # leave running
157
+ python -m hvac_scanner # scan 127.0.0.2-30 in the GUI
158
+ ```
159
+
160
+ The screenshot above was taken against it. Windows and Linux only (macOS
161
+ needs loopback aliases); ports below 1024 need root on Linux.
162
+
163
+ ### Install with Scoop
164
+
165
+ On Windows with [Scoop](https://scoop.sh), the executable below installs with
166
+ two commands and gets a Start menu shortcut:
167
+
168
+ ```powershell
169
+ scoop bucket add jamesccupps https://github.com/jamesccupps/scoop-bucket
170
+ scoop install jamesccupps/hvac-network-scanner
171
+ ```
172
+
173
+ No Scoop yet? [scoop.sh](https://scoop.sh) shows how to install it. The
174
+ scanner still updates itself; `scoop update hvac-network-scanner` works too.
175
+
176
+ ### Standalone executable
177
+
178
+ For a Windows machine without Python — an engineering workstation you would
179
+ rather not install anything on — grab `HVACNetworkScanner.exe` from the
180
+ [latest release](https://github.com/jamesccupps/HVAC-Network-Scanner/releases).
181
+ One ~13 MB file, no installer, no runtime.
182
+
183
+ To build it yourself:
184
+
185
+ ```bash
186
+ pip install --require-hashes -r packaging/requirements-build.txt
187
+ pyinstaller packaging/hvac_scanner.spec --noconfirm
188
+ # -> dist/HVACNetworkScanner.exe
189
+ ```
190
+
191
+ PyInstaller is a build dependency only; the package itself stays
192
+ dependency-free at runtime. `packaging/requirements-build.txt` pins it and
193
+ everything it needs by version and hash, the same file CI builds from. The executable ships the GUI — the CLI remains
194
+ available from a normal Python install.
195
+
196
+ **The executable is code-signed** (from 2.13.1): its Authenticode signature
197
+ names James Cupps as the publisher, and Windows checks it. SmartScreen can
198
+ still warn about a new release until enough people have downloaded it; then
199
+ **More info** shows the publisher, and **Run anyway** goes on. A signature says
200
+ who built the file, not what it does, and a network scanner is exactly the sort
201
+ of program where you should not simply take that on trust.
202
+
203
+ Verify it before you run it. Each release publishes the SHA-256 of the
204
+ executable in its notes and as `HVACNetworkScanner.exe.sha256`; compare it
205
+ against the file you got:
206
+
207
+ ```powershell
208
+ Get-FileHash .\HVACNetworkScanner.exe -Algorithm SHA256
209
+ ```
210
+
211
+ The binary is built by GitHub Actions from the tagged commit, not on a
212
+ developer machine — the workflow is in
213
+ [.github/workflows/ci.yml](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/.github/workflows/ci.yml) and its build log is
214
+ public, so you can see exactly what went into it, including the hash. From
215
+ 2.9.1 the build also signs an attestation that ties the file to that
216
+ workflow run and commit; with the [GitHub CLI](https://cli.github.com/):
217
+
218
+ ```powershell
219
+ gh attestation verify .\HVACNetworkScanner.exe --repo jamesccupps/HVAC-Network-Scanner
220
+ ```
221
+
222
+ If you would rather not trust a binary at all, build it yourself with the two
223
+ commands above; it is the same spec file and the same pinned tooling CI uses.
224
+
225
+ **Updates.** The executable checks for a new release once a day. From 2.13
226
+ it downloads it by itself, checks it against the release's `latest.json` (a
227
+ manifest signed with the project's Ed25519 key; the public half is built into
228
+ the app) and installs it when you close the scanner; **Restart to update to …**
229
+ in the header installs it at once. If anything fails, the previous exe is put
230
+ back. Turn **Install updates automatically** off in Advanced to be asked
231
+ instead (**Update to …**), or the daily check off altogether. A copy run from
232
+ Python is told about new versions instead. Copies older than 2.10 need one
233
+ manual download.
234
+
235
+ **Advisory list.** The firmware findings come from CISA's ICS advisories. A
236
+ daily GitHub workflow rebuilds the list from CISA's machine-readable data and
237
+ publishes it signed; the app picks it up with its daily check (or
238
+ `--update-advisories`), so new advisories reach the report without a new
239
+ release. The report says how current its list is.
240
+
241
+ ## Using the GUI
242
+
243
+ ```bash
244
+ python -m hvac_scanner
245
+ ```
246
+
247
+ Type the network(s) to scan, tick the protocols, press **Scan** (or
248
+ Ctrl+Enter). Results appear as each device finishes, not at the end:
249
+
250
+ - **Devices** — one row per device across protocols: address, the device's
251
+ own name, model, vendor, type, web UI and the factory-default credentials
252
+ for that product. Select a row for everything the scan learned about it in
253
+ the details panel; double-click it (or **Show points**) to list its points.
254
+ Right-click for web UI, copy, ping.
255
+ - **BACnet Points** — every object read, with present value, engineering
256
+ units and status. Points in alarm or fault are red, overridden or out of
257
+ service amber, and multi-state values read as their state text
258
+ ("Occupied"). Double-click a point for its full name and description.
259
+ - **Trends, Schedules & Alarms** — what each trend log records, how often,
260
+ and whether it is still recording (disabled or full-and-stopped logs stand
261
+ out); each schedule's weekly program and the objects it controls; and
262
+ each notification class's alarm recipients, priorities and
263
+ acknowledgement (a class routed to no one stands out).
264
+ - **Modbus Registers**, **Services** (open ports, banners, page titles, TLS
265
+ certificates) and **Raw JSON**.
266
+
267
+ The filter box (Ctrl+F) narrows every tab at once — type `vav` or a device
268
+ name or an IP. Column headers sort; IP addresses sort numerically. Ctrl+C
269
+ copies the selected rows as tab-separated text that pastes straight into a
270
+ spreadsheet. A device name that starts like a formula (`=`, `+`, `-`, `@`)
271
+ is pasted, and exported to CSV, as text: device names are chosen by whoever
272
+ controls the device, and BACnet names can be changed by anyone on the
273
+ network.
274
+
275
+ **Depth** sets how much of each device is read. *devices* reads only each
276
+ device's identity (name, model, vendor, firmware, description, location):
277
+ the fastest inventory, with no points; tick *Services* as well for devices
278
+ and their open ports. *quick* samples about 5% of each device's points,
279
+ *normal* (the default) reads up to each model's known size, and *full*
280
+ reads everything.
281
+
282
+ The scan log gives every section the clock time and the time since the
283
+ start, says how long each device took and how many of its requests went
284
+ unanswered, and ends with where the time went pass by pass.
285
+
286
+ **Export** writes a **survey report** (HTML — findings, inventory and open
287
+ services in one file you can hand to the building owner), the device list
288
+ (CSV), a **point list** (CSV, one row per point and register — the thing you
289
+ take away from a site survey), the full results (JSON, also Ctrl+S) or a
290
+ classification report. **Compare** diffs this
291
+ scan against an earlier JSON export.
292
+
293
+ **Advanced** holds the timeout (the longest wait; a device that has
294
+ answered quickly gets a shorter one, never under a second), the per-device rate limit (use 20-50 ms on
295
+ sites with small field controllers), parallel deep scans, a per-device time
296
+ limit (180 s; a device that reaches it keeps what was read and is marked
297
+ partial), unicast discovery,
298
+ BBMD registration, broadcast override, Who-Is chunking, an object cap,
299
+ SNMP communities, and the MS/TP address probe for trunks behind routers on
300
+ other subnets. Everything you set is remembered for next time; while the
301
+ panel is folded away the button says how many settings differ from the
302
+ defaults, and the scan log lists them when a scan starts. A number that is
303
+ not a number stops the scan with the reason rather than falling back to a
304
+ default. A scan of more than 1,024 addresses in all asks first.
305
+
306
+ **Site** saves the targets and every option under a name — for the
307
+ buildings you audit again and again — and brings them back from the list.
308
+ The CLI runs the same profiles with `--profile NAME`.
309
+
310
+ ### Target syntax
311
+
312
+ The target field and CLI accept any mix of:
313
+
314
+ ```
315
+ 10.0.0.0/24 # CIDR
316
+ 10.0.0.5 # single host
317
+ 10.0.0.2-100 # last-octet range
318
+ 10.0.0.2-10.0.0.12 # full-IP range
319
+ 10.0.0.0/30, 10.0.1.5, 10.0.2.1-20 # mixed list
320
+ ```
321
+
322
+ The broadcast address for BACnet Who-Is is computed automatically from
323
+ whatever you type — narrow CIDRs (e.g. `/26`), ranges, and single hosts
324
+ all auto-broadcast to the enclosing `/24`. The scan log shows the chosen
325
+ broadcast target so it's never magic. Power users can override via the
326
+ `--broadcast` CLI flag or `ScanOptions.bacnet_broadcast`.
327
+
328
+ ## Using the CLI
329
+
330
+ New in v2. Runs headless — no display, no Tk. Intended for Task Scheduler, cron, and CI pipelines.
331
+
332
+ ```bash
333
+ # Basic scan of a /24
334
+ python -m hvac_scanner.cli 192.168.1.0/24
335
+
336
+ # Multiple networks, export to JSON and CSV
337
+ python -m hvac_scanner.cli 10.0.0.0/24 10.0.1.0/24 \
338
+ --json scan.json --csv scan.csv
339
+
340
+ # BACnet only, with conservative rate limiting for small JACEs / UC400s
341
+ python -m hvac_scanner.cli 192.168.5.0/24 --bacnet-only --rate-limit 50
342
+
343
+ # Large-campus friendly: chunk Who-Is by 1000-instance ranges instead of
344
+ # one global broadcast. Avoids I-Am storms on big sites.
345
+ python -m hvac_scanner.cli 10.0.0.0/24 --whois-chunk 1000 --rate-limit 50
346
+
347
+ # Scan a narrow range of hosts — broadcast is auto-computed:
348
+ python -m hvac_scanner.cli 10.0.0.2-100
349
+
350
+ # Target specific devices only (no scan sweep at all):
351
+ python -m hvac_scanner.cli 10.0.0.19,10.0.0.21,10.0.0.192
352
+
353
+ # The BAS is on its own VLAN and broadcasts do not reach it: ask each
354
+ # address directly (this happens automatically for non-local subnets)
355
+ python -m hvac_scanner.cli 10.50.20.0/24 --unicast always
356
+
357
+ # ...and find the MS/TP devices behind its routers too, no BBMD needed
358
+ # (a few minutes per MS/TP network: two addresses at a time)
359
+ python -m hvac_scanner.cli 10.50.20.0/24 --unicast always --mstp-probe
360
+
361
+ # A site saved in the GUI, with its own targets and options
362
+ python -m hvac_scanner.cli --profile "Building A" --html survey.html
363
+
364
+ # Several SNMP communities, tried in turn
365
+ python -m hvac_scanner.cli 10.0.0.0/24 --snmp-community public --snmp-community bas
366
+
367
+ # Survey report and point list for the building owner
368
+ python -m hvac_scanner.cli 10.0.0.0/24 --html survey.html --points-csv points.csv
369
+
370
+ # ...or build the report later from a saved scan
371
+ python -m hvac_scanner.report scan.json -o survey.html
372
+
373
+ # Power-user: override the auto-computed broadcast
374
+ python -m hvac_scanner.cli 10.0.0.0/24 --broadcast 255.255.255.255
375
+
376
+ # Quiet mode for scheduled runs
377
+ python -m hvac_scanner.cli 192.168.5.0/24 --json /var/log/bas-scan.json --quiet
378
+
379
+ # Generate a classification report — handy when you've scanned gear
380
+ # that fell back to the heuristic and you want to submit a profile:
381
+ python -m hvac_scanner.cli 10.0.0.0/24 --export-classification report.txt
382
+ ```
383
+
384
+ See [docs/CLI_USAGE.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/docs/CLI_USAGE.md) for the full flag reference and a Windows Task Scheduler XML example.
385
+
386
+ Exit codes:
387
+
388
+ - `0` — scan completed
389
+ - `1` — bad arguments (including a value out of range, more addresses than
390
+ `--max-hosts`, public addresses without `--allow-public`, or a `--baseline`
391
+ file that is missing or damaged)
392
+ - `2` — interrupted (Ctrl+C), so the results are partial
393
+ - `3` — internal error
394
+ - `4` — scan completed and differed from the baseline (`--fail-on-change`)
395
+
396
+ ## What's new
397
+
398
+ ### v2.14.1 (2026-11-16)
399
+
400
+ - **Every Desigo CC and Insight server shows in the P2 results**: one that
401
+ took just over 2 s to refuse the probe was left out, a different one each
402
+ scan.
403
+ - **A scan from another subnet says when MS/TP devices are out of sight**:
404
+ their routers' broadcasts don't cross subnets, so they were simply missing.
405
+ The scan log and the report now say so and name the BBMD to register with.
406
+ - **A dropped read is asked again**: a controller that missed one request no
407
+ longer loses its model name (a DXR2 was called a PXC, with the PXC default
408
+ password) or its segmentation.
409
+
410
+ ### v2.14.0 (2026-11-15)
411
+
412
+ - **Show points opens the right tab, and the device list stays put**: on a
413
+ Modbus device it opened Trends instead of Modbus Registers, and after it the
414
+ Devices tab listed nothing until the filter was cleared. Each tab now keeps
415
+ its own filter, with a **Clear** button (or Esc) beside it.
416
+ - **One device can no longer spoil the results**: a value cut short by a
417
+ device used to drop all of its trend logs, schedules, alarm routing and
418
+ network ports from the scan, and an oddly encoded alarm recipient could
419
+ stop the HTML report for the whole scan. Now only the object or field it
420
+ belongs to is affected, and the scan log says so.
421
+ - **Sites saved at depth "devices" stay that gentle**: they used to run as a
422
+ normal deep scan from `--profile` and in the window.
423
+ - **Public addresses need a yes**: a target that reaches public internet
424
+ addresses (a mistyped first octet, say) brings up a question naming them;
425
+ on the command line it needs `--allow-public`.
426
+ - **Number settings are checked the same way everywhere**: `nan`, `inf` and
427
+ values like 99999999999 are refused with the reason, in the window, on the
428
+ command line and in saved site profiles.
429
+ - Smaller fixes: a field marked wrong is unmarked once it checks out; the
430
+ settings file is readable by its owner only on Linux and macOS; a
431
+ downloaded update is checked again just before it installs; the OPC UA
432
+ probe has a time limit like the others; device names reach the terminal
433
+ without control characters; a range like `300.1.1.2-4` is refused.
434
+
435
+ ### v2.13.1 (2026-11-10)
436
+
437
+ - **Code-signed**: `HVACNetworkScanner.exe` is signed by James Cupps, so
438
+ Windows names the publisher. Nothing else changes.
439
+
440
+ ### v2.13.0 (2026-11-08)
441
+
442
+ - **The advisory list keeps itself current**: a daily job rebuilds it from
443
+ CISA's data and publishes it signed, and the scanner downloads it with its
444
+ daily check, so new advisories reach the report without a new release. The
445
+ list now holds every CISA advisory for the products it covers (53 entries),
446
+ and Desigo CC is checked per release.
447
+ - **Updates install themselves**: a new release downloads in the background
448
+ and installs when you close the scanner, or at once with **Restart to update
449
+ to …**. Turn **Install updates automatically** off in Advanced to be asked.
450
+
451
+ ### v2.12.0 (2026-11-06)
452
+
453
+ - **Firmware covered by published advisories**: the report compares the
454
+ firmware each controller reports with CISA ICS advisories (Trane Tracer SC+,
455
+ Siemens APOGEE PXC, Desigo PXC and DXR2, Desigo CC) and lists the devices
456
+ to update, with the version to update to, and those to check by hand.
457
+ Versions are compared only; nothing is sent to test for the flaws.
458
+
459
+ ### v2.11.0 (2026-11-06)
460
+
461
+ More of what a building network holds, and faster on unreliable controllers.
462
+ Full list in [CHANGELOG.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CHANGELOG.md).
463
+
464
+ - **LonWorks/IP (IP-852)**: routers and nodes on UDP 1628 report their node
465
+ type, name, Neuron IDs, configuration server and whether authentication
466
+ is on.
467
+ - **Serial gateways**: Moxa NPort, MGate and OnCell devices, often where P1,
468
+ N2, MS/TP and Modbus RTU buses reach the network, found with Moxa's
469
+ identify request only.
470
+ - **OPC UA identity**: the server's own name and product, and whether it
471
+ allows unsecured endpoints or anonymous sessions (4840 and KEPServerEX's
472
+ 49320). Niagara platform ports are probed too.
473
+ - **Adaptive timeout**: a controller that drops requests now costs about a
474
+ second per drop, not the full timeout. On one site a quick scan went from
475
+ 3 min 39 s to 2 min 32 s and four lossy controllers from minutes to under
476
+ half a minute each.
477
+ - **Accurate vendor names**: Alerton is Honeywell's; Vertiv and Copeland are
478
+ no longer listed as Emerson.
479
+
480
+ ### v2.10.0 (2026-11-06)
481
+
482
+ Tested on a real site over four rounds. Full list in
483
+ [CHANGELOG.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CHANGELOG.md).
484
+
485
+ - **Updates from inside the app**: the executable checks once a day and
486
+ installs a new release with one click, after checking it against a signed
487
+ manifest; if anything fails the previous exe is put back. Copies older
488
+ than 2.10 update by hand once.
489
+ - **Devices only** depth for a fast inventory, and a **per-device time
490
+ limit** (180 s by default) so one bad controller cannot hold a scan up.
491
+ - **A log that says where the time went**: the clock on every section, how
492
+ long each device took and how many requests it left unanswered, and a
493
+ time summary at the end. The report lists controllers that drop requests.
494
+ - **Finds the whole site**: every silent address on another subnet is
495
+ probed (and asked twice), whatever answered through a BBMD; lost packets
496
+ no longer drop a controller to slow single reads; devices answering from
497
+ outside the targets are named by subnet; the export records the BACnet
498
+ port and the address the scan ran from.
499
+ - **Devices named for what they are** (DXR2 models, PXC Modular/Compact,
500
+ Desigo PXC4/5/7, Insight, Tracer Ensemble, drives, gateways); the same
501
+ fault on many identical controllers is one report row; the dark theme's
502
+ scrollbars are visible.
503
+
504
+ ### v2.9.1 (2026-11-06)
505
+
506
+ Fixes from an external review: robustness against broken or hostile
507
+ devices, gentler traffic, and exports that say what they are. Full list in
508
+ [CHANGELOG.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CHANGELOG.md).
509
+
510
+ - **A broken or hostile device can no longer end a scan**: oversized
511
+ integers, object counts in the billions, I-Am floods, Modbus servers that
512
+ never finish a reply, and service banners that trickle in for hours are
513
+ all bounded.
514
+ - **Gentler**: the scanner never shares UDP 47808 with BACnet software
515
+ already running on the PC, sizes ReadPropertyMultiple to what each device
516
+ can send back, opens at most two connections to a host at a time, and
517
+ stops probing a Modbus unit a gateway says is absent.
518
+ - **Exports say what was scanned**: passes that were off, failed or stopped
519
+ are recorded, and the report shows "Not scanned" instead of "None".
520
+ Spreadsheet formulas in device names are neutralized; the classification
521
+ report no longer holds addresses or names; a site's own SNMP community is
522
+ not exported.
523
+ - Chunked Who-Is covers the whole instance range; the diff tells apart
524
+ devices that share an instance number (and reports them); the release
525
+ executable comes with a build attestation.
526
+
527
+ ### v2.9.0 (2026-11-04)
528
+
529
+ - **Alarm routing**: every notification class's recipients, when they
530
+ receive alarms and at what priority, with findings for classes routed to
531
+ no one and recipients that did not answer the scan.
532
+ - **Router tables**: the networks a router knows through other routers,
533
+ also used to reach MS/TP networks behind a chain of routers.
534
+ - A codec fix for six- and seven-octet context values (B/IP MAC addresses
535
+ inside constructed values).
536
+
537
+ ### v2.8.0 (2026-10-29)
538
+
539
+ The rest of the BACnet roadmap, and saved sites. Full list in
540
+ [CHANGELOG.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CHANGELOG.md).
541
+
542
+ - **MS/TP behind routers on other subnets, without a BBMD**: networks are
543
+ found from the routers' Network Port objects and asked with a routed
544
+ Who-Is; `--mstp-probe` asks each MS/TP address to find the devices that
545
+ only ever broadcast.
546
+ - **BBMD tables**: which subnets each BBMD links, and who is registered as a
547
+ foreign device to hear the site's broadcasts.
548
+ - **Trend logs and schedules** as metadata — what is trended, how often,
549
+ whether it is still recording; weekly programs and what they control —
550
+ in a new tab and in the survey report.
551
+ - **BACnet/SC detection**, with a high-severity finding for a hub that
552
+ accepts connections without a client certificate.
553
+ - **Saved site profiles** in the GUI, runnable from the CLI with
554
+ `--profile`.
555
+ - **KNXnet/IP detection**, a fuller **Niagara Fox** identity (and AX end
556
+ of life flagged), Modbus **Report Server ID**, and BACnet/SC hubs found
557
+ through the devices that name them — from checking the scanner against
558
+ nmap, zgrab2, Redpoint, bacnet-stack and BACpypes3.
559
+
560
+ ### v2.7.0 (2026-10-29)
561
+
562
+ A review-and-polish release. Highlights; the full list is in
563
+ [CHANGELOG.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CHANGELOG.md).
564
+
565
+ **Correctness**
566
+
567
+ - **Engineering units were wrong for most point types.** A humidity sensor
568
+ showed "W", a CO2 sensor "kPa-alt", an energy meter "kPa"; duct static,
569
+ psi, gpm and kW had no label at all. The table is now the full
570
+ BACnetEngineeringUnits enumeration. Object types 32-62 (Integer Value,
571
+ Large Analog Value, Network Port, ...) were missing or off by one.
572
+ - **Devices relayed by a BBMD were put at the BBMD's address**, so the deep
573
+ scan asked the wrong host. They are now attributed to their own address.
574
+ - **Modbus no longer reports phantom devices.** A gateway's "no device at
575
+ this unit" exception counted as a device, and a meter that answers every
576
+ unit ID was listed nine times.
577
+ - MS/TP devices found by the global Who-Is are labeled and counted as MS/TP.
578
+ Binary points read active/inactive. Older HTTPS gear (TLS 1.0/1.1) now
579
+ yields its banner and certificate.
580
+
581
+ **Speed** — about twice as fast end to end on the bundled simulated site (28 s
582
+ to 15 s). Sweeps of real subnets, where every empty address costs a
583
+ timeout, gain more:
584
+
585
+ - BACnet devices are deep-scanned in parallel (4 at a time by default),
586
+ without any one controller or MS/TP trunk seeing more than one request.
587
+ - The Modbus and service sweeps use an asyncio connect sweep, port-major so
588
+ each host sees one connection attempt at a time; SNMP sends to every host
589
+ from one socket and waits once.
590
+
591
+ **New**
592
+
593
+ - **Unicast discovery** finds controllers on other subnets and VLANs, where
594
+ a Who-Is broadcast never arrives.
595
+ - **A rebuilt GUI**: live summary and progress, a filter across every tab, a
596
+ device details panel, point-list export, remembered settings, keyboard
597
+ shortcuts, and an icon.
598
+ - **Point status**: points in alarm, fault, overridden or out of service
599
+ are flagged, and multi-state values read as their state text.
600
+ - **An HTML survey report**: findings ranked by severity (default
601
+ credentials on a reachable login, cleartext logins, SNMP defaults,
602
+ certificates, flagged points), the inventory and open services, in one
603
+ file for the building owner.
604
+ - A point-list CSV export, multiple SNMP communities, `--version`, and a
605
+ hint when nothing answers (usually Windows Firewall, or a VLAN boundary).
606
+ - `tools/sim_site.py`, a simulated site to try the scanner on, which the
607
+ end-to-end tests also run against.
608
+
609
+ - **Siemens APOGEE P2 detection**: firmware 2.x panels and P2 supervisors
610
+ are found on TCP/5033 and identified, without a handshake and without
611
+ registering on them, so an APOGEE building no longer looks empty.
612
+
613
+ Up next is in [ROADMAP.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/ROADMAP.md).
614
+
615
+ ## Troubleshooting
616
+
617
+ **Nothing answers on BACnet.** On Windows, check Windows Defender Firewall
618
+ allows the scanner (python.exe or HVACNetworkScanner.exe) inbound UDP 47808:
619
+ replies to a broadcast come from addresses the scanner never sent to, and the
620
+ firewall drops them unless the program is allowed. Accept the prompt the first
621
+ time it runs, or add it under *Allow an app through firewall*.
622
+
623
+ **The controllers are on another subnet or VLAN.** A broadcast does not cross
624
+ a router. Unicast discovery handles this automatically for targets that are
625
+ not on a local /24; set it to `always` (Advanced, or `--unicast always`) to
626
+ force it, or register with a BBMD to reach MS/TP devices behind remote
627
+ routers too. UDP 47808 has to be routed between the two networks either way.
628
+
629
+ **Siemens APOGEE panels don't show up on BACnet.** Firmware 2.x panels speak
630
+ P2, not BACnet/IP. Keep *APOGEE P2* ticked and they are detected on TCP/5033
631
+ and listed as such; reading their points needs a P2 tool (see *Known
632
+ out-of-scope* above).
633
+
634
+ **Small controllers misbehave during a scan.** Set a rate limit of 20-50 ms
635
+ and lower Parallel devices to 1.
636
+
637
+ **A few controllers take minutes each.** They are dropping requests, and
638
+ each lost one costs a wait (about a second once the scanner has seen the
639
+ device answer, the full timeout before that). The log says how many went unanswered,
640
+ the report lists them under *Controllers that drop requests*, and the
641
+ per-device time limit (Advanced) caps what any one of them can cost. The
642
+ cause is usually near the controller: a cable, a duplex mismatch, errors on
643
+ its switch port, or a controller too busy to keep up.
644
+
645
+ ## Safety and legal
646
+
647
+ This tool is intended for scanning networks you own or are authorized to audit. Running BACnet or Modbus sweeps against unfamiliar networks is at best rude and at worst unlawful in many jurisdictions. Building automation systems can also behave unpredictably when they see unexpected traffic — small field controllers have been known to lock up under probe load, and some equipment will fail-safe into unsafe mechanical states. Don't point it at anything you haven't been explicitly asked to assess.
648
+
649
+ The default-credentials database reflects the factory defaults published in each vendor's own documentation. It's here so the legitimate owner or operator of a system can quickly confirm whether defaults were ever changed, not as a remote-access toolkit. Those defaults are shown, never tried.
650
+
651
+ **What the scanner sends.** It reads; it does not write or reconfigure:
652
+
653
+ - **BACnet**: Who-Is (broadcast, ranged, routed or unicast),
654
+ Who-Is-Router-To-Network, Read-BDT and Read-FDT, ReadProperty and
655
+ ReadPropertyMultiple. No writes, no ReinitializeDevice, no
656
+ DeviceCommunicationControl, no subscriptions; it never answers requests.
657
+ - **Modbus TCP**: function codes 43/14, 17, 3, 4 and 1 to a few unit IDs;
658
+ never unit 0, never a write.
659
+ - **KNXnet/IP**: one description request; no connection, so no tunnel slot.
660
+ - **APOGEE P2**: one identify frame with a deliberately wrong BLN name.
661
+ - **Other services**: connect-and-close, an HTTP `GET /`, and banner reads;
662
+ nothing logs in.
663
+
664
+ Two exceptions, both worth knowing about:
665
+
666
+ - **SNMP asks with a community string** (`public` unless you set others),
667
+ which is a password of sorts: an agent may log a wrong one or send an
668
+ authentication-failure trap. Turn SNMP off if that matters on the site.
669
+ - **BBMD registration (`--bbmd`, off by default) is a write**: it adds the
670
+ scanner to the BBMD's foreign-device table so its broadcasts reach other
671
+ subnets. The entry lasts at most 300 seconds (plus BACnet's 30-second
672
+ grace) after the scan stops renewing it.
673
+
674
+ ## Project layout
675
+
676
+ ```
677
+ hvac_scanner/
678
+ ├── constants.py # Vendor DB, BACnet units, object types, HVAC ports
679
+ ├── codec.py # Pure-function BACnet packet encode/decode
680
+ ├── bacnet.py # UDP transport: shared socket, concurrent requests, RPM, unicast discovery
681
+ ├── modbus.py # Modbus TCP: per-host sessions, unit-ID probing, register reads
682
+ ├── services.py # TCP service probes, banners, TLS certificates
683
+ ├── snmp.py # Raw UDP SNMP sysDescr fan-out
684
+ ├── netsweep.py # asyncio TCP connect sweep shared by Modbus, P2 and services
685
+ ├── p2.py # Siemens APOGEE P2 detection (registration-free probe)
686
+ ├── knx.py # KNXnet/IP gateway detection
687
+ ├── lonworks.py # LonWorks/IP (IP-852) router and node detection
688
+ ├── moxa.py # Moxa serial gateway identify (UDP 4800)
689
+ ├── opcua.py # OPC UA server identity (GetEndpoints)
690
+ ├── fingerprint.py # Cross-protocol model identification
691
+ ├── device_profiles.py # Per-vendor enumeration caps + scan-depth presets
692
+ ├── netrange.py # Target syntax: CIDR, ranges, host lists
693
+ ├── engine.py # ScanEngine orchestrator + result/export
694
+ ├── certs.py # Minimal X.509 parsing for HTTPS probes
695
+ ├── diff.py # Baseline comparison (what changed since last scan)
696
+ ├── report.py # HTML survey report (findings, inventory, services)
697
+ ├── advisories.py # Published ICS advisories matched to reported firmware
698
+ ├── advisories.json # The advisory list (rebuilt daily from CISA's data)
699
+ ├── cli.py # Headless command-line interface
700
+ ├── gui.py # Tk GUI (thin wrapper over ScanEngine)
701
+ ├── settings.py # Remembered GUI settings
702
+ ├── limits.py # Bounds for the number settings (CLI, GUI and profiles)
703
+ ├── text.py # Device text made safe for logs and spreadsheets
704
+ ├── updater.py # In-app updates: signed manifest check, download, swap
705
+ ├── ed25519.py # Ed25519 signature check for the update manifest
706
+ ├── update_key.py # The public keys releases and the advisory list are signed with
707
+ ├── icon.py # The app icon, drawn in code
708
+ ├── __main__.py # `python -m hvac_scanner` → GUI
709
+ └── __init__.py # Public API
710
+
711
+ tools/
712
+ ├── sim_site.py # Simulated BAS site on loopback (tests, demos, screenshots)
713
+ ├── gui_demo.py # Drive the GUI through a simulated scan and screenshot it
714
+ └── advisory_watch.py # Rebuild the advisory list from CISA's CSAF feed (daily workflow)
715
+
716
+ data/advisories.signed.json # The signed advisory list installed copies download
717
+
718
+ packaging/ # PyInstaller spec, hash-pinned build tooling, icon, entry point,
719
+ # signing.py (signs the release's latest.json),
720
+ # test_update.ps1 (a real update to the new build)
721
+
722
+ site/ # The project page (GitHub Pages, .github/workflows/pages.yml)
723
+
724
+ tests/ # 882 tests
725
+ ├── test_e2e_site.py # The whole engine against the simulated site
726
+ ├── test_v27.py # v2.7 fixes: units, BBMD origin, concurrency, Modbus, GUI
727
+ ├── test_codec.py # BACnet packet encode/decode + parser regressions
728
+ ├── test_bacnet_client.py, test_rpm_batching.py, test_point_batching.py,
729
+ ├── test_bbmd.py, test_mstp_routing.py, test_target_filtering.py, ...
730
+ ├── test_modbus.py, test_snmp.py, test_certs.py, test_services_probes.py
731
+ ├── test_engine.py, test_streaming.py, test_diff.py, test_fingerprint.py, ...
732
+ ├── test_gui_options.py # GUI controls reach ScanOptions (skips headless)
733
+ ├── test_v291.py # 2.9.1: the external review's findings, one by one
734
+ ├── test_v210.py # 2.10: updater, signing, report grouping, coverage
735
+ ├── test_v211.py # 2.11: LonWorks/IP, Moxa, OPC UA, naming, adaptive timeout
736
+ ├── test_v213.py # 2.13: advisory list download and CISA watcher, install on close
737
+ ├── test_no_site_data.py # Guard: no site-identifying data in the tree
738
+ └── conftest.py
739
+ ```
740
+
741
+ ## Development
742
+
743
+ ```bash
744
+ git clone https://github.com/jamesccupps/HVAC-Network-Scanner.git
745
+ cd HVAC-Network-Scanner
746
+ pip install -e ".[dev]"
747
+ pytest
748
+ ```
749
+
750
+ Pull requests welcome. See [CONTRIBUTING.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/CONTRIBUTING.md) and
751
+ [ROADMAP.md](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/ROADMAP.md).
752
+
753
+ ## Contact
754
+
755
+ Open an [issue](https://github.com/jamesccupps/HVAC-Network-Scanner/issues) for bugs and feature requests. For security reports or general questions, email <jamesccupps@proton.me>.
756
+
757
+ ## License
758
+
759
+ MIT — see [LICENSE](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/LICENSE).
760
+
761
+ ## Author
762
+
763
+ James Cupps — <https://github.com/jamesccupps>