NRSuite

NRSuite is an Android companion app paired with custom ESP32 firmware, built to bring Wi-Fi and BLE security research tooling into a fast, portable phone-based workflow - no laptop required.

It connects to any ESP32 dev board flashed with NRSuite firmware over USB-OTG (serial), and drives it as a Wi-Fi/BLE offense and defense platform.

Authorized use only. NRSuite is for security research and testing on networks and devices you own or are explicitly authorized to test. See LEGAL.md.

• Features
• Installation
• Getting Started
• Requirements
• Building from Source
• Wire Protocol
• Screenshots
• Hardware Images
• Contributing
• Related Repos
• Versioning
• License

The following modules appear in the app as disabled ("Unavailable") placeholder cards, reserving their place in the catalog ahead of firmware support:

• IR (infrared transmit/receive)
• RF (Sub-GHz)
• RFID/NFC

For a full status and roadmap breakdown across every phase, see FEATURES.md.

1. Download the latest nrsuite-vX.X.X-beta.apk from Releases.
2. Verify the SHA256 checksum listed in the release notes before installing:

   # Linux / macOS
   sha256sum nrsuite-vX.X.X-beta.apk
   
   # Windows (PowerShell)
   certutil -hashfile nrsuite-vX.X.X-beta.apk SHA256

3. Enable Install from unknown sources on your device if needed - Settings → Security.
4. Install the APK.

git clone https://github.com/7wp81x/nrsuite-android.git
cd nrsuite-android
./gradlew assembleDebug

Output: app/build/outputs/apk/debug/app-debug.apk

You can also open the project in Android Studio and sync Gradle - see Building from Source for prerequisites.

You also need an ESP32 dev board flashed with NRSuite firmware. Flash it directly from inside the app using the built-in flasher, or manually via PlatformIO - see nrsuite-firmware for supported boards and instructions.

1. Flash NRSuite firmware to your ESP32 - use the in-app flasher, or PlatformIO from nrsuite-firmware.
2. Connect your ESP32 to your phone via a USB-OTG cable.
3. Open NRSuite - the app auto-detects the connected device.
4. Grant USB host permission when prompted (one-time per device).
5. Select a module from the home screen and start testing.

• Android 8.0 (API 26) or higher
• USB-OTG support (required - the app uses USB host mode to communicate with the ESP32)
• USB-OTG cable or adapter

• Any ESP32 development board flashed with NRSuite firmware
• See nrsuite-firmware for supported boards and flashing instructions

• Android Studio Ladybug or newer (latest stable recommended)
• JDK 11 (bundled with Android Studio)
• Android SDK with API 36 (compileSdk) and API 26 (minSdk) installed

git clone https://github.com/7wp81x/nrsuite-android.git
cd nrsuite-android
./gradlew assembleDebug

Signed release APKs are published by the maintainer. For testing your own changes, the debug build is sufficient.

app/src/main/java/com/swp81x/nrsuite/
  core/
    ble/               # BLE scan/profile/tracker models and scan limits
    credentials/       # Credential storage models and store
    defense/           # Rogue AP / client-presence / hidden-AP / deauth-alert models, OUI heuristics
    eapol/             # EAPOL frame parser (for WPA handshake capture)
    flasher/           # ESP32 in-app flasher (SLIP codec, USB serial transport)
    history/           # Session history entries
    log/               # Log entry model (Logs screen, live module logs)
    oui/               # Offline OUI/vendor database (MAC Lookup, defense modules)
    pcap/              # Pcap file reader and writer
    protocol/          # Frame codec and NrJson wire protocol (shared with firmware)
    session/           # Connection state and NrSession manager
    sniff/             # Sniff request model
    storage/           # Mass storage models (ESP32 flash file browser)
    usb/               # USB serial transport, device catalog, NrTransport
    wifi/              # Pcap SSID parser
    wpa/               # WPA handshake parser, verifier, and cracker
  service/
    NrSuiteForegroundService.kt   # Foreground service keeping USB session alive
  ui/
    components/       # Reusable Compose components
    theme/            # Color, typography, theme
    NRSuiteApp.kt     # App entry point and module catalog
    NRSuiteContent.kt # Shell navigation, permission flow, screen dispatch
    HomeScreen.kt     # Dashboard, categories, module list
    LogsScreen.kt     # Logs and session history
    DeviceScreen.kt   # USB device selection and connection state
    SettingsScreen.kt # Settings and firmware flasher
    ModuleAvailability.kt # Shared "module unavailable on this board" banner/FAB gating
    RogueApScreen.kt / DeauthDetectorScreen.kt / ClientPresenceScreen.kt /
    HiddenApScreen.kt / TrackerDetectorScreen.kt   # Defense modules
    BleScannerScreen.kt / BleProfileScreen.kt / BleScreen.kt   # BLE recon + BLE HID
    MacLookupScreen.kt / SerialMonitorScreen.kt    # Tools / firmware utilities
    *Screen.kt        # Remaining feature module screens
  MainActivity.kt
  MainViewModel.kt               # Application-scoped controller
  MainViewModelUsb.kt            # USB discovery, permission, connection lifecycle
  MainViewModelFlasher.kt        # Firmware image selection and flashing
  MainViewModelWifi.kt           # Scan, deauth, beacon, sniff
  MainViewModelPortal.kt         # Captive Portal and Evil Twin
  MainViewModelBle.kt            # BLE HID
  MainViewModelBleScanner.kt     # BLE device discovery
  MainViewModelBleProfile.kt     # BLE GATT enumeration
  MainViewModelStorage.kt        # Mass storage, BadUSB, DuckyScript
  MainViewModelCredentials.kt    # Credential sessions and WPA cracking
  MainViewModelDefense.kt        # Shared defense-module plumbing
  MainViewModelRogueAp.kt        # Rogue AP Detector
  MainViewModelHiddenAp.kt       # Hidden AP Revealer
  MainViewModelClientPresence.kt # Client Detector
  MainViewModelTracker.kt        # Tracker Detector
  MainViewModelOui.kt            # MAC Lookup
  MainViewModelSerialMonitor.kt  # Serial Monitor
  NrSuiteApplication.kt

NRSuite uses a custom framing protocol (FrameCodec / NrJson) over USB serial between the app and the ESP32 firmware. The protocol spec is versioned separately in nrsuite-protocol so the app and firmware can evolve independently without silent breaking changes.

If your contribution touches any app ↔ firmware communication, update the protocol spec first and reference the spec version in your PR.

Home	Modules	Logs

Device Manager	WiFi Scan	Packet Sniffer

Deauth Detector	Rogue AP Detector	BLE Scanner

BadUSB	Credential Manager	Firmware Flasher

More screenshots in ./screenshots/.

USB hub + ESP32-S2	ESP32-S3 SuperMini

See CONTRIBUTING.md for the full guide: branching model, PR process, testing expectations, and legal/ethical scope boundaries.

Short version:

• Open an issue before starting any non-trivial feature.
• Branch from develop, not main.
• One feature or fix per PR.
• Test on real hardware for anything touching USB serial, the flasher, or module screens.
• Jamming features (RF/Wi-Fi/BLE denial-of-service transmission) will not be merged - see CONTRIBUTING.md.

This table is updated with each release. Always check compatibility before mixing app and firmware versions.

If you find a vulnerability in NRSuite itself (for example, a flaw in the mesh encryption scheme, credential storage, or the USB flasher), please report it privately rather than opening a public issue. See SECURITY.md.

MIT

This license covers redistribution of the code. It does not authorize use of the tool against systems you do not own or lack explicit permission to test. See LEGAL.md.

NRSuite is a tool for security research and authorized red-team operations, intended for legal and authorized security testing purposes only. Use of this software for any malicious or unauthorized activity is strictly prohibited. By downloading, installing, or using NRSuite, you agree to comply with all applicable laws and regulations. This software is provided free of charge; the developers assume no liability for any misuse. Use at your own risk. See LEGAL.md for full terms.