This repository contains the source code of the RoLaGuard engine. This component is the responsible of processing packets and generating alerts, detecting issues in assets, list them, between other tasks.
To access the main project with instructions to easily run the rolaguard locally visit the RoLaGuard repository. For contributions, please visit the CONTRIBUTING file
To process the packets, the engine use analyzers. Two are provided in this repository:
-
Base: this module is the responsible of registering every gateway, device or session that is part of the network. Also, it does some checks to detect, for example, duplicated sessions, join replay attacks, gateways changing their location, etc. For a complete list of alerts see the alerts list.
-
Bruteforcer: this module looks for JoinRequests and/or JoinAccepts and tries to bruteforce them using the keys dictionary and a set of keys generated on the fly using easy to guess combinations. Since this module is CPU demanding, each device is bruteforced once per day in order to save CPU, although this can be changed in the bruteforcer source code.
This is the complete list of alerts generated by the engine. Note that some of them are only available in the enterprise version and the source code is not provided in this repository.
| Code | Title | Location | Edition | Risk | Description |
|---|---|---|---|---|---|
| LAF-001 | Possible Join replay attack | Base analyzer | Community | LOW | The DevNonce is a number used by the device at the moment of sending the Join Request (in OTAA operation mode) that assures the uniqueness and authenticity of that message. Since this number must be a random number between 0 and 65535, if it is repeated, it can be inferred that a third party is sending captured Join Request messages, previously sent by the device, in order to generate new sessions. |
| LAF-002 | Devices sharing the same DevAddr | Base analyzer | Community | INFO | Two different devices might have been assigned the same DevAddr. This is not a security threat, but it should not happen since the lorawan server would not be able to distinguish by which device a message is generated. |
| LAF-006 | Possible ABP device found | Base analyzer | Community | HIGH | If the counter was reset (came back to 0), the DevAddr is kept the same, and no previous Join process was detected, may imply that the device is Activated By Personalization (ABP), which is discouraged for security reasons. |
| LAF-007 | Possible duplicated sessions | Base analyzer | Community | MEDIUM | Since it was received a message with a lower counter than expected, it may imply that an attacker has generated valid session keys and is sending data messages with an arbitrary payload. |
| LAF-009 | Easy to guess key | Bruteforcer | Community | HIGH | The AppKey of the device was guessed. |
| LAF-010 | Gateway changed location | Base analyzer | Community | MEDIUM | Since the gateway is not supposed to change its location, it may have been stolen or moved. |
| LAF-011 | Device not re-generating session keys | Base analyzer | Community | HIGH | If the counter was reset (came back to 0), the DevAddr is kept the same, and no previous Join was detected, it may imply that the device is not going through a re-join process when its counter is overflowed (from 65535 to 0). |
| LAF-100 | Device signal intensity below threshold | Base analyzer | Community | LOW | A packet from this device was received with an signal strength below the threshold set in the policy. |
| LAF-101 | Device losing many packets | Base analyzer | Community | LOW | The device is losing more packets than the threshold set in the policy. |
| LAF-102 | Device signal to noise ratio below threshold | Base analyzer | Community | LOW | A packet from this device was received with a signal to noise ratio below the threshold set in the policy. |
| LAF-400 | New device | Base analyzer | Community | INFO | A new device was detected in the network. |
| LAF-401 | Device connection lost | Base analyzer | Community | LOW | A device has not send packets for a long period of time. It might be disconnected. |
| LAF-402 | New gateway found | Base analyzer | Community | INFO | A new gateway was detected in the network. |
| LAF-403 | Gateway connection lost | Base analyzer | Community | LOW | A gateway has not send packets for a long period of time. It might be disconnected. |
| LAF-404 | Device failed to join | Base analyzer | Community | LOW | Device is sending many join requests but it is not joining to the network. |
| LAF-500 | Minor anomaly in device message | Machine learning | Enterprise | INFO | One variable of a received packet presents an abnormal value. |
| LAF-501 | Anomaly in Join Requests frequency | Machine learning | Enterprise | MEDIUM | It was detected an anomaly in the time frequency between Join Request messages of one device. |
| LAF-503 | Anomaly in device message | Machine learning | Enterprise | HIGH | Some variables of a received packet present abnormal values. |
| LAF-600 | Issue solved | System backoffice | Community | INFO | An issue has been solved |
To build the docker image locally:
docker build -t rolaguard-engine