# BlueToolkit: a modular Bluetooth security testing framework for BR/EDR and BLE > BlueToolkit is a black-box Bluetooth vulnerability testing framework with three modules, recon to gather device capabilities, exploit to run checks against public Bluetooth flaws, and report to emit structured JSON. It suits security researchers testing Bluetooth Classic and BLE devices, and the way it is put together matters more than any single check, because the exploits are YAML templates downloaded from a separate repository and the hardware requirements are picky enough that several checks need a specific board plugged in. **sgxgsx/BlueToolkit** — BlueToolkit is an extensible Bluetooth Classic vulnerability testing framework that helps uncover new and old vulnerabilities in Bluetooth-enabled devices. Could be used in the vulnerability research, penetration testing and bluetooth hacking. We also collected and classified Bluetooth vulnerabilities in an "Awesome Bluetooth Security" way - Repository: https://github.com/sgxgsx/BlueToolkit - Stars: 743 · Forks: 78 - Language: Jupyter Notebook - License: NOASSERTION - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/sgxgsx-bluetoolkit ## Three modules, and black-box is the deliberate constraint BlueToolkit is a modular, black-box Bluetooth security testing framework for Bluetooth Classic (BR/EDR) and Bluetooth Low Energy (BLE), and it supports semi-automated testing. The three modules are named in the README and each has a single job. Recon gathers Bluetooth capabilities and security configuration. It is the module that answers what the device supports and how it is configured, which is the input you need before deciding what to try against it. Exploit executes tests for, as the README puts it, currently 43 public exploits, with the categories given as MitM, RCE, DoS and others. The vulnerability templates live in the exploits folder, and the README says support for more can be added by TODO, which is a direct statement that the set is extensible by design rather than fixed. Report generates structured, machine- and human-readable JSON reports. The black-box constraint is the load-bearing design decision, and the README includes a commented-out paragraph that explains what it would take to go beyond it. The framework works in a black-box fashion, but it is also possible to operate the toolkit in a gray-box fashion, and for that one needs to extend the framework and connect it to the operating system of the target so that it would be possible to observe Bluetooth logs and guarantee no false positives. That paragraph is in the README as an HTML comment, so it is a stated intention rather than a shipped feature. It is also the sharpest statement of the framework's main weakness. A black-box check can only see what the device exposes over the air, so a device that is vulnerable but does not respond in an observable way will look clean. Gray-box operation fixes that by reading the target's own logs, and it is the difference between a positive result and a guaranteed one. The project is written mostly in Python, with the primary language recorded as Jupyter Notebook, and the licence is a custom one that GitHub cannot classify. ## Templates live in a separate repository, so the framework is a harness The structure of BlueToolkit is worth understanding before you run it, because most of what people think of as the tool is not in this repository. The README says BlueToolkit automatically downloads all vulnerability and hardware templates, and that the BlueToolkit templates repository provides a full list of ready-to-use templates. The templates are pulled in as submodules, which the top level listing confirms with a `update_submodules.sh` script and a `.gitignore` that excludes them. The template format is YAML. The README says you can write your own templates and checks as well as add new hardware by following the templating guide, and that the YAML reference syntax is documented separately. The top level directories map onto that structure directly: `exploits/` for the vulnerability templates, `hardware/` for the hardware profiles, `bluekit/` for the framework code itself, `evaluation/` for the research evaluation, `static/` for assets, `vagrant/` for the VM setup, plus `install.sh` and `update_submodules.sh` at the root. The separation has a real consequence for how you use the tool. The framework is a harness and a runner, and the knowledge it executes lives in a repository you can fork and extend. If a vendor ships a new Bluetooth flaw, adding it to the framework means writing a YAML template and a hardware profile, not modifying the runner. The reverse also holds: an upgrade of the templates repository can add exploit coverage without touching the code you have installed. It also means the framework's own version number tells you little about coverage. The listed release is `woot-artifact-eval` from 2025-06-10, a tag named after the research artifact rather than a numbered release, so the meaningful question about which exploits a given install supports is answered by the templates, not by the tag. ## Installing on bare metal or in a VirtualBox VM driven by Vagrant BlueToolkit can be installed on bare metal Ubuntu and Debian systems, which the README calls the recommended route, or using a virtual machine. The normal installation is three commands: ```sh git clone https://github.com/sgxgsx/BlueToolkit chmod +x ./BlueToolkit/install.sh sudo ./BlueToolkit/install.sh [-dev] ``` The `[-dev]` flag is optional according to the way it is written, and the sudo is needed because the installer sets up the tools that talk to Bluetooth adapters. The installer also prompts to install the specific modules for Braktooth and BluetoothAssistant, which require specific hardware devices to be available and plugged in. Standalone modules can also be installed separately by running the installer again, which is useful when you are adding hardware later and do not want to reinstall everything. The virtual machine route is a different shape. It needs VirtualBox and Vagrant as prerequisites, and the clone pulls submodules from the start: ```sh git clone https://github.com/sgxgsx/BlueToolkit --recurse-submodules cd BlueToolkit/vagrant vagrant up ``` The USB pass-through step is the part people miss. After installation, the virtual machine has to be given access to the Bluetooth module or additional hardware through USB. The instructions spell out the click path: USB support is already switched on, so open VirtualBox, find a running virtual machine and click Show, then click Devices and USB. You are presented with multiple devices that you can switch on for the virtual machine, and you tick the ones you need, the Bluetooth module, hardware or a phone, or tick all of them to be sure. That last option is a reasonable default given how many of the checks need a second radio. The framework needs to act as one Bluetooth device against another, so the target and the tool have to be distinct radios, and a VM cannot see the host's adapter unless it is passed through. The README points to a wiki for more documentation than the repository itself carries. ## The bluekit command line and how to scope a run The tool is driven by a single command, `bluekit`, and the README shows the usage output it prints for the help flag. The beginning of that output reads: ```console usage: bluekit [-h] [-t TARGET] [-l] [-c] [-ct] [-ch] [-v VERBOSITY] [-ex EXCLUDEEXPLOITS [EXCLUDEEXPLOITS ...]] [-e EXPLOITS [EXPLOITS ...]] [-r] [-re] [-rej] [-hh HARDWARE [HARDWARE ...]] ... positional arguments: rest options: -h, --help show this help message and exit -t TARGET, --target TARGET target MAC address -l, --listexploits List exploits or not ``` The target is a MAC address, and every action other than listing exploits is scoped to one. The listing itself needs no root, which the README notes, and that is a good first command to run because it tells you what the installed templates actually cover. Three flags cover the three modules. `-r` runs a recon script, `-re` creates a report for a target device, and `-rej` creates a report for a target device in JSON. There is also `-ct` to check connectivity and availability of the target, and `-ch` to start from a checkpoint, which is the mechanism for resuming a long run rather than starting over. The scoping flags are where the design pays off, because a full run against a device is a long sequence of active tests. `-e` scans only for the exploits you list, and the usage text is explicit that `--exclude` is not taken into account when `--exploits` is used. `-ex` excludes exploits, `-hh` scans only exploits based on the hardware you name, and again `--exclude` and `--exploit` are not taken into account. So the three scoping mechanisms are alternatives rather than filters that compose, which is a rough edge but a clear one, since it means the effective set of checks is always predictable once you pick a mode. The README gives four worked examples: listing all available exploits with no root required, running recon, testing connectivity, and testing one or more exploits by space separated name. ## Some checks need a specific board, and one swap costs you two exploits The hardware section is short and it is where the framework's practicality is decided, because you cannot run every check with a generic adapter. Some attacks require specific hardware. An ESP-WROVER-KIT-VE is needed for the Braktooth vulnerabilities. A Nexus 5 phone is needed for Internalblue, and the README is candid about the substitution: it could be replaced with a CYW20735, but two exploits will not work and it would need a new hardware profile. A CYW920819M2EVB-01 is needed for the BIAS, BLUR and BLUFFS attacks. That Nexus 5 line is worth pausing on, because it shows the shape of the whole framework. A check is not just a script, it is a script plus a hardware profile, and the profile encodes the behaviour of a particular radio. Swapping the radio changes the behaviour, so the check that relied on a particular quirk of that phone no longer applies, and the two affected exploits are removed rather than approximated. This is a real constraint on adoption. Braktooth, Internalblue, BIAS, BLUR and BLUFFS are among the best known Bluetooth Classic attacks, and the ones that get the most attention in a security review are exactly the ones that need a specific board. A researcher with a generic adapter and one target device can run the template checks that do not need special hardware, and that is a meaningful subset given 43 templates, but the headline protocol attacks need the shopping list above. The hardware profile mechanism is what makes this workable rather than brittle. Because profiles are data, a new radio can be described in YAML and added to the templates repository, and a check that depends on a quirk of the original board can be marked as requiring it. The cost is that a check without a matching profile simply cannot run, and the README gives no hint about which of the 43 fall into that group. The installer knows about this too, since it prompts to install the specific modules for Braktooth and BluetoothAssistant on the basis that those require specific hardware to be available and plugged in. ## The automotive evaluation and the collected vulnerability catalogue The README reports an evaluation of BlueToolkit on 22 cars from different vendors, naming Audi, BMW, Chevrolet, Honda, Hyundai, Mercedes-Benz, Mini, Opel, Polestar, Renault, Skoda, Toyota, VW and Tesla, and states that it uncovered 128 vulnerabilities, with the evaluation README in the `evaluation/` directory of the repository carrying the detail. That number is the framework's most concrete evidence of usefulness, and it is also the reason to read it with care. A single run of 43 checks against 22 devices will produce findings that vary in severity and in how much they say. Some are protocol implementation weaknesses that are genuinely interesting; others are configuration observations that a device owner would treat as trivial. The evaluation directory exists to let a reader separate those, and the framework's own report module exists to give the findings structure. The second body of work is a catalogue. The README says the project collected and classified Bluetooth vulnerabilities in an Awesome Bluetooth Security way, and lists the sources used: ACM, IEEE SP, Blackhat, DEFCON, Car Hacking Village, NDSS and Google Scholar, with the search engines used including Google, Baidu, Yandex and Bing, and the keyword set beginning with terms such as Bluetooth security toolkit and Bluetooth exploit. So the repository carries three things rather than one: a runner, a set of templates, and a curated index of published Bluetooth research. The index is worth having on its own, since the tooling ecosystem for Bluetooth security is scattered across conference proceedings and conference papers. The work led to a research paper accepted at WOOT 25. There is a separate repository for demonstrating how to hijack online accounts via MAP for already established connections or with a MitM position, which is linked from the README as related work rather than as part of the toolkit. One caveat on all of this. The paper link in the README is a placeholder that reads add missing link when we have it, so the citation for the underlying research is not actually in the repository, and the evaluation is described as covering 22 cars, which is a sample of a product line rather than of a model year, so the per-vendor findings are not necessarily representative of every model in the range. ## Conclusion Adopt BlueToolkit if you are assessing Bluetooth Classic or BLE devices and want a repeatable, template-driven workflow with machine readable output rather than a pile of ad hoc scripts. Do not adopt it as a general scanner, because it is semi-automated and several checks need specific hardware, so check first that the board you own matches one of the documented profiles, since the Internalblue checks call for a Nexus 5 and swapping in a CYW20735 leaves two exploits non-functional. ## FAQ ### What are the three modules of BlueToolkit? Recon gathers Bluetooth capabilities and security configuration, Exploit executes tests for currently 43 public exploits covering MitM, RCE, DoS and others, and Report generates structured machine- and human-readable JSON reports. ### How do I install BlueToolkit? Clone the repository, make install.sh executable and run it with sudo. The installer will prompt to install the specific modules for Braktooth and BluetoothAssistant, which need particular hardware plugged in, and standalone modules can be installed later by running the installer again. ### What hardware does BlueToolkit need for specific attacks? An ESP-WROVER-KIT-VE for the Braktooth vulnerabilities, a Nexus 5 for Internalblue, and a CYW920819M2EVB-01 for the BIAS, BLUR and BLUFFS attacks. The README notes that a CYW20735 can replace the Nexus 5 but two exploits will not work and a new hardware profile would be needed. ### How do I add my own exploit to BlueToolkit? The vulnerability and hardware templates live in a separate templates repository that BlueToolkit downloads automatically, and the README says you can write your own templates and checks and add new hardware by following the templating guide, with the YAML reference syntax documented separately. ### Can BlueToolkit be used in a virtual machine? Yes. The README describes a Vagrant based setup using Virtualbox, with the clone using --recurse-submodules and vagrant up in the vagrant directory. You then need to pass the Bluetooth module or other hardware through to the virtual machine via the VirtualBox Devices and USB menu. ### Is BlueToolkit still being maintained? The repository is not archived and the last push was on 2026-08-23. The only listed release is the tag woot-artifact-eval from 2025-06-10, named after the research artefact rather than a numbered version, and the licence is a custom one GitHub cannot classify. ## Sources - [Issues](https://github.com/sgxgsx/BlueToolkit/issues) - [README](https://github.com/sgxgsx/BlueToolkit/blob/main/README.md) - [Releases](https://github.com/sgxgsx/BlueToolkit/releases) - [sgxgsx/BlueToolkit on GitHub](https://github.com/sgxgsx/BlueToolkit) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sgxgsx-bluetoolkit