git404hub

what is race fr?

ekomssavior/race — explained in plain English

Analysis updated 2026-05-18

15PythonAudience · researcherComplexity · 4/5Setup · moderate

tl;dr

A security research tool that demonstrates three disclosed Bluetooth vulnerabilities in the Airoha RACE protocol used by many headphones and speakers.

vibe map

mindmap
  root((race framework))
    What it does
      Exploits RACE protocol CVEs
      Bluetooth device discovery
      Link key extraction
    Tech stack
      Python
      Bluetooth Low Energy
      BlueZ
    Use cases
      Authorized security testing
      Vulnerability research
      Protocol analysis
    Audience
      Security researchers
    Setup
      Install BlueZ and pip packages
      Run as root
      CLI scan and exploit commands

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Test whether your own Bluetooth headphones or speakers are affected by the disclosed RACE protocol vulnerabilities.

VIBE 2

Study how the Airoha RACE protocol's flash memory access and authentication flaws work, for authorized security research.

VIBE 3

Learn the exact command codes and packet format the RACE protocol uses.

VIBE 4

Reference published CVE disclosures alongside a working proof-of-concept implementation.

what's the stack?

PythonBluetooth Low EnergyBlueZ

how it stacks up fr

ekomssavior/race0pen-sourcer/hearth13127905/deep-learning-based-air-gesture-text-recognition-
Stars151515
LanguagePythonPythonPython
Setup difficultymoderatemoderatemoderate
Complexity4/53/53/5
Audienceresearchervibe coderdeveloper

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · moderate time til it works · 30min

Requires Linux with BlueZ and a Bluetooth adapter, intended strictly for authorized security testing per the README's disclaimer.

in plain english

RACE is a security research tool that demonstrates a set of real vulnerabilities in the Airoha RACE protocol, a communication protocol used inside many Bluetooth headphones and speakers from brands like Sony, Marshall, Bose, JBL, Jabra, and others. The three vulnerabilities it targets, tracked as CVE-2025-20700, CVE-2025-20701, and CVE-2025-20702, allow an attacker within Bluetooth range to connect to a vulnerable device without authentication, read and write its flash memory, and extract a security credential called a Link Key that can then be used to impersonate the device. The README states plainly that the software is meant for authorized security testing only. The tool works over Bluetooth Low Energy and offers a command line interface with several stages. A discovery or scan step finds nearby devices that expose the vulnerable RACE service, a fingerprint step queries a target device for its chip model, software version, and build date, a flash dump step extracts the device's Link Key from memory, and an impersonation step uses that key to pose as the original device, which the README says can be used to intercept calls, contacts, and messages sent over Bluetooth's hands-free profile. There is also a combined mode that automates scanning and exploitation together. Installation requires a Linux system with the Bluetooth stack installed, plus Python packages for Bluetooth Low Energy communication. The code is organized into a command line entry point, a session management module, separate transport modules for Bluetooth Low Energy and classic Bluetooth, and modules for each attack stage. The README documents the exact protocol format and command codes used to talk to affected devices, and links to a public vulnerability disclosure page and the CVE database entries for further technical detail. The README does not state a license.

prompts (copy fr)

prompt 1
Explain what CVE-2025-20700, CVE-2025-20701, and CVE-2025-20702 allow an attacker to do.
prompt 2
Walk me through installing the Bluetooth and Python dependencies this tool needs on Linux.
prompt 3
Explain how the fingerprint and flash dump stages of this tool work at the protocol level.
prompt 4
Help me understand the RACE protocol packet format described in this README.

Frequently asked questions

what is race fr?

A security research tool that demonstrates three disclosed Bluetooth vulnerabilities in the Airoha RACE protocol used by many headphones and speakers.

What language is race written in?

Mainly Python. The stack also includes Python, Bluetooth Low Energy, BlueZ.

How hard is race to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is race for?

Mainly researcher.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.