MeshCore Security

1. Description

MeshCore Security is an experimental dashboard and collection of proof-of-concept tools for security research into the MeshCore protocol.

It connects to a MeshCore companion node over TCP, USB serial, or BLE, captures and inspects traffic, decodes known group channels, explores weak channel-name recovery, and demonstrates identity and sender-impersonation risks. The goal is to make potential weaknesses easier to understand, reproduce safely, and encourage fixes so the broader MeshCore ecosystem becomes healthier.

2. Disclaimer

Caution

This project was written almost entirely by AI. It is not intended to impress anyone, serve as production software, or be used on a real/public mesh. Its purpose is to demonstrate potential vulnerabilities in a controlled setting and encourage improving the security of the MeshCore ecosystem.

The code is experimental and potentially unsafe. It may be incorrect, version-specific, or capable of causing unintended disruption. It is not a security audit and makes no claim that every related vulnerability has been found.

Use these tools only in an isolated test environment where you own every device or have explicit authorization from its owner. You are responsible for complying with applicable laws. The authors do not endorse misuse and provide the software without warranty.

3. Minimum system requirements

This project has been tested only on Apple silicon Macs. Other platforms may work, but they are currently untested. Feel free to test and make contributions if your platform is not supported.

• An Apple silicon Mac (M-series)
• Python 3.12 or newer
• uv
• A MeshCore companion reachable by TCP/Wi-Fi, USB serial, or BLE
• git, make, and a C compiler (provided on macOS by the Xcode Command Line Tools)
• An OpenCL-capable GPU/runtime for group-channel recovery and vanity identity generation

The packet viewer and decoder do not require John the Ripper or OpenCL. The group-channel brute-forcer and vanity identity generator require both. On Apple silicon, John builds as a native arm64 process and uses the integrated GPU through Apple's OpenCL runtime.

4. Features

Screenshots are shown as thumbnails beside the features they illustrate. Click any tile to open the full-resolution image.

Known-channel decoding and sender impersonation

Manage hashtag channels and named channels with hexadecimal secrets, then decode live group messages. Send group messages impersonating an observed sender name and captured repeater route.

See meshcore-dev/MeshCore#3109 for further details.

Channel viewer Decoded traffic, observed users, and repeater paths.

Sender-impersonation test Prepare an impersonated message using an observed identity.

Group-channel name recovery

Use John the Ripper to search for weak channel names from captured encrypted packets.

See meshcore-dev/MeshCore#3044 for further details.

Channel-name recovery

Advert and identity-confusion vulnerabilities

Inspect Room and Repeater adverts, generate evil twin MITM identities with matching public-key prefixes & suffixes, advertise them explicitly, and decode packets received by them.

1. Repeater packets are forwarded to original repeaters so that victims are unaware that any credential thefts have ocurred.
2. Room authentication packets are forwarded and messages are forwarded from the room to the victim. Messages from the victim to the room are currently not forwarded.

See meshcore-dev/MeshCore#2556 for further details.

Vanity identity generation Configure matching public-key characters for an evil twin identity.	Identity-confusion demonstration An original room and a same-name test identity in an isolated client.
Decoded twin identity logs for repeaters and rooms.

5. Installation

Clone the repository

git clone https://github.com/donutsoft/meshcore-security.git
cd meshcore-security

Install the prerequisites

Install the Xcode Command Line Tools if they are not already present:

xcode-select --install

Install uv with Homebrew:

brew install uv

Alternatively, use the official standalone installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

Build the GPU tools

The complete dashboard requires the bundled John the Ripper formats for group-channel recovery and vanity identity generation:

./john/meshcore_john.sh setup
./john/meshcore_john.sh self-test

setup clones John the Ripper jumbo into john/.john-jumbo, installs the two MeshCore OpenCL formats, and builds them. self-test verifies that both formats compile and run on the selected OpenCL device. Review the script before running it; it downloads an upstream repository and builds native code locally.

Start the dashboard

uv run app.py

Open http://127.0.0.1:8080 and use the connection dialog to select a companion.

6. Contributing and vulnerability disclosure

Contributions that improve the dashboard, tests, documentation, reproducibility, mitigations, or defensive understanding are welcome.

This repository is not the place to disclose or submit zero-day vulnerabilities. Any newly discovered vulnerability must first be reported privately to the MeshCore team, with reasonable time allowed for investigation and remediation. Do not open an issue or pull request containing undisclosed exploit details. Public discussion or a proof-of-concept contribution should happen only after disclosure to the MeshCore team.

License

This repository is dedicated to the public domain under the Unlicense.