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.
- hvac_network_scanner-2.14.1.dist-info/METADATA +763 -0
- hvac_network_scanner-2.14.1.dist-info/RECORD +38 -0
- hvac_network_scanner-2.14.1.dist-info/WHEEL +5 -0
- hvac_network_scanner-2.14.1.dist-info/entry_points.txt +5 -0
- hvac_network_scanner-2.14.1.dist-info/licenses/LICENSE +21 -0
- hvac_network_scanner-2.14.1.dist-info/top_level.txt +1 -0
- hvac_scanner/__init__.py +30 -0
- hvac_scanner/__main__.py +11 -0
- hvac_scanner/advisories.json +1355 -0
- hvac_scanner/advisories.py +374 -0
- hvac_scanner/bacnet.py +1725 -0
- hvac_scanner/certs.py +281 -0
- hvac_scanner/cli.py +671 -0
- hvac_scanner/codec.py +1592 -0
- hvac_scanner/constants.py +1057 -0
- hvac_scanner/device_profiles.py +421 -0
- hvac_scanner/diff.py +331 -0
- hvac_scanner/ed25519.py +144 -0
- hvac_scanner/engine.py +2754 -0
- hvac_scanner/fingerprint.py +445 -0
- hvac_scanner/gui.py +2503 -0
- hvac_scanner/icon.py +108 -0
- hvac_scanner/knx.py +186 -0
- hvac_scanner/limits.py +52 -0
- hvac_scanner/lonworks.py +199 -0
- hvac_scanner/modbus.py +448 -0
- hvac_scanner/moxa.py +133 -0
- hvac_scanner/netrange.py +192 -0
- hvac_scanner/netsweep.py +166 -0
- hvac_scanner/opcua.py +350 -0
- hvac_scanner/p2.py +203 -0
- hvac_scanner/report.py +1021 -0
- hvac_scanner/services.py +575 -0
- hvac_scanner/settings.py +204 -0
- hvac_scanner/snmp.py +225 -0
- hvac_scanner/text.py +65 -0
- hvac_scanner/update_key.py +14 -0
- hvac_scanner/updater.py +458 -0
|
@@ -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
|
+
[](https://github.com/jamesccupps/HVAC-Network-Scanner/actions/workflows/ci.yml)
|
|
38
|
+
[](https://github.com/jamesccupps/HVAC-Network-Scanner/releases/latest)
|
|
39
|
+
[](https://github.com/jamesccupps/HVAC-Network-Scanner/blob/v2.14.1/LICENSE)
|
|
40
|
+
[](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
|
+

|
|
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>
|