-
Notifications
You must be signed in to change notification settings - Fork 55
umap documentation
umap is a tool which allows you to test the security of USB host implementations i.e. something you plug a USB device into, like a PC or a tablet. Its primary function at the moment is a fuzzer with test cases based on a combination of data from standards documentation and the author's experience of where USB bugs are commonly found. However, it also has additional functionality that will be expanded further in future versions, for example:
- Operating system identification
- Installed application identification
- Vendor-specific driver enumeration
- Endpoint Protection System assessment
umap requires a Facedancer board to enable devices to be virtualised in Python and presented to the target host. The firmware and basic Facedancer demo software can be downloaded here.
umap is written in Python so to run it just type:
$ sudo python umap.py
(umap must be run as root)
---------------------------------------
_ _ _ __ ___ __ _ _ __
| | | | '_ ` _ \ / _` | '_ \
| |_| | | | | | | (_| | |_) |
\__,_|_| |_| |_|\__,_| .__/
|_|
The USB host assessment tool
Andy Davis, NCC Group 2013
Version: 1.01
Based on Facedancer by Travis Goodspeed
For help type: umap.py -h
---------------------------------------
Error: Facedancer serial port not supplied
As you can see, it complains that you haven't supplied the serial port to which the Facedancer is connected. By typing umap.py -h you can see how to do this:
Usage: umap.py
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-P SERIAL Facedancer serial port **Mandatory option** (SERIAL=/dev/ttyX
or just 1 for COM1)
-L List device classes supported by umap
-i identify all supported device classes on connected host
-c CLS identify if a specific class on the connected host is supported
(CLS=class:subclass:proto)
-O Operating system identification
-e DEVICE emulate a specific device (DEVICE=class:subclass:proto)
-v VID specify Vendor ID (hex format e.g. 1a2b)
-p PID specify Product ID (hex format e.g. 1a2b)
-r REV specify product Revision (hex format e.g. 1a2b)
-f FUZZC fuzz a specific class (FUZZC=class:subclass:proto:E/C/A[:start
fuzzcase])
-s FUZZS send a single fuzz testcase
(FUZZS=class:subclass:proto:E/C:Testcase)
-d DLY delay between enumeration attempts (seconds): Default=1
-l LOG log to a file
-R REF Reference the VID/PID database (REF=VID:PID)
-u update the VID/PID database (Internet connectivity required)
Experimental Options:
-A APPLE emulate an Apple iPhone device (APPLE=VID:PID:REV)
-b VENDOR brute-force vendor driver support (VENDOR=VID:PID)
The only mandatory option is -P to provide the serial port that the Facedancer board is connected to e.g.
$ sudo umap.py -P /dev/ttyUSB0
In order to fuzz a USB host you need to emulate the process of physical insertion and removal of your virtual device. The USB design is expecting this process to be performed by a human and therefore, attempting to perform the operation too quickly results in the host getting confused (...but that a whole different area of potential research). As a result, USB fuzzing can be very slow (7-10 seconds per fuzz test case) so it's very important to be able to enumerate what classes of USB device are supported by the host before you start fuzzing.
To display which device classes umap can emulate use the -L option, which results in something like this:
XX:YY:ZZ - XX = Class : YY = Subclass : ZZ = Protocol 01:01:00 - Audio : Audio control : PR Protocol undefined 01:02:00 - Audio : Audio streaming : PR Protocol undefined 02:02:01 - CDC Control : Abstract Control Model : AT commands V.250 02:03:ff - CDC Control : Telephone Control Model : Vendor specific 02:06:00 - CDC Control : Ethernet Networking Control Model : No class-specific protocol required 03:00:00 - Human Interface Device : No subclass : None 06:01:01 - Image : Still image capture device : Bulk-only protocol 07:01:02 - Printer : Default : Bidirectional interface 08:06:50 - Mass Storage : SCSI : BBB 09:00:00 - Hub : Default : Default 0a:00:00 - CDC Data : Default : Default 0b:00:00 - Smart Card : Default : Default
As you can see, USB class information is represented by three bytes, the first being the base class e.g. 08 = Mass Storage class, the second is the sub-class e.g. 06 = SCSI (for Mass Storage) and the third is the protocol e.g. BBB (for Mass Storage).
In order to identify which of these virtual devices is supported by the USB host that your are testing, use the following command:
$ sudo python3 umap.py -P /dev/ttyUSB0 -i 01:01:00 - Audio : Audio control : PR Protocol undefined **SUPPORTED** 01:02:00 - Audio : Audio streaming : PR Protocol undefined **SUPPORTED** 02:02:01 - CDC Control : Abstract Control Model : AT commands V.250 02:03:ff - CDC Control : Telephone Control Model : Vendor specific 02:06:00 - CDC Control : Ethernet Networking Control Model : No class-specific protocol required 03:00:00 - Human Interface Device : No subclass : None **SUPPORTED** 06:01:01 - Image : Still image capture device : Bulk-only protocol **SUPPORTED** 07:01:02 - Printer : Default : Bidirectional interface 08:06:50 - Mass Storage : SCSI : BBB **SUPPORTED** 09:00:00 - Hub : Default : Default **SUPPORTED** 0a:00:00 - CDC Data : Default : Default **SUPPORTED** 0b:00:00 - Smart Card : Default : Default