Ask about network traffic. Get clear answers.

mmtReader is a deep packet inspection engine that AI Agents use to analyze network traffic and produce human-readable reports with visualizations.

Get Started ->

How It Works

An AI Agent receives a natural language question about network traffic, runs mmtReader to inspect the packets, and returns a structured answer with visualizations.

flowchart LR
    A[Human question<br/>Which services are slow?] --> B[AI Agent]
    B --> C[mmtReader analyze<br/>-t capture.pcap -a]
    C --> D[Protocol stats<br/>Packet counts, bandwidth,<br/>sessions per protocol]
    D --> E[AI Agent]
    E --> F[Human answer<br/>Plain language + diagram]

The AI Agent handles the translation: raw protocol statistics become plain language with actionable insights.

Agent Workflow

sequenceDiagram
    participant Human as Human
    participant Agent as AI Agent
    participant Reader as mmtReader
    
    Human->>Agent: Which services use the most bandwidth?
    Agent->>Reader: ./mmtReader analyze -t capture.pcap -a --json
    Reader-->>Agent: {protocols: [{name: HTTP, ...}, ...]}
    Agent->>Human: HTTP dominates at 37% of traffic (5.29 MB)

Architecture

[pcap file / network interface]
        │
        ▼
  mmtReader.c (entry point)
  ├── pcap_open_offline() / capture_init()
        │
        ▼
  core/engine.c
  ├── engine_process_packet() — MMT-DPI classification + extraction
  ├── packet_handler() — update counters
  ├── new_ipv4_session_handler() — count sessions
  └── new_ipv6_session_handler() — count sessions
        │
        ▼
  core/engine.c (stats aggregation)
  ├── get_protocol_stats() — per-instance stats
  ├── proto_hierarchy_ids_to_str() — path formatting
  └── insert_proto_info() — sorted linked list
        │
        ▼
  cli/output.c
  ├── output_print_stats_ex() — format and print (TEXT or JSON)
  └── engine_print_pcap_stats() — drop counts
        │
        ▼
  engine_destroy() — cleanup resources

Sample Output

Raw mmtReader output (what the Agent receives):

MMT-SDK 1.8.0 (42cac8b7) - Montimage
Build: Aug 12 2026 18:32:44

Protocol Statistics (with path):
  HTTP          :  5287 pkts,  5967094 data bytes,  5681596 payload bytes
    TCP.HTTP    :  5287 pkts,  5967094 data bytes,  5681596 payload bytes
  MSN           :  3735 pkts,  4259140 data bytes,  4057450 payload bytes
    TCP.MSN     :  3735 pkts,  4259140 data bytes,  4057450 payload bytes
  SSL           :  3090 pkts,  2771386 data bytes,  2604526 payload bytes
    TCP.SSL     :  3090 pkts,  2771386 data bytes,  2604526 payload bytes
  DNS           :   87 pkts,    15154 data bytes,     15154 payload bytes
    UDP.DNS     :   87 pkts,    15154 data bytes,     15154 payload bytes
  ICMP          :   34 pkts,     5078 data bytes,      5078 payload bytes
    ICMP        :   34 pkts,     5078 data bytes,      5078 payload bytes

Protocol Statistics:
  HTTP          :  5287 pkts,  5967094 data bytes,  5681596 payload bytes
  MSN           :  3735 pkts,  4259140 data bytes,  4057450 payload bytes
  SSL           :  3090 pkts,  2771386 data bytes,  2604526 payload bytes
  DNS           :   87 pkts,    15154 data bytes,     15154 payload bytes
  ICMP          :   34 pkts,     5078 data bytes,      5078 payload bytes

Input Statistics:
  Packets      :  14261 packets
  Data Volume  :  9216531 bytes
  Total Sessions: 679 sessions
  Protocols    :  28 protocols
  Duration     :  299 seconds
  Bandwidth    :  30875.60 bytes/sec
  PPS          :  47.77 packets/sec

What the Agent tells the user:

"The capture contains 14,261 packets over 299 seconds (47.77 pps). HTTP is the dominant protocol with 5,287 packets (37% of traffic). MSN Messenger is second at 3,735 packets (26%). SSL/TLS accounts for 3,090 packets (22%). DNS has 87 packets, ICMP has 34. There are 679 total sessions across 28 protocols."

Key Features

Feature	What you get
Natural language interface	Ask questions in plain English
Protocol classification	Identify every protocol in the traffic
Visual output	Mermaid-ready stats for embedding
JSON output	Machine-readable for automation pipelines
Live or offline	Analyze pcap files or monitor live interfaces (Ethernet + WiFi)
Session tracking	Per-protocol IPv4/IPv6 session counts

Quick Start

Build mmtReader:

make build

Run a sample analysis:

./mmtReader analyze -t smallFlows.pcap -a

Install system-wide:

sudo ./install.sh

Usage Examples

Question: "What protocols are in this capture?"

# Agent runs:
./mmtReader analyze -t capture.pcap -a

Output the agent receives:

Protocol Statistics (with path):
  HTTP          :  5287 pkts,  5967094 data bytes,  5681596 payload bytes
    TCP.HTTP    :  5287 pkts,  5967094 data bytes,  5681596 payload bytes
  MSN           :  3735 pkts,  4259140 data bytes,  4057450 payload bytes
    TCP.MSN     :  3735 pkts,  4259140 data bytes,  4057450 payload bytes
  SSL           :  3090 pkts,  2771386 data bytes,  2604526 payload bytes
    TCP.SSL     :  3090 pkts,  2771386 data bytes,  2604526 payload bytes
  DNS           :   87 pkts,    15154 data bytes,     15154 payload bytes
    UDP.DNS     :   87 pkts,    15154 data bytes,     15154 payload bytes
  ICMP          :   34 pkts,     5078 data bytes,      5078 payload bytes
    ICMP        :   34 pkts,     5078 data bytes,      5078 payload bytes

Question: "How much traffic is on port 443?"

# Agent runs with port classification:
./mmtReader analyze -t capture.pcap -a -z 1

Question: "Show me the data in JSON for my dashboard:"

# Agent runs with JSON output:
./mmtReader analyze -t capture.pcap --json -a

JSON output the Agent receives:

{
  "version": "1.8.0 (42cac8b7)",
  "input_stats": {
    "packets": 14261,
    "data_volume": 9216531,
    "duration_seconds": 298.51,
    "bandwidth_bytes_per_sec": 30875.60,
    "packets_per_sec": 47.77,
    "total_sessions": 679,
    "protocols": 28
  },
  "protocol_paths": [
    {"packets": 5287, "data_volume": 5967094, "payload_volume": 5681596, "path": "ethernet.ip.tcp.http"},
    {"packets": 3735, "data_volume": 4259140, "payload_volume": 4057450, "path": "ethernet.ip.tcp.msn"},
    {"packets": 3090, "data_volume": 2771386, "payload_volume": 2604526, "path": "ethernet.ip.tcp.ssl"},
    {"packets": 87, "data_volume": 15154, "payload_volume": 15154, "path": "ethernet.ip.udp.dns"},
    {"packets": 34, "data_volume": 5078, "payload_volume": 3922, "path": "ethernet.ip.icmp"}
  ],
  "protocols": [
    {"name": "http", "packets": 5287, "data_volume": 5967094, "payload_volume": 5681596},
    {"name": "msn", "packets": 3735, "data_volume": 4259140, "payload_volume": 4057450},
    {"name": "ssl", "packets": 3090, "data_volume": 2771386, "payload_volume": 2604526},
    {"name": "dns", "packets": 87, "data_volume": 15154, "payload_volume": 15154},
    {"name": "icmp", "packets": 34, "data_volume": 5078, "payload_volume": 3922}
  ],
  "anomalies": []
}

Live monitoring:

# Agent triggers live capture (Ethernet):
sudo ./mmtReader capture -i eth0 -a -b 100

# Or on a WiFi interface:
sudo ./mmtReader capture -i wlP9s9 -a -s

Classification flags the Agent can toggle:

Flag	Classification	Default	Use case
`-x`	IP address classification	On	Identify services by IP
`-y`	Hostname (SNI) classification	On	Identify by domain name
`-z`	Port number classification	On	Identify by port
`-a`	Show protocol paths	Off	Full hierarchy (TCP.HTTP)
`-s`	Session counts	Off	Per-protocol session tracking
`--json`	JSON output	Off	Machine-readable output
`-F N`	Top flows (capture only)	Off	Report top N sessions by volume

Question: "How much traffic is on port 443?"

# Agent runs with port classification:
./mmtReader analyze -t capture.pcap -a -z 1

Question: "Show me the data in JSON for my dashboard:"

# Agent runs with JSON output:
./mmtReader analyze -t capture.pcap --json -a -s

JSON output the Agent receives:

{
  "version": "1.8.0 (42cac8b7)",
  "input_stats": {
    "packets": 14261,
    "data_volume": 9216531,
    "duration_seconds": 298.51,
    "bandwidth_bytes_per_sec": 30875.60,
    "packets_per_sec": 47.77,
    "total_sessions": 679,
    "protocols": 28
  },
  "protocol_paths": [
    {"packets": 5287, "data_volume": 5967094, "payload_volume": 5681596, "path": "ethernet.ip.tcp.http"},
    {"packets": 3735, "data_volume": 4259140, "payload_volume": 4057450, "path": "ethernet.ip.tcp.msn"},
    {"packets": 3090, "data_volume": 2771386, "payload_volume": 2604526, "path": "ethernet.ip.tcp.ssl"},
    {"packets": 87, "data_volume": 15154, "payload_volume": 15154, "path": "ethernet.ip.udp.dns"},
    {"packets": 34, "data_volume": 5078, "payload_volume": 3922, "path": "ethernet.ip.icmp"}
  ],
  "protocols": [
    {"name": "http", "packets": 5287, "data_volume": 5967094, "payload_volume": 5681596},
    {"name": "msn", "packets": 3735, "data_volume": 4259140, "payload_volume": 4057450},
    {"name": "ssl", "packets": 3090, "data_volume": 2771386, "payload_volume": 2604526},
    {"name": "dns", "packets": 87, "data_volume": 15154, "payload_volume": 15154},
    {"name": "icmp", "packets": 34, "data_volume": 5078, "payload_volume": 3922}
  ],
  "anomalies": []
}

Live monitoring:

# Agent triggers live capture (Ethernet):
sudo ./mmtReader capture -i eth0 -a -b 100

# Or on a WiFi interface:
sudo ./mmtReader capture -i wlP9s9 -a -s

Classification flags the Agent can toggle:

Flag	Classification	Default	Use case
`-x`	IP address fingerprinting	On	Identify services by IP
`-y`	Hostname (SNI) fingerprinting	On	Identify by domain name
`-z`	Port number fingerprinting	On	Identify by port
`-a`	Show protocol paths	Off	Full hierarchy (TCP.HTTP)
`-s`	Session counts	Off	Per-protocol session tracking
`--json`	JSON output	Off	Machine-readable output

Comparison

	mmtReader	Raw pcap analysis	Wireshark
Natural language input	Yes (via AI)	No	No
AI-ready output	JSON + text	Raw bytes	GUI only
Protocol paths	`-a` flag	Manual filtering	Manual filtering
Session tracking	`-s` flag	Manual	Manual
Top flows	`-F N` flag	Manual	Manual
Root required (live)	Yes	Yes	Yes
WiFi support	Yes (auto-convert)	No	No

FAQ

How does the AI Agent use mmtReader?

The agent constructs the appropriate mmtReader command based on the question, runs it, and translates the output into plain language. The --json flag provides structured data for programmatic processing.

Can I use mmtReader without an AI Agent?

Yes. It is a standard CLI tool. Run ./mmtReader analyze -t file.pcap -a for protocol stats, or sudo ./mmtReader capture -i eth0 -a for live monitoring.

What traffic types are supported?

Ethernet (DLT_EN10MB) and WiFi (802.11) traffic. WiFi frames are automatically converted to Ethernet format for DPI processing. Both IPv4 and IPv6 are tracked.

Does mmtReader require root?

Only for live capture (capture subcommand). Analyzing pcap files (analyze subcommand) works without root privileges.

Get Started

Build:

make build

Analyze a pcap file:

./mmtReader analyze -t smallFlows.pcap -a

Live capture:

sudo ./mmtReader capture -i eth0 -a
# or WiFi:
sudo ./mmtReader capture -i wlP9s9 -a

User Guide -> · Architecture -> · Development -> · Apache 2.0 Licensed

Original Technical Documentation (click to expand)

MMT-Reader

Lightweight CLI tool for deep packet inspection and per-protocol network statistics via MMT-DPI.

MMT-Reader analyzes network traffic from pcap capture files or live network interfaces and produces per-protocol statistics including packet counts, data volume, payload volume, and protocol path hierarchies. It leverages the MMT-DPI library for deep packet inspection and protocol classification.

Key Features

Subcommand interface — analyze for pcap files, capture for live interfaces
Dual input modes — Read from pcap files (offline) or live network interfaces (online)
Per-protocol statistics — Packet count, data volume, and payload volume for every detected protocol
Protocol path display — Full DPI path hierarchy (e.g. TCP.HTTP.Google) with the -a/--proto-path flag
Top-flow reporting — Rank the DPI's sessions by volume during a live capture with capture -F/--flows <seconds>: application protocol, client and server endpoints, bytes and packets
JSON output — Machine-readable statistics with --json
Three classification strategies — IP address (-x), hostname (-y), and port (-z) fingerprinting, each independently toggleable
Real-time monitoring — Live capture with configurable buffer size (-b) and kernel/driver drop reporting
IPv4 & IPv6 session tracking — Per-protocol session counts with -s/--sessions
Config file support — INI-style ~/.mmtreader.conf with per-command sections
Environment variables — MMTREADER_JSON, MMTREADER_NO_COLOR, MMTREADER_QUIET
Graceful shutdown — Press Ctrl+C to stop live capture and print final statistics
Modular architecture — Clean separation: engine (core/), CLI parsing (cli/), output rendering (cli/), capture (capture/), config (config/), utilities (utils/)

Installation

System Dependencies

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y build-essential gcc g++ make libpcap-dev libconfuse-dev

RHEL / CentOS / Fedora:

sudo yum group install "Development Tools"
sudo yum install libpcap-devel

MMT-DPI Library

MMT-Reader requires the MMT-DPI library installed at /opt/mmt/dpi/:

/opt/mmt/dpi/
├── include/
│   ├── mmt_core.h
│   └── tcpip/
│       └── mmt_tcpip.h
└── lib/
    ├── libmmt_core.so

Install MMT-DPI following the upstream instructions before compiling.

Compile

make build

Install Globally

Make mmtReader available system-wide with the self-contained installer — it installs everything on a fresh machine:

# Full install: system deps + MMT-DPI + mmtReader (requires root)
sudo ./install.sh

# Install only mmtReader (MMT-DPI must already be present)
sudo ./install.sh --mmt-reader-only

# Custom install prefix (no root needed)
./install.sh --prefix ~/local --mmt-reader-only

# Verify
mmtReader -h

The installer handles:

System dependencies — gcc, make, libpcap-dev, etc.
MMT-DPI library — builds from the sibling mmt-dpi/ repo (or uses a pre-built copy)
mmtReader binary — compiles and installs to your chosen prefix
Man page — installs to man1/ for man mmtReader
Shell completions — installs bash completion to share/bash-completion/completions/

Alternatively, use make (requires MMT-DPI pre-installed):

make build          # compile
sudo make install   # install to /usr/local
sudo make uninstall # remove

Shell Completions

Install shell completions for tab-completion of subcommands, flags, and file paths.

Automatic (via installer)

The install.sh script and make install both install bash completions automatically.

Manual Installation

Bash — copy to your system completions directory:

sudo cp completions/mmtReader.bash /usr/share/bash-completion/completions/mmtReader

Or add to ~/.bashrc:

echo 'source "$(dirname "$(readlink -f "$0")")/completions/mmtReader.bash"' >> ~/.bashrc
source ~/.bashrc

Zsh — copy to your fpath:

mkdir -p ~/.zsh/completions
cp completions/mmtReader.zsh ~/.zsh/completions/_mmtReader
echo 'fpath+=(~/.zsh/completions)' >> ~/.zshrc
source ~/.zshrc

Fish — copy to completions directory:

mkdir -p ~/.config/fish/completions
cp completions/mmtReader.fish ~/.config/fish/completions/mmtReader.fish

Usage

MMT-Reader uses a subcommand-based interface. Available commands:

Subcommand	Description
`analyze`	Analyze a PCAP trace file (offline mode)
`capture`	Capture and analyze live network traffic (online mode)

Global Options

Flag	Argument	Default	Description
`-q, --quiet`	None	0	Suppress progress output
`-v, --verbose`	None	0	Verbose debug output to stderr
`-h, --help`	None	—	Print help and exit
`-V, --version`	None	—	Print version and exit
`-c, --config <file>`	Path	`~/.mmtreader.conf`	Config file for default options
`-C, --no-color`	None	0	Disable ANSI color output
`-x <0	1>`	`1` = enable, `0` = disable	1
`-y <0	1>`	`1` = enable, `0` = disable	1
`-z <0	1>`	`1` = enable, `0` = disable	1

Note: -x, -y, and -z are hidden from --help but fully functional.

`analyze` Subcommand

./mmtReader analyze [OPTIONS]

Flag	Argument	Description
`-t, --trace <file>`	Path to pcap file	Required — analyze a pcap capture file
`-i, --interface <iface>`	Interface name	Live network interface (alternative to `-t`)
`-b, --buffer <MB>`	Buffer size in MB	Pcap handler buffer (default: 50)
`-a, --proto-path`	None	Show per-protocol-path statistics
`-s, --sessions`	None	Show per-protocol session counts
`-j, --json`	None	JSON output format
`-T, --text`	None	Explicit text output (default)
`-c, --config <file>`	Path	Config file (default: `~/.mmtreader.conf`)
`-C, --no-color`	None	Disable ANSI color output

No root privileges required. Reads and replays traffic deterministically.

`capture` Subcommand

./mmtReader capture [OPTIONS]

Flag	Argument	Description
`-i, --interface <iface>`	Interface name	Required — network interface to capture from
`-b, --buffer <MB>`	Buffer size in MB	Pcap handler buffer (default: 50)
`-a, --proto-path`	None	Show per-protocol-path statistics
`-s, --sessions`	None	Show per-protocol session counts
`-F, --flows <seconds>`	Seconds	Capture for N seconds, then print the top sessions by volume (capture only — `analyze` rejects it)
`-j, --json`	None	JSON output format

Requires root/administrator privileges (or setcap on Linux). Supports Ethernet and WiFi interfaces.

Usage Examples

# Analyze a pcap file with protocol paths
./mmtReader analyze -t smallFlows.pcap -a

# Live capture with custom 100 MB buffer
sudo ./mmtReader capture -i eth0 -b 100 -a

# Live capture on a WiFi interface
sudo ./mmtReader capture -i wlP9s9 -a -s

# Disable IP classification (faster, less accurate)
./mmtReader analyze -t capture.pcap -a -x 0

# MMP-only mode (disable all classification)
./mmtReader analyze -t capture.pcap -a -x 0 -y 0 -z 0

# JSON output with session counts
./mmtReader analyze -t capture.pcap --json -s

# Verbose mode with quiet output
./mmtReader analyze -t capture.pcap -v -q

Output Format

MMT-Reader prints four sections at the end of execution:

Protocol statistics with path (if -a is set) — per-path breakdown of packets, volume, and payload
Protocol statistics (aggregated) — per-protocol totals sorted by packet count
Input statistics — summary: packets, data volume, sessions, protocols, duration, bandwidth, pps, fps
PCAP statistics (online mode only) — received packets and kernel/driver drop counts

Project Structure

mmtReader/
├── mmtReader.c        # Thin CLI entry point (~150 lines)
├── mmtReader.1        # Man page
├── Makefile           # Build, install, uninstall targets
├── install.sh         # Self-contained global installer
├── LICENSE            # Apache License 2.0
├── README.md          # This file
├── mmt-reader.png     # Screenshot
├── smallFlows.pcap    # Test pcap
├── CONTRIBUTING.md    # How to contribute
├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1
├── SECURITY.md        # Vulnerability reporting
├── completions/       # Shell completion scripts
│   ├── mmtReader.bash # Bash completion
│   ├── mmtReader.zsh  # Zsh completion
│   └── mmtReader.fish # Fish completion
├── core/
│   ├── engine.c       # MMT-DPI engine: packet processing, stats
│   └── engine.h       # Engine API
├── cli/
│   ├── parse.c/h      # Argument parsing, subcommand dispatch
│   └── output.c/h     # Text/JSON output rendering
├── capture.c/h        # Live pcap capture operations
├── config.c/h         # INI config file support
├── utils/
│   ├── version.c/h    # Version banner and display
│   └── colors.c/h     # ANSI color support
├── tests/
│   ├── test_config.c  # Config file parsing tests
│   ├── test_anomaly.c # Anomaly detection tests
│   ├── test_parse.c   # CLI parsing tests
│   └── test_cli.sh    # Integration tests
└── docs/
    ├── USER_GUIDE.md      # Full CLI reference and examples
    ├── DEVELOPMENT.md     # Build, extend, and debug guide
    ├── ARCHITECTURE.md    # 4-layer architecture diagram
    ├── CHANGELOG.md       # Version history
    ├── CONFIG.md          # Config file reference
    └── TESTING.md         # Test suite guide

Documentation

Document	Description
USER_GUIDE.md	Full CLI reference, output format, usage examples, and troubleshooting
DEVELOPMENT.md	Build instructions, code structure, adding protocol handlers, debugging
ARCHITECTURE.md	4-layer architecture diagram and data flow
CONFIG.md	INI config file reference (`~/.mmtreader.conf`)
TESTING.md	Test suite guide and how to run tests
CHANGELOG.md	Version history and release notes

Related Publications

To be filled in step 5 with links to papers, presentations, or blog posts about MMT-DPI and MMT-Reader.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on reporting bugs, submitting feature requests, and code style conventions.

License

This project is licensed under the Apache License 2.0.

Acknowledgments

MMT-DPI — Deep packet inspection library providing protocol classification and attribute extraction
libpcap — Portable packet capture library
Montimage — Original author and maintainer

For questions or support, contact: contact@montimage.com

Name		Name	Last commit message	Last commit date
.oss-ready		.oss-ready
cli		cli
completions		completions
core		core
docs		docs
skills/mmt-reader		skills/mmt-reader
tests		tests
utils		utils
.gitignore		.gitignore
.gitissue.yml		.gitissue.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Jenkinsfile		Jenkinsfile
LICENSE		LICENSE
Makefile		Makefile
README.backup.md		README.backup.md
README.md		README.md
SECURITY.md		SECURITY.md
capture.c		capture.c
capture.h		capture.h
config.c		config.c
config.h		config.h
flows.c		flows.c
flows.h		flows.h
install.sh		install.sh
mmt-reader.png		mmt-reader.png
mmtReader.1		mmtReader.1
mmtReader.c		mmtReader.c
smallFlows.pcap		smallFlows.pcap
test.pcap		test.pcap

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Ask about network traffic. Get clear answers.

How It Works

Agent Workflow

Architecture

Sample Output

Key Features

Quick Start

Usage Examples

Comparison

FAQ

Get Started

MMT-Reader

Key Features

Installation

System Dependencies

MMT-DPI Library

Compile

Install Globally

Shell Completions

Automatic (via installer)

Manual Installation

Usage

Global Options

analyze Subcommand

capture Subcommand

Usage Examples

Output Format

Project Structure

Documentation

Related Publications

Contributing

License

Acknowledgments

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`analyze` Subcommand

`capture` Subcommand