{"id":13627544,"url":"https://github.com/seemoo-lab/chirpotle","last_synced_at":"2025-04-05T10:31:10.138Z","repository":{"id":58508256,"uuid":"263160142","full_name":"seemoo-lab/chirpotle","owner":"seemoo-lab","description":"A LoRaWAN Security Evaluation Framework","archived":false,"fork":false,"pushed_at":"2024-02-11T18:57:07.000Z","size":3401,"stargazers_count":39,"open_issues_count":2,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T14:46:06.544Z","etag":null,"topics":["lora","lorawan","riot-os","security-framework"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seemoo-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-11T21:16:44.000Z","updated_at":"2025-03-15T15:00:03.000Z","dependencies_parsed_at":"2024-08-01T22:51:51.262Z","dependency_job_id":null,"html_url":"https://github.com/seemoo-lab/chirpotle","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Fchirpotle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Fchirpotle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Fchirpotle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seemoo-lab%2Fchirpotle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seemoo-lab","download_url":"https://codeload.github.com/seemoo-lab/chirpotle/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247324598,"owners_count":20920679,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lora","lorawan","riot-os","security-framework"],"created_at":"2024-08-01T22:00:35.435Z","updated_at":"2025-04-05T10:31:06.867Z","avatar_url":"https://github.com/seemoo-lab.png","language":"Jupyter Notebook","funding_links":[],"categories":["LoRaWAN","Wireless Protocols"],"sub_categories":["Tools","LoRa / LoRaWAN"],"readme":"![ChirpOTLE](assets/chirpotle.png)\n\nChirpOTLE is a practical LoRaWAN security evaluation framework that provides tools for the deployment and management of a LoRa testbed based on COTS hardware.\nIt allows managing LoRa field nodes from a central controller and to orchestrate experiments and tests using a Python 3 interface.\n\nBy collocating the nodes with a LoRaWAN network, the built-in functions for receiving, transmitting, jamming, and sniffing can be used to study their effects on the network under test.\nWith its dissector and predefined building blocks like wormholes, the framework allows for quick vulnerability assessment in LoRaWAN networks as well as for the evaluation of attempts for their mitigation.\n\n## Basic Setup\n\nThe framework is managed through the `chirpotle.sh` shell script.\nIt creates and manages a virtual environment, node configurations and it takes care of creating the RPC stubs for communication with the nodes.\n\nTo get started with the controller, just run the `install` task and you are ready to go:\n\n```bash\n./chirpotle.sh install\n```\n\nIf you want to be able to use the framework independent of the working directory, you can add it to your `.bashrc`:\n\n```bash\necho \"alias chirpotle=\\\"$(pwd)/chirpotle.sh\\\" \\\"\\$@\\\"\" \u003e\u003e ~/.bashrc\n```\n\nYou will then be able to call it from any directory like:\n\n```bash\nchirpotle interactive\n```\n\nBy default, the virtual environment is created in the `env` folder in the repository and the configurations are stored in `conf`.\nIf you want a clean install, you can delete the `env` folder without losing your configuration.\n\n## Configure Your Setup\n\nAs ChirpOTLE is meant to be deployed in the field, it uses a star topology with the controller in the center and nodes in the field.\nController and field nodes are connected through **SSH for deployment** and **RPC calls** for control during experiments.\n\n\u003e **Note:** The tool assumes a secure network connection between controller and nodes, the RPC traffic is not secured and SSH host keys are trusted by default.\n\nFor this description, we assume you have the following setup:\n\n- The controller is running on your desktop machine, and you've installed ChirpOTLE as mentioned [above](#basic-setup)\n- You have two Raspberry Pis running a fresh installation of Raspbian, and they are available as loranode1.example and loranode2.example\n- To each of the Pis, you've got a [LoPy 4](https://docs.pycom.io/datasheets/development/lopy4/) connected via a USB-to-Serial bridge, so it's available as `/dev/ttyUSB0`\n\n\u003e **Note:** Other LoRa hardware can be used with the framework, see [`Makefile.preconf` of the companion application](node/companion-app/riot-apps/chirpotle-companion/Makefile.preconf) for more options.\n\n### Prepare the Nodes\n\nFirst, you need to make the nodes available for root access via SSH.\nCopy your SSH key to `/root/.ssh/authorized_keys` on each of the Raspberry Pis.\n\n\u003e **Note:** Your SSH public key is usually located in `~/.ssh/id_rsa.pub`. If that file does not exist, run `ssh-keygen -t rsa -b 4096` on your desktop machine.\n\nAfter having deployed the keys, you can start installing Python 3 and pip on the Pis.\nAll other software installation will be managed by the framework.\n\n```bash\nssh root@loranode1.example apt-get update\nssh root@loranode2.example apt-get update\nssh root@loranode1.example apt-get install python3 python3-pip\nssh root@loranode2.example apt-get install python3 python3-pip\n```\n\n### Create a Configuration\n\nNow it is time to setup the configuration, so that your controller knows which nodes are avaialble.\n\nAll configurations are stored in the `conf` folder of the repository after running `chirpotle.sh install`, but the easiest way for most cases is to use the interactive editor.\n\nRun `./chirpotle.sh confeditor`, and you'll be greeted with the main menu:\n\n```bash\nWhat do you want to do?\n        \n   📝  List/edit controller configurations \n   📝  List/edit node profiles\n   Save changes and quit \n```\n\n- Select `List/edit controller configuration`.\n- Select `Create new configuration`\n- Enter the name `testconf`\n- Select `Add Node`\n   - Name: `alice` (This is how you will address the node in scripts)\n   - Host: `loranode1.example`\n   - Node profile: `uart-lopy4`\n- Select `Add Node`\n   - Name: `bob` (This is how you will address the node in scripts)\n   - Host: `loranode2.example`\n   - Node profile: `uart-lopy4`\n\nYour configuration should now look like this:\n\n```\n   🖥️  Node: alice (loranode1.example, uart-lopy4) \n   🖥️  Node: bob (loranode2.example, uart-lopy4) \n   ➕ Add node                                          \n   🏷️  Rename this confiugration                       \n   Delete this configuration                           \n   Go back \n```\n\nIf everything seems alright, select `go back` in all menus, and your configuration will be saved as `testconf`.\n\n### Deploy ChirpOTLE to the Nodes\n\nNow, you can test if everything is set up correctly and if the nodes have all required software installed:\n\n```bash\n./chirpotle.sh deploycheck --conf conftest\n```\n\n\u003e **Note:** Most of the CLI commands support the `--conf` option to select the configuration that you want to use.\nIf you omit this option, the CLI will try to use a configuration with the name `default`.\n\nYou should now see green checkmarks for everything that is working, a warning sign for optional software that is not required in every case and a red x for unfulfilled requirements.\nIf you see errors, please re-check the instructions above.\n\nIf all requirements are fulfilled, you can start deploying ChirpOTLE to the nodes:\n\n```bash\n./chirpotle.sh deploy --conf conftest\n```\n\nThis command will do the following:\n\n- Build and bundle the TPy node in `submodules/tpy/node`\n- Bundle the add additional ChirpOTLE modules in `node/remote-modules`\n- Build and bundle the companion application for the remote MCUs from `node/companion-app`\n- For each node:\n   - Copy everything to the nodes\n   - Install additional software (globally, using pip)\n   - If MCUs are connected to the nodes (the LoPy 4 boards in this case): Flash the MCUs with the companion application\n\n### Start the Nodes\n\nAs a last step before starting with experiments, you need to launch the node deamon on each node:\n\n```bash\n./chirpotle.sh restartnodes --conf conftest\n```\n\nNow you should be ready to go!\n\n## Getting Started\n\nTo familiarize with the framework, the best way is to start an interactive session.\nAfter you have set everything up, you can run the `interactive` task to start such a session:\n\n```bash\n./chirpotle.sh interactive --conf testconf\n```\n\nIf you used the setup mentioned above, you can now try to communicate between both LoRa boards:\n\n```python\n# Assure both use the same channel setup\nbob_lora.set_lora_channel(**alice_lora.get_lora_channel())\n\n# Configure IQ inversion to default values\nalice_lora.set_lora_channel(invertiqtx=True)\nbob_lora.set_lora_channel(invertiqrx=False)\n\n# Set Bob in receive mode\nbob_lora.receive()\n\n# Transmit a frame\nalice_lora.transmit_frame([int(b) for b in b'Hello, World'])\n\n# Check if Bob received it\nbobframe = bob_lora.fetch_frame()\nif bobframe is not None:\n    print(\"Bob received: {payload_str} (RSSI={rssi} dB, SNR={snr} dB)\".format(**{\n      **bobframe,\n      \"payload_str\": \"\".join([chr(b) for b in bobframe['payload']]),\n    }))\nelse:\n    print(\"No frame received\")\n```\n\nTo run one of the example scripts, you can use the `run` task with a python script as parameter:\n\n```bash\n./chirpotle.sh run --conf testconf example.py\n```\n\n## Getting Started with Jupyter Notebooks\n\nThe framework also comes with an integration for Jupyter notebooks.\nAfter creating you configuration like mentioned above, you can just run:\n\n```bash\n./chirpotle.sh deploy --conf testconf\n./chirpotle.sh restartnodes --conf testconf\n./chirpotle.sh notebook --conf testconf\n```\n\nOn the first run, the `notebook` action will install Jupyter notebook in the virtual environment.\nThe default notebook folder is called `notebook` and created in the repository root.\nIt also contains an `examples` folder with notebooks that show you how to setup your experiments and how to integrate the framework with data visualization tools like `matplotlib` to create a seamless workflow.\n\n## System Requirements\n\nMost of the software that is required to run the framework is managed by the framework in the virtual environment.\nHowever, some preparations have to be made to bootstrap the management.\n\n### Controller\n\nFor the basic installation of the controller, Python \u003e=3.9 is required, pip and the `venv` module must be present.\nEarlier versions might still work but are no longer supported.\nEverything else will be fetched by the installer and be placed in the virtual environment.\n\nIf you do not want to use your system's default python (the installer will check first for `python3`, then for `python` on your path), you can specify the `PYTHON` environment variable during installation to point to a specific executable:\n\n```bash\nPYTHON=/opt/my-python/bin/python ./chirpotle.sh install\n```\n\nThe framework was tested on Debian Bullseye and we check basic functionality in GitHub Actions for Ubuntu 22.04 and 20.04, but it should work on most other Linux distributions as well.\n\n### Nodes\n\nCalling `./chirpotle.sh deploy` will install the framework globally on the node using an SSH connection as user `root`.\nTherefore, the public SSH key of the user running the ChirpOTLE controller must be added to root's `authorized_keys` file on the node.\nFurthermore, you need to install Python3 with pip, git, make and gcc on each node.\nFor Debian-based systems, you can run:\n\n```bash\napt install python3 python3-pip git build-essential\n```\n\nYou can check if your nodes meet the requirements by calling `./chirpotle.sh deploycheck`.\nThe output will also suggest quick fixes in case some of the requirements are not met.\n\nCurrently supported hardware:\n\n* Raspberry Pi with [Dragino LoRa GPS HAT](https://wiki.dragino.com/index.php?title=Lora/GPS_HAT)\n* [Pycom LoPy 4](https://pycom.io/product/lopy4/) with external USB-to-Serial converter ([Documentation](docs/board_lopy4.md))\n* [Adafruit Feather M0 LoRa](https://www.adafruit.com/product/3178)\n* [LILYGO T-Beam](https://github.com/Xinyuan-LilyGO/LilyGo-LoRa-Series), v1.1\n\n## Development\n\nIf you want to modify the framework, you need to install it in development mode for changes to be immediately available.\nTherefore, the `install` task supports a `--dev` flag:\n\n```bash\n./chirpotle.sh install --dev\n```\n\nIf you've already installed the framework in the default virtual environment (`env` in the repository root), you can just delete that folder and install again.\n\n## Read Our Paper\n\nThe ChirpOTLE framework has been published at [ACM WiSec '20](https://wisec2020.ins.jku.at/) with our paper:\n\nFrank Hessel, Lars Almon, and Flor Álvarez. 2020. ChirpOTLE: A Framework for Practical LoRaWAN Security Evaluation. In _13th ACM Conference on Security and Privacy in Wireless and Mobile Networks (WiSec '20), July 8–10, 2020, Linz (Virtual Event), Austria_. ACM, New York, NY, USA, 11 pages. https://doi.org/10.1145/3395351.3399423\n\nA [preprint](https://arxiv.org/abs/2005.11555) is available.\nScripts and data for all experiments from the paper can be found in [experiments/wisec2020](experiments/wisec2020/README.md).\nIf you use our work for your research, please cite the paper:\n\n```\n@inproceedings{chirpotle2020,\n  title     = {ChirpOTLE: A Framework for Practical LoRaWAN Security Evaluation},\n  author    = {Hessel, Frank and Almon, Lars and Álvarez, Flor},\n  booktitle = {Proceedings of the 13th Conference on Security and Privacy in Wireless and Mobile Networks},\n  date      = {2020},\n  month     = jul,\n  address   = {Linz (Virtual Event), Austria},\n  doi       = {10.1145/3395351.3399423},\n  publisher = {ACM},\n  series    = {WiSec '20},\n  url       = {https://doi.org/10.1145/3395351.3399423},\n}\n```\n\n## License\n\nWe provide the ChirpOTLE framework under the [GNU General Public License, Version 3](LICENSE).\nHowever, the repository contains (modified) third-party code and tools which has been published using a different licenses:\n\n| Component                       | License                                                                   | Directory/Files                                              |\n| ------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------ |\n| esp-idf                         | [Apache License, Version 2](submodules/esp-idf/LICENSE)¹                  | `submodules/esp-idf`                                         |\n| RIOT                            | [GNU Lesser Public General License, Version 2.1](submodules/RIOT/LICENSE) | `submodules/RIOT`                                            |\n| TPy                             | n/a                                                                       | `submodules/tpy`                                             |\n| xtensa-esp32-elf for RIOT       | n/a                                                                       | `submodules/xtensa-esp32-elf`                                |\n| ubjson (deprecated RIOT module) | [GNU Lesser Public General License, Version 2.1](submodules/RIOT/LICENSE)²| `node/companion-app/riot-modules/{incude/ubjson.h|ubjson/*}` |\n| ChirpStack Docker config  | [MIT License](experiments/wisec2020/infrastructure/network/chirpstack/LICENSE)² | `experiments/wisec2020/infrastructure/network/chirpstack`    |\n| LoRaMAC node      | [Revised BSD license](experiments/wisec2020/infrastructure/node/LoRaMAC-node/LICENSE)¹² | `experiments/wisec2020/infrastructure/node/LoRaMAC-node/`    |\n\n¹ The submodule may contain submodules on its own, which again is published under different licenses, so please also check the description of the submodule.\n\n² We modified this component and publish the changes under the same license.\n\n## Powered by\n\n[![Logo: TU Darmstadt](assets/logo_tuda.png)](https://www.tu-darmstadt.de)\n[![Logo: Secure Mobile Networking Lab](assets/logo_seemoo.png)](https://www.seemoo.de)\n[![Logo: CYSEC](assets/logo_cysec.png)](https://www.cysec.de)\n[![Logo: ATHENE](assets/logo_athene.png)](https://www.athene-center.de)\n[![Logo: emergenCITY](assets/logo_emergencity.png)](https://www.emergencity.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseemoo-lab%2Fchirpotle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseemoo-lab%2Fchirpotle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseemoo-lab%2Fchirpotle/lists"}