Merge with umap2Plus

README.rst

@@ -1,61 +1,50 @@
-Umap2
+nü-map
 =====
 
-Umap2 is the second revision of NCC Group's
+nü-map (or nümap/numap) is the second revision of NCC Group's
 python based USB host security assessment tool.
 
 This revision will have all the features that
 were supported in the first revision:
 
-- *umap2emulate* - USB device emulation
-- *umap2scan* - USB host scanning for device support
-- *umap2detect* - USB host OS detection (no implemented yet)
-- *umap2fuzz* - USB host fuzzing
+- *numap-emulate* - USB device emulation
+- *numap-scan* - USB host scanning for device support
+- *numap-detect* - USB host OS detection (no implemented yet)
+- *numap-fuzz* - USB host fuzzing
 
 In this revision there will be some additional
 features:
 
 - USB host fuzzing uses kitty as fuzzing engine
-- Umap2 not only contains executable scripts,
+- nümap not only contains executable scripts,
   but is also installed as a package
   and may be used as a library
 
-Umap2 is developed by NCC Group and Cisco SAS team.
+nümap was developed by NCC Group and Cisco SAS team.
+The numap modernization is developed by the FaceDancer team, incluing 
+@ktemkin and Great Scott Gadgets, LLC. Most of the credit still goes to the original authors.
 
-Warning: umap2 is still an experimental,
-alpha stage tool.
-The APIs, executable names, etc. are likely to be changed
-in the near future.
-Use at your own risk.
 
-Support
--------
-
-- IRC: `#umap2 on Freenode <https://webchat.freenode.net/?channels=umap2>`_
 Installation
 ------------
 
 Since this is a very early version,
-Umap2 is not yet available from pypi,
+nümap is not yet available from pypi,
 instead, use pip to install it directly from github:
 
 ::
 
-    $ pip install git+https://github.com/nccgroup/umap2.git#egg=umap2
-
-Python Versions
----------------
+    $ pip install git+https://github.com/usb-tools/nu-map.git#egg=numap
 
-Umap2 is python2/3 compatible for most parts.
-However, the fuzzer script (**umap2kitty**) runs only on python2.
 
 "Soft" Dependencies
 -------------------
 
-Umap2's dependencies are listed in **setup.py** and will be installed with umap2,
+nümap's dependencies are listed in **setup.py** and will be installed with numap,
 however, there are couple of things that you might want to do to add support
 for some devices:
 
+
 Mass Storage
 ~~~~~~~~~~~~
 
@@ -73,11 +62,11 @@ Hardware
 --------
 
 - `Facedancer <http://goodfet.sourceforge.net/hardware/facedancer21/>`_
-  is the recommended hardware for Umap2.
-  Umap2 was developed based on it, and you'll get the most support with it.
+  is the recommended hardware for nümap.
+  nümap was developed based on it, and you'll get the most support with it.
 - `Raspdancer <http://wiki.yobi.be/wiki/Raspdancer>` is supported on RPi
 - **GadgetFS** is partially supported.
-  This support is very experimental (even more than the rest of Umap2)
+  This support is very experimental (even more than the rest of nümap)
   and limited.
 
   - BeagleboneBlack starting from Linux kernel 4.4.9 with a patched gadgetfs
@@ -96,52 +85,52 @@ Usage
 Device Emulation
 ~~~~~~~~~~~~~~~~
 
-Umap2's basic functionallity is emulating a USB device.
+nümap's basic functionallity is emulating a USB device.
 You can emulate one of the existing devices
-(use **umap2list** to see the available devices):
+(use **numap-list** to see the available devices):
 
 ::
 
-    $ umap2emulate -P fd:/dev/ttyUSB0 -C mass_storage
+    $ numap-emulate -P fd:/dev/ttyUSB0 -C mass_storage
 
 or emulate your own device:
 
 ::
 
-    $ umap2emulate -P fd:/dev/ttyUSB0 -C ~/my_mass_storage.py
+    $ numap-emulate -P fd:/dev/ttyUSB0 -C ~/my_mass_storage.py
 
 A detailed guide to add your device will be added soon,
-in the meantime, you can take a look at umap2 devices
-under *umap2/dev/*
+in the meantime, you can take a look at numap devices
+under *numap/dev/*
 
 Device Support Scanning
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Umap2 can attempt to detect what types of USB devices
+nümap can attempt to detect what types of USB devices
 are supported by the host.
-It is done by emulating each device that is implemented in Umap2
+It is done by emulating each device that is implemented in nümap
 for a short period of time,
 and checking whether a device-specific message was sent.
 
 ::
 
-    $ umap2scan -P fd:/dev/ttyUSB0
+    $ numap-scan -P fd:/dev/ttyUSB0
 
 Vendor Specific Device Support Scanning
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In addition for scanning support of various device classes,
-Umap2 can scan the host for support of vendor specific devices.
+nümap can scan the host for support of vendor specific devices.
 
 Vendor specific scanning helps identifying the vendor specific drivers
 that are available on the host.
 
-This can be done using the current Umap2 VID-PID DB (still working on it),
+This can be done using the current nümap VID-PID DB (still working on it),
 or another file in the same format:
 
 ::
 
-    $ umap2vsscan -P fd:/dev/ttyUSB0 -d $UMAP2_DIR/data/vid_pid_db.py
+    $ numap-vsscan -P fd:/dev/ttyUSB0 -d $UMAP2_DIR/data/vid_pid_db.py
 
 Or by scanning a specific vid-pid range -
 in this example -
@@ -150,17 +139,17 @@ and PID from 0x0000 to 0xffff:
 
 ::
 
-    $ umap2vsscan -P fd:/dev/ttyUSB0 -s 1001-1004:0000-ffff
+    $ numap-vsscan -P fd:/dev/ttyUSB0 -s 1001-1004:0000-ffff
 
 Any patches/additions to the vid_pid_db.py file are very welcome!
 
 Fuzzing
 ~~~~~~~
 
-A detailed guide for fuzzing using Umap2 can be found in 
-`docs/fuzzing.rst <https://github.com/nccgroup/umap2/blob/master/docs/fuzzing.rst>`_
+A detailed guide for fuzzing using nümap can be found in 
+`docs/fuzzing.rst <https://github.com/nccgroup/numap/blob/master/docs/fuzzing.rst>`_
 
-Fuzzing with Umap2 is composed of three steps,
+Fuzzing with nümap is composed of three steps,
 which might be unified into a single script in the future.
 
 1. Find out what is the order of messages
@@ -169,45 +158,34 @@ which might be unified into a single script in the future.
 
    ::
 
-        $ umap2stages -P fd:/dev/ttyUSB0 -C keyboard -s keyboard.stages
+        $ numap-stages -P fd:/dev/ttyUSB0 -C keyboard -s keyboard.stages
 
 2. Start the kitty fuzzer in a separate shell,
    and provide it with the stages generated in step 1.
 
    ::
 
-        $ umap2kitty -s keyboard.stages
+        $ numap-kitty -s keyboard.stages
 
-3. Start the umap2 keyboard emulation in fuzz mode
+3. Start the numap keyboard emulation in fuzz mode
 
    ::
 
-        $ umap2fuzz -P fd:/dev/ttyUSB0 -C keyboard
+        $ numap-fuzz -P fd:/dev/ttyUSB0 -C keyboard
 
 After stage 3 is performed, the fuzzing session will begin.
 
 Note About MTP fuzzing
 ++++++++++++++++++++++
 
-While umap2 may be used to emulate and discover MTP devices
+While numap may be used to emulate and discover MTP devices
 (see "Soft dependencies" section of this README),
 it does not fuzz the MTP layer at this point.
 In order to fuzz the MTP layer,
 you can use the fuzzer embedded in the MTP library.
-We plan to support MTP fuzzing directly from umap2 in future releases.
+We plan to support MTP fuzzing directly from numap in future releases.
 
 Host OS Detection
 ~~~~~~~~~~~~~~~~~
 
 TBD
-
-Toubleshooting
---------------
-
-If you have issues with Umap2, try the
-`troubleshooting section <https://github.com/nccgroup/umap2/blob/master/docs/troubleshooting.rst>`_
-
-Raspdancer
---------------
-You need SPI-Py <https://github.com/lthiery/SPI-Py> and GPIO python libraries.
-Use phy `rd`

data/vid_pid_db.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-from umap2.apps.vsscan import DBEntry, OS
+from numap.apps.vsscan import DBEntry, OS
 import sys
 
 db = [
@@ -6185,8 +6185,8 @@
     history = set()
     for db_entry in db:
         if (db_entry.vid, db_entry.pid) in history:
-            print 'Duplicate found: 0x%04x, 0x%04x' % (db_entry.vid, db_entry.pid)
+            print('Duplicate found: 0x%04x, 0x%04x' % (db_entry.vid, db_entry.pid))
             sys.exit(1)
         else:
             history.add((db_entry.vid, db_entry.pid))
-    print 'DB OK!'
+    print('DB OK!')

data/vid_pid_db_from_usb_ids.py

@@ -5,7 +5,7 @@
 It is much more extensive than vid_pid_db.py,
 and contains no information about the drivers.
 '''
-from umap2.apps.vsscan import DBEntry, OS
+from numap.apps.vsscan import DBEntry, OS
 import sys
 
 db = [
@@ -15492,8 +15492,8 @@
     history = set()
     for db_entry in db:
         if (db_entry.vid, db_entry.pid) in history:
-            print 'Duplicate found: 0x%04x, 0x%04x' % (db_entry.vid, db_entry.pid)
+            print('Duplicate found: 0x%04x, 0x%04x' % (db_entry.vid, db_entry.pid))
             sys.exit(1)
         else:
             history.add((db_entry.vid, db_entry.pid))
-    print 'DB OK!'
+    print('DB OK!')

docs/fuzzing.rst

@@ -1,7 +1,7 @@
 Fuzzing USB Hosts
 =================
 
-This document describes the full process of fuzzing USB hosts with Umap2.
+This document describes the full process of fuzzing USB hosts with nümap.
 
 Fuzzing a host consists of three basic steps.
 While the fuzzer does not require you to write any code,
@@ -18,11 +18,11 @@ Step 1 - Select Device
 ~~~~~~~~~~~~~~~~~~~~~~
 
 First, you need to detrmine which driver/subsystem/class you want to fuzz.
-You can find out what is supported on the host by running ``umap2scan``:
+You can find out what is supported on the host by running ``numapscan``:
 
 ::
 
-    $ umap2scan -P <PHY>
+    $ numapscan -P <PHY>
 
 Step 2 - Record Valid Flow
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -32,11 +32,11 @@ and decided on a device that you want to emulate in your fuzzing,
 you need to record the basic communication flow of the host with this device.
 This step is essential for effective fuzzing,
 as different hosts communicate with the same device in different ways.
-The tool to do that is ``umap2stages``:
+The tool to do that is ``numapstages``:
 
 ::
 
-    $ umap2stages -P <PHY> -C <CLASS> -s <STAGES_FILE_NAME>
+    $ numapstages -P <PHY> -C <CLASS> -s <STAGES_FILE_NAME>
 
 Step 3 - Start Fuzzing
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -48,24 +48,24 @@ First, you need to start the kitty-based fuzzer backend in a separate shell:
 
 ::
 
-    $ umap2kitty -s <STAGES_FILE_NAME>
+    $ numapkitty -s <STAGES_FILE_NAME>
 
 There are some command line options available in kitty,
 you can see them in the next section.
 
-Now you need to start the umap2 stack.
+Now you need to start the numap stack.
 Once it is up, it will signal the fuzzer backend
 and the fuzzing proces will begin
 
 ::
 
-    $ umap2fuzz -P <PHY> -C <CLASS>
+    $ numapfuzz -P <PHY> -C <CLASS>
 
 
 Monitor Progress
 ~~~~~~~~~~~~~~~~
 
-The output from ``umap2kitty`` and ``umap2fuzz`` is not meant as a UI.
+The output from ``numapkitty`` and ``numapfuzz`` is not meant as a UI.
 If you want to watch the fuzzing session, use Kitty's web UI,
 which is available either from the browser at http://localhost:26001.
 Or using ``kitty-web-client`` which is a command line tool to retrieve
@@ -78,13 +78,13 @@ reports about failed tests.
 Fuzzing Options
 ---------------
 
-By passing command line parameters to ``umap2kitty`` you can achieve a better fuzzing session.
+By passing command line parameters to ``numapkitty`` you can achieve a better fuzzing session.
 Here are some examples of such parameters.
 To see all of the fuzzer options, run
 
 ::
 
-    $ umap2kitty -s <STAGES> -k "--help"
+    $ numapkitty -s <STAGES> -k "--help"
 
            These are the options to the kitty fuzzer object, not the options to the runner.
 
@@ -111,21 +111,21 @@ Fuzzing session file allows you to store the results of a run. It has three main
 1. Continue a fuzzing session that was stopped for some reason:
     ::
 
-        $ umap2kitty -s <STAGES> -k "-f mysessionfile"
+        $ numapkitty -s <STAGES> -k "-f mysessionfile"
         # closed terminal by mistake :(
         #
         # Continue from the same place :)
-        $ umap2kitty -s <STAGES> -k "-f mysessionfile"
+        $ numapkitty -s <STAGES> -k "-f mysessionfile"
 
 2. Review the failures from finished session (If for some reason the reports were not retreived).
 3. **Most important** - retest failures. This allows you to retest crashes and make sure that the crash is reproducible, or debug it, or test on a new version.
     ::
 
         # first run - failures on tests 1,7,10
-        $ umap2kitty -s <STAGES> -k "-f mysessionfile"
+        $ numapkitty -s <STAGES> -k "-f mysessionfile"
 
         # re-run only failures (tests 1,7,10)
-        $ umap2kitty -s <STAGES> -k "-r mysessionfile"
+        $ numapkitty -s <STAGES> -k "-r mysessionfile"
 
 
 Running Only a Subset of the tests
@@ -137,6 +137,6 @@ For example - run tests 1,2,3,45,7,9 and everything above 100
 
 ::
 
-    $ umap2kitty -s <STAGES> -k "-t 1-5,7,9,100-"
+    $ numapkitty -s <STAGES> -k "-t 1-5,7,9,100-"