Learn what a malicious USB device can do in seconds — so you never plug one in blindly.
A USB stick found in a parking lot, a conference giveaway, or a charging port at the airport might look harmless. In reality, devices like BadUSB, Rubber Ducky, and HID keyboard injectors can act as a keyboard the moment they are plugged in — typing commands faster than a human ever could, with no user interaction required.
GoodUSB is an educational cybersecurity project that recreates this attack chain in a controlled, visible way. It is designed to:
- Show students, coworkers, and the public how fast and silent a USB-based attack can be
- Demonstrate common post-exploitation techniques (ransomware simulation, keylogging, audio capture, security bypass)
- Encourage safe habits: never plug in unknown USB devices, use USB data blockers, and enable device authorization policies
Watch the full demonstration: YouTube — GoodUSB Demo
The project uses an Arduino Leonardo (or any board with native USB HID / Keyboard.h support) programmed to emulate a keyboard. Within seconds of insertion, it automatically:
| Step | Action | What It Teaches |
|---|---|---|
| 1 | Launches an animated face overlay (face.py) |
Social engineering / distraction techniques |
| 2 | Displays scrolling text messages (text.py) |
How attackers communicate or misdirect users |
| 3 | Runs system information collection (info.ps1) |
Reconnaissance — gathering host details |
| 4 | Opens the target/ folder and runs fake ransomware |
How ransomware encrypts files in plain sight |
| 5 | Triggers a visual glitch effect (virus.ps1) |
Psychological impact / denial-of-service demos |
| 6 | Captures keystrokes (Keylogger.py) |
Credential and message theft |
| 7 | Records microphone audio (micSpy.py) |
Audio surveillance risk |
| 8 | Attempts to disable Windows Defender & Firewall | How malware tries to evade protection |
All of this runs without the user clicking anything — exactly like a real BadUSB attack.
GoodUSB/
├── Arduino scripts/ # HID keyboard payloads (upload to Arduino Leonardo)
│ └── FINAL.txt # Main orchestration script
├── scripts/ # Python demonstration tools
│ ├── face.py # Animated character overlay (tkinter + GIFs)
│ ├── text.py # Scrolling text display
│ ├── fake_ransomware.py # AES encryption simulator (reversible)
│ ├── Keylogger.py # Keystroke capture demo
│ └── micSpy.py # Microphone recording demo
├── powershell/ # Windows automation scripts
│ ├── info.ps1 # System information gathering
│ ├── virus.ps1 # Visual glitch effect simulator
│ └── security_status_v2.ps1 # Security toggle demo (admin)
├── target/ # Sample "victim" files for ransomware demo
├── GIFs/ # Animation assets for face.py
├── requirements.txt # Python dependencies
├── SETUP_GUIDE.md # Installation & troubleshooting
├── CHANGELOG.md # Version history
└── README_V2.md # Detailed technical documentation
| Component | Purpose |
|---|---|
| Arduino Leonardo (or Pro Micro, Digispark) | USB HID keyboard emulation via Keyboard.h |
| USB cable | Connects the device to the target machine |
| Windows 10/11 PC | Target system (scripts are Windows-focused) |
The Arduino must support native USB HID. Arduino Uno/Nano (ATmega328P without USB HID) will not work for this project.
pip install -r requirements.txtBefore running, update hardcoded paths in:
Arduino scripts/FINAL.txt— script paths on the target machinescripts/face.py— path to theGIFs/folder
Replace example paths like C:\Users\NITRO\Desktop\GOOD USB\ with your actual project location.
Copy the included target/ folder to the target machine's Desktop, or let fake_ransomware.py create it automatically. It contains sample documents used during the encryption demonstration.
- Open
Arduino scripts/FINAL.txtin the Arduino IDE - Select Arduino Leonardo as the board
- Upload the sketch
- The device is now a pre-programmed USB attack payload
# Test ransomware simulator (encrypts files in target/)
python scripts/fake_ransomware.py
# Run again to decrypt
python scripts/fake_ransomware.py# Test glitch effect (no admin required)
.\powershell\virus.ps1See SETUP_GUIDE.md for full installation and troubleshooting.
The project includes a video walkthrough showing the complete attack chain from USB insertion to final payload execution:
After seeing this demo, here are practical defenses:
- Never plug in unknown USB devices — treat found drives like found hypodermic needles
- Use USB data blockers (charge-only adapters) when charging in public
- Disable auto-run and require admin approval for new devices
- Enable Device Guard / USB restrictions in enterprise environments (Group Policy)
- Keep Windows Defender and Firewall enabled — the demo shows how attackers try to disable them
- Educate others — share this project in security awareness training
⚠️ EDUCATIONAL USE ONLY
This project is intended exclusively for:
- Cybersecurity education and awareness training
- Authorized penetration testing on systems you own
- Security research in isolated lab environments
Unauthorized use on systems you do not own or have explicit written permission to test may violate computer fraud and abuse laws in your jurisdiction.
- Do not deploy this on public machines, school networks, or employer systems without authorization
- Do not use this project to harm, extort, or spy on others
- All payloads are reversible and designed for demonstration, not real damage
You are solely responsible for how you use this software.
v2.0 — Enhanced UI, AES encryption, progress bars, logging, and comprehensive documentation.
See CHANGELOG.md and README_V2.md for full technical details.
Van Cipher Restricted License v1.0 — see LICENSE.
You may read this repo on GitHub for learning. Any use, deployment, fork-for-use, or redistribution requires written permission from Abdullah Y. Habash (@vancipher). Contact via GitHub or cyberxsec.me.
Made for cybersecurity education
If this project stops one person from plugging in a random USB drive — it did its job.