hisanak / MUD-PD

A tool for characterizing the network behavior of IoT Devices. The primary intended use is to assist in the generation of allowlist files formatted according to the Manufacturer Usage Description specification.

MUD-PD

MUD-PD is designed to help internet of things (IoT) manufacturers, developers, and researchers to implement the Manufacturer Usage Description (MUD) specification. MUD-PD is a tool assist in the characterization of IoT device network behavior and the creation and definition of appropriate MUD files.

For more information about the IETF MUD Specification: https://tools.ietf.org/html/rfc8520

For more information about characterizing the network behavior of IoT devices see: https://csrc.nist.gov/publications/detail/white-paper/2020/04/01/methodology-for-characterizing-network-behavior-of-iot-devices/draft

NIST Disclaimers

Certain commercial products or company names are identified here to describe the experimental and computational procedure adequately. Such identification is not intended to imply recommendation or endorsement by the National Institute of Standards and Technology, nor is it intended to imply that the products or names identified are necessarily the best available for the purpose.

NIST Software License

See LICENSE.TXT

Key Updates

2020-07-24: Local caching of device details

2020-06-25: Fingerbank integration to assist in device identification

2020-06-25: Multiprocessing of PCAP files enabled (4+ threads recommended)

2019-10-31: MUD file generation wizard powered by MUDgee *see prerequisites

2019-10-22: Generation of human readable reports enabled

**see README_FF.md for future feature development

Prerequisites and use

MUD-PD has been built and tested on Apple (macOS 10.14) and Linux (Ubuntu 18+) computers. MUD-PD currently does not run on Windows.

System specifications used for development and testing:

	macOS	Linux (VM)
CPU	4th Gen i7	8th Gen i7
CPU Threads	8	4
RAM	16 GB	6 GB

0. Git

   • macOS: easiest through an installer such as the one found at: https://www.atlassian.com/git/tutorials/install-git

   • Linux:

   shell> sudo apt-get install git

1. Python 3.7.2+

   • Check version

     shell> python3 --version

   • Instructions for updating/installing python3 can be found at: https://www.python.org/downloads/

     You can also try the following commands

     • macOS:

     shell> brew install python3

     • Linux

     shell> sudo apt-get install python3.7

     or

     shell> sudo apt-get install python3.8

2. MySQL

   1. MySQL Server

      Follow directions at: https://dev.mysql.com/downloads/mysql/

      Note: may need to create a new user and grant permissions using the following commands:

      shell> sudo mysql -u root -p
      mysql> CREATE USER '<new_user>'@'localhost' IDENTIFIED BY '<new_password>';
      mysql> GRANT ALL PRIVILEGES ON *.* TO '<new_user>'@'localhost';
      mysql> FLUSH PRIVILEGES;

   2. MySQL Workbench (optional)

      (recommended for those who may wish to interact directly with the database and write custom queries)

      Follow directions at: https://dev.mysql.com/downloads/workbench/

3. pip (may already be installed)

   • macOS:

   shell> curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
   shell> python3 get-pip.py

   • Linux:

   shell> sudo apt-get install python3-pip

4. TkInter for Python3 (may already be installed)

   • macOS: instructions can be found at https://python.org/downloads/mac/tcltk/

   • Linux:

   shell> sudo apt-get install python3-tk

5. Libpcap

   Used for generating packet captures to import into the database and tool

   • Linux:

   shell> sudo apt-get install tcpdump

   • macOS: readily available by default
   • Windows: follow instructions at https://nmap.org/npcap/

Important note about Wireshark:

If Wireshark is installed, one of the required Python libraries may conflict with the application. Thus, it is best to ensure that the version of Wireshark installed is 3.2.5 or later.

Installation

1. Install MUD-PD:

   shell> git clone https://github.com/usnistgov/MUD-PD.git
   shell> cd MUD-PD
   shell> pip3 install -r requirements.txt

2. Install MUDgee: (for MUD file generation)

   • Follow instructions at: https://github.com/ayyoob/mudgee
   • IMPORTANT:
     • Both the MUDgee and MUD-PD repositories must be installed in the same parent directory
     • Latest verified compatible version: Latest commit f63a88d on Jul 5 2019

Running MUD-PD

shell> python3 mudpd.py

First Steps

1. Connect to existing database
2. Create and (re)initialize database
3. Import capture file
4. Generate MUD file
5. Generate device report
6. Box containing list of imported capture files
7. Box containing list of local devices active on network during traffic captures
8. Box containing list of communication within selected capture files
9. Inspect selected imported capture file
10. Toggle communication view to north/south (external), east/west (internal), or unfiltered traffic
11. Future feature not yet enabled. Eventually to filter communication to only that "between" selected devices or any packets to/from "either" device but not necessarily between both
12. Limit list of packets in communication box to the selected number

1. Create your first database:

   • Connect to existing database:

2. Import PCAP files:

Contact Us

These programs were developed by Paul Watrobski and Joshua Klosterman. Questions and bug reports may be directed to Paul Watrobski. Please include the commit hash you are using as well as any code line numbers output in the terminal.

These scripts should be cited as:

P. Watrobski, J. Klosterman, "MUD-PD", https://github/ustnistgov/MUD-PD

The commit hash and list of programs used should be included where applicable.