umap documentation

What does umap do?

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

Required hardware

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.

Running umap

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.

./umap.py -P /dev/ttyUSB0

First - what drivers are supported?

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