rfmon-to-influx

Successful Associations, grouped by AP within 24h

Writing (mostly meta-) data received in Wireless-Monitor-Mode into an InfluxDB.

Table of contents

• 1. Description
  • 1.1. What kind of data
  • 1.2. Data-Usage
  • 1.3. Tools used
  • 1.4. Architecture
• 2. Usage/Installation
  • 2.1. Prerequisites
  • 2.2. Choosing an Export-Method
  • 2.3. Running with Docker
  • 2.4. Environment-Variables
• 3. Data collected
  • 3.1. Data-Types
  • 3.2. Metric-Overview
  • 3.3. Metric-Details
  • 3.4. Tag-Overview
  • 3.5. Tag-Details
• 4. Potential Issues
  • 4.1. Channel/Frequency
  • 4.2. Technology
  • 4.3. Data protection
  • 4.4. Ethical

1. Description

This Program listens on an Wifi-Interface in Monitor-Mode (rfmon) and logs most actions made into an influx or influx-like time-database.

1.1. What kind of data

Any packet sent by a router or station nearby is received and its metadata is collected and categorised.

The host does not have to be part of that network.

1.2. Data-Usage

The data can be used to identify problems with the wifi-communication nearby e.g.

• Wifi-Congestion at certain times of the day
• occurring signal-issues
  • e.g. due to broken Microwave-Ovens disrupting communications
  • or moving big Objects (e.g. Machines) causing signal-reduction.

Aswell as gaining knowledge about installed routers and user interaction with them e.g.

• in a company environment
  • Logging presense and activity of interconnected machines
  • Finding other Access-Points not allowed due to potential disruption of Production-Lines

Other usages might be threat-detection at Wifi-Level e.g.

• Deauthentication-Attacks
• Bruteforce-Attempts

1.3. Tools used

The program uses tcpdump for listening in a subProcess and then extract the metadata when packets arrive.

1.4. Architecture

The system heavily uses NodeJS-Streams to read, transform and pass data around.

2. Usage/Installation

2.1. Prerequisites

The Wifi-Interface cannot be used elsewhere at the same time e.g. Network-Manager. (Packet-capture e.g. tcpdump or Wireshark is ok)

As of this version, the program does not set the interface into monitor mode or changes to channels.

2.1.1. Interface into Monitor-Mode (rfmon)

You can change into Monitor-mode beforehand with the packages net-tools and wireless-tools:

ifconfig <interface> down
iwconfig <interface> mode Monitor
ifconfig <interface> up

2.1.2. Set/Change channels

You can set the channel of the interface (if the interface allows this) with the package wireless-tools:

iw dev <interface> set channel <channelNumber>

2.2. Choosing an Export-Method

The system allows exporting directly into InfluxDB version >= 2.0 or into any system using the InfluxDb-Line-Protocol e.g. QuestDB over TCP.

As of writing (using InfluxDB v2.1 and using the flux-language), the data written by this system was a bit too much for InfluxDB and it struggled very quickly on a fairly beefy machine.

Thats why the additional LineProtocol-Export-Method was added. Freedom of choice of the Time-Database.

If you want to use the InfluxDB-Line-Protocol, simply set the environment variable USE_INFLUXDB_LINEPROTOCOL to true along with the-other necessary Host and Port-variables.

2.3. Running with Docker

2.3.1. Permissions

The container must run as root, to have permission to listen on the wifi-interface.

2.3.2. docker run

Either run with docker directly.

for InfluxDB

docker run
  -d
  --restart unless-stopped 
  --network host
  -e WIFI_INTERFACE="<yourInterfaceName or leave empty for wlan0>"
  -e INFLUX_URL="http://influxdb:8086/"
  -e INFLUX_TOKEN="<yourToken>"
  -e INFLUX_ORG="<yourOrganisation>"
  ruakij/rfmon-to-influx:2

for InfluxDB-Line-Protocol

docker run
  -d
  --restart unless-stopped 
  --network host
  -e WIFI_INTERFACE="<yourInterfaceName or leave empty for wlan0>"
  -e USE_INFLUXDB_LINEPROTOCOL="true"
  -e INFLUXDB_LINEPROTOCOL_HOST="<host>"
  -e INFLUXDB_LINEPROTOCOL_PORT="<port>"
  ruakij/rfmon-to-influx:2

2.3.3. docker-compose

Or use the more preferred way with docker-compose.

docker-compose.yml

for InfluxDB

version: '3'

services:
  rfmon:
    container_name: rfmon
    image: ruakij/rfmon-to-influx:2
    restart: unless-stopped
    network_mode: "host"
    environment:
      - WIFI_INTERFACE="<yourInterfaceName or leave empty for wlan0>"
      - INFLUX_URL="http://influxdb:8086/"
      - INFLUX_TOKEN="<yourToken>"
      - INFLUX_ORG="<yourOrganisation>"
      - INFLUX_BUCKET="<yourBucket>"

for InfluxDB-Line-Protocol

version: '3'

services:
  rfmon:
    container_name: rfmon
    image: ruakij/rfmon-to-influx:2
    restart: unless-stopped
    network_mode: "host"
    environment:
      - WIFI_INTERFACE="<yourInterfaceName or leave empty for wlan0>"
      - USE_INFLUXDB_LINEPROTOCOL="true"
      - INFLUXDB_LINEPROTOCOL_HOST="<host>"
      - INFLUXDB_LINEPROTOCOL_PORT="<port>"

And then pull&start the container:

docker-compose up -d

2.4. Environment-Variables

2.4.1. Necessary

for InfluxDB

Variable	Description
INFLUX_URL	Url of influx-server
INFLUX_TOKEN	Token with write-access
INFLUX_ORG	Organisation and..
INFLUX_BUCKET	Bucket to write into

for InfluxDB-Line-Protocol

Variable	Description
USE_INFLUXDB_LINEPROTOCOL	Enable LineProtocol
INFLUXDB_LINEPROTOCOL_HOST	Host and..
INFLUXDB_LINEPROTOCOL_PORT	Port of your server

2.4.2. Optional

Variable	Default	Description
LOGLEVEL	INFO	Loglevel
WIFI_INTERFACE	wlan0	Wifi-Interface name in Monitor-Mode
HOSTNAME	Device's Hostname	Hostname to use as global hostname-tag (Unused)

3. Data collected

8 Metrics are constructed with 6-10 tags identifying them.

3.1. Data-Types

Type	Example	Description
String	Wlan	-
Number	0	Any normal number, positive and negative
Boolean	true	true or false values
MAC	12:34:56:78:9A:BC	Address for L2-networks

3.2. Metric-Overview

---

Name	Type	Description
rfmon_signal_dbm	Number (-95 <> -20)	Signal-Level of every Packet in dBm
rfmon_datarate_bytes	Number (1 <> 144)	Data-Rate of every Packet in MBit/s
rfmon_ssid_names	String (Length: 0-32)	SSIDs of any Packet containing it
rfmon_authenticationtype_info	String	Authentication-Type used by Sender
rfmon_associationsuccess_bools	Boolean	Result of an Association
rfmon_disassociationreason_info	String	Disconnect-Reason from a ST (not always sent)
rfmon_handshakestage_info	Number (1 <> 4)	Stage of a handshake (1 and 3 from ST, 2 and 4 from AP)

3.3. Metric-Details

3.3.1. rfmon_ssid_names

String (Length: 0-32)

SSIDs from ProbeRequest might be empty (probe for any) or in case of Beacon-Frames could be hidden.

3.3.2. rfmon_authenticationtype_info

String {OpenSystem_1, OpenSystem_2, Unknown}

3.4. Tag-Overview

---

Name	Type	Description
srcmac	MAC	Sender's MAC-Address (not present in ClearToSend-Packet)
dstmac	MAC	Destination's MAC-Address (not present in RequestToSend-Packet)
bssid	MAC	AP's MAC-Address
frequency	Number	Frequency the packet was captured on in MHz
packetType	String	Type of packet
flags_MoreFragments	Boolean	Packet is incomplete
flags_Retry	"	Packet is being retried
flags_PwrMgt	"	Sender will not sleep
flags_MoreData	"	More data in send-buffer to be expected
flags_Protected	"	Packet is protected
flags_Order	"	Packet is strictly ordered

3.5. Tag-Details

3.5.1. frequency

Number (2412 <> 2484)

The frequency corresponds to following wifi-channels:

Channel	Frequency
1	2412
2	2417
3	2422
4	2427
5	2432
6	2437
7	2442
8	2447
9	2452
10	2457
11	2462
12	2467
13	2472
14	2484

See Wikipedia - List of WLAN channels - 2.4GHz for more Information.

3.5.2. packettype

String

Type	Sender	Description
Beacon	AP	Signal its presence and provide synchronisation for Stations
ProbeRequest	ST	Ask if certain RA/SSID is available
ProbeResponse	AP	Directly respond to Request and Signal own presence
Data	Both	Data-packets
RequestToSend	ST	Ask for transmission-time
ClearToSend	RA	Ack transmission-time
Acknowledgment	Both	Ack Data-Packets
BlockAcknowledgment	Both	Ack alot of Data-Packets at once
NoData	Both	Packet without content, typically used to transmit QoS-States
Authentication	Both	Authentication-process to establish identity and set states
AssociationRequest	ST	Register to AP
AssociationResponse	AP	Respond to registering
Disassociation	ST	Actively unregister e.g. to associate with different AP
Handshake	Both	4-Way-EAPOL-Handshake to generate encryption-keys between participants
Unknown	-	Unknown packets not identified into above types

4. Potential Issues

4.1. Channel/Frequency

The System can only monitor one channel at a time which might not be enough cover, to combat this, more Interfaces and Systems can be deployed.

This is not entirely unproblematic, as the system cannot currently prevent packages from being inserted more than once.

4.2. Technology

Mismatches between sender and receiver-technologies (e.g. MIMO or HT) can cause packets not being logged at all. Though this should only be a problem for data-packets.

4.3. Data protection

Because the system collects any data, this can be problematic, specially in countries with strong data-protection laws.

A wifi MAC address is likely to be considered as information of an identifiable natural person, e.g. under GDPR Art.4 (1) and its processing may only be done with prior consent or has to be anonymised.

4.4. Ethical

The large-scale collection of data for behavioural or movement analysis, especially without consent of the data subject, is highly controversial.

Metadata that can be used to track precise activities, such as wifi data, is very powerful and should only be collected and used when necessary.

If this data falls into the hands of a malicious actor, more precise attacks on the targets could be carried out, such as break-insv, behaviour-based discrimination or more successful phishing.