Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rwhalb/mtraceroute
A python3 library for performing an enhanced scapy Multi-Traceroute (MTR) with resulting SVG visual.
https://github.com/rwhalb/mtraceroute
Last synced: 7 days ago
JSON representation
A python3 library for performing an enhanced scapy Multi-Traceroute (MTR) with resulting SVG visual.
- Host: GitHub
- URL: https://github.com/rwhalb/mtraceroute
- Owner: rwhalb
- License: gpl-2.0
- Created: 2020-01-10T22:29:08.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-06T16:18:25.000Z (over 1 year ago)
- Last Synced: 2024-01-24T00:44:21.201Z (10 months ago)
- Language: Python
- Size: 322 KB
- Stars: 51
- Watchers: 4
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-scapy - mtraceroute - Create cool graphs over multiple traceroute analysis. (Tools)
README
# mtraceroute
  
---
A python3 library for performing an enhanced [scapy](https://github.com/secdev/scapy) Multi-Traceroute (MTR)
with resulting SVG visual.
Features include running multiple queries with each target, display of
Round Trip Time (RTT) calculations, selection of using
Network Protocols: TCP, UDP and ICMP and with enhanced scapy
SVG visual results and session packet capture output.
This library is also used by the [Network Security Toolkit](https://www.networksecuritytoolkit.org) (NST).
The NST (Web User Interface) WUI provides key enhancements including
a GUI options interface, an interactive MTR SVG graphic,
NST IPv4 Address Tools integration, IPv4 Address Geolocation,
MTR session Packet Capture, ASN lookup,
MTR historical session selection and management,
MTR SVG graphic editing, MTR session console output access
and SVG Graphic image conversion.
[Details found on the NST Wiki](https://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Use_The_Scapy:_Multi-Traceroute_-_MTR)
## Installation
### Pipy
```
TODO
pip3 install mtraceroute
```
### Manual
```
python3.9 -m venv ./venv
source ./venv/bin/activate
pip3 install -r requirements.txt
python3 setup.py install
```
## Usage ##
Use the python3 control script: "mtrrt" to help facilitate the creation of a
Multi-Traceroute (MTR) session.
```
mtrrt --help
*** The mtrrt script performs a Multi-Traceroute (MTR) using scapy - v1.36.0 ***
mtrrt -t || --targets [-r || --retry ] [--timeout ]
[--netproto ] [--stype [--sport ]]
[-p || --dports ]
[--minttl ] [--maxttl ] [--gateway ]
[-g || --graphic ] [-s || --showpadding] [--privaddr] [--dotfile]
[-f || --dirfile ] -i | --interface [--l3rawsocket]
[--ptype [--payload ]]
[-q || --nquery ] [-w || --wrpcap ]
[-a || --asnresolver ] [ --vspread ] [--rtt]
[--title ] [--ts ] [-v || --verbose ] [-h || --help]
* Where and are a comma separated string. The can be in CIDR notation format.
* Use the (--netproto) option to specify the MTR Network Protocol (Must be one of: "TCP" (Default), "UDP", or "ICMP").
* Use the (--stype) option to choose the source port type: "Random" (Default) or "Increment".
* Use the (--sport) option to specify a source port (Default: 50000) for source port type: "Increment".
If the source port type: "--stype Increment" is used, then the source port will be increased by one (1) for
each packet sent out during an MTR session.
* Use the (--ptype) option to choose the a packet payload type: "Disabled" (TCP Default) "RandStrTerm" (UDP Default),
"RandStr" (ICMP Default), "ASCII" or "ASCII-Hex".
* Use the (--payload) option for a ASCII string value (e.g., 'Data1: 56\n') for ptype: "ASCII".
* Use the (--payload) option for a ASCII-Hex string value (e.g., '01fe44fFEf') for ptype: "ASCII-Hex".
The "--payload ASCII-Hex" option must use 2 ASCII characters to represent one Hexadecimal byte: "f" => "0F" or "0f".
* To add additional TCP destination service ports for tracerouting: "80,443" (Default: "80").
* Use the (-s || --showpadding) to display packets with padding as red triangles.
* The (-a || --asnresolver) option can be: "Disabled", "All", "whois.cymru.com", "riswhois.ripe.net" or "whois.ra.net".
* Use the (--privaddr) option to disable showing an associated AS Number bound box (cluster)
on the Multi-Traceroute graph for a private IPv4 Address.
* Use the (--timeout) option to limit the time waiting for a Hop packet response (Default: 2.0 seconds).
* Use the (-q || --nquery) count for the number of traces to perform per service target (Default: 1).
* The default graphic type is an SVG graphic: "svg".
* The default directory file name for the resulting mtr graphic: "/tmp/graph.svg".
* Use the (-f || --dirfile) option to change the resulting output directory:
Example: "-f /var/nst/wuiout/scapy/graph.svg" - Output directory: "/var/nst/wuiout/scapy".
* The default Network Interface will be used to send out the traceroute unless the (-i || --interface) option is used.
* Use the (--gateway) option to override the detected gateway address.
* Increase the verbosity output with a level of 1 or more (Default: 0).
* Use the (--dotfile) option to dump the mtr DOT graph object to a file (.dot file) in the output directory.
* Use the (--vspread) option to set the Vertical Separation in inches between nodes (Default: 0.75in).
* Use the (--rtt) option to display Round-Trip Times (msec) on the graphic for each Hop along a Traceroute.
* Use the (--title) option to override the default Title value: "Multi-Traceroute (MTR) Probe".
* Use the (--ts) option to include the Title Time Stamp text below the Title Text.
* Include internal mtr object variables in output at verbosity level: 8.
* Include trace packet dump output at verbosity level: 9 (***Warning: A large text output may occur).
*** Example:
mtrrt -t "www.google.com,www.networksecuritytoolkit.org" -r 0 --timeout 3.5 --netproto "TCP" -p "80,443" --minttl 1 --maxttl 20 -q 2 -a "All" --vspread 0.60 --rtt -v 1;
```
## Example Runs
Shown are 3 use cases: A simple one, one more complex and a CIDR trace route.
### Simple Run
A single TCP trace route from private host: 10.222.222.10 to target: [www.google.com](https://www.google.com) port: https (443).
This run creates a resultant SVG trace route graphic and packet capture in directory: "/tmp".
```
mtrrt \
--targets 'www.google.com' \
--dirfile '/tmp/scapy-mtr_2020-02-18_16-56-30.svg' --nquery 1 --interface 'lan0' \
--netproto 'TCP' --dports '443' --wrpcap '/tmp/scapy-mtr_2020-02-18_16-56-30.pcap' \
--retry 0 --minttl 1 --maxttl 30 --asnresolver 'All' --verbose 1 \
--stype 'Random' --dotfile --rtt --privaddr --ptype 'Disabled' \
--vspread 0.75 --title 'Multi-Traceroute (MTR) Probe' --ts '2020-02-18 16:56:30' --timeout 2 2>&1;
```
### Complex Run
A more complex TCP trace route from private host: 10.222.222.10 to targets: [www.google.com](https://www.google.com), [openwrt.org](https://openwrt.org) ports: http (80), https (443). Packets returned with padding are also shown.
This run creates a resultant SVG trace route graphic and packet capture in directory: "/tmp".
__Note: To zoom in on the graphic below just open the image in a new tab.__
```
mtrrt \
--targets 'www.google.com,openwrt.org' \
--dirfile '/tmp/scapy-mtr_2020-02-18_17-00-04.svg' --nquery 3 --interface 'lan0' \
--netproto 'TCP' --dports '80, 443' --wrpcap '/tmp/scapy-mtr_2020-02-18_17-00-04.pcap' \
--retry 0 --minttl 1 --maxttl 30 --asnresolver 'All' --verbose 1 \
--stype 'Random' --dotfile --showpadding --rtt --privaddr --ptype 'Disabled' \
--vspread 0.75 --title 'Multi-Traceroute (MTR) Probe' --ts '2020-02-18 17:00:04' --timeout 2 2>&1;
```
### CIDR Run
A TCP trace route from private host: 10.222.222.10 to [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) targets: [www.google.com/30](https://www.google.com) port: https (443). The use of multiple queries (i.e., --nquery > 1) and CIDR address notation format can help expose load balancing tiers.
This run creates a resultant SVG trace route graphic and packet capture in directory: "/tmp".
__Note: To zoom in on the graphic below just open the image in a new tab.__
```
mtrrt \
--targets 'www.google.com/30' \
--dirfile '/tmp/scapy-mtr_2020-02-18_17-04-55.svg' --nquery 3 --interface 'lan0' \
--netproto 'TCP' --dports '443' --wrpcap '/tmp/scapy-mtr_2020-02-18_17-04-55.pcap' \
--retry 0 --minttl 1 --maxttl 30 --asnresolver 'All' --verbose 1 \
--stype 'Random' --dotfile --rtt --privaddr --ptype 'Disabled' \
--vspread 0.75 --title 'Multi-Traceroute (MTR) Probe' --ts '2020-02-18 17:04:55' --timeout 2 2>&1;
```
---