AutoGadgetFS

What’s AutoGadgetFS ?

AutoGadgetFS is an open source framework that allows users to assess USB devices and their associated hosts/drivers/software without an in-depth knowledge of the USB protocol. The tool is written in Python3 and utilizes RabbitMQ and WiFi access to enable researchers to conduct remote USB security assessments from anywhere around the globe. By leveraging ConfigFS, AutoGadgetFS allows users to clone and emulate devices quickly, eliminating the need to dig deep into the details of each implementation. The framework also allows users to create their own fuzzers on top of it.

Requirments:

• 💻 Host machine running Linux (Debian/Ubuntu/Kali)
• 🥧 Raspberry Pi Zero with WIFI support
• 🎯 Target machine options:
  • Virtual Machine
  • Standalone machine
• 🔌 2 x USB micro cables
• 🔱 Target USB device
• 🐞 Hardware debugger ( Optional )

The Setup:

Device testing only:

Minimal agfs in the middle setup:

Complete agfs in the middle setup with debugging support:

USB Device class support:

[✔️] USB HID Devices fully supported (Man in the middle)

[⚠️] Device only testing .. All USB devices (NO Man in the middle)

[⏳] Future releases... All USB devices (Man in the middle)

Capabilities:

1. Find, Select and Attach to a USB device with ease.
2. Emulate any USB HID device .
3. Perform AGFS in the middle sniffing for HID devices ( save communication to disk ).
4. Device sniffing ( Any device ).
5. Multiple Fuzzers allow you to Fuzz a device or a host.
6. Random fuzzers ( with fixed or random length packets ).
7. Smart Fuzzers that learn from previous USB communications.
8. Describe Fuzzer to tell the Fuzzer which bytes to Fuzz leaving the rest of the packet the same.
9. Gadget Fuzzer.
10. Sequential Fuzzer.
11. Control transfer Enumerator.
12. Replay of packets from a file.
13. Replay of packets from a saved USBLyzer capture.
14. Visual way of presenting packets to allow ease of reverse engineering of the communication.
15. Alerts for device in DFU mode, or if the device leaks information.
16. USB device and host can be anywhere on the internet.
17. Monitor sudden interface changes.

RoadMap:

1. Sniff control transfer requests to a device and reply to them.
2. MITM and emulate all types of devices.
3. Console/QT based interface.
4. More Interfaces/endpoints support on the RPI zero W.
5. Support more boards like the greatfet.
6. Move to a custom board.
7. Work on making raspberry pi have full support for usb device emulation with all interfaces.
8. correlate sent and received packets via sequence numbers.

Installation:

Linux Machine:

• Note: WSL/WSL2 is not supported due to issues with USB pass-through.

• Install Python3, ipython3 ,git, pip and rabbitMQ server

  sudo apt install python3 ipython3 git python3-pip rabbitmq-server dfu-util
  sudo service rabbitmq-server start
  

• Clone the repository

  git clone https://github.com/ehabhussein/AutoGadgetFS
  cd AutoGadgetFS
  

• Install the requirements

  sudo -H pip3 install -r requirements.txt
  

• Downgrade prompt toolkit for better ipython experience:

  sudo python3 -m pip install prompt-toolkit~=2.0
  

• Enable the web interface for rabbitMQ

  sudo rabbitmq-plugins enable rabbitmq_management
  http://localhost:15672/ to reach the web interface
  

• login to the web interface with the credentials guest:guest

  • NOTE: if you are not installing rabbitMQ on localhost add the following user and login with it:

    sudo rabbitmqctl add_user autogfs usb4ever
    sudo rabbitmqctl set_user_tags autogfs administrator
    

  • Upload the rabbitMQ configuration file

    • In the overview tab scroll to the bottom to import definitions
    • Upload the file found in: rabbitMQbrokerconfig/rabbitmq-Config.json

    sudo service rabbitmq-server restart
    

• Test the installation

  sudo ipython3
  
  Python 3.7.7 (default, Apr  1 2020, 13:48:52)
  Type 'copyright', 'credits' or 'license' for more information
  IPython 7.9.0 -- An enhanced Interactive Python. Type '?' for help.
  
  In [1]: import libagfs
  
  In [2]: x = libagfs.agfs()
  
  ***************************************
  AutoGadgetFS: USB testing made easy
  ***************************************
  Enter IP address of the rabbitmq server: 127.0.0.1
  
  In [3]: exit
  
  sudo `python3` agfsconsole.py
  
  ***************************************
  AutoGadgetFS: USB testing made easy
  ***************************************
  Enter IP address of the rabbitmq server: 127.0.0.1
  Give your project a name?!:
  

• Patch Pyusb langID ( Not needed unless you get pyusb errors for langID ):

  • Edit the file /usr/local/lib/python3/dist-packages/usb/util.py

    • make changes to the def get_string method to look like below:

      if 0 == len(langids):
          return "Error Reading langID"
          #raise ValueError("The device has no langid")
      if langid is None:
          langid = langids[0]
      elif langid not in langids:
          return "Error Reading langID"
          #raise ValueError("The device does not support the specified langid")
      

    • If you prefer to use patch apply the following patch to the file: AutoGadgetFS/pyusb_patches/pyusb_langid.patch

Raspberry Pi Zero W: