Documentation (latest)
License
Build Status
PyPI
DOI

• Presentation
• Installation
• Help
• Related tools

Presentation

Mptcpanalyzer is a python tool conceived to help with MPTCP pcap analysis (as mptcptrace for instance).

It accepts packet capture files (*.pcap) as inputs and from there you can:

• list MPTCP connections
• compute statistics on a specific MPTCP connection (list of subflows, reinjections, subflow actual contributions...)
• export a CSV file with MPTCP fields
• plot one way delays
• ...

Commands are self documented with autocompletion. The interpreter with autocompletion that can generate & display plots such as the following:

Table of Contents

Installation

You will need a wireshark version >= 3.0.0 and python >= 3.7

Once wireshark is installed you can install mptcpanalyzer via pip: $ python3 -mpip install mptcpanalyzer --user or try the development version by:

$ git clone https://github.com/teto/mptcpanalyzer.git && cd mptcpanalyzer
$ poetry install    # (or "python3 setup.py develop" if you use pip)

or if you use nix

$ nix develop
$ export PYTHONPATH="$PWD:$PYTHONPATH"

How to use ?

mptcpanalyzer can run into 3 modes:

1. interactive mode (default): an interpreter with some basic completion will accept your commands. There is also some help embedded.
2. if a filename is passed as argument, it will load commands from this file
3. otherwise, it will consider the unknow arguments as one command, the same that could be used interactively

For example, we can load mptcp pcaps (available at wireshark wiki or in this repository examples folder).

Run $ mptcpanalyzer --load examples/iperf-mptcp-0-0.pcap. The script will try to generate a csv file, it can take several seconds depending on the computer/pcap until the prompt shows up. Type ? to list available commands (and their aliases). You have for instance:

• lc (list connections)
• ls (list subflows)
• plot
• ...

help ls will return the syntax of the command, i.e. ls [mptcp.stream] where mptcp.stream is one of the number appearing in lc output.

Look at Examples

Examples

Head to the Wiki for more examples.

Plot One Way Delays from a connection: plot owd tcp examples/client_2_filtered.pcapng 0 examples/server_2_filtered.pcapng 0 --display

Plot tcp sequence numbers in both directions: plot tcp_attr -h

Get a summary of an mptcp connection

> load_pcap examples/server_2_filtered.pcapng
> mptcp_summary 0

Map tcp.stream between server and client pcaps:

>map_tcp_connection examples/client_1_tcp_only.pcap examples/server_1_tcp_only.pcap  0
TODO
>print_owds examples/client_1_tcp_only.pcap examples/server_1_tcp_only.pcap 0 0

Map tcp.stream between server and client pcaps:

> map_mptcp_connection examples/client_2_filtered.pcapng examples/client_2_filtered.pcapng 0
2 mapping(s) found
0 <-> 0.0 with score=inf  <-- should be a correct match
-tcp.stream 0: 10.0.0.1:33782  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 0: 10.0.0.1:33782  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=inf
-tcp.stream 2: 10.0.0.1:54595  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 2: 10.0.0.1:54595  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=inf
-tcp.stream 4: 11.0.0.1:59555  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 4: 11.0.0.1:59555  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=inf
-tcp.stream 6: 11.0.0.1:35589  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 6: 11.0.0.1:35589  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=inf
0 <-> 1.0 with score=0
-tcp.stream 0: 10.0.0.1:33782  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 1: 10.0.0.1:33784  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=30
-tcp.stream 2: 10.0.0.1:54595  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 3: 10.0.0.1:57491  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=30
-tcp.stream 4: 11.0.0.1:59555  <-> 11.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 5: 11.0.0.1:50077  <-> 11.0.0.2:05201  (mptcpdest: Server) with score=30
-tcp.stream 6: 11.0.0.1:35589  <-> 10.0.0.2:05201  (mptcpdest: Server) mapped to tcp.stream 7: 11.0.0.1:50007  <-> 10.0.0.2:05201  (mptcpdest: Server) with score=30

FAQ

Moved to the Wiki

How to contribute

PRs welcome ! See the doc.

Reference

If you plan to use this tool in a publication, You can reference mptcpanalyzer via the following Digital Object Identifier:

or cite:

@inproceedings{Coudron:2019:PAM:3340422.3343638,
 author = {Coudron, Matthieu},
 title = {Passive Analysis for Multipath TCP},
 booktitle = {Proceedings of the Asian Internet Engineering Conference},
 series = {AINTEC '19},
 year = {2019},
 isbn = {978-1-4503-6849-0},
 location = {Phuket, Thailand},
 pages = {25--32},
 numpages = {8},
 url = {http://doi.acm.org/10.1145/3340422.3343638},
 doi = {10.1145/3340422.3343638},
 acmid = {3343638},
 publisher = {ACM},
 address = {New York, NY, USA},
 keywords = {Multipath TCP, passive analysis, reinjection},
}

Related tools

Similar software: