USB-Defender

A cross-platform security ecosystem for real-time USB malware detection, quarantine, AI-powered analysis, and beautiful visualization.

USB-Defender protects you from malicious files hiding in USB drives. It comes in two interconnected parts:

1. The Desktop App (Command Center): A sleek, modern GUI that lives on your PC. It auto-detects USB insertion, runs background scans, and provides a beautiful dashboard to manage quarantined files.
2. The Portable Scanner: A standalone, zero-dependency executable that lives on the USB drive itself, protecting the drive when you plug it into other people's untrusted machines.

---

Features

1. The Desktop Command Center (Tauri + React + Python)

• Zero-Click Auto-Scan: Automatically detects when a USB drive is plugged in and scans it silently in the background.
• Beautiful Dashboard: Real-time threat feed, severity distribution charts, and historical logs.
• Quarantine Vault: Safely decrypt and restore files that were mistakenly flagged, right from the UI.
• "Arm USB" Button: One-click deployment of the Portable Scanner directly to your USB drive.

2. The Portable USB Engine

• True Portability: Native binaries for Windows (.exe) and Linux (ELF), plus a zero-dependency Python fallback. No installation required on the target machine.
• Gemini AI Threat Verification: Uses Google's Gemini 2.5 Flash to act as a cybersecurity analyst, analyzing flagged files to verify if they are truly malicious or just false positives (like developer scripts).
• Safe XOR Quarantine: High-severity threats are instantly neutralized using Symmetric XOR Encryption, preventing accidental execution.
• Developer-Friendly Heuristics: Automatically ignores .git and node_modules to eliminate false positives on development projects.

---

Architecture

graph TD
    subgraph "Your PC (Installed Desktop App)"
        A[Tauri Desktop App] --> B[React Dashboard]
        A --> C[Python API Sidecar]
        C --> D[USB Auto-Detector]
        D -->|USB Plugged In| E[Auto-Scan Engine]
        E --> F[Quarantine Vault]
        E --> G[SQLite Database]
        B -->|WebSocket| C
    end

    subgraph "Any PC (Portable Mode)"
        H[USB Drive] --> I[usb-defender-portable]
        I --> J[Scan USB Root]
        J --> K[Terminal Report + Quarantine]
    end

Loading

---

Installation & Usage

Option 1: The Desktop App

Download the installer for your platform from the Releases page.

• Windows: Download and run the .msi installer.
• Linux: Download the .deb, .rpm, or .AppImage.
• macOS: Download the .dmg — aarch64 for Apple Silicon, x86_64 for Intel.

Once installed, simply open USB Defender and plug in a USB drive!

Unsigned builds: the installers are not code-signed, so Windows SmartScreen shows "unrecognised app" (More info → Run anyway) and macOS Gatekeeper blocks first launch (right-click → Open, or xattr -d com.apple.quarantine "/Applications/USB Defender.app").

Where your data lives

Logs, the SQLite database, your quarantine records and your edited signature rules are stored per-user, outside the application bundle:

Platform	Location
Linux	~/.local/share/usb-defender (or $XDG_DATA_HOME/usb-defender)
Windows	%APPDATA%\USB Defender
macOS	~/Library/Application Support/USB Defender

Set USB_DEFENDER_DATA_DIR to override.

Option 2: The Portable Scanner

If you just want to protect a specific USB drive:

1. Open the Desktop App and go to the Scanner tab.
2. Select your USB drive and click "Arm USB".
3. Alternatively: Download the portable binaries from the Releases page and copy them to the root of your USB drive manually.

Using the Portable Scanner on a friend's PC:

• Windows: Double-click USBDefender.exe or run scan.bat.
• Linux: Run ./usb-defender-linux or ./scan.sh.
• Any OS: Run python3 usb_defender_portable.py.

The scanner will present an interactive terminal menu allowing you to scan the drive, use Gemini AI, or restore quarantined files.

---

Development Setup

Want to build USB-Defender from source?

1. Clone the repository:

git clone https://github.com/ZyAzOsK/USB-defender.git
cd USB-defender

2. Setup the Python API Sidecar:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Build the sidecar binaries (required — tauri.conf.json declares both in externalBin, so the Tauri build fails without them):

./scripts/build_sidecar.sh        # Linux / macOS
scripts\build_sidecar.bat         # Windows

This produces usb-defender-api and usb-defender-portable, appends the host target triple, then smoke-tests the API sidecar — verifying it serves /api/status, completes a WebSocket upgrade on /ws/monitor, and resolves its data directory outside the PyInstaller temp dir.

4. Run the Desktop App (Development Mode):

cd dashboard
npm install
npm run tauri dev

5. Run the tests:

python -m pytest app/tests -v
python scripts/bump_version.py --check   # all version strings agree

Cutting a release:

python scripts/bump_version.py 1.0.4     # updates all 5 version declarations
git commit -am "release: v1.0.4" && git tag v1.0.4 && git push --tags

CI refuses to publish if the tag and tauri.conf.json disagree.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.