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
  └── flows.c: flows_packet_handler() — record the session (-F only)
        │
        ▼
  core/engine.c (stats aggregation)
  ├── engine_get_stats() — totals read back from MMT-DPI
  ├── get_protocol_stats() — per-instance stats
  ├── proto_hierarchy_to_str() — path formatting (MMT-DPI)
  └── proto_info_insert() — sorted linked list
        │
        ▼
  cli/output.c
  └── output_print_stats_ex() — format and print (TEXT or JSON)
        │
        ▼
  engine_destroy() — cleanup resources

Sample Output

Raw mmtReader output (what the Agent receives) — abridged: the classification preamble on stderr is omitted and the protocol tables show a representative subset of the 37 paths / 28 protocols (every number below is exact):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|		 MONTIMAGE
|	 mmtReader version: 0.4.0
|	 MMT-DPI SDK version: 1.8.0 (42cac8b7)
|	 ./mmtReader: built Aug 27 2026 12:15:56
|	 http://montimage.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - - - MMT-READER STATS - - - - -

Protocol statistics with the protocol path:

	#pkts	#volume	#payload	#proto_path
      5287    5967094    5681596                                         ethernet.ip.tcp.http
      3515    4204044    4014234                                     ethernet.ip.tcp.http.msn
      3090    2771386    2604526                                          ethernet.ip.tcp.ssl
        87      15154      11500                                          ethernet.ip.udp.dns
        34       5078       3922                                             ethernet.ip.icmp
      ...        ...        ...                                                           ...

Protocol statistics:

	#pkts	#volume	#payload	#proto_name
     14261    9216531    9216531 ethernet
     14243    9215613    9016211 ip
     13708    9135182    8669110 tcp
      5287    5967094    5681596 http
      3735    4259140    4057450 msn
      3090    2771386    2604526 ssl
       501      75353      58319 udp
        87      15154      11500 dns
        34       5078       3922 icmp
      ...        ...        ... ...

>>>>>> INPUT STATISTICS <<<<<< 

	Packets: 14261
	Data: 9216531 bytes
	Total Sessions: 679
	Protocols: 28
	Duration: 299 seconds
	Bandwidth: 30875.60 bytes/second
	pps: 47.77 packets/second
	fps: 2.27 sessions/second

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 the protocol path:

	#pkts	#volume	#payload	#proto_path
      5287    5967094    5681596                                         ethernet.ip.tcp.http
      3515    4204044    4014234                                     ethernet.ip.tcp.http.msn
      3090    2771386    2604526                                          ethernet.ip.tcp.ssl
        87      15154      11500                                          ethernet.ip.udp.dns
        34       5078       3922                                             ethernet.ip.icmp
      ...        ...        ...                                                           ...

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": {
    "mmtreader": "0.4.0",
    "mmt_dpi": "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": 3515, "data_volume": 4204044, "payload_volume": 4014234, "path": "ethernet.ip.tcp.http.msn"},
    {"packets": 3090, "data_volume": 2771386, "payload_volume": 2604526, "path": "ethernet.ip.tcp.ssl"},
    {"packets": 87, "data_volume": 15154, "payload_volume": 11500, "path": "ethernet.ip.udp.dns"},
    {"packets": 34, "data_volume": 5078, "payload_volume": 3922, "path": "ethernet.ip.icmp"}
  ],
  "protocols": [
    {"name": "ethernet", "packets": 14261, "data_volume": 9216531, "payload_volume": 9216531},
    {"name": "ip", "packets": 14243, "data_volume": 9215613, "payload_volume": 9016211},
    {"name": "tcp", "packets": 13708, "data_volume": 9135182, "payload_volume": 8669110},
    {"name": "http", "packets": 5287, "data_volume": 5967094, "payload_volume": 5681596},
    {"name": "msn", "packets": 3735, "data_volume": 4259140, "payload_volume": 4057450}
  ],
  "anomalies": []
}

protocol_paths and protocols are abridged above — a full run on smallFlows.pcap reports 37 paths and 28 protocols.

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 (`ethernet.ip.tcp.http`)
`-s`	Session counts	Off	Per-protocol session tracking
`--json`	JSON output	Off	Machine-readable output
`-F <seconds>`	Top flows (capture only)	Off	Capture for N seconds, then print the top sessions by volume

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. ethernet.ip.tcp.http.msn) 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, or any file named with -c/--config
Environment variables — MMTREADER_JSON, MMTREADER_NO_COLOR, MMTREADER_QUIET
One precedence rule — compiled defaults < ~/.mmtreader.conf < --config file < environment < CLI flags
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 make libpcap-dev jq

RHEL / CentOS / Fedora:

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

jq (≥ 1.7) is a test-time requirement only: make test pipes the tool's JSON output through it. It is not needed to build or run mmtReader itself.

There is no configuration-library dependency — config.c implements its own INI parser, so no external config library is required or linked.

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.

Minimum version: 1.8.0. The build aborts with an explicit error when the installed SDK is missing or older (make check-sdk).

Compile

make build

make first runs check-sdk (aborting when the SDK is missing or older than 1.8.0), then compiles all nine sources in one gcc invocation with -g -O2 -Wall -Wextra and -DMMTREADER_VERSION='"0.4.0"' — the warning gate lives in its own WARNFLAGS variable so a make CFLAGS=... override cannot disable it, and the -D injects mmtReader's product version separately from the MMT-DPI SDK version:

MMT-DPI SDK 1.8.0 OK
cc -g -O2 -Wall -Wextra -DMMTREADER_VERSION='"0.4.0"' -o mmtReader mmtReader.c core/engine.c ...

Test

make clean && make test

Runs 14 numbered test groups (plus sub-groups 2b and 5b): 299 unit asserts, 52/52 CLI integration checks, and 6/6 SDK-check assertions, ending with All tests passed!. One skip is expected under an unprivileged run — live capture on lo needs root or cap_net_raw. Requires jq. See docs/TESTING.md for the per-group breakdown.

Coverage

make coverage

Reruns the test suite with the unit-test binaries instrumented via --coverage and prints a per-source line/branch coverage summary using plain gcov (gcovr/lcov are not required). The default build is untouched — instrumentation applies only to the unit-test binaries; gcov artifacts (.gcno/.gcda/.gcov) are removed when the target finishes.

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 (~280 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
├── CHANGELOG.md       # Live changelog (incl. [Unreleased])
├── 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
├── flows.c/h          # Top-flow tracking and reporting (capture -F)
├── config.c/h         # INI config file support (hand-rolled parser)
├── utils/
│   ├── version.c/h    # Version banner and display
│   └── colors.c/h     # ANSI color support
├── tests/             # Unit suites + CLI integration script
│   ├── test_config.c  # Config file parsing tests
│   ├── test_anomaly.c # Anomaly detection tests
│   ├── test_parse.c   # CLI parsing tests
│   ├── test_wifi.c    # 802.11 → Ethernet conversion tests
│   ├── test_flows.c   # Top-flow reporting tests
│   ├── test_capture_dispatch.c # Capture dispatch tests
│   ├── test_engine_output.c    # Engine output tests
│   ├── test_engine_stats.c     # Engine statistics tests
│   ├── test_sdk_check.sh       # SDK version gate tests
│   └── test_cli.sh    # CLI 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       # Historical release notes
    ├── CONFIG.md          # Config file reference
    ├── PLAYBOOK.md        # End-to-end agent workflows
    ├── DECISIONS.md       # Architecture decision log
    └── 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
PLAYBOOK.md	End-to-end agent workflows and JSON recipes
CHANGELOG.md	Live changelog, including the `[Unreleased]` section
docs/CHANGELOG.md	Historical release notes (0.1.0–0.4.0)

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
.github/workflows		.github/workflows
.oss-ready		.oss-ready
ci		ci
cli		cli
completions		completions
core		core
docs		docs
skills/mmt-reader		skills/mmt-reader
tests		tests
utils		utils
.gitignore		.gitignore
.gitissue.yml		.gitissue.yml
AGENTS.md		AGENTS.md
AGENT_ENVIRONMENT.md		AGENT_ENVIRONMENT.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Jenkinsfile		Jenkinsfile
LICENSE		LICENSE
Makefile		Makefile
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

Test

Coverage

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