usnistgov/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.

Table of Contents:

• MUD-PD
  • NIST Disclaimers
  • NIST Software License
  • General Disclaimer
  • Key Updates
  • Prerequisites and Use
  • Installation
  • Running MUD-PD
  • First Steps
  • Troubleshooting
  • Contact Us
  • Citation Instructions

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

General Disclaimer

It is expected that any data generated from MUD-PD, particularly MUD files, are validated by the user of the tool. MUD-PD is intended as a research tool, used in a controlled setting. Thus, it is expected that the user either take proper security precautions or accept the risks of using on a mission-critical system. Any risks or damages resulting from use of MUD-PD are wholly the responsibility of the user.

Key Updates

2021-03-31: Final planned feature push - Data processing threaded separately from GUI, improving the feel and responsiveness. MUD Wizard updated to allow rules to be copied or moved between communication types

2021-03-12: PcapNg files now supported (read/write capture environment details from/to the comment field). MUD files are now generated through a newly designed wizard that requires "muddy" *see prerequisites

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+ cores/threads recommended)

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

Prerequisites and Use

MUD-PD has been built and tested on Apple (macOS 10.14) and Linux (Ubuntu 18+) computers. If using Ubuntu, version 20.04 LTS is recommended. MUD-PD is currently untested and unlikely to work 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 (Ubuntu 20.04+):

   sudo apt-get install git

1. Python 3.8.4+

   • Check version

     python3 --version

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

     You can also try the following commands

     • macOS:

     brew install python3

     • Linux

     sudo apt-get install python3.8

     or

     sudo apt-get install python3.9

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:

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

   • Linux:

   sudo apt-get install python3-pip

4. TkInter for Python3 (may already be installed)

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

   • Linux:

   sudo apt-get install python3-tk

5. Wireshark (tshark) 3.4.4+

   Used to process and import packet captures. Can also be used to generate packet capture files

   • Download from: https://www.wireshark.org/download.html
   • Linux:

   sudo apt-get install tshark

6. Libpcap

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

   • Linux:

   sudo apt-get install tcpdump

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

Installation

1. Install MUD-PD:

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

2. Install muddy: (for MUD file generation)

   • Follow instructions at: https://github.com/usnistgov/muddy
   • IMPORTANT:
     • Latest verified compatible commit: 1434c380cdd49077b273c9aafdb2c7e0ef733636 (2021-04-05)
     • Verified to work when muddy is installed within the root directory of the MUD-PD repository

Running MUD-PD

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. 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:

Troubleshooting

1. Functional Issues:

   a. Run shell> pip3 install -r requirements.txt

   b. Verify that all prerequisite versions have been met (see "Prerequisites and Use" above)

   c. If the above steps don't solve the issue, please "Contact Us" (see below)

2. Visual issues:

   a. On Ubuntu, scaling may not work correctly for some buttons. Try a different scale percentage.

   b. On macOS, Dark Mode may modify the colors of some text and background. Try selecting Light Mode.

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.