Nzyme collects 802.11 management frames directly from the air and sends them to a Graylog (Open Source log management) setup for WiFi IDS, monitoring, and incident response. It only needs a JVM and a WiFi adapter that supports monitor mode.
Think about this like a long-term (months or years) distributed Wireshark/tcpdump that can be analyzed and filtered in real-time, using a powerful UI.
One or more WiFi adapters that support monitor mode on your operating system.
The most important component is one (or more) WiFi adapters that support monitor mode. Monitor mode is the special state of a WiFi adapter that makes it read and report all 802.11 frames and not only certain management frames or frames of a network it is connected to. You could also call this mode sniffing mode: The adapter just spits out everything it sees on the channel it is tuned to.
The problem is, that many adapter/driver/operating system combinations do not support monitor mode.
The internet is full of compatibility information but here are the adapters I run nzyme with on a Raspberry Pi 3 Model B:
In the end, it shoulnd’t really matter what you run it on, but the docs and guides will most likely refer to a Raspberry Pi with a Raspbian on it.
You can start a GELF input for nzyme using your Graylog Web Interface. Navigate to System -> Inputs, select GELF TCP in the dropdown menu and hit Launch new input. A modal dialog will open and ask you a few questions about, for example, which address to bind on and what port to use. The input will be immediately available for nzyme after pressing Save.
Because we don’t want to listen on only one, but possibly all WiFi channels, we either need dozens of adapters, with one adapter for each channel, or we cycle over multiple channels on a single adapter rapidly. Nzyme allows you to configure multiple channels per WiFi adapter.
For example, if you configure nzyme to listen on channel 1,2,3,4,5,6 on wlan0 and 7,8,9,10,11 on wlan1, it will tune wlan0 to channel 1 for a configurable time (default is 1 second) and then switch to channel 2, then to channel 3 and so on. By doing this, we might miss a bunch of wireless frames but are not missing out on some channels completely.
The best configuration depends on your use-case but usually you will want to tune to all 2.4 Ghz and 5 Ghz WiFi channels.
On Linux, you can get a list of channels your WiFi adapter supports like this:
Success will highly depend on how well supported your WiFi adapters and drivers are. Use the recommended adapters for best results. You can get them from Amazon Prime and have them ready in one or two days.
At least on OSX, your adapter will not switch channels when already connected to a network. Make sure to disconnect from networks before using nzyme with the on-board WiFi adapter. On other systems, switching to monitor mode should disconnect the adapter from a possibly connected network.
Nzyme works well with both the OpenJDK or the Oracle JDK and requires Java 7 or 8.
Wifi adapters can draw quite some current and I have seen Raspberry Pi 3’s shut down when connecting more than 3 ALFA adapters. Consider this before buying tons of adapters.
The onboard WiFi chips of recent Raspberry Pi models can be put into monitor mode with the alternative nexmon driver. The problem is, that the onboard antenna is not very good. If possible, use an external adapter that supports monitor mode instead.
Make sure you have Java 7 or 8 installed:
Download the most recent Debian package (.DEB) from the Releases page.
Install the package:
Now enable the nzyme service to make it start on boot of the Raspberry Pi:
Think about this like a long-term (months or years) distributed Wireshark/tcpdump that can be analyzed and filtered in real-time, using a powerful UI.
What kind of data does it collect?
Nzyme collects, parses and forwards all relevant 802.11 management frames. Management frames are unecrypted so anyone close enough to a sending station (an access point, a computer, a phone, a lightbulb, a car, a juice maker, ...) can pick them up with nzyme.- Association request
- Association response
- Probe request
- Probe response
- Beacon
- Disassociation
- Authentication
- Deauthentication
What do I need to run it?
Everything you need is available from Amazon Prime and is not very expensive. There even is a good chance you have the parts around already.One or more WiFi adapters that support monitor mode on your operating system.
The most important component is one (or more) WiFi adapters that support monitor mode. Monitor mode is the special state of a WiFi adapter that makes it read and report all 802.11 frames and not only certain management frames or frames of a network it is connected to. You could also call this mode sniffing mode: The adapter just spits out everything it sees on the channel it is tuned to.
The problem is, that many adapter/driver/operating system combinations do not support monitor mode.
The internet is full of compatibility information but here are the adapters I run nzyme with on a Raspberry Pi 3 Model B:
- ALFA AWUS036NH - 2.4Ghz and 5Ghz (Amazon Prime, about $40)
- ALFA AWUS036NEH - 2.4Ghz (Amazon Prime, about $50)
- ALFA AWUS036ACH - 2.4Ghz and 5Ghz (Amazon Prime, about $50)
- Panda PAU05 - 2.4Ghz (Amazon Prime, about $15)
A small computer to run nzyme on.
I recommend to run nzyme on a Raspberry Pi 3 Model B. This is pretty much the reference architecture, because that is what I run it on. A Raspberry Pi 3 Model B running Nzyme with three WiFi adapters in monitor mode has about 25% CPU utilization in the busy frequencies of Downtown Houston, TX.In the end, it shoulnd’t really matter what you run it on, but the docs and guides will most likely refer to a Raspberry Pi with a Raspbian on it.
A Graylog setup
You need a Graylog setup with ah GELF TCP input that is reachable by your nzyme sensors. GELF is a Graylog-specific and structured log format. Because nzyme sends GELF, you don't have to set up any kind of parsing rules in Graylog and still have all fields available as key:value pairs for powerful search and analysis.You can start a GELF input for nzyme using your Graylog Web Interface. Navigate to System -> Inputs, select GELF TCP in the dropdown menu and hit Launch new input. A modal dialog will open and ask you a few questions about, for example, which address to bind on and what port to use. The input will be immediately available for nzyme after pressing Save.
Channel hopping
The 802.11 standard defines many frequencies (channels) a network can operate on. This is useful to avoid contention and bandwidth issues, but also means that your wireless adapter has to be tuned to a single channel. During normal operations, your operating system will do this automatically for you.Because we don’t want to listen on only one, but possibly all WiFi channels, we either need dozens of adapters, with one adapter for each channel, or we cycle over multiple channels on a single adapter rapidly. Nzyme allows you to configure multiple channels per WiFi adapter.
For example, if you configure nzyme to listen on channel 1,2,3,4,5,6 on wlan0 and 7,8,9,10,11 on wlan1, it will tune wlan0 to channel 1 for a configurable time (default is 1 second) and then switch to channel 2, then to channel 3 and so on. By doing this, we might miss a bunch of wireless frames but are not missing out on some channels completely.
The best configuration depends on your use-case but usually you will want to tune to all 2.4 Ghz and 5 Ghz WiFi channels.
On Linux, you can get a list of channels your WiFi adapter supports like this:
$ iwlist wlan0 channel
wlan0 32 channels in total; available frequencies :
Channel 01 : 2.412 GHz
Channel 02 : 2.417 GHz
Channel 03 : 2.422 GHz
Channel 04 : 2.427 GHz
Channel 05 : 2.432 GHz
Channel 06 : 2.437 GHz
Channel 07 : 2.442 GHz
Channel 08 : 2.447 GHz
Channel 09 : 2.452 GHz
Channel 10 : 2.457 GHz
Channel 11 : 2.462 GHz
Channel 12 : 2.467 GHz
Channel 13 : 2.472 GHz
Channel 14 : 2.484 GHz
Channel 36 : 5.18 GHz
Channel 38 : 5.19 GHz
Channel 40 : 5.2 GHz
Channel 44 : 5.22 GHz
Channel 46 : 5.23 GHz
Channel 48 : 5.24 GHz
Channel 52 : 5.26 GHz
Channel 54 : 5.27 GHz
Channel 56 : 5.28 GHz
Channel 60 : 5.3 GHz
Channel 62 : 5.31 GHz
Channel 64 : 5.32 GHz
Channel 100 : 5.5 GHz
Channel 102 : 5.51 GHz
Channel 104 : 5.52 GHz
Channel 108 : 5.54 GHz
Channel 110 : 5.55 GHz
Channel 112 : 5.56 GHz
Current Frequency:2.432 GHz (Channel 5)Things to keep in mind
A few general things to know before you get started:Success will highly depend on how well supported your WiFi adapters and drivers are. Use the recommended adapters for best results. You can get them from Amazon Prime and have them ready in one or two days.
At least on OSX, your adapter will not switch channels when already connected to a network. Make sure to disconnect from networks before using nzyme with the on-board WiFi adapter. On other systems, switching to monitor mode should disconnect the adapter from a possibly connected network.
Nzyme works well with both the OpenJDK or the Oracle JDK and requires Java 7 or 8.
Wifi adapters can draw quite some current and I have seen Raspberry Pi 3’s shut down when connecting more than 3 ALFA adapters. Consider this before buying tons of adapters.
Installation and configuration on a Raspberry Pi 3
RequirementsThe onboard WiFi chips of recent Raspberry Pi models can be put into monitor mode with the alternative nexmon driver. The problem is, that the onboard antenna is not very good. If possible, use an external adapter that supports monitor mode instead.
Make sure you have Java 7 or 8 installed:
sudo apt install openjdk-8-jrejava -version
openjdk version "1.8.0_40-internal"
OpenJDK Runtime Environment (build 1.8.0_40-internal-b04)
OpenJDK Zero VM (build 25.40-b08, interpreted mode)Download the most recent Debian package (.DEB) from the Releases page.
Install the package:
sudo dpkg -i [nzyme deb file]sudo cp /etc/nzyme/nzyme.conf.example /etc/nzyme/nzyme.confNow enable the nzyme service to make it start on boot of the Raspberry Pi:
sudo systemctl enable nzymesudo systemctl start nzymesudo systemctl status nzyme$ tail -f /var/log/nzyme/nzyme.lo
18:11:43.598 [main] INFO horse.wtf.nzyme.Main - Printing statistics every 60 seconds. Logs are in [logs/] and will be automatically rotated.
18:11:49.611 [main] INFO horse.wtf.nzyme.Nzyme - Building PCAP handle on interface [wlan0]
18:12:12.908 [main] INFO horse.wtf.nzyme.Nzyme - PCAP handle for [wlan0] acquired. Cycling through channels <1>.
18:12:13.009 [nzyme-loop-0] INFO horse.wtf.nzyme.Nzyme - Commencing 802.11 frame processing on [wlan0] ... (⌐■_■)–︻╦╤─ – – pew pew
18:12:14.662 [main] INFO horse.wtf.nzyme.Nzyme - Building PCAP handle on interface [wlan1]
18:12:15.987 [main] INFO horse.wtf.nzyme.Nzyme - PCAP handle for [wlan1] acquired. Cycling through channels <36>.
18:12:15.992 [nzyme-loop-1] INFO horse.wtf.nzyme.Nzyme - Commencing 802.11 frame processing on [wlan1] ... (⌐■_■)–︻╦╤─ – – pew pew
18:13:05.422 [statistics-0] INFO horse.wtf.nzyme.Main -
+++++ Statistics: +++++
Total frames considered: 597 (92 malformed), beacon: 506, probe-resp: 15, probe-req: 76
Frames per channel: 112: 21, 1: 26, 3: 10, 4: 158, 6: 97, 8: 2, 9: 15, 10: 2, 11: 264, 12: 2
Malformed Frames per channel: 6: 1.03% (1), 8: 50.00% (1), 9: 13.33% (2), 11: 32.95% (87), 12: 50.00% (1),
Probing devices: 5 (last 60s)
Access points: 26 (last 60s)
Beaconing networks: 17 (last 60s)
18:14:05.404 [statistics-0] INFO horse.wtf.nzyme.Main -
