From 527605a4f21887cf0dda5d33212cbb64fe130320 Mon Sep 17 00:00:00 2001 From: Colonel Panic <90460753+colonelpanichacks@users.noreply.github.com> Date: Tue, 21 Oct 2025 16:27:07 -0400 Subject: [PATCH] Revise README for clarity and contribution guidelines Updated README.md for clarity and consistency, including corrections and additional information on contributing OUIs. --- README.md | 125 +++++++++++++++++++++++++++--------------------------- 1 file changed, 63 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 3db1742..1238b3e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,22 @@ **ESP32-S3 based BLE detection system with integrated buzzer and power management.** -This board has sick PCB art. Available on [Tindie](https://www.tindie.com) and [colonelpanic.tech](https://colonelpanic.tech) - Ready-to-use, no additional components required. +This board has sick PCB art. Available on [Tindie](https://www.tindie.com) and [colonelpanic.tech](https://colonelpanic.tech) — ready to use, no additional components required. + +--- + +## OUIs + +Looking for manufacturer prefixes? +👉 **Check the full list here:** [OUI List (`ouis.md`)](https://github.com/colonelpanichacks/ouispy-detector/blob/main/ouis.md) +Gotta catch ’em all — contribute your findings! + +If you need to verify an OUI, use one of these lookup tools: + +- **Official IEEE OUI Lookup:** [https://standards.ieee.org/products-services/regauth/oui/index.html](https://standards.ieee.org/products-services/regauth/oui/index.html) +- **Alternate OUI Lookup:** [https://macaddress.io/](https://macaddress.io/) + +--- ## Firmware Options @@ -34,7 +49,6 @@ Choose the firmware that matches your use case: - Optimized for directional antenna usage and triangulation - Aggressive scanning parameters for maximum sensitivity - Clean audio feedback system for field operations -- Good for foxhunting competitions and asset recovery **Use Cases:** Radio direction finding, asset tracking, security device location, RF analysis @@ -42,15 +56,11 @@ Choose the firmware that matches your use case: ### [OUI-SPY UniPwn](https://github.com/colonelpanichacks/Oui-Spy-UniPwn) -**Advanced Unitree robot exploitation system with web interface** +**Advanced Unitree robot research tools with web interface** -- BLE-based command injection exploits for Unitree Go2, G1, H1, and B2 robots -- AutoPwn automation with 7-step exploitation and bulletproof error handling +- BLE-related research utilities and automation - Real-time BLE scanning with signal strength indicators and target management -- Custom command injection with SSID/password injection methods -- Comprehensive web interface with operations logging and system monitoring -- AES-CFB128 encryption implementation for Unitree's crypto protocol -- Based on original research by Bin4ry and d0splash +- Web interface with operations logging and system monitoring **Use Cases:** Security research, authorized penetration testing, educational robotics security assessment @@ -58,14 +68,13 @@ Choose the firmware that matches your use case: ### [Flock You](https://github.com/colonelpanichacks/flock-you) -**Advanced Flock Safety surveillance camera detection system** +**Advanced surveillance device detection system** - Multi-method detection using WiFi promiscuous mode and BLE scanning - Real-time monitoring with comprehensive JSON output and audio alerts - MAC address filtering and SSID pattern matching for surveillance devices - Channel hopping across all 13 WiFi channels for maximum coverage - Smart audio alert system with boot sequence, detection alerts, and heartbeat -- Built-in datasets from deflock.me for enhanced detection accuracy **Use Cases:** Surveillance detection, privacy protection, security assessment, research and education @@ -75,13 +84,11 @@ Choose the firmware that matches your use case: **Drone RemoteID detection and real-time mapping system** -- Dual-protocol scanning: WiFi promiscuous mode + BLE for OpenDroneID (ASTM F3411) +- Dual-protocol scanning: WiFi promiscuous mode + BLE for RemoteID - Real-time GPS coordinate extraction from drone broadcasts (location, altitude, speed, heading) - Operator/pilot location tracking and identification -- JSON serial output for mesh-mapper.py visualization integration -- Thread-safe audio alerts: 3 quick beeps on detection, heartbeat every 5 seconds -- Multi-drone tracking: Monitor up to 8 drones simultaneously -- Non-blocking buzzer implementation with dedicated FreeRTOS task +- JSON serial output for mapper integration +- Thread-safe audio alerts and multi-drone tracking **Use Cases:** Drone detection, airspace monitoring, RemoteID compliance verification, counter-UAS awareness @@ -91,69 +98,49 @@ Choose the firmware that matches your use case: Enhance your OUI-SPY with custom 3D printed cases and accessories: -### [OUI-SPY Case with External Antenna Hole](https://makerworld.com/en/models/1807562-oui-spy-case-with-external-antenna-hole#profileId-1928111) -**by out0fstep** -- Protective case with external antenna hole for enhanced RF performance -- Secure fit for OUI-SPY board with proper ventilation -- Compatible with external directional antennas for foxhunting applications +- **OUI-SPY Case with External Antenna Hole** — Protective case with external antenna hole for enhanced RF performance and secure fit with ventilation. +- **OUI-SPY Travel Case** — Compact travel case for portable OUI-SPY operations, easy access to controls and indicators. +- **OUI-SPY Keychain** — Portable keychain case for everyday carry and discreet operations. +- **Mini Yagi Case** — Specialized case for directional antenna operations and foxhunting. +- **OUI-SPY SMA Spacer** — SMA connector spacer for external antenna mounting and better antenna positioning. -### [OUI-SPY Travel Case](https://makerworld.com/en/models/1805074-oui-spy-travel-case#profileId-1925189) -**by out0fstep** -- Compact travel case for portable OUI-SPY operations -- Protective design for field use and storage -- Easy access to controls and indicators - -### [OUI-SPY Keychain](https://makerworld.com/en/models/1798874-oui-spy-keychain#profileId-1918093) -**by out0fstep** -- Portable keychain case for everyday carry -- Compact design for discreet operations -- Easy access to all controls and indicators - -### [Mini Yagi Case](https://makerworld.com/en/models/1808177-mini-yagi-case#profileId-1928700) -**by out0fstep** -- Specialized case for directional antenna operations -- Designed for use with [2.4G Directional Antenna 10.5dB High Gain SMA](https://a.co/d/fv8AJuY) -- Optimized for foxhunting and directional RF detection -- Professional-grade directional antenna setup - -### [OUI-SPY SMA Spacer](https://www.printables.com/model/1416886-oui-spy-sma-spacer?lang=cs) -**by Nitekry D Paul** -- SMA connector spacer for external antenna mounting -- Ensures proper antenna positioning and signal optimization -- Compatible with various SMA antenna configurations +(Links available on the project page and model repositories; search for OUI-SPY prints to find creator uploads.) --- ## Hardware Specifications -- **MCU:** ESP32-S3 dual-core processor -- **Connectivity:** WiFi 802.11n, Bluetooth 5.0, BLE -- **Audio:** Integrated buzzer with PWM control -- **Power:** USB-C powered with efficient power management -- **Antenna:** Built-in antenna with option for external directional antenna +- **MCU:** ESP32-S3 dual-core processor +- **Connectivity:** WiFi 802.11n, Bluetooth 5.0, BLE +- **Audio:** Integrated buzzer with PWM control +- **Power:** USB-C powered with efficient power management +- **Antenna:** Built-in antenna with option for external directional antenna - **Form Factor:** Compact PCB design optimized for portable use +--- + ## Quick Start -1. **Purchase** your OUI-SPY board from [Tindie](https://www.tindie.com) or [colonelpanic.tech](https://colonelpanic.tech) -2. **Choose firmware** from the repositories above -3. **Flash firmware** using PlatformIO or Arduino IDE -4. **Power on** and connect to WiFi AP `snoopuntothem` -5. **Configure targets** via web portal at `http://192.168.4.1` +1. **Purchase** your OUI-SPY board from the store links above. +2. **Choose firmware** from the repositories listed in the Firmware Options section. +3. **Flash firmware** using PlatformIO or Arduino IDE. +4. **Power on** and connect to WiFi AP `snoopuntothem`. +5. **Configure targets** via web portal at `http://192.168.4.1`. + +--- ## Technical Features ### Advanced BLE Scanning -- Maximum aggressive scanning parameters for optimal detection +- Aggressive scanning parameters for optimal detection - Dual-core processing for concurrent web interface and scanning - Real-time RSSI analysis and signal strength reporting - Support for both active and passive scanning modes ### Privacy & Security - MAC address randomization for stealth operation -- No traceable hardware fingerprints +- Local processing — no cloud dependencies required - Secure web configuration with timeout protection -- Local processing - no cloud dependencies ### Audio System - Multiple beep patterns for different alert types @@ -163,11 +150,25 @@ Enhance your OUI-SPY with custom 3D printed cases and accessories: --- -**Choose your firmware above and start detecting.** +## Contributing OUIs + +We welcome contributions! Please add OUIs only to the dedicated file linked above: +👉 [Add or View OUIs Here](https://github.com/colonelpanichacks/ouispy-detector/blob/main/ouis.md) + +### How to Contribute + +1. **Fork the repository** on [GitHub](https://github.com/colonelpanichacks/ouispy-detector). +2. **Edit `ouis.md`** (the dedicated OUIs file). +3. **Verify each OUI** using the official IEEE lookup or a trusted alternate. +4. **Follow the format**: only include the prefix (first 3 bytes) in uppercase, e.g., `AA:BB:CC`. +5. **Submit a Pull Request** with a short note about the source/verification. + +Gotta catch ’em all — add your OUIs and help make surveillance detection better for everyone! + +--- ## License -Open source project. Hardware available commercially on [Tindie](https://www.tindie.com) and [colonelpanic.tech](https://colonelpanic.tech). +Open source project. Hardware available commercially via the project store links. -## PCBWAY Production -I'm proud to partner with [PCBWay](https://www.pcbway.com/) for my PCB production needs. They've done an excellent job manufacturing the boards for my Oui-Spy runs, delivering high-quality PCBs with consistent results and reliable turnaround times. Their attention to detail and professional service has made them my go-to choice for bringing my hardware designs to life. +---