LoRaWAN Auditing Framework
LoRaWAN Auditing Framework
IoT deployments just keep growing and one part of that significant growth is composed of millions of LPWAN (low-power wide-area network) sensors deployed at hundreds of cities (Smart Cities) around the world, also at industries and homes. One of the most used LPWAN technologies is LoRa for which LoRaWAN is the network standard (MAC layer). LoRaWAN is a secure protocol with built-in encryption but implementation issues and weaknesses affect the security of most current deployments.
This project intends to provide a series of tools to craft, parse, send, analyze and crack a set of LoRaWAN packets in order to audit or pentest the security of a LoraWAN infrastructure.
Tools description
Here is a description of the directories and the tools/function inside them.
/tools
The main purpose of the tools provided in this directory is to ease the execution of a penetration test to a LoRaWAN infrastructure.
UdpSender.py
This tool is intended to send uplink packets (to the network server or gatewayBridge, depending on the infrastructure) or downlink packets (to the packet-forwarder). Optionally, packets can be fuzzed and a valid MIC can be calculated.
UdpProxy.py
This UDP proxy is mainly intended to be placed between a series gateways (packet_forwarders) and a network server or gateway bridge depending on the infrastructure being evaluated. It also offers the possibility to fuzz data in the desired direction (uplink or downlink).
TcpProxy.py
This TCP proxy is mainly intended to be placed between the network server and an MQTT brokers. It also offers the possibility to fuzz data.
tools/lorawan
This directory contains a series of scripts to parse, craft, bruteforcer, etc. LoRaWAN packets.
lorawan/BruteForcer.py
This script receives a JoinAccept or JoinRequest in Base64 and tries to decrypt its AppKey with a set of possible keys which can be provided in a file or can be generated on the fly.
lorawan/MicGenerator.py
This script receives a PHYPayload packet in Base64 and a key which can be the NwkSKey of the AppKey depending on the packet type and generates the new MIC.
lorawan/PacketCrafter.py
This script receives a lorawan JSON packet and transforms it to Base64. It does the inverse as packetParser.py, so the output of that script can be used here and vice-versa.
lorawan/PacketParser.py
This script parses and prints a single LoRaWAN PHYPayload data in Base64. It does the inverse as packetCrafter.py, so the output of that script can be used here and vice-versa.
lorawan/SessionKeysGenerator.py
This script receives a JoinAccept and a JoinRequest in Base64, and an AppKey to generate the session keys.
lorawan/utils/*
These are auxiliary functions used by the UdpSender.py and UdpProxy.py. In Fuzzer.py you can see fuzzing modes implemented.
/auditing
The general purpose of this directory is to collect LoRaWAN packets and analyze different aspects of the traffic, as well as trying a set of keys to try to bruteforce the AppKey.
/auditing/datacollectors
This directory contains a set of scripts that receive LoRaWAN packets from different sources (i.e. gateway packet_forwarder, The Things Network, etc.) and save them into files, with a standard format. This files should be fetched later by the script /auditing/analyzers/LafProcessData.py to execute different sub-tools.
datacollectors/GenericMqttCollector.py
This script connects to the MQTT broker, retrieves all the topics and saves messages into a file in the specified field. The filename is composed by the date that this script was started.
datacollectors/LoraServerIOCollector.py
This script connects to a loraserver.io MQTT broker and saves messages into the DB. You must specify a unique collectorID and you can specify the topics you want to subscribe to.
datacollectors/PacketForwarderCollector.py
This script receives UDP packets from the UDP proxy in the gateway packet_forwarder format and persists them.
analyzers/LafProcessData.py
This script reads a from a file or files or stdin and executes different sub-tools. Depending on the option selected you can execute an analysis of the LoRaWAN traffic, try to bruteforce the AppKey, or parse all the packets received. These options can be combined.
/lorawanwrapper
This directory provides a set of wrappers for the library https://github.com/brocaar/lorawan/, which is written in Golang. These functions are implemented by the tools.
/scripts
Here you will find a series of scripts intended to automate different tasks. Make sure to give them execution permission if necessary (chmod +x your_script for Linux/MacOS).
/scripts/lorawan_gateway_scripts
Easily set up your gateway and switch its channels for sniffing purposes. For more information about how to use them, you can see the readme in this directory.
gateway_channel_changer/LoRa-GW-Installer.sh
This script is used to install all necessary software packages on a Raspberry PI for building up a LoRaWAN Gateway in conjunction with a connected LoRa Concentrator (iC980-SPI, RHF0M301-SPI, RAK831-SPI or any other by manual setup).
gateway_channel_changer/Continuous-Channel-Switch.sh and gateway_channel_changer/LoRa-GW-Channel-Setup.sh
Since it is not possible to know in which frequencies LoRa devices are operating, we have created a script that can switch gateways channels from the US915 and EU868 frequency bands for sniffing purposes. Although there are professional and expensive gateways that support 32 or 64 channels, most gateways support up to 8 channels. This script is intended to run in this kind of gateways.
At least in the US915 frequency band, the first 8 channels are the most used. But there are well-known implementations that use another group of the channel, as for example The Things Networks, which use the second group (8-15) of channels for uplink communication.
Install
Copyright (c) 2019, IOActive Inc
