{"id":13650492,"url":"https://github.com/rwhalb/mtraceroute","last_synced_at":"2025-04-22T18:31:44.152Z","repository":{"id":43374898,"uuid":"233140900","full_name":"rwhalb/mtraceroute","owner":"rwhalb","description":"A python3 library for performing an enhanced scapy Multi-Traceroute (MTR) with resulting SVG visual.","archived":false,"fork":false,"pushed_at":"2023-03-06T16:18:25.000Z","size":330,"stargazers_count":51,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-01-24T00:44:21.201Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rwhalb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-01-10T22:29:08.000Z","updated_at":"2024-01-24T00:44:21.202Z","dependencies_parsed_at":"2024-01-03T05:09:50.671Z","dependency_job_id":"4eaa5765-0c5c-4c38-8ca8-247571a2cfaf","html_url":"https://github.com/rwhalb/mtraceroute","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwhalb%2Fmtraceroute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwhalb%2Fmtraceroute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwhalb%2Fmtraceroute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rwhalb%2Fmtraceroute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rwhalb","download_url":"https://codeload.github.com/rwhalb/mtraceroute/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250297382,"owners_count":21407202,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T02:00:37.249Z","updated_at":"2025-04-22T18:31:43.884Z","avatar_url":"https://github.com/rwhalb.png","language":"Python","funding_links":[],"categories":["Tools","Python"],"sub_categories":[],"readme":"# mtraceroute\n\n![Release: 1.36.0](https://img.shields.io/badge/Release-1.36.0-blue) ![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg) ![Python3.7|3.8|3.9|3.10](https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9%20%7C%203.10-blue)\n---\nA python3 library for performing an enhanced [scapy](https://github.com/secdev/scapy) Multi-Traceroute (MTR)\nwith resulting SVG visual.\n\nFeatures include running multiple queries with each target, display of\nRound Trip Time (RTT) calculations, selection of using\nNetwork Protocols: TCP, UDP and ICMP and with enhanced scapy\nSVG visual results and session packet capture output.\n\nThis library is also used by the [Network Security Toolkit](https://www.networksecuritytoolkit.org) (NST).\nThe NST (Web User Interface) WUI provides key enhancements including\na GUI options interface, an interactive MTR SVG graphic,\nNST IPv4 Address Tools integration, IPv4 Address Geolocation,\nMTR session Packet Capture, ASN lookup,\nMTR historical session selection and management,\nMTR SVG graphic editing, MTR session console output access\nand SVG Graphic image conversion.\n\n[Details found on the NST Wiki](https://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Use_The_Scapy:_Multi-Traceroute_-_MTR)\n\n\n## Installation\n### Pipy\n\n```\nTODO\npip3 install mtraceroute\n```\n\n### Manual\n\n```\npython3.9 -m venv ./venv\nsource ./venv/bin/activate\npip3 install -r requirements.txt\npython3 setup.py install\n```\n\n## Usage ##\n\nUse the python3 control script: \"mtrrt\" to help facilitate the creation of a\nMulti-Traceroute (MTR) session.\n\n```\nmtrrt --help\n\n*** The mtrrt script performs a Multi-Traceroute (MTR) using scapy - v1.36.0 ***\n\nmtrrt -t || --targets \u003cTarget Host List\u003e [-r || --retry \u003cRetry\u003e] [--timeout \u003cFractional Seconds\u003e]\n             [--netproto \u003cNetwork Protocol\u003e] [--stype \u003cType\u003e [--sport \u003cSource Port\u003e]]\n             [-p || --dports \u003cDestination Service Ports\u003e]\n             [--minttl \u003cMin TTL\u003e] [--maxttl \u003cMax TTL\u003e] [--gateway \u003cIPv4 Address\u003e]\n             [-g || --graphic \u003cGraphic Type\u003e] [-s || --showpadding] [--privaddr] [--dotfile]\n             [-f || --dirfile \u003cSVG Directory File Name\u003e] -i | --interface \u003cInterface Name\u003e [--l3rawsocket]\n             [--ptype \u003cType\u003e [--payload \u003cPayload\u003e]]\n             [-q || --nquery \u003cQuery Trace Count\u003e] [-w || --wrpcap \u003cpcap Directory File Name\u003e]\n             [-a || --asnresolver \u003cASN Resolver\u003e] [ --vspread \u003cVertical Node Separation\u003e] [--rtt]\n             [--title \u003cTitle Text\u003e] [--ts \u003cTitle Time Stamp\u003e] [-v || --verbose \u003clevel\u003e] [-h || --help]\n\n* Where \u003cTarget Host List\u003e and \u003cDestination Ports\u003e are a comma separated string. The \u003cTarget Host List\u003e can be in CIDR notation format.\n* Use the (--netproto) option to specify the MTR Network Protocol (Must be one of: \"TCP\" (Default), \"UDP\", or \"ICMP\").\n* Use the (--stype) option to choose the source port type: \"Random\" (Default) or \"Increment\".\n* Use the (--sport) option to specify a source port (Default: 50000) for source port type: \"Increment\".\n  If the source port type: \"--stype Increment\" is used, then the source port will be increased by one (1) for\n  each packet sent out during an MTR session.\n* Use the (--ptype) option to choose the a packet payload type: \"Disabled\" (TCP Default) \"RandStrTerm\" (UDP Default),\n \"RandStr\" (ICMP Default), \"ASCII\" or \"ASCII-Hex\".\n* Use the (--payload) option for a ASCII string value (e.g., 'Data1: 56\\n') for ptype: \"ASCII\".\n* Use the (--payload) option for a ASCII-Hex string value (e.g., '01fe44fFEf') for ptype: \"ASCII-Hex\".\n  The \"--payload ASCII-Hex\" option must use 2 ASCII characters to represent one Hexadecimal byte: \"f\" =\u003e \"0F\" or \"0f\".\n* To add additional TCP destination service ports for tracerouting: \"80,443\" (Default: \"80\").\n* Use the (-s || --showpadding) to display packets with padding as red triangles.\n* The (-a || --asnresolver) option can be: \"Disabled\", \"All\", \"whois.cymru.com\", \"riswhois.ripe.net\" or \"whois.ra.net\".\n* Use the (--privaddr) option to disable showing an associated AS Number bound box (cluster)\n  on the Multi-Traceroute graph for a private IPv4 Address.\n* Use the (--timeout) option to limit the time waiting for a Hop packet response (Default: 2.0 seconds).\n* Use the (-q || --nquery) count for the number of traces to perform per service target (Default: 1).\n* The default graphic type is an SVG graphic: \"svg\".\n* The default directory file name for the resulting mtr graphic: \"/tmp/graph.svg\".\n* Use the (-f || --dirfile) option to change the resulting output directory:\n  Example: \"-f /var/nst/wuiout/scapy/graph.svg\" - Output directory: \"/var/nst/wuiout/scapy\".\n* The default Network Interface will be used to send out the traceroute unless the (-i || --interface) option is used.\n* Use the (--gateway) option to override the detected gateway address.\n* Increase the verbosity output with a level of 1 or more (Default: 0).\n* Use the (--dotfile) option to dump the mtr DOT graph object to a file (.dot file) in the output directory.\n* Use the (--vspread) option to set the Vertical Separation in inches between nodes (Default: 0.75in).\n* Use the (--rtt) option to display Round-Trip Times (msec) on the graphic for each Hop along a Traceroute.\n* Use the (--title) option to override the default Title value: \"Multi-Traceroute (MTR) Probe\".\n* Use the (--ts) option to include the Title Time Stamp text below the Title Text.\n* Include internal mtr object variables in output at verbosity level: 8.\n* Include trace packet dump output at verbosity level: 9 (***Warning: A large text output may occur).\n\n*** Example:\nmtrrt -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;\n```\n\n## Example Runs\nShown are 3 use cases: A simple one, one more complex and a CIDR trace route.\n\n### Simple Run\nA single TCP trace route from private host: 10.222.222.10 to target: [www.google.com](https://www.google.com) port: https (443).\nThis run creates a resultant SVG trace route graphic and packet capture in directory: \"/tmp\".\n\n```\nmtrrt \\\n  --targets 'www.google.com' \\\n  --dirfile '/tmp/scapy-mtr_2020-02-18_16-56-30.svg' --nquery 1 --interface 'lan0' \\\n  --netproto 'TCP' --dports '443' --wrpcap '/tmp/scapy-mtr_2020-02-18_16-56-30.pcap' \\\n  --retry 0 --minttl 1 --maxttl 30 --asnresolver 'All' --verbose 1 \\\n  --stype 'Random' --dotfile --rtt --privaddr --ptype 'Disabled' \\\n  --vspread 0.75 --title 'Multi-Traceroute (MTR) Probe' --ts '2020-02-18 16:56:30' --timeout 2 2\u003e\u00261;\n```\n\n![Simple Run](example_runs/scapy-mtr_2020-02-18_16-56-30.svg)\n\n### Complex Run\nA 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.\nThis run creates a resultant SVG trace route graphic and packet capture in directory: \"/tmp\".\n\n__Note: To zoom in on the graphic below just open the image in a new tab.__ \n\n```\nmtrrt \\\n  --targets 'www.google.com,openwrt.org' \\\n  --dirfile '/tmp/scapy-mtr_2020-02-18_17-00-04.svg' --nquery 3 --interface 'lan0' \\\n  --netproto 'TCP' --dports '80, 443' --wrpcap '/tmp/scapy-mtr_2020-02-18_17-00-04.pcap' \\\n  --retry 0 --minttl 1 --maxttl 30 --asnresolver 'All' --verbose 1 \\\n  --stype 'Random' --dotfile --showpadding --rtt --privaddr --ptype 'Disabled' \\\n  --vspread 0.75 --title 'Multi-Traceroute (MTR) Probe' --ts '2020-02-18 17:00:04' --timeout 2 2\u003e\u00261;\n```\n\n![Complex Run](example_runs/scapy-mtr_2020-02-18_17-00-04.svg)\n\n### CIDR Run\nA 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 \u003e 1) and CIDR address notation format can help expose load balancing tiers.\nThis run creates a resultant SVG trace route graphic and packet capture in directory: \"/tmp\".\n\n__Note: To zoom in on the graphic below just open the image in a new tab.__ \n\n```\nmtrrt \\\n  --targets 'www.google.com/30' \\\n  --dirfile '/tmp/scapy-mtr_2020-02-18_17-04-55.svg' --nquery 3 --interface 'lan0' \\\n  --netproto 'TCP' --dports '443' --wrpcap '/tmp/scapy-mtr_2020-02-18_17-04-55.pcap' \\\n  --retry 0 --minttl 1 --maxttl 30 --asnresolver 'All' --verbose 1 \\\n  --stype 'Random' --dotfile --rtt --privaddr --ptype 'Disabled' \\\n  --vspread 0.75 --title 'Multi-Traceroute (MTR) Probe' --ts '2020-02-18 17:04:55' --timeout 2 2\u003e\u00261;\n```\n\n![Complex Run](example_runs/scapy-mtr_2020-02-18_17-04-55.svg)\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frwhalb%2Fmtraceroute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frwhalb%2Fmtraceroute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frwhalb%2Fmtraceroute/lists"}