Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The USG is Good, not Bad
The USG is a firewall for your USB ports. It connects between your computer and an untrusted USB device, isolating the badness with an internal hardware firewall.
Why should I use a USG?
Say you just bought yourself a shiny new USB flash drive. You rip it out of the packaging and plug it straight into your computer. Oops, big mistake!
- Do you know who developed your flash drive's firmware? (It's probably not the company name printed on the packaging)
- Has the firmware been audited for backdoors and malicious functionality?
- Can you confirm that the firmware running on your drive hasn't been maliciously modified during or after manufacture?
If you can't answer 'yes' to all these questions, you should not trust that shiny new flash drive. Plugging it in gives full control of your computer to whoever wrote your drives' firmware.
The USG isolates BadUSB devices from your computer, while still passing through the data you need. The USG's firmware is fully open and auditable, so you can trust it. And when you use a USG, you no longer have to trust the opaque firmware of dubious origin running on every USB device you own.
Antivirus will not save you
Antivirus scanners cannot detect BadUSB because there is no virus to detect. Malicious USB commands reach directly into your USB driver stack, exploiting your computer before file-based scanners realise anything happened.
You can protect yourself from BadUSB by using virtualised operating systems such as Qubes. But the USG is the only plug-and-play BadUSB protection that does not require you to switch operating systems. It can even protect your legacy and embedded systems running out-of-date software.
You should be using a USG if...
- You care about the security of your computer, and you connect USB devices to it.
- You use Qubes OS with Anti Evil Maid on an external flash drive.
- You connect USB devices to embedded systems (network switches, medical equipment, uranium enrichment facilities...)
Get your own USG
The USG v1.0 is available now from the online store.
You can also build your own USG v0.9 from off-the-shelf development boards. Some assembly required.
Made in New Zealand
The USG is designed and assembled in New Zealand by a specialist in electronics, firmware, and secure technologies. To protect the integrity of this project the USG is manufactured locally, and production will never be outsourced to another country.
As the USG firmware is open source, you do not need to trust the pre-loaded firmware. The truly paranoid are welcome to build their own firmware from one of the tagged releases.
Contact the USG's developer if you need to customize the USG for a particular application. The developer is also available on a consultancy basis for other embedded or security-focused development work.
The USG's firmware supports the following devices, at USB 1 speeds (12Mbps).
- Mass Storage - Flash drives and hard drives, 512byte sectors and 2TB max
- Mice - 4 buttons with scroll wheel
- Keyboards - 101 keys
Q. What devices does the USG support?
A. The USG supports mass storage (flash drives), keyboards, and mice. Future firmware revisions may add extra devices and other goodies.
Q. The USG doesn't support my device. What should I do?
A. Of course the safest course of action is to not use that device! A more realistic suggestion is to use a virtualized operating system that isolates the untrusted USB device inside a sacrificial virtual machine. Qubes is a good choice for those familiar with Linux.
Q. How fast is the USG?
A. Version 1 of the USG uses 12Mbps hardware, so your mass storage transfers will run at around 1MByte per second.
Developing high-speed hardware is expensive. If you want to see faster speeds support the project so I have more incentive to make that investment!
Q. What operating systems does the USG support?
A. Everything! Besides Windows, Mac OS, and Linux, embedded systems with USB ports are also likely vulnerable to BadUSB, so you should use a USG with them as well.
Q. Can I use a hub with the USG?
A. The USG does not support hubs on it's downstream (device) side, for a very good reason. A malicious USB device can hide a hub inside itself to connect a second function, which can then do unexpected bad things to your computer. Read the Technical Details page for more info.
So the rule is one USG, one USB device.
Note that you can use hubs on the USG's upstream (computer) side. However this does come with a security risk, as that hub can also be programmed as a BadUSB and attack your computer. Think twice before using a hub, particularly one that has been attached to other computers.
Q. I have more USB devices than USGs to protect them with. Which device should I protect first?
A. You should prioritize devices that frequently move between computers, such as flash drives.
The USG can protect your secure computers from attacks from a bad device. It can also protect your device from attacks from infected computers (see this question). A good idea is to permanently attach your USG to a flash drive, to ensure both your device and your computers are always protected.
USB devices that stay in one place such as mice and keyboards are a lower risk than devices that move around. However the paranoid should protect every device attached to their computer, as any programmable device can persist a malware infection across operating system reinstallations.
A. The USG was not designed to resist physical overvoltage attacks because they are obvious and easily contained. The information in your computer is more valuable than your computer itself, and the USG defends you against attacks that compromise your information.
But having said that, the USG will provide some protection. The voltage surge will pass through and damage two microprocessors and two ESD surge suppressors before it reaches your computer. The USG's circuits will be destroyed, but the voltage surge will probably be reduced to a safe level at your computer's port. If anyone does perform this test, you are welcome to tell me the result!
Q. I'm super paranoid. Can I disable support for some types of USB device?
A. Yes you certainly can. This configuration currently needs to be done at firmware compile time. You can even make the USG a read-only storage device. See the instructions for setting firmware build options.
Q. Can the USG protect the firmware on my device from a malicious host computer?
A. Yes! The USG uses two processors to create a bi-directional firewall, and only a restricted set of commands are allowed to pass through. So a malicious host cannot alter a USB device's firmware.
Q. Can a malicious device or computer attack the USG?
A. Totally. The USG's firmware is as vulnerable as any other USB device out there. But the key point is that an infection cannot jump across the USG's internal firewall, so the other side of the USG is safe.
Furthermore any infection cannot persist between restarts, because writes to internal flash memory are disabled on startup. So when you reinsert your USG to a different computer or to use a different device, you are starting from a clean state every time.
Q. What if a malicious entity intercepts my parcel and programs bad firmware into my USG?
A. You can load your own firmware into the USG before you use it. See the DFU Firmware Upgrade page for details. The truly paranoid are welcome to build their own firmware from one of the tagged releases.
Q. If I can't trust USB devices, why should I trust your USG?
A. I'm glad you asked! By day I am an electronic engineer, and for years I have provided technical assistance to practitioners of Falun Dafa, who regularly face computer attacks from agents of the Chinese Communist Party.
The USG has 'Good' in its name for a reason. It is my way of protecting computer users against a class of attack that they currently have no defense for. It is particularly useful for individuals and organizations that face advanced threats including corporate espionage or state sponsored attacks.
I've put a lot of time and energy into this project, with the hope that more people can use it to keep themselves safe.
Q. If I use a USG, is my computer 100% safe?
A. The USG protects you against low-level USB attacks from devices including flash drives. But it cannot protect you from viruses stored inside the drive's file system, as this is a higher software layer above the USB bus.
You should consider hardening your operating system, or use virtualization to isolate attacks inside a sacrificial virtual machine. Try Qubes.
Q. Does it have a red flashing light to tell me when a USB device is bad?
A. No*. It is not possible to determine whether a USB device is good or bad. A bad device may 'act good' for days or weeks before launching an attack. A bad device may also use host profiling to determine whether it is connected to a vulnerable host (your computer) or not (your USG), and alter its behavior accordingly.
*Actually yes. The USG does have flashing error LEDs. But they can only tell you that something has gone wrong, due to buggy devices or problems with the USG's firmware. They cannot tell you with any certainty whether a BadUSB attack has been attempted. The good news is that whatever the cause of a fault, the USG will immediately shut down and disconnect itself from your computer before flashing the error LEDs. Read more about the LED fault codes here.
If you have a device that consistently causes the USG to error out, don't bypass the USG and connect it directly to your computer. That would defeat the purpose of the USG! Find another USB device to perform the same function.