montimage/mmt repository overview

⁠MMT on Docker

This repository enables running Montimage Monitoring Tool (MMT) in a Docker container to simplify network traffic monitoring and analysis across different platforms.

MMT is primarily an enterprise-level network monitoring solution designed for Linux-based infrastructure environments. While MMT doesn't have native support for Windows or macOS, this Docker-based approach provides a cross-platform solution that works on any system capable of running Docker containers.

If you are a developer looking to build or modify the MMT Docker image, please see the DEVELOPER.md⁠ file.

⁠What is MMT?

Montimage Monitoring Tool (MMT) is a powerful enterprise-level network monitoring and analysis solution that provides:

• Real-time traffic monitoring and analysis
• Protocol identification and extraction
• Security threat detection
• Performance measurement
• Traffic statistics and visualization

MMT is designed for enterprise network infrastructures where Linux is the primary operating system. It's widely used in telecommunications, critical infrastructure monitoring, cybersecurity operations centers, and enterprise network management.

This Docker-based implementation bridges the platform gap, allowing users of Windows, macOS, and other operating systems to utilize MMT's powerful capabilities without requiring a dedicated Linux environment.

⁠How It Works

The following diagram illustrates how MMT on Docker captures and analyzes your network traffic:

graph LR
    A[Host Network] -->|tcpdump| B[Network Capture]
    B -->|netcat| C[Docker Container]
    C -->|mmt-probe| D[Analysis Engine]
    D -->|Reports| E[Results Directory]
    
    subgraph Host Machine
    A
    B
    E
    end
    
    subgraph MMT Container
    C
    D
    end

1. Host Network: Your network interface that contains the traffic you want to analyze
2. Network Capture: tcpdump captures raw packets from your network
3. Docker Container: The containerized MMT environment
4. Analysis Engine: MMT-probe processes and analyzes the traffic
5. Results Directory: Analysis reports are stored in a mounted directory on your host

⁠Quick Start for macOS Users

⁠Prerequisites for macOS

1. Install Docker Desktop:

   • Download from Docker Desktop for Mac⁠
   • Install and launch Docker Desktop
   • Wait for Docker to start (whale icon in menu bar turns solid)

2. Install tcpdump and netcat using Homebrew:

   brew install tcpdump netcat
   

   Copy

⁠Step-by-Step Instructions for macOS

1. Pull the Docker image:

   docker pull montimage/mmt:latest
   

   Copy

2. Find your network interface:

   networksetup -listallhardwareports
   

   Copy

   Look for your active interface (typically en0 for Wi-Fi or en1 for Ethernet)

3. Start capturing network traffic (keep this terminal window open):

   sudo tcpdump -i en0 -U -w - | nc -l 12345
   

   Copy

   Replace en0 with your actual interface name

4. Open a new terminal window and run the MMT container:

   # Create reports directory
   mkdir -p ~/mmt-reports
   
   # Run the container
   docker run -d --name mmt-probe --rm \
     -v ~/mmt-reports:/opt/mmt/probe/result/report/online \
     montimage/mmt:latest
   

   Copy

5. View the analysis results:

   ls -la ~/mmt-reports
   

   Copy

6. Stop monitoring when finished:

   docker stop mmt-probe
   

   Copy

   Also press Ctrl+C in the tcpdump terminal window

⁠Quick Start for Windows Users

⁠Prerequisites for Windows

1. Install Docker Desktop:

   • Download from Docker Desktop for Windows⁠
   • Ensure WSL 2 is installed and enabled (WSL installation guide⁠)
   • Install and launch Docker Desktop
   • Make sure Docker is running (whale icon in system tray)

2. Install packet capture tools:

   • Download and install Wireshark⁠
   • Download and install Nmap⁠ (includes ncat)

⁠Step-by-Step Instructions for Windows

1. Pull the Docker image:

   docker pull montimage/mmt:latest
   

   Copy

2. Find your network interface:

   Get-NetAdapter
   

   Copy

   Note the name of your active network interface (e.g., "Wi-Fi" or "Ethernet")

3. Start capturing network traffic (keep this PowerShell window open):

   & 'C:\Program Files\Wireshark\tshark.exe' -i Wi-Fi -w - | & 'C:\Program Files\Nmap\ncat.exe' -l 12345
   

   Copy

   Replace Wi-Fi with your actual interface name

4. Open a new PowerShell window and run the MMT container:

   # Create reports directory
   mkdir -p $HOME\mmt-reports
   
   # Run the container
   docker run -d --name mmt-probe --rm `
     -v "$HOME\mmt-reports:/opt/mmt/probe/result/report/online" `
     montimage/mmt:latest
   

   Copy

5. View the analysis results:

   dir $HOME\mmt-reports
   

   Copy

6. Stop monitoring when finished:

   docker stop mmt-probe
   

   Copy

   Also press Ctrl+C in the packet capture window

⁠Quick Start for Linux Users

⁠Prerequisites for Linux

1. Install Docker:

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install docker.io
   sudo systemctl start docker
   sudo systemctl enable docker
   
   # Fedora/CentOS
   sudo dnf install docker
   sudo systemctl start docker
   sudo systemctl enable docker
   

   Copy

2. Install tcpdump and netcat:

   # Ubuntu/Debian
   sudo apt-get install tcpdump netcat-openbsd
   
   # Fedora/CentOS
   sudo dnf install tcpdump nc
   

   Copy

⁠Step-by-Step Instructions for Linux

1. Pull the Docker image:

   docker pull montimage/mmt:latest
   

   Copy

2. Find your network interface:

   ip link show
   

   Copy

   Note the name of your active network interface (e.g., "eth0" or "ens33")

3. Start capturing network traffic (keep this terminal window open):

   sudo tcpdump -i eth0 -U -w - | nc -l -p 12345
   

   Copy

   Replace eth0 with your actual interface name

4. Open a new terminal window and run the MMT container:

   # Create reports directory
   mkdir -p ~/mmt-reports
   
   # Run the container
   docker run -d --name mmt-probe --rm \
     -v ~/mmt-reports:/opt/mmt/probe/result/report/online \
     montimage/mmt:latest
   

   Copy

   Alternatively, on Linux you can directly monitor a network interface:

   docker run -d --name mmt-probe --rm \
     --net=host -e HOST_INTERFACE=eth0 \
     -v ~/mmt-reports:/opt/mmt/probe/result/report/online \
     montimage/mmt:latest
   

   Copy

5. View the analysis results:

   ls -la ~/mmt-reports
   

   Copy

6. Stop monitoring when finished:

   docker stop mmt-probe
   

   Copy

   Also press Ctrl+C in the tcpdump terminal window

⁠Advanced Usage

⁠Analyzing a PCAP File

You can analyze a pre-recorded PCAP file using the MMT container:

macOS/Linux:

# Create reports directory
mkdir -p ~/mmt-reports

# Run the container with a PCAP file
docker run -d --name mmt-probe --rm \
  -v ~/mmt-reports:/opt/mmt/probe/result/report/online \
  -v ~/my-capture.pcap:/pcap/my-capture.pcap \
  -e PCAP_FILE=/pcap/my-capture.pcap \
  montimage/mmt:latest

Windows:

# Create reports directory
mkdir -p $HOME\mmt-reports

# Run the container with a PCAP file
docker run -d --name mmt-probe --rm `
  -v "$HOME\mmt-reports:/opt/mmt/probe/result/report/online" `
  -v "$HOME\my-capture.pcap:/pcap/my-capture.pcap" `
  -e PCAP_FILE=/pcap/my-capture.pcap `
  montimage/mmt:latest

Replace my-capture.pcap with your actual PCAP file name.

⁠Using a Custom Container Name

# For macOS/Linux
docker run -d --name my-custom-mmt --rm \
  -v ~/mmt-reports:/opt/mmt/probe/result/report/online \
  montimage/mmt:latest

⁠Using a Specific Image Version

# For macOS/Linux
docker run -d --name mmt-probe --rm \
  -v ~/mmt-reports:/opt/mmt/probe/result/report/online \
  montimage/mmt:v1.0

⁠Troubleshooting

⁠No Traffic Being Captured

1. Verify your network interface name
2. Ensure tcpdump is running with sudo/administrator privileges
3. Check that port 12345 is not being used by another application
4. Verify that netcat is properly installed

⁠Container Exits Immediately

If the container exits immediately after starting, check:

1. Docker logs: docker logs mmt-probe
2. Ensure tcpdump is running before starting the container
3. Check that port 12345 is accessible to the container

⁠Permission Issues with Reports Directory

If you encounter permission errors with the reports directory:

# Fix permissions on the reports directory
sudo chown -R $USER:$USER ./mmt-reports

⁠Troubleshooting

⁠macOS-Specific Issues

1. Docker can't connect to host.docker.internal:

   • Ensure Docker Desktop is running with the latest version
   • Try restarting Docker Desktop
   • If still failing, use a direct IP address by running:

     ifconfig en0 | grep "inet " | awk '{print $2}'
     

     Copy
     Then use this IP instead of host.docker.internal

2. Permission denied for tcpdump:

   • Make sure to run tcpdump with sudo
   • If prompted for password multiple times, run:

     sudo chmod +s /usr/sbin/tcpdump
     

     Copy

⁠Windows-Specific Issues

1. Container can't reach host for packet capture:

   • Ensure Windows Firewall allows incoming connections on port 12345
   • Try adding WSL integration in Docker Desktop settings
   • Use the IP address of your host instead of host.docker.internal:

     ipconfig | findstr IPv4
     

     Copy

2. Wireshark/tshark permission issues:

   • Run PowerShell as Administrator
   • Try using Wireshark GUI to capture to a file, then use the PCAP file analysis mode

⁠Linux-Specific Issues

1. Docker permission issues:

   • Make sure your user is in the docker group:

     sudo usermod -aG docker $USER
     # then logout and login again
     

     Copy

2. Network interface not found:

   • Make sure you're using the correct interface name
   • For direct monitoring, ensure you use --net=host

⁠Operating Modes

The container can operate in three modes:

1. Netcat Mode (Default): Captures traffic from the host machine through a netcat connection on port 12345. This is the recommended mode for most users and works across all operating systems (Windows, macOS, Linux).

2. Host Network Interface Mode: Available on Linux only, this mode directly captures traffic from a specified host network interface using the --net=host option. This mode represents the traditional deployment method for MMT in enterprise environments.

3. PCAP Analysis Mode: Analyzes a pre-recorded PCAP file from your host system. This mode is useful for analyzing previously captured traffic, forensic analysis, or testing purposes.

⁠Understanding MMT Reports

MMT generates several types of reports in the configured reports directory:

⁠Security Reports

These reports contain information about detected security events and potential threats.

⁠Statistics Reports

These reports provide statistical information about the monitored network traffic, including:

• Protocol distribution
• Traffic volume
• Connection statistics
• Application behavior

⁠Sample Commands to View Reports

View the most recent report:

ls -lt ./mmt-reports | head -n 5

View a specific security report:

cat ./mmt-reports/security_report_*.xml

⁠Visualizing Reports with MMT-Operator

MMT-Operator is a graphical web interface for visualizing and analyzing MMT reports. It runs on your host machine and provides dashboards, charts, and detailed analytics.

⁠Setting Up MMT-Operator

1. Clone and install MMT-Operator from the official repository⁠:

   git clone https://github.com/Montimage/mmt-operator.git
   cd mmt-operator/www
   npm install
   

   Copy

2. Install MongoDB (required for MMT-Operator):

   # For macOS using Homebrew
   brew tap mongodb/brew
   brew install [email protected]
   brew services start [email protected]
   

   Copy

3. Configure MMT-Operator to read the reports from your Docker container:

   Edit the www/config.json file to set the correct reports directory:

   # Navigate to the www directory
   cd mmt-operator/www
   
   # Edit the config.json file (using your preferred editor)
   vim config.json
   

   Copy

   The most important setting is the file_input.data_folder array. Make sure it includes the path to where your MMT reports are stored:

   "file_input": {
     "data_folder": [
       "/absolute/path/to/your/mmt-reports/"
     ],
     "delete_data": true,
     "nb_readers": 1
   },
   "input_mode": "file",
   

   Copy

   Replace /absolute/path/to/your/mmt-reports/ with the absolute path to your reports directory.

4. Access the MMT-Operator web interface:

   • Open your browser and navigate to http://localhost:8080 (default port)

⁠Key Features of MMT-Operator

• Real-time traffic visualization
• Security event monitoring
• Protocol breakdown analysis
• Historical data examination
• Customizable dashboards

For full documentation and advanced configuration options, visit the MMT-Operator GitHub repository⁠.

⁠License

This project is distributed under the terms of the license covering Montimage products.

⁠Support and Contributing

For any issues, questions, or improvements:

• Visit Montimage website⁠
• Contact support at [email protected]⁠