simeononsecurity/helium_diy_middleman repository overview

⁠Middleman for Helium

DockerHub⁠

• middleman_config_dir

  The directory in which middleman should search for its upstream gateway configurations. (See the Configuration files for middleman section).

  Default: /home/middleman/configs

• middleman_python

  The python interpreter to use when starting middleman if you need a very specific version to be used, or if it is installed in an unusual path.

  Default: python3

• middleman_port

  The UDP port on which middleman should listen for incoming packets from gateways.

  Default: 1681

• middleman_args

  Additional arguments to pass to middleman when running. Make sure to use double quotes when setting this variable.

⁠Docker Container Setup

Examples:

docker run --name diymiddleman -P -td simeononsecurity/helium_diy_middleman:latest      

docker run \
    --net='bridge' \
    -p 1681:1681/udp \
    -e middleman_port=1681 \
    -e middleman_tx_adjust='--tx-adjust 0' \
    -e middleman_rx_adjust='--rx-adjust 0' \
    -e gateway_ID=AA555A0000000000 \
    -e server_address=localhost \
    -e serv_port_up=1680 \
    -e serv_port_down=1680 \
    --name diymiddleman -P -td simeononsecurity/helium_diy_middleman:latest

⁠How It Works

This software listens for UDP datagrams on the specified port (defaults to 1680).
datagrams received on this port may be from gateways (PULL_DATA, PUSH_DATA, TX_ACK) or from miners (PULL_ACK, PUSH_ACK, PULL_RESP). any ACK message is dropped as they are for information only.

PULL_DATA messages from gateways are used to ensure a communication path through any NAT or router is open. These messages contain the MAC address (same as Gateway_ID) as well as the origin IP address and port. This mapping of gateway MAC to (IP, Port) is saved so the software knows where to send PULL_RESP messages.

PUSH_DATA messages from gateways are used to inform the miner of received LoRa packets. Each received LoRa packet, regardless of which gateway sent the message, is forwarded to all gateways. Since multiple gateways may receive the same message, a cache is of recent messages is kept and duplicate LoRa packets are dropped. The metadata such as gateway MAC address is modified so each miner thinks it is communicating with a unique gateway. The RSSI, SNR, and timestamp (tmst) fields are also modified to be in acceptable ranges and to ensure the timestamps are in order and increment as expected regardless of real gateway (we cant assume timestamps are synchronized if gateway doesnt have GPS).

PULL_RESP messages received from miners contain data to transmit (usually for device JOINs or PoC). These are forwarded unmodified to the gateway with the same MAC address as the virtual gateway interfacing with the miner, if it exists, and a PULL_DATA was received from the gateway. This ensures transmit behavior of a miner remains consistent. This restriction may be removed in later revisions.

To ensure PULL_RESPs are received by the other miners, a fake PUSH_DATA payload is created for every PULL_RESP with simulated RSSI, SNR, and timestamp (currently hardcoded RSSI and SNR). This fake PUSH_DATA runs through the same process as real ones except it is not forwarded to the miner that sent the PULL_RESP (so gateways don't receive their own transmissions).

All PULL_DATA, PUSH_DATA, and PULL_RESP messages are immediately sent the corresponding ACK regardless of whether the data was actually delivered.

Additionally, all virtual gateways (interfaces for real miners) periodically send PULL_DATA and PUSH_DATA messages with stat payloads to the gateways. These messages are required to ensure the software remains accessible to gateways and the behavior mimics the semtech packet forwarder. To send valid stats messages each virtual gateway keeps track of the number of PUSH_DATA and PULL_RESP messages it received and increments a counter for each.

⁠Areas for Further Development

• More sophisticated metadata modification to adapt to PoC changes. The framework exists for this and much more sophistication can be added to the separate modify_rxpk.py code. Advanced metadata modification could include queries to an ETL database, querying ML models (either specific to a gateway or global), etc. An important point is the entire blockchain history and challenge history for these gateways and miners are available for determining appropriate metadata.
• Detection of dead miner or gateway (using ACKs). There is no way to forget a miner or gateway without software restart.
• Transmission errors are silently ignored, for reliable transmissions these should be fed back to miners.
• Security: this code is vulnerable to lots of attacks. One possible attack is spoofing gateways.

⁠Disclaimers

• This is technically considered gaming.
• I have done very little testing.
• Software is 100% proof of concept. No guarantees on reliability or accuracy only use for testing
• This software can be used for "gaming" or "exploits". Part of creating this software is to demo these exploits to encourage community discussion, expose limitations, and be a weak test for any exploit fixes. You should only use this software for testing purposes and not for widespread gaming or exploitation of the Helium network.