Documentation (latest) | |
Documentation (stable) | |
License | |
Build Status | |
PyPI | |
DOI | ย |
Mptcpanalyzer is a python (>=3.6) tool conceived to help with MPTCP pcap analysis (as mptcptrace for instance). It is tested on linux only.
It accepts as input a capture file (.pcap or .pcapng) and from there generates a CSV file (thanks to tshark, the terminal version of wireshark) with the MPTCP fields required for analysis. From there you can:
- list MPTCP connections
- compute statistics on a specific MPTCP connection (list of subflows, reinjections, subflow actual contributions...) It accepts as input a capture file (*.pcap) and depending on from there can :
- export a CSV file with MPTCP fields
- plot data sequence numbers for all subflows
- plot DSN interarrival times
- See Features for more
Most commands are self documented and/or with autocompletion.
Then you have an interpreter with autocompletion that can generate & display plots such as the following:
You can reference mptcpanalyzer via the following Digital Object Identifier:
First of all you will need a wireshark version that supports my MPTCP patches. See the next section to check for requirements.
Once wireshark is installed you can install mptcpanalyzer via pip:
$ python3 -mpip install mptcpanalyzer --user
python3.6 is mandatory since we rely on its type hinting features. Dependancies are (some will be made optional in the future):
- stevedore to handle the plugins architecture
- the data analysis library pandas >= 0.17.1
- lnumexpr to run specific queries in pandas
- matplotlib to plot graphs
- cmd2 to generate the command line
None pending \o/
You will need a wireshark version that contains:
mptcpanalyzer can run into 3 modes:
- interactive mode (default): an interpreter with some basic completion will accept your commands. There is also some help embedded.
- if a filename is passed as argument, it will load commands from this file
- otherwise, it will consider the unknow arguments as one command, the same that could be used interactively
For example, we can load an mptcp pcap (I made one available on [wireshark wiki] (https://wiki.wireshark.org/SampleCaptures#MPTCP) or in this repository, in the examples folder).
Run $ mptcpanalyzer --load examples/iperf-mptcp-0-0.pcap
. The script will try to generate
a csv file, it can take a few minutes depending on the computer/pcap until the promt 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
From simple to hardcore:
- Mptcpanalyzer itself proposes few flags to customize plots: --title to override the default title and --style. You can set several --style at the same time, they are passed to matplotlib and as such allow for a wide Matplotlib customization.
- Some commands can export datasets to a machine readable format such as --csv/--json. Else you can look in mptcpanalyzer cache for the full csv file yourself.
- Mptcpanalyzer can automatically load (plot) plugins. See the doc.
- Your last hope is to fork the project. Have fun !
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
Get a summary of an mptcp connection
> load_pcap examples/server_2_filtered.pcapng
> 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
See the doc.
- use configobj to load config defaults/validation ?
- as in mptcpplot plot some events (e.g., MP_JOIN) differently ?
- choose colors of subflows
- Why packets ids don't match the frame.number from my pcap ? mptcpanalyzer
If I have forgotten about your tool, file an issue, for know we are aware of:
- mptcptrace with some examples here
- mptcpplot with generated output example