Skip to content

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.

Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 

README.md

MUD-PD

A tool for characterizing the network behavior of IoT devices particularly for use with MUD (Manufacturer Usage Description)

MUD Specification: https://tools.ietf.org/html/rfc8520

Note well: This tool is still in the development phase, and has only been tested on Linux (Ubuntu 18+) and macOS (10.14). Windows is currently not supported, but is in the works.

Prerequisites

  1. Git

    shell> sudo apt-get install git
  2. 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
  3. 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/

  4. 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
  5. TkInter for Python3 (may already be installed)

    shell> sudo apt-get install python3-tk
  6. Libpcap

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

    • Linux:
    shell> sudo apt-get install tcpdump

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

Execution

shell> python3 mudpd.py

First Steps

MUD-PD GUI at Start-up

  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: Create Database Button Create Database

    • Connect to existing database: Connect to Database Button Connect to Database
  2. Import PCAP files: Import PCAP files

About

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.

Resources

Releases

No releases published

Languages

You can’t perform that action at this time.