KNX Network Scanning with KNXmap

What Is KNXmap

KNXmap is a KNXnet/IP scanning and auditing tool designed for KNX building automation installations. KNX (EN 50090, ISO/IEC 14543) is the dominant building automation fieldbus standard in Europe and is widely deployed in commercial buildings, hotels, airports, and high-end residential projects for controlling lighting, HVAC, shading, and access systems. KNXnet/IP extends the KNX protocol over Ethernet using UDP on port 3671 and the multicast address 224.0.23.12, allowing IP-based access to the KNX bus through KNXnet/IP gateways and routers.

The tool was created by security researchers at Insinuator and is hosted on GitHub at github.com/takeshixx/knxmap. KNXmap fills a gap that commercial KNX engineering tools like ETS (Engineering Tool Software) do not address: it provides a command-line interface purpose-built for network reconnaissance, device enumeration, and security auditing of KNXnet/IP infrastructure. Where ETS is a commissioning and programming tool, KNXmap is an assessment tool that helps BAS engineers and security professionals understand what is exposed on a KNX network and whether gateways are properly secured.

KNXmap is written entirely in Python, relies heavily on the asyncio module for concurrent scanning, and has zero external dependencies beyond the Python standard library. This makes it straightforward to deploy on any system with Python 3.4 or later without worrying about package conflicts or compilation steps.

Installing KNXmap

KNXmap requires Python 3.4 or newer (Python 3.6+ is recommended for the most stable asyncio behavior). There are no third-party library dependencies. Installation takes under two minutes on any platform with Python and Git available.

Installation from Source

1. Clone the repository: git clone https://github.com/takeshixx/knxmap.git
2. Change into the directory: cd knxmap
3. Install via setup.py: python setup.py install
4. Verify the installation: knxmap --help

Alternatively, you can run KNXmap directly from the cloned directory without installing it system-wide: python -m knxmap --help. This approach is useful for quick assessments where you do not want to modify the system Python environment.

Virtual Environment (Recommended)

For clean dependency isolation, install KNXmap inside a virtual environment:

1. Create the environment: python3 -m venv knxmap-env
2. Activate it: source knxmap-env/bin/activate (Linux/macOS) or knxmap-env\Scripts\activate (Windows)
3. Clone and install: git clone https://github.com/takeshixx/knxmap.git && cd knxmap && python setup.py install

Python 3.3 note: Users on legacy Python 3.3 need to install the asyncio module separately from PyPI (pip install asyncio). Python 3.4 and later include asyncio in the standard library and require no additional packages.

Scanning for KNXnet/IP Gateways

The primary use case for KNXmap is discovering KNXnet/IP gateways on a network. KNXnet/IP gateways bridge between IP networks and the KNX twisted-pair (TP) bus, and they are the entry point for any IP-based access to KNX devices. KNXmap discovers gateways using two methods:

Multicast Search

KNXnet/IP defines a discovery mechanism where a client sends a Search Request to the multicast address 224.0.23.12 on UDP port 3671. Every KNXnet/IP gateway on the local network segment responds with a Search Response containing its device name, KNX individual address, supported service families (Core, Device Management, Tunnelling, Routing), and hardware details. KNXmap leverages this mechanism to find all gateways reachable via multicast without requiring any prior knowledge of IP addresses.

Unicast Description Requests

When you already know specific IP addresses or want to scan a particular subnet, KNXmap sends KNX Description Requests directly to each target via unicast UDP. This is useful when multicast traffic is blocked by network infrastructure or when scanning across routed subnets where multicast does not propagate. Targets can be specified as individual IP addresses, space-separated lists, or CIDR notation:

• Single target: knxmap scan 192.168.1.100
• Multiple targets: knxmap scan 192.168.1.100 192.168.1.110 192.168.1.120
• CIDR subnet: knxmap scan 192.168.1.0/24

A successful gateway scan returns the device name, individual address (e.g., 1.0.1), hardware type, serial number, multicast address, MAC address, and supported KNXnet/IP services. This information alone is valuable for building an inventory of KNX gateways on a network and identifying devices that may be misconfigured or unnecessarily exposed.

Device Discovery

Beyond finding gateways, KNXmap can enumerate individual devices on the KNX bus behind a gateway. KNX devices are addressed using a three-level individual address scheme: Area.Line.Device (e.g., 1.1.5). KNXmap scans a range of these addresses through a gateway to determine which physical addresses have active devices.

Bus Scanning with --bus-info

To scan for devices on the KNX bus, supply the gateway IP address followed by a range of KNX individual addresses and the --bus-info flag:

knxmap scan 192.168.1.100 1.1.0-1.1.6 --bus-info

This command connects to the gateway at 192.168.1.100, opens a KNXnet/IP tunnelling connection, and probes individual addresses 1.1.0 through 1.1.6 on the bus. For each responding device, KNXmap retrieves identification data including the device descriptor, firmware version, serial number, and supported application layer services. The --bus-info flag triggers these additional property reads, which provide fingerprinting data beyond simple address enumeration.

Bus Monitoring

KNXmap supports a bus monitor mode that passively captures all telegrams on the KNX bus. Instead of actively probing addresses, the tool places the gateway into bus monitor mode and prints every frame it receives. This is the least intrusive way to discover active devices because it does not inject any traffic onto the bus—it simply listens. Bus monitoring reveals which individual addresses are actively communicating, what group addresses are in use, and what types of telegrams are being exchanged.

Group Monitoring

The group monitor mode focuses specifically on group address communication. In KNX, group addresses are the mechanism by which sensors, actuators, and controllers exchange data (e.g., a wall switch sending an ON command to a lighting group address). Group monitoring captures these messages and displays the source address, destination group address, and payload. This provides insight into the functional configuration of the installation: which devices are controlling which outputs, what values are being transmitted, and how frequently communication occurs.

Security Assessment Use Cases

KNX installations in commercial buildings often lack adequate security controls. The KNX protocol was designed in an era when physical access to the bus cable was considered sufficient protection. With KNXnet/IP extending bus access over Ethernet and potentially over the internet, the attack surface has expanded significantly. KNXmap addresses several assessment scenarios that BAS security auditors encounter.

Exposed Gateway Identification

KNXnet/IP gateways that are reachable from general-purpose IT networks or the internet represent a critical risk. An attacker who can reach a gateway on UDP port 3671 can potentially read sensor data, send commands to actuators (lights, HVAC dampers, door locks), or reprogram devices. KNXmap's subnet scanning capability helps auditors identify every gateway on a network segment, including devices that may have been connected inadvertently or left with default configurations.

Authentication and Access Control Verification

Traditional KNXnet/IP gateways do not require authentication for tunnelling connections. Any client that can reach the gateway on UDP 3671 can open a tunnel and interact with the bus. KNXmap can verify whether a gateway accepts unauthenticated connections, which is the expected behavior for legacy devices but represents a security gap that should be mitigated through network segmentation. The newer KNX IP Secure standard (introduced in 2019) adds authentication and encryption to KNXnet/IP, but adoption remains limited in existing installations.

BCU Key Assessment

KNX devices support a Bus Coupling Unit (BCU) key that restricts programming access. When a BCU key is set, an attacker cannot modify device configurations without knowing the key. However, many installations leave the BCU key at its default (all zeros) or unset entirely. CISA advisory ICSA-23-236-01 specifically addresses the risk of KNX devices operating without BCU keys, noting that an attacker with bus access could lock devices and prevent legitimate access. KNXmap's device enumeration and bus-info features can help auditors catalog devices and determine which devices may be vulnerable to unauthorized configuration changes.

Network Segmentation Validation

The most effective defense for KNX installations is proper network segmentation: KNXnet/IP gateways should reside on a dedicated automation VLAN that is isolated from general IT traffic and the internet. KNXmap can be run from different network segments to validate that gateways are not reachable from unauthorized locations. If a scan from the corporate IT VLAN discovers KNXnet/IP gateways that should be isolated on the BAS VLAN, the segmentation is ineffective.

Authorized Testing Context

KNXmap is a security assessment tool. Use it only on networks and systems you own or have explicit written authorization to test. Unauthorized scanning of KNX installations can disrupt building operations, trigger alarms, interfere with safety-critical systems (fire dampers, emergency lighting, access control), and may violate computer fraud and abuse laws in most jurisdictions.

Before using KNXmap on any installation, confirm the following:

• Written authorization from the building owner or facility management that explicitly permits KNX network scanning and bus device enumeration.
• Scope definition that specifies which IP ranges and KNX address ranges are in scope, and which systems (fire/life safety, access control, elevators) are excluded.
• Coordination with building operations so that facility staff are aware of the assessment window and can respond if scanning triggers unexpected behavior in connected actuators or alarms.
• Rollback plan in case active scanning (as opposed to passive bus monitoring) causes unintended state changes on KNX actuators. Know how to restore normal operation of affected devices via ETS or the building management system.

Passive modes (bus monitor and group monitor) are inherently safer than active scanning because they do not inject traffic onto the bus. When possible, start with passive monitoring to assess the installation before moving to active enumeration. Even passive monitoring, however, requires authorization because it captures operational data about building systems.

For BAS integrators and facility engineers conducting internal assessments of their own installations, KNXmap provides a practical way to audit gateway exposure without engaging an external penetration testing firm. Document your findings and remediation steps as part of your ongoing cybersecurity hygiene for building automation infrastructure.

Common Mistakes

1. Scanning without verifying gateway connectivity first. KNXmap communicates over UDP port 3671. If a firewall, VLAN ACL, or host-based firewall blocks this port, scans return no results and produce minimal error output. Before running KNXmap, verify basic UDP connectivity to the target gateway using a simple tool like nmap -sU -p 3671 192.168.1.100. If port 3671 is filtered, resolve the network path issue before assuming the target is not a KNX gateway.
2. Using an overly broad KNX address range. KNX individual addresses span 1.0.0 through 15.15.255, which is over 65,000 possible addresses. Scanning the entire range through a single gateway is slow and generates substantial bus traffic that can degrade real-time control performance. Start with the specific area and line numbers documented in the site's KNX project file (exported from ETS) or discovered through passive bus monitoring. A targeted scan like 1.1.0-1.1.20 is far more practical than 1.0.0-15.15.255.
3. Running active scans during occupied hours on a production building. Active bus scanning sends read requests to devices, which consumes bus bandwidth and can cause latency in normal KNX communication. On a busy bus segment, this may result in missed telegrams, delayed actuator responses, or visible effects like flickering lights. Schedule active scanning during unoccupied periods or maintenance windows whenever possible.
4. Forgetting that KNXnet/IP tunnelling connections are limited. Most KNXnet/IP gateways support only a small number of simultaneous tunnelling connections (typically one to four). If another client such as ETS, a visualization system, or a BMS supervisor is already connected, KNXmap may fail to establish a tunnel. Verify that tunnelling slots are available before scanning, and coordinate with the BAS team to avoid connection conflicts.
5. Confusing KNXnet/IP Routing with Tunnelling. KNXnet/IP has two communication modes: Tunnelling (point-to-point between a client and a gateway) and Routing (multicast-based communication between IP routers). KNXmap's bus scanning features use Tunnelling, which requires a direct connection to a gateway. If your target device is a KNXnet/IP router that only supports Routing mode, KNXmap's active scan commands will not work. Use the gateway discovery scan first to identify which services each device supports.

Platform Compatibility

KNXmap is a pure Python application with no compiled extensions or platform-specific dependencies. It runs anywhere Python 3.4+ is available.

For comparison, the XKNX library is another Python-based KNX tool, but it serves a different purpose. XKNX is an asynchronous KNX/IP library designed for building automation applications and Home Assistant integration, requiring Python 3.10 or newer. KNXmap is focused on discovery and auditing, while XKNX is focused on runtime device control and integration. They complement each other: use KNXmap to discover and inventory the installation, then use XKNX (or ETS) for ongoing monitoring and control.

Nmap also provides KNX discovery capability through the knx-gateway-discover NSE script (authored by the same developer behind KNXmap). This script sends a KNX Search Request to the multicast address and reports responding gateways. It is useful for quick checks during general network assessments but does not provide the bus-level scanning and monitoring capabilities that KNXmap offers.

Source Attribution

This guide draws from the following publicly available sources:

• GitHub — takeshixx/knxmap — official repository, README, and wiki documentation including scanning modes, getting started guide, APCI functions, and key bruteforcing reference.
• Insinuator.net — KNXmap: A KNXnet/IP Scanning and Auditing Tool — original release announcement and tool overview by the developers.
• XKNX Documentation — reference for the XKNX asynchronous Python KNX library, used for comparison context.
• CISA Advisory ICSA-23-236-01 — KNX Protocol — security advisory regarding KNX device vulnerabilities and BCU key risks.
• KNX Association — Interfaces Documentation — official KNXnet/IP protocol reference for multicast addresses, port assignments, and service families.