TarlogicSecurity · sidinsearch · Jul 16, 2025 · Jul 16, 2025 · Jul 16, 2025 · Jul 16, 2025
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Siddharth Shinde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,69 +1,83 @@
-# BlueSpy - PoC to record audio from a Bluetooth device
+# BlueWave - Bluetooth Audio Analysis Tool
 
-![BlueSpy script](resources/BlueSpy.png)
+![BlueWave Screenshot](screenshot.png)
 
-This repository contains the implementation of a proof of concept to record and replay audio from a bluetooth device without the legitimate user's awareness.
+## Overview
 
-The PoC was demonstrated during the talk **BSAM: Seguridad en Bluetooth** at **RootedCON 2024** in Madrid.
+BlueWave is an enhanced version inspired by [BlueSpy](https://github.com/TarlogicSecurity/BlueSpy), with added features such as a Web UI for more accessible control and monitoring of Bluetooth devices. This PoC tool is designed to demonstrate vulnerabilities that allow unauthorized pairing and audio recording from Bluetooth devices.
 
-It's designed to raise awareness about the insecure use of Bluetooth devices, and the need of a consistent methodology for security evaluations. That's the purpose of **BSAM, the Bluetooth Security Assessment Methodology**, published by Tarlogic and available [here](https://www.tarlogic.com/bsam/).
+The PoC was showcased during the **BSAM: Seguridad en Bluetooth** talk at **RootedCON 2024** in Madrid. Its main goal is to raise awareness about insecure Bluetooth usage and promote the **Bluetooth Security Assessment Methodology (BSAM)**. More details can be found in the [BSAM publication](https://www.tarlogic.com/bsam/).
 
-This proof of concept exploits the failure to comply with the [**BSAM-PA-05 control**](https://www.tarlogic.com/bsam/controls/bluetooth-pairing-without-interaction/) within the BSAM methodology. Consequently, the device enables the pairing procedure without requiring user interaction and exposes its functionality to any agent within the signal range.
+## Key Features
 
-More information on our [blog](https://www.tarlogic.com/blog/bluespy-spying-on-bluetooth-conversations/).
+- **Web Interface**: Seamless Bluetooth management through a user-friendly web UI.
+- **Device Discovery**: Scan and find nearby Bluetooth devices.
+- **Pairing and Connection**: Exploits vulnerabilities in the Bluetooth pairing process.
+- **Audio Recording and Playback**: Captures audio from Bluetooth devices and allows replay.
 
-## Requirements
+## System Requirements
 
-The code is written in Python and has been tested with Python 3.11.8, but it mainly uses widely available tools in Linux systems.
+- Python 3.11.8
+- Linux system with the BlueZ Bluetooth stack
+- PulseAudio-compatible audio server (e.g., PipeWire)
 
-The PoC uses the following tools:
-+ `bluetoothctl`
-+ `btmgmt`
-+ `pactl`
-+ `parecord`
-+ `paplay`
+## Tools Used
 
-In Arch Linux distributions, `bluetoothctl` and `btmgmt` can be installed with the package `bluez-utils`, while `pactl`, `parecord` and `paplay` are available in the `libpulse` package.
-
-For the PoC to work, it is necessary to have a working installation of the BlueZ Bluetooth stack, available in the `bluez`package for Arch Linux distributions. A working installation of an audio server compatible with PulseAudio, such as PipeWire, is also required to record and play audio.
+- `bluetoothctl` for device interaction
+- `btmgmt` for Bluetooth management
+- `pactl`, `parecord`, `paplay` for audio control and playback
+- `Flask` for the Web Interface
 
 ## Setup
 
-Ensure that your device is capable of functioning as an audio source, meaning it has a microphone, and that it is discoverable and connectable via Bluetooth.
+1. Ensure that the target Bluetooth device is discoverable and connectable.
+2. Verify that your system has a functioning BlueZ Bluetooth stack and a PulseAudio-compatible audio server.
 
-For instance, to be discoverable and connectable, the earbuds used during the talk must be outside of their charging case. By default, they only activate the microphone when placed in the user's ears, although this setting can be adjusted in the configuration app.
+## Installation
 
-Additionally, ensure that the device is not already connected, or alternatively, that it supports multiple connections.
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/sidinsearch/BlueWave.git
+   cd BlueWave
+   ```
 
-## Execution
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
 
-Firstly, the address of the device must be discovered using a tool such as `bluetoothctl`:
+3. Run the Web UI:
+   ```bash
+   flask run
+   ```
 
-```
-$ bluetoothctl
+## Execution
+
+To discover the device address:
+```bash
+bluetoothctl
 [bluetooth]# scan on
 ```
 
-Once the address of the device is discovered, the script can handle the rest:
-
-```
-$ python BlueSpy.py -a <address>
+To start BlueWave:
+```bash
+python BlueSpy.py -a <device_address>
 ```
 
-Note: The script might prompt for superuser permissions to modify the configuration of your **BlueZ** instance and pair it with the remote device.
+Superuser permissions may be required to modify the BlueZ configuration.
 
 ## Troubleshooting
 
-`BlueSpy.py` is the main script that executes every step of the process. However, if you encounter issues with any of the phases, so it might be helpful to execute them individually:
-+ `pair.py` utilizes the command-line tool `btmgmt` to modify the configuration of your **BlueZ** and initiate a pairing process with the remote device. The exact commands used are in the `pair` function inside `core.py`.
-+ `connect.py` utilizes the command-line tool `bluetoothctl` to initiate a quick scan (necessary for BlueZ) and establish a connection to the device. The exact commands used are in the `connect` function inside `core.py`.
-+ `just_record.py` utilizes the command-line tools `pactl` and `parecord` to search for the device in the system's audio sources (it must function as a microphone) and initiate a recording session. The exact commands used are in the `record` function inside `core.py`.
-+ The `playback` function inside `core.py` executes `paplay` to play back the captured audio.
+If issues arise:
+- Check the individual scripts like `pair.py`, `connect.py`, and `just_record.py`.
+- Run commands manually for debugging as detailed in `core.py`.
 
-If you encounter issues with any of the phases, examine the commands in `core.py` and try to execute them in a shell. This will provide more information on what may be failing.
+## References and Further Reading
 
-## References
+- [BSAM: Bluetooth Security Assessment Methodology](https://www.tarlogic.com/bsam/)
+- [BlueSpy Blog Post](https://www.tarlogic.com/blog/bluespy-spying-on-bluetooth-conversations/)
+- [Original BlueSpy Project](https://github.com/TarlogicSecurity/BlueSpy)
 
-If you have any questions regarding how the Bluetooth standard operates or how to assess the security of a Bluetooth device, please refer to our BSAM methodology webpage:
-+ [BSAM: Bluetooth Security Assessment Methodology](https://www.tarlogic.com/bsam/)
+## License
 
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
diff --git a/WEB_INTERFACE.md b/WEB_INTERFACE.md
@@ -0,0 +1,53 @@
+# BlueSpy Web Interface
+
+This is a web-based GUI for the BlueSpy application, which allows you to record audio from Bluetooth devices.
+
+## Features
+
+- Scan for Bluetooth devices
+- Connect to devices
+- Record audio
+- Manage recordings (play, download, delete)
+- View logs
+
+## Requirements
+
+- Python 3.11 or higher
+- Flask
+- All the requirements for the BlueSpy application
+
+## Installation
+
+1. Make sure you have all the required dependencies installed:
+
+```bash
+pip install flask
+```
+
+2. Ensure that your system has the necessary Bluetooth tools installed as mentioned in the main README.md.
+
+## Usage
+
+1. Start the web interface:
+
+```bash
+python app.py
+```
+
+2. Open your web browser and navigate to `http://localhost:5000`
+
+3. Use the interface to:
+   - Scan for Bluetooth devices
+   - Connect to a device
+   - Start/stop recording
+   - Manage your recordings
+
+## Troubleshooting
+
+- If you encounter issues with scanning or connecting to devices, ensure that your Bluetooth adapter is working correctly.
+- Check the logs in the web interface for error messages.
+- For more detailed troubleshooting, refer to the main README.md file.
+
+## Security Considerations
+
+This web interface is intended for local use only. Do not expose it to the internet without proper security measures in place.