Vertical network awareness — AV · BACnet/IP · Industrial-OT · DICOM

Umbrella issue #543, with four children: #540 AV / Audio-Video-over-IP, #541 BACnet/IP building automation, #542 Industrial / OT, and #723 DICOM (healthcare).

Four IP-native domains that a generic IPAM does not speak. They look unrelated but they are the same DDI primitives, specialized: a uniqueness registry, a segmentation-documentation layer, and conformity rules over both. Each is a togglable feature module in the Network group, default-enabled so operators discover them, and switched off by the sites that don’t run that vertical.

The healthcare research pass concluded there should be no network.healthcare catch-all — the vertical splits into separable pieces, and DICOM is the anchor. The probe-safety piece is #722, which is not a vertical at all: it is a constraint on SpatiumDDI’s own behaviour and ships un-gated for every install. See Fragile-device probe suppression.

Documentation is in progress. This covers the shipped Phase 1 of each module — the registry, conformity, and UI surfaces. The discovery phases have not shipped; see What is deliberately not here for why, which is not simply “not yet”.

The four at a glance

All rows land via the REST API or the UI. Nothing in this feature family emits a packet.

AV / Audio-Video-over-IP (#540)

It extends the multicast registry, it does not duplicate it

A Dante flow is a MulticastGroup. AV adds a 1:1 sidecar (av_flow_profile) carrying what the multicast registry has no business knowing: the AV protocol, the human flow label an engineer reads off a Dante Controller or 2110 routing panel, and the PTP clock domain.

It is a sidecar rather than columns on multicast_group so that a market-data multicast shop that never enables network.av gets no extra columns on a hot table, and disabling the module is a clean table drop.

Module relationship. network.av is only meaningful alongside network.multicast — an AV flow is a multicast group. There is no module-dependency mechanism in the feature-module system, so this is documentation rather than an enforced constraint: turning off network.multicast while leaving network.av on leaves the AV surface pointing at groups the operator can no longer browse.

Reserved ranges are what make the checks real

av_reserved_range records, per IPSpace, that a CIDR belongs to a given AV protocol. Best-practice AoIP is static multicast assignment, so an operator’s declared plan is the thing worth checking against.

Well-known starting points are offered as presets, not auto-inserted — a vendor default is a default the operator may deliberately have moved off:

exclusive distinguishes “this range is for Dante and nothing else belongs here” from “Dante lives here among other things”. Most plants want exclusive; shared exists because small shops run one flat 239.x range for everything and would otherwise get a permanent wall of warnings.

POST /api/v1/av/allocation-preview answers “would this allocation collide with another protocol’s declared range?” before the operator commits.

Conformity

• av_flow_outside_reserved_range — fails when an AV flow’s address sits outside every range declared for its protocol. Not applicable when no range is declared for that protocol: absence of policy is not a violation, and failing every flow in that state would train operators to ignore the check.
• av_flow_no_ptp_domain — advisory warn when the clock domain is unrecorded. PTP misconfiguration is the most common AoIP failure mode and the domain is the first thing asked for when audio drops, but a missing value is undocumented state, not a broken network. Applied uniformly across protocols; NDI is arguably not PTP-locked the way AES67/2110 are, but the field records documentation rather than asserting the flow is clocked, and special-casing it would encode a timing claim this registry cannot verify.

BACnet/IP building automation (#541)

Device instance numbers are the point

Every BACnet device carries a device instance number (0–4,194,302, 22-bit) that must be unique across the entire internetwork — not per-subnet, not per-site. Duplicate instances are a classic BAS failure that takes days to trace, and integrators track them in spreadsheets that drift.

That is the same uniqueness-registry problem IPAM already solves for addresses, applied to a parallel number space — which is what makes it belong in a DDI rather than a BAS head-end. uq_bacnet_device_instance enforces it in the database, not merely in the API, because the failure it prevents is precisely the one that makes an internetwork misbehave silently.

4194303 (0x3FFFFF) is reserved by the standard as the “unconfigured / wildcard” instance used in Who-Is, so the maximum assignable value is one below it. The API returns a 409 naming the conflicting device rather than surfacing a raw integrity error.

BBMD topology is a checkable rule

BACnet broadcasts don’t cross IP routers, so each IP subnet in a multi-subnet BACnet/IP network needs exactly one BACnet Broadcast Management Device:

• zero → that subnet’s devices are invisible to the rest of the internetwork
• two or more → duplicated broadcast traffic and duplicate I-Am responses

bbmd_one_per_subnet fails in both directions and names the offending device instances when there are too many. A subnet with no BACnet devices at all is not applicable rather than failing — most subnets in a mixed estate aren’t BACnet subnets, and flagging them would bury the real findings.

bdt / fdt (Broadcast Distribution Table / Foreign Device Table) are stored as JSONB snapshots: read-mostly copies of someone else’s state that get rendered and diffed wholesale rather than queried into. Phase 1 accepts them via the API so a plant can document topology it already knows.

Vendor labels

backend/app/services/bacnet/vendors.py maps well-known ASHRAE vendor ids to display names. It is deliberately small: a wrong label is worse than no label, because an integrator chasing a duplicate instance who sees the wrong manufacturer is being actively misled toward the wrong panel, on the wrong floor, with the wrong vendor’s tool. Unresolved ids fall through to the operator-supplied vendor_name. ASHRAE has assigned well over a thousand ids; full coverage belongs in an importer with provenance, the way OUI data is handled.

bacnet_vendor_id_unknown advises on devices reporting vendor id 0 or none — 0 is legitimately ASHRAE itself, but in the field it almost always means a misconfigured, cloned, or counterfeit controller.

Industrial / OT (#542)

Safety posture — read-only identification, permanently

This module identifies and inventories industrial devices. It never reads tags, writes coils or registers, subscribes to OPC UA, or otherwise touches a control protocol. That is a safety and liability boundary, not a roadmap gap. Any hint of write access to a control protocol is out of scope, full stop.

It is also explicitly not an OT-security product. Deep passive DPI and anomaly detection are Nozomi / Claroty / Dragos territory; the angle here is DDI system-of-record plus segmentation documentation.

PROFINET names are identities

In PROFINET the device name, not the IP, is the device’s identity: DCP assigns the address once by name, and a replacement unit is commissioned by giving it the old name. profinet_device_name gets its own indexed column rather than a custom field because it is a string OT engineers search by.

Purdue zoning

ot_zone records the Purdue level and cell/area for a subnet; ot_device records the level for the device. purdue_level is Numeric(2,1) rather than an integer because level 3.5 — the DMZ between the manufacturing and enterprise zones — is real and universally used, and it is exactly the boundary the conformity check cares most about.

• ot_device_crosses_purdue_boundary — fails when a device’s level differs from its subnet’s zoned level. A Level-1 PLC in a Level-4 enterprise subnet is the finding an auditor asks for. Not applicable when either side is unset: an unrecorded level is missing documentation, not a violation, and treating unknown as guilty would make the check unusable during rollout.
• ot_zone_missing_purdue_level — advisory; a subnet carrying OT devices but no zone row. This is the check that explains an empty segmentation report.

cell_area is free text rather than an FK: plants name cells in wildly local ways and a registry here would be friction with no payoff at this phase.

CSV import

POST /api/v1/ot/devices/import/{preview,commit} ingests engineering-tool exports (TIA Portal, Studio 5000). Rows key on IP address, and an address that does not already exist in IPAM is reported as a row error rather than created — this importer enriches inventory, it does not invent it.

DICOM — medical imaging (#723)

AE Titles are the textbook uniqueness registry

A DICOM Application Entity Title is a flat, institution-wide-unique, 16-byte identifier. Every modality, PACS node, workstation and archive answers to one, and every peer that wants to talk to it must have that exact string configured. Duplicates break C-MOVE, Storage Commitment, Modality Worklist and MPPS, and the failure has been documented since 1997 with an unchanged root cause: vendor defaults nobody changed.

DICOM PS3.15 Annex H defines dicomUniqueAETitlesRegistryRoot — an LDAP registry object whose only purpose is allocating unique AE Titles via a compare-and-set against an enforced constraint. It is essentially undeployed. In practice the namespace lives in a spreadsheet.

That is the BACnet device-instance argument with better provenance: the standard itself says the value must be unique and specifies a registry for it, and no incumbent system owns the namespace. So uq_dicom_ae_title is the point of the table, not an incidental index — and a collision answers 409 naming the AE that already holds the title, because the conflicting row is usually in another department, commissioned by another vendor’s engineer.

Contrast with the rest of healthcare, which is why there is no network.healthcare module: HL7/MLLP port sprawl is real but the interface engine owns it; FHIR is HTTPS with path-based discovery; WMTS is not IP at all.

The anchor is nullable, on purpose

dicom_ae.ip_address_id is nullable with ON DELETE SET NULL — deliberately unlike bacnet_device’s CASCADE. An AE Title outlives the host it runs on. It is burned into peer configuration across the estate, so decommissioning an IP must demote the title to a reservation, not free a name a dozen modalities still send to. Cascading would hand it straight to the next commissioning engineer.

An unbound AE is therefore a normal, first-class state: the list has a “Reservations only” filter, the API a ?unbound=true query, and the UI a reservation badge.

AE Title validation — 16 bytes, and spaces are legal

The AE value representation is easy to get wrong in the strict direction, and strict is the worse failure: a registry that rejects a title real devices use records a plan that fails at commissioning. services/dicom/titles.py implements PS3.5 verbatim:

• maximum 16 bytes — bytes, not characters, so a non-ASCII title can be over the limit at 15 characters;
• spaces are legal but non-significant (they are padding), so leading and trailing space is trimmed and internal spaces are kept;
• an all-space value is forbidden, which after trimming is the same statement as “must not be empty”;
• backslash (0x5C, the multi-value delimiter) and all control characters are excluded.

There is no alphanumeric-only rule and no case rule. Case is significant to peers, so titles are stored as given and matched exactly; only the vendor-default advisory compares case-insensitively.

Peers make renumbering answerable

dicom_peer is a directed AE→AE edge describing a configured association — documented by the operator or imported, never inferred from traffic, which would mean parsing DICOM that carries PHI. Direction is load-bearing: an AE’s outbound edges stop sending when it moves, its inbound edges stop being able to reach it, and those are different remediation lists. GET /api/v1/dicom/aes/{id}/impact returns them split.

Conformity

Import

POST /api/v1/dicom/aes/import/{preview,commit} ingests the estate’s existing AE table. Two contracts differ from the OT importer:

• The join key is ae_title, not the IP — that is the identity DICOM cares about and the one the unique constraint is on. Two rows in one file sharing a title is a per-row error, because that duplicate is the exact collision the registry exists to surface.
• The address column is optional. A blank address registers an unbound reservation rather than failing. A supplied address IPAM doesn’t know is still an error — an export enriches inventory, it does not invent it.

Hard guardrail — no PHI, ever

The registry stores network identity only: titles, hosts, ports, roles, vendors, departments. It records nothing about patients, studies or images. Storing patient-identifiable data would make SpatiumDDI a HIPAA Business Associate, which is permanently out of scope. notes is documented on the wire as a network-configuration field, because an unlabelled free-text box is the surest way to end up storing PHI by accident.

Fragile-device probe suppression (#722)

Not a vertical, and deliberately not behind a feature module: it is a constraint on SpatiumDDI’s own behaviour and a correctness fix to three shipped features, so it is on for every install.

Medical- and OT-device vendors explicitly instruct sites not to scan their VLANs — Swisslog’s pneumatic-tube deployment guide says to omit ping sweeps and nmap of any range supporting the PTS, and the same hazard covers patient monitors, BMC / IPMI endpoints, and the PLC / RTU class network.ot registers. Fragile IP stacks fault or drop off the network under a sweep. Until this flag existed there was no way for an operator to say so.

do_not_probe + do_not_probe_reason live on IPSpace, IPBlock and Subnet, and OR down the chain. That is deliberately unlike the DDNS fields they otherwise mirror, which resolve to the first non-inheriting ancestor and so let a descendant override its parent. A hospital that marks its clinical IPSpace do-not-probe must not have one subnet quietly opt back in, so there is no per-level inherit toggle and nothing downstream can un-set the flag. The nearest flagged level supplies the reason, because that is the most specific explanation an operator wrote.

Every probe origin consults the same resolver (app/services/ipam/probe_policy.py):

dig, whois, DNS-propagation and mac-vendor are not gated: they query a resolver or an off-prem service about a name, they do not probe the name’s host. Passive collection is untouched by design — PCAP (#59), DHCP fingerprinting, RA sniffing and ARP-table reads observe traffic that already exists.

The override. override_do_not_probe: true requires superadmin — not a permission grant, because use_network_tools is a routine grant delegated admins hold and the point of the flag is that whoever clears it is accountable. It writes a probe.do_not_probe_override audit row before the probe runs, and it is per-request: nothing is remembered, so the next call is refused again. The alternative — refusing absolutely — just gets the flag turned off estate-wide, which is a worse outcome than a recorded exception.

Fail-safe direction. A target the resolver cannot map to a subnet is allowed. Refusing everything unmappable would make the tools page unusable against off-IPAM infrastructure, and an operator who never modelled a network in IPAM never told us it was fragile. Hostnames are matched against IPAddress.hostname rather than resolved through DNS: a lookup inside an authorization check makes the verdict depend on a round-trip nobody can see the result of, and lets a hostile record steer the guard.

The conformity check works backwards from the registries. The flag is opt-in, so fragile_subnet_probed (target: subnet) fails when a subnet carries registered ot_device rows, dicom_ae rows, or role="bmc" addresses but is not covered by the flag — if an operator has told us a subnet holds that gear, they have already told us it is fragile. Suppression inherited from a parent counts as covered.

bmc also joins the IP_ROLES set in the same issue: BMC / IPMI / Redfish endpoints are exactly this fragile class, and naming them is what lets an operator find every one and decide whether their subnet belongs behind the flag.

What is deliberately not here

Every discovery phase across all three modules is unshipped, and the reasons are structural rather than scheduling.

The umbrella’s shared dependency was cancelled. #543 named #40 (mDNS / Bonjour / WSD passive discovery) as “the common enabling primitive; worth landing early”. #40 was closed as not planned after a feasibility review, which found that mDNS/WSD are link-local multicast — only a host-networked, on-segment agent hears anything, and the agent↔subnet binding that would require is not modelled today.

Each phase remains worth doing; each is its own piece of work with its own prerequisites, and none of them is a metadata phase.

Also permanently out of scope: patient-identifiable data of any kind (see the DICOM PHI guardrail above) and inferring DICOM associations from captured traffic; RTP jitter / packet-loss / SDP essence analysis and NMOS IS-05 connection control (SpatiumDDI is a registry, not a media monitor); running PIM/IGMP or acting as a BBMD (we document the topology, we don’t participate in it); BACnet object/point-level management (we track the device, not its 600 objects); and BACnet MS/TP or other serial datalinks, which aren’t IP-addressable.

Operational notes

• Backup / factory reset. The seven tables — plus the four multicast tables they depend on — are covered by the verticals backup section and the DESTROY-VERTICALS factory-reset section. Resetting the verticals section destroys only the vertical metadata; the underlying IPAM addresses and subnets are untouched.
• RBAC. The builtin Network Editor role grants admin on av_flow, bacnet_device, ot_device, and dicom_ae. Builtin roles are re-seeded on every boot, so no migration is involved. do_not_probe (#722) is a field on the IPAM rows and needs no resource type of its own — editing it requires write on the space / block / subnet, and overriding it requires superadmin.
• Enum vocabularies (av_protocol, ot_protocol, ot_role, role, device_class, seen_via) are module-level frozenset[str] validated at the API layer rather than Postgres enums, matching the multicast registry’s convention — adding a protocol later must not require a migration. Values with a specification-defined range (BACnet’s 22-bit instance space, PTP’s single octet, Purdue 0–5, the DICOM 16-byte AE length ceiling and its port range) do carry database CHECK constraints, because those bounds will never move.
• seen_via already accepts the discovery-phase values (mdns, nmos, whois, enip, dcp, echo, …) so those phases need no data migration.