scamper — interact with scamper processes and data


Introduction

scamper is a tool that actively probes the Internet in order to analyze Internet topology and performance. The scamper tool provides rich functionality, this scamper module provides convenient classes and methods for interacting with scamper processes and data. The module has two related halves – those for interacting with running scamper processes (through ScamperCtrl and related classes) and those for reading and writing data previously collected with scamper (ScamperFile). These classes are supported by other classes that store measurement results. The types of measurements supported by this module include ping, traceroute, alias resolution, DNS queries, HTTP, UDP probes, and packet capture.

Interacting with Scamper Processes

Simple Parallel Measurement

The following example implements the well-known single-radius measurement technique, which conducts delay measurements to an IP address from a distributed set of vantage points, and reports the shortest of all the observed delays with the name of the vantage point that observed the delay. The ScamperCtrl object is instantiated with a single parameter that identifies a directory that contains a set of Unix domain sockets, each of which represents a vantage point running scamper; the ScamperCtrl object makes these vantage points available via instances(), which the caller uses to conduct a ping measurement via each of them. These ping measurements operate in parallel – the ping measurements on each of the nodes operate asynchronously. We then collect the results of the measurements, noting the minimum observed delay, and the vantage point where it came from. We pass a 10-second timeout to responses() so that if a vantage point experiences an outage after we send the measurements, it would not hold up the whole experiment. Finally, we print the result of the measurement.

import sys
from datetime import timedelta
from scamper import ScamperCtrl

if len(sys.argv) != 3:
  print("usage: single-radius.py $dir $ip")
  sys.exit(-1)

ctrl = ScamperCtrl(remote_dir=sys.argv[1])
for i in ctrl.instances():
  ctrl.do_ping(sys.argv[2], inst=i)

min_rtt = None
min_vp = None
for o in ctrl.responses(timeout=timedelta(seconds=10)):
  if o.min_rtt is not None and (min_rtt is None or min_rtt > o.min_rtt):
    min_rtt = o.min_rtt
    min_vp = o.inst

if min_rtt is not None:
  print(f"{min_vp.name} {(min_rtt.total_seconds()*1000):.1f} ms")
else:
  print(f"no responses for {sys.argv[2]}")

Reactive Measurement

The next example shows a more complex measurement. Let’s say we want to know the RTTs to the authoritative name servers for a zone from a single vantage point. This implementation takes two parameters – a single vantage point, and a zone name to study. We open an interface to that VP, and then issue a DNS query for the authoritative name servers for the zone from that VP. There are a couple of interesting things to note. First, we do not pass a handle representing the VP instance to the do_dns() method, as the ScamperCtrl interface only has a single instance associated with it – it is smart enough to use that single instance for the measurement. Second, we pass sync = True to make the measurement synchronous – the method does not return until it has the results of that single measurement. This is shorter (in terms of lines of code) and more readable than issuing an asynchronous measurement and then collecting the single result. Then, we issue asynchronous queries for the IPv4 and IPv6 addresses for the name servers returned and send ping measurements for each of the addresses. Finally, we print the names of the nameservers, their IP addresses, and the minimum RTT observed to each.

import sys
from datetime import timedelta
from scamper import ScamperCtrl

if len(sys.argv) != 3:
  print("usage: authns-delay.py $vp $zone")
  sys.exit(-1)

ctrl = ScamperCtrl(remote=sys.argv[1])

# get the list of NS for the zone
o = ctrl.do_dns(sys.argv[2], qtype='NS', wait_timeout=1, sync=True)

# issue queries for the IP addresses of the authoritative servers
ns = {}
for rr in o.ans():
  if rr.ns is not None and rr.ns not in ns:
    ns[rr.ns] = 1
    ctrl.do_dns(rr.ns, qtype='A', wait_timeout=1)
    ctrl.do_dns(rr.ns, qtype='AAAA', wait_timeout=1)

# collect the unique addresses out of the address lookups
addr = {}
for o in ctrl.responses(timeout=timedelta(seconds=3)):
  for a in o.ans_addrs():
    addr[a] = o.qname

# collect RTTs for the unique IP addresses
for a in addr:
  ctrl.do_ping(a)
for o in ctrl.responses(timeout=timedelta(seconds=10)):
  print(f"{addr[o.dst]} {o.dst} " +
        (f"{(o.min_rtt.total_seconds() * 1000):.1f}"
         if o.min_rtt is not None else "???"))

Dynamic Event-driven Measurement

The module also supports a more dynamic approach to interacting with many vantage points that each signal their desire for more work. The following code maintains a list of addresses per vantage point to ping. The vps dictionary maintains a mapping of ScamperInst to that list of addresses. When each instance signals that it is ready for more work, the morecb is called, with the overall ScamperCtrl, the specific ScamperInst that wants another measurement, and the param specified to the ScamperCtrl constructor.

import sys
from scamper import ScamperCtrl
from datetime import timedelta

@staticmethod
def _feedme(ctrl, inst, vps):
  if len(vps[inst]) == 0:
    inst.done()
  else:
    ctrl.do_ping(vps[inst].pop(0), inst=inst)

@staticmethod
def _main(vps):
  vps = {}
  ctrl = ScamperCtrl(morecb=_feedme, param=vps)
  for vp in vps:
    inst = ctrl.add_remote(vp)
    vps[inst] = ["192.0.2.1", "192.0.2.2", "192.0.2.3"]

  # issue measurements as each VP asks for a new measurement
  while not ctrl.is_done():
    o = None
    try:
      o = ctrl.poll(timeout=timedelta(seconds=10))
    except Exception as e:
      print(f"got exception {e}")
      continue

    # if ctrl.poll() returns None, either all measurements are
    # complete, or we timed out.  say what happened.
    if o is None:
      if ctrl.is_done():
        print("done")
      else:
        print("timed out")
      break

    print(f"{o.inst.name} {o.dst} {o.min_rtt}")

  return 0

if __name__ == "__main__":
  sys.exit(_main(sys.argv[1:]))

The module supports many different types of measurements:

  1. Traceroute via do_trace()

  2. Ping via do_ping()

  3. Alias resolution via do_ally(), do_mercator(), do_midarest(), do_midardisc(), do_prefixscan(), and do_radargun()

  4. DNS via do_dns()

  5. Packet capture via do_sniff()

  6. MDA traceroute via do_tracelb()

  7. HTTP via do_http()

  8. UDP probes via do_udpprobe()

Reading and Writing Files

To read results stored in a native scamper warts(5) file, instantiate a ScamperFile object, passing the name of the file to open as the first parameter. Read each object out of the file using the read() method, or by using the built in Iterator, demonstrated below. If the file contains objects of different types, but you are only interested in a subset of the object types, you can signal the types with the filter_types() method, or by signalling that with the constructor. Finally, you can close the file when you are finished using the close() method.

The following code illustrates the overall approach:

from scamper import ScamperFile, ScamperTrace

addrs = {}
file = ScamperFile("foo.warts.gz")
for o in file:
  if isinstance(o, ScamperTrace):
    for hop in o.hops():
      if hop.addr is not None:
        addrs[hop.addr] = 1
file.close()

for o in sorted(list(addrs)):
  print(o)

This code reads ScamperTrace objects out of foo.warts.gz, storing addresses observed in each traceroute in a dictionary to identify the unique addresses. Finally, it prints the addresses in sorted order.

To write measurements to a file, instantiate a ScamperFile object, passing ‘w’ as the mode parameter. By default, ScamperFile will write warts(5) output, but this can be changed either by specifying the kind parameter, or by using an appropriate suffix in the filename. ScamperFile can write compressed warts(5) output using “warts.gz”, “warts.bz2”, or “warts.xz”, write json output with “json”, or simple text output with “text”. Write each object out by passing the object to the write() method.

If you wish to save measurement results collected via a ScamperCtrl, then open a file, and pass it to the ScamperCtrl constructor.

from scamper import ScamperCtrl, ScamperFile

outfile = ScamperFile("foo.warts.gz", 'w')
ctrl = ScamperCtrl(remote_dir="/tmp/dir", outfile = outfile)

This way, ScamperCtrl will record all measurement objects in the file, so that you do not have to write() them yourself.

API Reference

Classes for Managing Scamper

ScamperCtrl

class scamper.ScamperCtrl(meta=False, morecb=None, eofcb=None, param=None, unix=None, remote=None, remote_dir=None, outfile=None)

ScamperCtrl objects provide an event-driven interface to one or more scamper processes, each of which is represented by a single ScamperInst object. The general workflow is to instantiate a ScamperCtrl object connected that manages one or more ScamperInst objects, issue measurements via the various do methods, read and save results, and either issue new measurements or finish.

The ScamperCtrl constructor takes the following named parameters, all of which are optional. The meta parameter signals whether the caller wants meta objects (ScamperList, ScamperCycle) or not; the default is False. The morecb parameter is a callback function that ScamperCtrl will call when an scamper instance signals that it wants more work. The callback takes three parameters: a ScamperCtrl, a ScamperInst, and a user-supplied parameter that is passed to the callback to use. The eofcb parameter is a callback that ScamperCtrl will call when an instance signals that it has finished. The callback takes the same three parameters as morecb. The param parameter is the user-supplied parameter that will be passed to morecb and eofcb. The outfile parameter identifies a ScamperFile opened for writing that should record all measurement results. This can save the caller from writing code to store individual measurement results as these are passed to the caller. The unix parameter identifies the path in the file system to a unix domain socket representing a local scamper instance, which will then become accessible via a ScamperInst. The remote parameter identifies the path in the file system to a unix domain socket representing a remote scamper instance, which will then become accessible via a ScamperInst. The remote_dir parameter identifies the path to a directory in the file system containing multiple unix domain sockets, each of which represent a remote scamper instance that will become accessible via ScamperInst objects.

These first set of methods and attributes allow a program to manage and use a set of ScamperInst.

add_unix(path)

Add a single ScamperInst which represents a local scamper process available via a Unix domain socket at the specified location in the file system identified with the path parameter. The method returns the ScamperInst object to the caller. You do not have to store the object, as the ScamperCtrl object also retains a reference to the ScamperInst.

You can also connect a local scamper process when constructing the ScamperCtrl object by passing the path to the unix parameter in the constructor. This will save you writing code.

Raises a RuntimeError if the path is invalid, or the caller does not have sufficient privileges in the file system to open the socket.

add_inet(port, addr=None)

Add a single ScamperInst which represents a scamper process available on a regular socket. The port parameter is mandatory. The addr parameter is optional. If not supplied, the port is assumed to refer to a local scamper instance which can be found on the loopback IP address. The method returns the ScamperInst object to the caller. You do not have to store the object, as the ScamperCtrl object also retains a reference to the ScamperInst.

Raises a RuntimeError if the port is invalid, or the caller cannot connect to the port.

add_remote(path)

Add a single ScamperInst which represents a scamper process on a remote system available via a Unix domain socket at the specified location in the file system identified with the path parameter. The method returns the ScamperInst object to the caller. You do not have to store the object, as the ScamperCtrl object also retains a reference to the ScamperInst.

You can also connect a remote scamper process when constructing the ScamperCtrl object by passing the path to the remote parameter in the constructor. This will save you writing code.

Raises a RuntimeError if the path is invalid, or the caller does not have sufficient privileges in the file system to open the socket.

add_remote_dir(path)

Add a ScamperInst for each remote system available via a Unix domain socket in the specified directory in the file system identified with the path parameter.

You can also connect these systems when constructing the ScamperCtrl object by passing the path to the remote_dir parameter in the constructor. This will save you writing code.

Raises a RuntimeError if the path is invalid, or the caller does not have sufficient privileges in the file system to open a socket.

instances()

Return a list of ScamperInst managed by the ScamperCtrl. This provides a convenient interface to issue commands to all available vantage points.

instc

The total number of ScamperInst managed by this ScamperCtrl.

The following methods provide interfaces for obtaining measurement results, as well as handling exceptions.

poll(timeout=None, until=None)

Wait for a measurement result to become available from one of the ScamperInst under management. The method will block until a result is available, or an exception occurs. The timeout parameter limits the time the method will block before returning, and is a timedelta object. The until parameter specifies when the method should return, if there is no result available by then, and is a datetime object.

If an exception has occurred asynchronously, perhaps because a ScamperInst rejected a command, or a user-provided callback function raised an exception, this method will raise it.

responses(timeout=None, until=None)

Return all measurement results for all issued measurements, blocking until there are no issued measurements outstanding. The caller can limit the time this method will block by using the timeout and until parameters. The timeout parameter is a timedelta that specifies the length of time the responses generator can block before returning. The until parameter is a datetime that specifies when the method should return.

This method will not raise any exceptions that get queued asynchronously by ScamperCtrl. The caller should call the exceptions() method to obtain exceptions after responses() returns.

exceptions()

This method returns queued exceptions. You should call this method after calling responses().

done()

Signal that there is no further measurements to be issued on any of the connected ScamperInst.

is_done()

Returns True when all issued measurements have returned and all ScamperInst have signalled end-of-file.

taskc

The total number of tasks outstanding.

The following methods provide interfaces for issuing measurements. Each of the ScamperCtrl do_ methods have three parameters in common, which we document here for brevity. The first, sync, determines whether the measurement operates synchronously or not. By default, a measurement operates asynchronously (sync = False), and the do_ methods return a ScamperTask object that represents the measurement. When operating synchronously (sync = True), the do_ methods each return the result of the measurement when it becomes available. The second parameter in common is the inst parameter. This identifies the ScamperInst that the measurement should be executed on. If the ScamperCtrl object is operating with a single instance, then you do not have to pass an inst parameter – it will use that single instance. Otherwise, you have to identify the specific ScamperInst that the measurement should be executed on. The third common parameter is the userid parameter, which is an integer value that the caller can tag on the measurement for its own purpose. The value has to be able to be represented in an unsigned 32-bit integer, as that is what scamper uses internally.

do_trace(dst, confidence=None, dport=None, icmp_sum=None, firsthop=None, gaplimit=None, loops=None, hoplimit=None, pmtud=None, squeries=None, ptr=None, payload=None, method=None, attempts=None, all_attempts=None, rtr=None, sport=None, src=None, tos=None, wait_timeout=None, wait_probe=None, userid=None, inst=None, sync=False)

Schedule a traceroute measurement to the IP address identified by dst. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

The confidence parameter specifies a confidence level to reach before assuming all the interfaces have been observed that will reply at that hop, and can be either 95 or 99. sport and dport specify the (base) source and destination TCP/UDP ports to use in probes. icmp_sum specifies the checksum to use in the ICMP header for icmp-paris traceroute. firsthop specifies the TTL to start probing with. gaplimit specifies how many consecutive unresponsive hops before traceroute should stop. loops specifies the number of loops allowed before traceroute stops. pmtud, if True, instructs scamper to do Path-MTU probing of the path, to identify MTU changes in the path. squeries specifies the number of consecutive hops to probe before stopping to wait for a response. ptr, if True, instructs scamper to look up the name of any IP address observed in a response. payload specifies a bytes object with a payload to include in each probe. method specifies the type of probing strategy to use: icmp-paris, udp-paris, tcp, tck-ack, udp, or icmp. attempts specifies the number of attempts to try, per TTL; if all_attempts is True, then all attempts are sent, otherwise scamper stops after receiving a response for the hop. rtr specifies the IP address of the first hop router, overriding the system’s choice of router. src specifies the source IP address to use in probes. tos specifies the value to put in the 8-bit field previously known as IP Type of Service. wait_timeout specifies the length of time to wait for a response to a probe. wait_probe specifies the minimum length of time between consecutive probes.

The userid, inst, and sync parameters are documented above. This method will return a ScamperTrace object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_tracelb(dst, confidence=None, dport=None, firsthop=None, gaplimit=None, method=None, attempts=None, rtr=None, sport=None, tos=None, wait_timeout=None, wait_probe=None, userid=None, inst=None, sync=False)

Schedule an MDA (load-balancer) traceroute measurement to the IP address identified by dst. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

The confidence parameter specifies a confidence level to reach before assuming all the interfaces have been observed that will reply at that hop, and can be either 95 or 99. sport and dport specify the (base) source and destination TCP/UDP ports to use in probes. firsthop specifies the TTL to start probing with. gaplimit specifies how many consecutive unresponsive hops before traceroute should stop. method specifies the type of probing strategy to use: udp-dport, icmp-echo, udp-sport, tcp-sport, or tcp-ack-sport. attempts specifies the number of attempts to try, per TTL. ptr, if True, instructs scamper to look up the name of any IP address observed in a response. rtr specifies the IP address of the first hop router, overriding the system’s choice of router. tos specifies the value to put in the 8-bit field previously known as IP Type of Service. wait_timeout specifies the length of time to wait for a response to a probe. wait_probe specifies the minimum length of time between consecutive probes.

The userid, inst, and sync parameters are documented above. This method will return a ScamperTracelb object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_ping(dst, tcp_seq=None, tcp_ack=None, attempts=None, icmp_id=None, icmp_seq=None, icmp_sum=None, dport=None, sport=None, wait_probe=None, wait_timeout=None, tos=None, ttl=None, mtu=None, stop_count=None, method=None, payload=None, rtr=None, recordroute=None, size=None, src=None, userid=None, inst=None, sync=False)

Schedule a ping measurement to the IP address identified by dst. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

tcp_seq and tcp_ack specify the values to insert in the TCP sequence and acknowledgment fields. attempts specifies the number of probes to send. icmp_id, icmp_seq, and icmp_sum specify the ID, sequence, and checksum values to use in the ICMP header. sport and dport specify the source and destination port values for TCP and UDP probe methods. wait_probe and wait_timeout specify the length of time between probes, and how long to wait for a response to a probe. tos and ttl specify the type-of-service and TTL values to use in the IP header. mtu specifies a pseudo-MTU value to use for the measurement; if a response is larger, then scamper will send a packet too big to induce fragmentation in subsequent responses. stop_count specifies the number of probes that need a response before stopping. method specifies the probe strategy to use: icmp-echo, icmp-time, udp, udp-port, tcp-syn, tcp-syn-sport, tcp-synack, tcp-ack, tcp-ack-sport, or tcp-rst. payload specifies a bytes object with a payload to include in each probe. rtr specifies the IP address of the first hop router, overriding the system’s choice of router. recordroute, if True, includes an IP record-route option in probes. size specifies the size of probe packets to send. src specifies the source IP address to use in probes.

The userid, inst, and sync parameters are documented above. This method will return a ScamperPing object if sync is True.

do_dns(qname, server=None, qtype=None, attempts=None, rd=None, wait_timeout=None, userid=None, inst=None, sync=False)

Schedule a DNS measurement for the name identified by qname. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

server specifies the IP address of the DNS server to use. qtype specifies the type of query to make. attempts specifies the number of queries to send before stopping. rd, if True, signals to the DNS server that this is a recursive query. wait_timeout specifies the length of time to wait for a response.

The userid, inst, and sync parameters are documented above. This method will return a ScamperHost object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_http(dst, url, headers=None, insecure=False, limit_time=None, userid=None, inst=None, sync=False)

Schedule an HTTP GET to the IP address specified in dst using the URL specified in the url parameter. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

headers specifies a dictionary that maps header names to values to include in the GET request. insecure, if True, allows scamper to ignore TLS certificate errors with an HTTPS and proceed with the request. limit_time specifies the maximum length of time that the HTTP query may take.

The userid, inst, and sync parameters are documented above. This method will return a ScamperHttp object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_udpprobe(dst, dport, payload, inst=None, userid=None, sync=False)

Send a UDP probe to the IP address and port specified by dst and dport, with the specified payload.

The userid, inst, and sync parameters are documented above. This method will return a ScamperUdpprobe object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_ally(dst1, dst2, fudge=None, icmp_sum=None, dport=None, sport=None, method=None, attempts=None, wait_probe=None, wait_timeout=None, userid=None, inst=None, sync=False)

Schedule an Ally-style alias resolution measurement for the two IP addresses identified by dst1 and dst2. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

The fudge value specifies the maximum difference between IPID values to still consider as possibly from the same counter. icmp_sum specifies the ICMP checksum value to use in probes. sport and dport specify the (base) source and destination ports to use in probes. method specifies the probing strategy: udp, udp-dport, tcp-ack, tcp-ack-sport, tcp-syn-sport, or icmp-echo. attempts specifies the total number of probes to send in this measurement. wait_probe and wait_timeout specify the length of time between probes, and how long to wait for a response to a probe.

The userid, inst, and sync parameters are documented above. This method will return a ScamperDealias object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_mercator(dst, userid=None, inst=None, sync=False)

Conduct a Mercator-style alias resolution measurement to the IP address identified by dst. The userid, inst, and sync parameters are documented above. This method will return a ScamperDealias object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_midarest(probedefs=None, addrs=None, rounds=None, wait_probe=None, wait_round=None, wait_timeout=None, userid=None, inst=None, sync=False)

Conduct MIDAR-style estimation-stage probing of a list of IP addresses specified in the addrs parameter. The probedefs parameter must contain a list of ScamperDealiasProbedef objects that define a probing method. Both addrs and probedefs are mandatory named parameters. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

The rounds parameter specifies how many rounds to conduct. wait_probe, wait_round, and wait_timeout specify the minimum time between probes, the minimum time between rounds, and the minimum time to wait for a response for a probe.

The userid, inst, and sync parameters are documented above. This method will return a ScamperDealias object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_midardisc(probedefs=None, schedule=None, startat=None, wait_timeout=None, userid=None, inst=None, sync=False)

Conduct MIDAR-style discovery-stage probing using of a list ScamperDealiasProbedef objects that each identify a method and IP address in the probedefs parameter, and a list of ScamperDealiasMidardiscRound objects that specify individual rounds in the schedule parameter. Both probedefs and schedule are mandatory named parameters. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

startat specifies a unix timestamp when probing should commence, and wait_timeout specifies the length of time to wait for a response to a probe.

The userid, inst, and sync parameters are documented above. This method will return a ScamperDealias object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_radargun(probedefs=None, addrs=None, rounds=None, wait_probe=None, wait_round=None, wait_timeout=None, userid=None, inst=None, sync=False)

Conduct radargun-style probing using a list of ScamperDealiasProbedef objects that each identify a method in the probedefs parameter. Either all probedefs contain an IP address, or the IP addresses to probe will be found in addrs. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

rounds specifies the number of rounds for this measurement. wait_probe, wait_round, and wait_timeout specify the minimum time between probes, the minimum time between rounds, and the minimum time to wait for a response for a probe.

The userid, inst, and sync parameters are documented above. This method will return a ScamperDealias object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_prefixscan(near, far, prefixlen, fudge=None, icmp_sum=None, dport=None, sport=None, method=None, attempts=None, wait_probe=None, wait_timeout=None, userid=None, inst=None, sync=False)

Conduct a prefixscan measurement to infer an alias on the router with IP address near that is within a subnet containing far. This measurement requires the near and far addresses defining a link to probe, and the size of the prefix to search in prefixlen. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

The fudge value specifies the maximum difference between IPID values to still consider as possibly from the same counter. icmp_sum specifies the ICMP checksum value to use in probes. sport and dport specify the (base) source and destination ports to use in probes. method specifies the probing strategy: udp, udp-dport, tcp-ack, tcp-ack-sport, tcp-syn-sport, or icmp-echo. attempts specifies the total number of attempts per probe, before moving onto the next address pair. wait_probe and wait_timeout specify the length of time between probes, and how long to wait for a response to a probe.

The userid, inst, and sync parameters are documented above. This method will return a ScamperDealias object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

do_sniff(src, icmp_id, limit_pkt_count=None, limit_time=None, userid=None, inst=None, sync=False)

Conduct a simple packet capture on the interface with the IP address in src for ICMP packets with an ICMP-ID value of icmp_id. The other parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults.

limit_pkt_count specifies the maximum number of packets to capture before returning, and limit_time specifies the maximum length of time to wait before returning.

The userid, inst, and sync parameters are documented above. This method will return a ScamperSniff object if sync is True, otherwise it will return a ScamperTask representing the scheduled measurement.

ScamperInst

class scamper.ScamperInst

ScamperCtrl provides ScamperInst objects to allow instances to be identified and managed. The class implements methods that allow ScamperInst objects to be sorted and hashed.

name

a string that identifies the instance in some way.

taskc

the number of tasks that have been issued but have not yet returned measurement results.

done()

signal that there are no further measurements to come on this ScamperInst. This allows the managing ScamperCtrl to signal ‘end-of-file’ when the ScamperInst has returned the last measurement result via the eofcb callback provided to the ScamperCtrl constructor, and allows is_done() to return True when this is the last ScamperInst managed by the ScamperCtrl and it has no further measurement results to return.

ScamperTask

class scamper.ScamperTask

class:ScamperCtrl provides ScamperTask objects to allow measurements that the caller has scheduled to be halted, if the user does not want the measurement to continue. The class also implements methods that allow ScamperTask objects to be sorted and hashed.

halt()

halt the measurement underway. If the measurement was actually started by a scamper instance, then the program will receive the measurement object in its current state.

Class for Reading Files

ScamperFile

class scamper.ScamperFile(filename, mode='r', kind=None, filter_types=None)

A ScamperFile can be used to read and write measurement results collected by scamper. The constructor takes the following parameters, the first of which is mandatory; the remainder are optional named parameters. The filename parameter is a string that identifies the name of the file to open. The mode parameter is a string (‘r’ or ‘w’) identifying whether the file is to be opened read or write. The kind parameter is a string specifying the type of the file to open, if opened for writing, and can be one of: warts, warts.gz, warts.bz2, warts.xz, json, or text. The filter_types parameter is a list containing the types of the objects to return when reading. By default, a file opened for reading returns all types of objects.

The class implements an iterator interface, which a caller can use to read objects out of the file.

file = ScamperFile("foo.warts", filter_types=[ScamperPing])
for ping in file:
  print(f"{ping.dst}")
filetype

a string reporting the type of file opened for reading. The string will contain either ‘warts’ or ‘arts’.

close()

close the file.

filename

a string reporting the name of the file originally specified to the constructor.

filter_types(*types)

specify the types of objects to return when reading the file. You can also specify the types of objects to return when constructing the ScamperFile object by passing the list of objects to the filter_types constructor parameter. This will save you writing code.

read()

read the next object from the file, if the file was opened for reading.

write(obj)

write the object to a ScamperFile object to the file, if the file was opened for writing.

is_write()

returns True if the file was opened for writing.

is_read()

returns True if the file was opened for reading.

Scamper Meta-Objects

ScamperAddr

class scamper.ScamperAddr(addr)

Scamper interally stores addresses with its own format, and the ScamperAddr class provides an interface to that format. When a scamper measurement object includes an address, it does so with a ScamperAddr object. The ScamperAddr constructor allows a program to create its own ScamperAddr objects from a string representation of the address. The ScamperAddr class implements methods for rendering string representations of the address, sorting, and hashing.

packed()

returns a Python bytes object containing the address

is_linklocal()

returns True if the address is in the IPv4 or IPv6 ranges for link-local addresses.

is_rfc1918()

returns True if the address is in the IPv4 RFC-1918 (private) address ranges.

is_unicast()

returns True if the address is in the IPv6 unicast prefix.

is_6to4()

returns True if the address is in the IPv6 6to4 prefix.

is_reserved()

returns True if the address is in one of the published reserved prefixes.

is_ipv4()

returns True if the address is an IPv4 address

is_ipv6()

returns True if the address is an IPv6 address

ScamperList

class scamper.ScamperList

Scamper appends two metadata objects to each measurement (ScamperList and ScamperCycle). This class implements methods that allow ScamperList objects to be sorted.

id

A numeric value assigned to the list.

name

A string containing an identifying name of the list.

descr

A string with optional metadata attached to the list.

monitor

A string with the name of the vantage point that used the list.

ScamperCycle

class scamper.ScamperCycle

Scamper appends two metadata objects to each measurement (ScamperCycle and ScamperList). This class implements methods that allow ScamperCycle objects to be sorted.

id

A numeric value assigned to the cycle.

start

The start time of the cycle, expressed as a datetime.

stop

The stop time of the cycle, expressed as a datetime.

hostname

The hostname of the ScamperInst at the start of the cycle, expressed as a string.

ScamperIcmpExt

class scamper.ScamperIcmpExt

Scamper records ICMP extension data across different measurement types in ScamperIcmpExt objects. The most common type of ICMP extension is the MPLS extension, and this class provides methods to interact with that class of ICMP extension. This class implements methods that allow ScamperIcmpExt objects to be sorted.

is_mpls()

returns True if the ICMP extension contains MPLS information.

mpls_count

returns the number of MPLS label stack entries in the extension.

mpls_label(i)

returns the label in the label stack entry at offset i.

mpls_ttl(i)

returns the TTL in the label stack entry at offset i.

mpls_exp(i)

returns the EXP bits in the label stack entry at offset i.

mpls_s(i)

returns the bottom-of-stack (S) bit in the label stack entry at offset i.

Traceroute

ScamperTrace

class scamper.ScamperTrace

This class provides information about a traceroute measurement from scamper. Both ScamperCtrl and ScamperFile objects provide traceroute measurement objects. The basic properties of the measurement are stored in a ScamperTrace object, while the properties of individual responses are stored in ScamperTraceHop objects.

The following attributes and methods report parameters provided to the traceroute.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address used in this measurement.

dst

a ScamperAddr containing the destination address used in this measurement.

rtr

a ScamperAddr containing the IP address of the router used in this measurement, if the default router was not used.

wait_timeout

a timedelta containing the length of time to wait before declaring a probe lost.

wait_probe

a timedelta containing the length of time to wait between sending probes.

attempts

the maximum number of probes sent per hop.

hoplimit

the maximum distance (IP TTL) to probe in the traceroute before stopping.

squeries

the number of consecutive hops that could have had an outstanding response before pausing for a response.

gaplimit

the maximum number of consecutive unresponsive hops that were allowed before stopping.

firsthop

the TTL of the first hop probed in the traceroute.

tos

the IP type-of-service byte set in the traceroute probes.

confidence

an integer value (95 or 99) that controlled the number of probes sent per hop before deciding that all addresses had been observed at the specified confidence level.

probe_size

the size of probes sent.

payload

the payload included in the probes, as a byte array.

probe_sport

the (base) source port used in the measurement, if the measurement used TCP or UDP probes. returns None if the measurement did not use TCP or UDP probes.

probe_dport

the (base) destination port used in the measurement, if the measurement used TCP or UDP probes. returns None if the measurement did not use TCP or UDP probes.

probe_icmp_sum

the ICMP checksum value used in the measurement, if the measurement used ICMP probes. returns None if the measurement did not use ICMP probes.

offset

the value used in the IP fragmentation offset header.

is_udp()

returns True if the method used UDP probes.

is_tcp()

returns True if the method used TCP probes.

is_icmp()

returns True if the method used ICMP probes.

The following attributes and methods report data collected in the traceroute.

hop_count

how many hops were probed in the path before stopping.

hops()

returns an iterator that provides the first response obtained for each responsive hop.

for h in trace.hops():
  print(f"{h}")
hop(i)

returns a ScamperTraceHop for the first response obtained for a probe at index i in the path, where i >= 0 and i is less than hop_count. If there was no response, this method returns None.

probe_count

the number of probes sent for this traceroute

pmtud

if the traceroute did Path MTU discovery, a ScamperTracePmtud object with the parameters and results of that measurement.

is_stop_noreason()

True if there is no recorded stop reason for the traceroute.

is_stop_completed()

True if the traceroute reached the destination.

is_stop_unreach()

True if the traceroute stopped because it received an ICMP destination unreachable message.

is_stop_icmp()

True if the traceroute stopped because it received an ICMP message that was not a destination unreachable message.

is_stop_loop()

True if the traceroute stopped because it encountered a loop.

is_stop_gaplimit()

True if the traceroute stopped because it did not obtain a reply for scamper.ScamperTrace.gaplimit hops.

is_stop_error()

True if scamper encountered an operating system error while conducting the traceroute.

is_stop_hoplimit()

True if the traceroute stopped because it reached the maximum distance into the network that it could probe, as defined by scamper.ScamperTrace.hoplimit.

is_stop_gss()

True if the traceroute stopped because it observed address in the global stop set.

is_stop_halted()

True if the traceroute was halted before it could complete.

ScamperTraceHop

class scamper.ScamperTraceHop

This class provides information about a response to a traceroute probe. It provides a method to render the ScamperTraceHop in a string format similar to regular traceroute output.

src

a ScamperAddr containing the IP address that replied to a probe.

name

a string containing the name in a DNS PTR record that was looked up, if scamper attempted to resolve a PTR for the IP address.

tx

a datetime for when the probe was sent, or None if scamper did not record a timestamp.

rtt

a timedelta containing the round-trip-time for this response.

attempt

the attempt number for the probe’s TTL. The first attempt has a value of 1.

probe_ttl

the TTL set in the probe packet.

probe_size

the size of the probe packet.

reply_ttl

the TTL value in the IP header of the response, if known. if unknown, then None.

reply_tos

the TOS value in the IP header of the response, if known. if unknown, then None.

icmp_type

the ICMP type value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

icmp_code

the ICMP code value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

reply_size

the size of the response, if known. if unknown, then None.

reply_ipid

the IPID value in the IP header of the response, if known. if unknown, then None.

is_tcp()

True if the response packet was a TCP packet.

is_icmp()

True if the response packet was an ICMP packet.

is_icmp_q()

True if the response contains an ICMP quotation.

is_icmp_unreach_port()

True if the response was an ICMP port unreachable.

is_icmp_echo_reply()

True if the response was an ICMP echo reply.

is_icmp_ttl_exp()

True if the response was an ICMP TTL expired (time exceeded) message.

is_icmp_ptb()

True if the response was an ICMP packet too big (fragmentation needed) message.

icmp_nhmtu

the next-hop MTU value encoded in the response, if the response was an ICMP packet too big message.

icmp_q_ttl

the TTL value in the quoted IP packet, if the response quoted an IP packet.

icmp_q_tos

the TOS value in the quoted IP packet, if the response quoted an IP packet.

icmp_q_ipl

the IP length value in the quoted IP packet, if the response quoted an IP packet.

tcp_flags

the TCP flags contained in a TCP response, if the response was a TCP packet.

icmpext

an ICMP extension structure, if the ICMP response included an extension.

ScamperTracePmtud

class scamper.ScamperTracePmtud

This class provides information about the PMTUD process within a traceroute, if the traceroute included a PMTUD process.

path_mtu

the end-to-end path MTU value inferred.

if_mtu

the MTU value of the interface used to send the probes.

out_mtu

the MTU value to the first hop, which could be different to the interface MTU if the interface has an MTU-mismatch with its network.

Ping

ScamperPing

class scamper.ScamperPing

This class provides information about a ping measurement from scamper. Both ScamperCtrl and ScamperFile objects provide ping measurement objects. The basic properties of the measurement are stored in a ScamperPing object, while the properties of individual responses are stored in ScamperPingReply objects.

print("ping from %s to %s" % (ping.src, ping.dst))
  for i in range(ping.probe_count):
    r = ping.reply(i)
    if r is None:
      print("no reply for attempt %d" % (i+1))
    else:
      print("reply from %s, attempt %d" % (i+1))

To iterate over all probes with responses, use the iterator.

print("ping from %s to %s" % (ping.src, ping.dst))
  for r in ping:
    print("reply from %s, attempt %d" % (r.src, r.attempt))

The following attributes and methods report parameters provided to the ping measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address used in this measurement.

dst

a ScamperAddr containing the destination address used in this measurement.

rtr

a ScamperAddr containing the IP address of the router used in this measurement, if the default router was not used.

wait_timeout

a timedelta containing the length of time to wait before declaring a probe lost.

wait_probe

a timedelta containing the length of time to wait between sending probes.

attempts

the maximum number of packets that could have been sent in this measurement.

stop_count

the number of responses before the measurement could stop.

payload

the payload included in the probes, as a bytes object, if the measurement specified the payload to set.

probe_size

the size of probes sent.

probe_ttl

the TTL set in the IP header of each probe.

probe_tos

the type-of-service value set in the IP header of each probe.

probe_sport

the (base) source port used in the measurement, if the measurement used TCP or UDP probes. None if the measurement did not use TCP or UDP probes.

probe_dport

the (base) destination port used in the measurement, if the measurement used TCP or UDP probes. None if the measurement did not use TCP or UDP probes.

probe_icmp_sum

the ICMP checksum value used in the measurement, if the measurement used ICMP probes. None if the measurement did not use ICMP probes.

probe_tcp_seq

the TCP sequence number value used in the probes, if the measurement used tcp-syn probes.

probe_tcp_ack

the TCP acknowledgment number value used in the probes, if the measurement used tcp-ack probes.

reply_pmtu

the psuedo-MTU value used for this measurement, if it used the too-big-trick.

is_icmp()

returns True if the method used ICMP probes.

is_icmp_time()

returns True if the method used ICMP timestamp request packets.

is_tcp()

returns True if the method used TCP probes.

is_tcp_ack_sport()

returns True if the method used TCP probes, with only the ACK flag set in the TCP header, and varied the source port with each probe.

is_udp()

returns True if the method used UDP probes.

is_vary_sport(self):

returns True if the ping measurement sent TCP or UDP packets where the source port changed for each packet.

is_vary_dport(self):

returns True if the ping measurement sent TCP or UDP packets where the destination port changed for each packet.

The following attributes and methods report data collected in the ping measurement.

probe_count

the total number of probes sent. This value will be between stop_count and attempts.

reply(i)

returns a ScamperPingReply for the nominated attempt, starting at index i, where i >= 0 and i is less than probe_count. If there was no reply, this method returns None.

nreplies

the number of probes for which scamper received at least one reply from the destination.

ndups

the number of additional replies that scamper received from the destination.

nloss

the number of probes for which scamper did not receive any reply.

nerrs

the number of response packets that were not from the destination.

min_rtt

the minimum RTT observed in responses from the destination, if scamper received at least one reply. the RTT value is expressed in a timedelta object.

max_rtt

the maximum RTT observed in responses from the destination, if scamper received at least one reply. the RTT value is expressed in a timedelta object.

avg_rtt

the average RTT observed in responses from the destination, if scamper received at least one reply. the RTT value is expressed in a timedelta object.

stddev_rtt

the standard deviation for the RTTs observed in responses from the destination, if scamper received at least one reply. the RTT value is expressed in a timedelta object.

ScamperPingReply

class scamper.ScamperPingReply

This class provides information about a response to a ping probe. It provides a method to render the ScamperPingReply in a string format similar to regular ping output.

src()

a ScamperAddr containing the IP address that replied to a probe.

is_from_target()

True if the reply came from the target.

tx

a datetime for when the probe was sent, or None if scamper did not record a timestamp.

rtt

a timedelta containing the round-trip-time for this response.

attempt

the attempt number for this probe. The first attempt has a value of 1.

probe_ipid

the IPID value set for this probe.

reply_ipid

the IPID value in the IP header of the response, if known. if unknown, then None.

reply_proto

the IP protocol number for this reply (TCP, UDP, ICMP)

reply_ttl

the TTL value in the IP header of the response, if known. if unknown, then None.

reply_size

the size of the response.

icmp_type

the ICMP type value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

icmp_code

the ICMP code value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

tcp_flags

the TCP flags contained in a TCP response, if the response was a TCP packet.

is_icmp()

True if the response packet was an ICMP packet.

is_tcp()

True if the response packet was a TCP packet.

is_udp()

True if the response packet was a UDP packet.

is_icmp_echo_reply()

True if the response was an ICMP echo reply.

is_icmp_unreach()

True if the response was an ICMP destination unreachable.

is_icmp_unreach_port()

True if the response was an ICMP port unreachable.

is_icmp_ttl_exp()

True if the response was an ICMP TTL expired (time exceeded) message.

is_icmp_tsreply()

True if the response was an ICMP timestamp reply.

MDA Traceroute

ScamperTracelb

class scamper.ScamperTracelb

This class provides information about an MDA traceroute (tracelb) measurement collected by scamper. Both ScamperCtrl and ScamperFile objects provide tracelb measurement objects. The basic properties of the measurement are stored in a ScamperTracelb object. The individual nodes in the graph are stored in ScamperTracelbNode objects, and links between these nodes are stored in ScamperTracelbLink objects. The ScamperTracelbProbeset objects store information about a set of probes sent along a link to solicit responses. The probes that were sent to discover topology are stored in ScamperTracelbProbe objects, and responses received are stored in ScamperTracelbReply objects.

These first attributes and methods report parameters provided to the tracelb measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address used in this measurement.

dst

a ScamperAddr containing the destination address used in this measurement.

rtr

a ScamperAddr containing the IP address of the router used in this measurement, if the default router was not used.

wait_timeout

a timedelta containing the length of time to wait before declaring a probe lost.

wait_probe

a timedelta containing the length of time to wait between sending probes.

attempts

the maximum number of attempts per probe.

gaplimit

the maximum number of consecutive unresponsive hops that were allowed before stopping.

firsthop

the TTL of the first hop probed in the traceroute.

tos

the IP type-of-service byte set in the traceroute probes.

confidence

an integer value (95 or 99) that controlled the number of probes sent per hop before deciding that all addresses had been observed at the specified confidence level.

probe_size

the size of probes sent.

probe_sport

the (base) source port used in the measurement, if the measurement used TCP or UDP probes. returns None if the measurement did not use TCP or UDP probes.

probe_dport

the (base) destination port used in the measurement, if the measurement used TCP or UDP probes. returns None if the measurement did not use TCP or UDP probes.

probe_icmp_id

the ICMP ID value used in the measurement, if the measurement used ICMP probes. returns None if the measurement did not use ICMP probes.

is_udp()

returns True if the method used UDP probes.

is_tcp()

returns True if the method used TCP probes.

is_icmp()

returns True if the method used ICMP probes.

The following attributes and methods report data collected in the traceroute.

probe_count

the total number of probes sent for this measurement.

node_count

the number of unique nodes in the graph.

nodes()

an Iterator to step through recorded nodes.

node(i)

obtain the ScamperTracelbNode item at index i, starting at zero.

the number of unique links in the graph.

an Iterator to step through recorded links.

obtain the ScamperTracelbLink item at index i, starting at zero.

ScamperTracelbNode

class scamper.ScamperTracelbNode

This class provides information about a node observed in an MDA traceroute graph.

src

a ScamperAddr containing the IP address for the node.

name

a string containing the name in a DNS PTR record that was looked up, if scamper attempted to resolve a PTR for the IP address.

icmp_q_ttl

the TTL value in the quoted IP packet for the node, if the response quoted an IP packet.

the number of links from this node.

obtain the ScamperTracelbLink at index i attached to this node.

return an Iterator to step through ScamperTracelbLink from this node.

ScamperTracelbProbeset

class scamper.ScamperTracelbProbeset

This class provides information about probes sent along a ScamperTracelbLink to solicit responses. It provides an Iterator interface to step through the probes.

probe_count

the number of probes in this set

probe(i)

obtain the ScamperTracelbProbe at offset i.

ScamperTracelbProbe

class scamper.ScamperTracelbProbe

This class provides information about a single probe sent as part of a ScamperTracelb measurement. It provides a str interface to obtain a simple string representation.

tx

a datetime for when the probe was sent.

flowid

the flowid associated with the probe.

ttl

the TTL set in the probe packet.

attempt

the attempt number for the probe’s TTL. The first attempt has a value of 1.

reply_count

the number of replies recorded for this probe.

reply(i)

return the ScamperTracelbReply at index i, starting at zero.

ScamperTracelbReply

class scamper.ScamperTracelbReply

This class provides information about a single reply received as part of a ScamperTracelb measurement.

src()

a ScamperAddr containing the IP address that replied to a probe.

rx

a datetime for when the reply was received.

ipid

the IPID value in the IP header of the response, if known. if unknown, then None.

ttl

the TTL value in the IP header of the response, if known. if unknown, then None.

icmp_type

the ICMP type value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

icmp_code

the ICMP code value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

icmp_q_ttl

the TTL value in the quoted IP packet, if the response quoted an IP packet.

icmp_q_tos

the TOS value in the quoted IP packet, if the response quoted an IP packet.

tcp_flags

the TCP flags contained in a TCP response, if the response was a TCP packet.

icmpext

an ICMP extension structure, if the ICMP response included an extension.

Alias Resolution

ScamperDealias

class scamper.ScamperDealias

This class provides information about an alias resolution measurement conducted by scamper. Both ScamperCtrl and ScamperFile objects provide dealias measurement objects.

These first attributes and methods report parameters provided to the dealias measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

startat

the datetime when this measurement was scheduled to start, or None if the measurement was to be started at the first scheduled opportunity. Only valid for MIDAR Discovery probing.

probedef_count

the number of ScamperDealiasProbedef in this measurement.

probedef(i)

obtain the ScamperDealiasProbedef at index i.

probedefs()

an Iterator that returns ScamperDealiasProbedef objects.

wait_probe

a timedelta containing the length of time to wait between sending probes.

wait_round

a timedelta containing the length of time to wait between rounds.

wait_timeout

a timedelta containing the length of time to wait before declaring a probe lost.

is_ally()

True if the measurement technique was Ally.

is_mercator()

True if the measurement technique was Mercator.

is_prefixscan()

True if the measurement technique was Prefixscan.

is_radargun()

True if the measurement technique was Radargun.

is_bump()

True if the measurement technique was Bump.

is_midarest()

True if the measurement technique was MIDAR-style Estimation.

is_midardisc()

True if the measurement technique was MIDAR-style Discovery.

The following attributes and methods report data collected in the measurement.

has_aliases()

True if the method has aliases to return. This method will only return True for Mercator, Ally, and Prefixscan. Other measurement techniques require post-processing.

aliases()

Returns a pair of ScamperAddr objects that the measurement technique inferred were aliases. This method will only return alias pairs for Mercator, Ally, and Prefixscan. Other measurement techniques require post-processing. None if no inferred aliases.

probe_count

the total number of probes sent for this measurement.

probe(i=0)

return the ScamperDealiasProbe at index i, starting at zero.

probes()

an Iterator that returns ScamperDealiasProbe objects.

ScamperDealiasProbedef

class scamper.ScamperDealiasProbedef(method, src=None, dst=None, ttl=None, size=None, sport=None, dport=None, icmp_id=None, icmp_sum=None)

The ScamperDealiasProbedef constructor allows a program to define a probe method for a ScamperDealias measurement via do_radargun(), do_midarest(), and do_midardisc(). Only the method parameter, which is a string identifying the name of a probing strategy, is mandatory. src and dst specify IP addresses to use in the source and destination of probes. ttl defines the TTL value to assign to probes, and size specifies the size of probes to send. sport and dport specify the (base) source and destination TCP/UDP ports to use in probes. icmp_id and icmp_sum specify the ID and checksum values to use in the header of ICMP probes.

The following attributes and methods report properties of a ScamperDealiasProbedef object.

dst

a ScamperAddr containing the destination address used in this ScamperDealiasProbedef.

src

a ScamperAddr containing the source address used in this ScamperDealiasProbedef.

ttl

the TTL value to use in the IP header.

size

the size of a probe using this ScamperDealiasProbedef.

sport

the (base) source port used by probes using this ScamperDealiasProbedef, if the definition specifies TCP or UDP probes, otherwise None.

dport

the (base) destination port used by probes using this ScamperDealiasProbedef, if the definition specifies TCP or UDP probes, otherwise None.

icmp_id

the ICMP ID value used by probes using this ScamperDealiasProbedef, if the definition specifies ICMP probes, otherwise None.

icmp_sum

the ICMP checksum value value used by probes using this ScamperDealiasProbedef, if the definition specifies ICMP probes, otherwise None.

is_udp()

returns True if the definition specifies UDP probes.

is_tcp()

returns True if the definition specifies TCP probes.

is_icmp()

returns True if the definition specifies ICMP probes.

ScamperDealiasMidardiscRound

class scamper.ScamperDealiasMidardiscRound(start, begin, end)

The ScamperDealiasMidardiscRound constructor allows a program to define parameters for a round in a MIDAR-style discovery round via do_midardisc(). All parameters are mandatory. start is a timedelta that represents when the round should start, relative to other rounds in the measurement. The first round should have a zero start offset. begin specifies the index of the first ScamperDealiasProbedef in the probedef set to use, while end specifies the last.

The following attributes and methods report properties of a ScamperDealiasMidardiscRound object.

start

a timedelta of when the roud should start relative to other rounds in the measurement.

begin

the begin index into an array of probedefs to use in this round.

end

the end index into an array of probedefs to use in this round.

ScamperDealiasProbe

class scamper.ScamperDealiasProbe

This class provides information about a single probe set as part of an alias resolution measurement.

probedef

the ScamperDealiasProbedef associated with this probe.

seq

the sequence number of this probe in relation to other probes in the measurement.

tx

a datetime for when the probe was sent.

ipid

the IPID value set in the probe.

reply_count

the number of replies recorded for this probe.

reply(i)

return the ScamperDealiasReply at index i, starting at zero.

replies()

an Iterator that returns ScamperDealiasReply objects.

ScamperDealiasReply

class scamper.ScamperDealiasReply

This class provides information about a single reply received as part of a ScamperDealias measurement.

src()

a ScamperAddr containing the IP address that replied to a probe.

rx

a datetime for when the reply was received.

ipid

the IPID value in the IP header of the response.

ttl

the IP TTL value in the IP header of the response.

size

the size of the response.

tcp_flags:

the TCP flags contained in a TCP response, if the response was a TCP packet.

icmp_type

the ICMP type value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

icmp_code

the ICMP code value for the response, if the response was an ICMP response. None if the response was not an ICMP response.

icmp_q_ttl

the TTL value in the quoted IP packet, if the response quoted an IP packet.

is_tcp()

True if the response packet was a TCP packet.

is_icmp()

True if the response packet was an ICMP packet.

is_icmp_ttl_exp()

True if the response was an ICMP TTL expired (time exceeded) message.

is_icmp_unreach()

True if the response was an ICMP destination unreachable.

is_icmp_unreach_port()

True if the response was an ICMP port unreachable.

DNS Measurement

ScamperHost

class scamper.ScamperHost

This class provides information about a DNS measurement conducted by scamper. Both ScamperCtrl and ScamperFile objects provide DNS measurement objects via the ScamperHost class.

These first attributes and methods report parameters provided to the DNS measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address used in this measurement.

dst

a ScamperAddr containing the DNS server queried in this measurement.

qtype_num

the query type number used in this measurement.

qtype

the query type used in this measurement, as a string. e.g. “A”

qclass

the query class used in this measurement, as a string, e.g. “IN”

qname

the queried name

The following attributes and methods report data collected in the measurement.

rcode

the DNS rcode value obtained in the response, if the query obtained a response.

ancount

the number of AN resource records from the first query with a response.

an(i)

obtain the ScamperHostRR at index i, starting at offset zero, in the AN section of the first query with a response.

ans()

obtain an Iterator over the ScamperHostRR in the AN section of the first query with a response.

ans_addrs()

return a list of all ScamperAddr from the AN section of the first query with a response.

nscount

the number of NS resource records from the first query with a response.

ns(i)

obtain the ScamperHostRR at index i, starting at offset zero, in the NS section of the first query with a response.

nss()

obtain an Iterator over the ScamperHostRR in the NS section of the first query with a response.

arcount

the number of AR resource records from the first query with a response.

ar(i)

obtain the ScamperHostRR at index i, starting at offset zero, in the AR section of the first query with a response.

ars()

obtain an Iterator over the ScamperHostRR in the AR section of the first query with a response.

ScamperHostRR

class scamper.ScamperHostRR

This class provides information about a DNS resource record from a ScamperHost reply. It provides a method to render the ScamperHostRR in a string format similar to regular host output.

rclass

the numeric class value from the RR.

rtype

the numeric type value from the RR.

ttl

the TTL value from the RR.

name

the name value from the RR.

addr

a ScamperAddr, if the RR contained an IP address. otherwise, None.

ns

a string containing the name server reported in the RR, if the RR reported a name server. otherwise, None.

cname

a string containing the canonical name (CNAME), if the RR reported a CNAME. otherwise, None.

ptr

a string containing the pointer (PTR) value in the RR, if the RR reported a PTR. otherwise, None.

mx

a ScamperHostMX containing the information recorded in an MX record, if the RR reported an MX. otherwise, None.

soa

a ScamperHostSOA containing information recorded in a SOA record, if the RR reported a SOA. otherwise, None.

ScamperHostMX

class scamper.ScamperHostMX

This class provides information about a DNS MX resource record from a ScamperHost reply.

pref

the preference value encoded in the RR.

exch

the exchange string encoded in the RR.

ScamperHostSOA

class scamper.ScamperHostSOA

This class provides information about a DNS SOA resource record from a ScamperHost reply.

mname

the primary master name server for the zone, as encoded in the RR.

rname

the email address of the administrator responsible for the zone, as encoded in the RR.

serial

the serial number of the zone, as encoded in the RR.

refresh

the time interval, in seconds, before the zone should be refreshed from the master, as encoded in the RR.

retry

the time interval, in seconds, that should elapse before a failed refresh should be retried, as encoded in the RR.

expire

the upper limit on the time interval, in seconds, that can elapse before the zone is no longer authoritative, as encoded in the RR.

minimum

the minimum TTL field that should be exported with any RR from this zone, as encoded in the RR.

HTTP Measurement

ScamperHttp

class scamper.ScamperHttp

This class provides information about an HTTP exchange conducted by scamper. Both ScamperCtrl and ScamperFile objects provide DNS measurement objects. This class provides an iterator over the series of ScamperHttpBuf records that comprised the HTTP exchange.

These first attributes and methods report parameters provided to the HTTP measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address used in this measurement.

dst

a ScamperAddr containing the destination address used in this measurement.

sport

the source TCP port that scamper used in the exchange.

dport

the destination TCP port that scamper used in the exchange.

url

the URL for this exchange.

The following attributes and methods report data collected in the HTTP exchange.

status_code

the status code returned by the server, if the server responded. Otherwise, None.

response

a bytes object containing the response payload, if the server responded. Otherwise, None. The response payload does not include the HTTP reader.

response_hdr

the HTTP header from the server, as a single string, if the server responded. Otherwise, None.

response_hdrs

the HTTP header from the server, stored in a dictionary that maps field names to field values. the field names and values are stored in lower case. if the server did not respond, the returned dictionary will be empty.

response_hdr_byname(name)

obtain the value of a specific header field, identified in the name parameter, sent by the server. the value is reported in the same case it was received. if the caller will fetch multiple response headers, it is more efficient to use the dictionary provided by response_hdrs. if the header field does not exist, None.

transmit_hdr

the HTTP header that scamper sent to the server, as a single string.

transmit_hdrs

the HTTP header that scamper sent to the server, stored in a dictionary that maps field names to field values. the field names and values are stored in lower case.

transmit_hdr_byname(name)

obtain the value of a specific header field, identified in the name parameter, sent by scamper to the server. the value is reported in the same case it was transmitted. if the caller will fetch multiple transmit headers, it is more efficient to use the dictionary provided by transmit_hdrs. if the header field does not exist, None.

ScamperHttpBuf

class scamper.ScamperHttpBuf

This class provides information about a single chunk of data transmitted or received by scamper during an HTTP measurement.

timestamp

a datetime reporting when the chunk was transmitted or received.

payload

a bytes object containing the payload for this chunk.

is_tx()

True if this chunk was transmitted by scamper to the server.

is_rx()

True if this chunk was received by scamper from the server.

is_tls()

True if this chunk was part of a TLS handshake with the server.

is_hdr()

True if this chunk is part of an HTTP header, from either scamper or the server.

is_data()

True if this chunk is part of the payload sent by the server.

UDP Probes

ScamperUdpprobe

class scamper.ScamperUdpprobe

This class provides information about a UDP probe sent by scamper. Both ScamperCtrl and ScamperFile objects provide UDP probe measurement objects via the ScamperUdpProbe class. This class provides an Iterator over one or more ScamperUdpprobeReply records.

for r in udpprobe:
  print(f"{r.rx} {len(r.payload)}")

These first attributes and methods report parameters provided to the UDP probe measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address used in this measurement.

dst

a ScamperAddr containing the destination address used in this measurement.

sport

the source TCP port that scamper used in the exchange.

dport

the destination TCP port that scamper used in the exchange.

wait_timeout

a timedelta containing the length of time to wait before declaring a probe lost.

payload

a bytes object containing the UDP payload sent by scamper.

The following attributes and methods report data collected in the measurement.

replyc

the number of replies received for this probe.

ScamperUdpprobeReply

class scamper.ScamperUdpprobeReply

This class provides information about a response to a UDP probe sent by scamper.

rx

a datetime for when the reply was received.

payload

a bytes object containing the UDP payload received by scamper.

Packet Capture

ScamperSniff

class scamper.ScamperSniff

This class provides information about a packet capture collected by scamper. Both ScamperCtrl and ScamperFile objects provide packet capture measurement objects via ScamperSniff. The class provides an Iterator that returns all captured packets in ScamperSniffPkt objects.

for p in sniff:
  print(f"{p.rx} {len(p.data)}")

These first attributes and methods report parameters provided to the packet capture measurement.

inst

the ScamperInst associated with this measurement, when the measurement is returned by a ScamperCtrl object.

list

the ScamperList associated with this measurement.

cycle

the ScamperCycle associated with this measurement.

userid

the userid parameter supplied to the measurement (an unsigned 32-bit integer)

start

the datetime when this measurement started.

src

a ScamperAddr containing the source address of the interface that was opened for packet capture.

limit_pkt_count

the maximum number of packets that this measurement would have waited for before finishing.

limit_time

a timedelta reporting the maximum length of time that the measurement would have waited for before finishing.

icmp_id

the ICMP ID value of packets to capture.

The following attributes and methods report data collected in the measurement.

finish

the datetime when this measurement finished.

pkt_count

the number of packets captured

pkt(i)

the ScamperSniffPkt at index i in the captured packets, starting at index zero.

ScamperSniffPkt

class scamper.ScamperSniffPkt

This class provides information about a packet captured by scamper.

rx

a datetime reporting when the packet was captured.

data

the contents of the packet, from the IP layer onwards.