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)

with ScamperCtrl(remote_dir=sys.argv[1]) as ctrl:
  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
for ns in o.ans_nses():
  ctrl.do_dns(ns, qtype='A', wait_timeout=1)
  ctrl.do_dns(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:

Traceroute via do_trace()
Ping via do_ping()
Alias resolution via do_ally(), do_mercator(), do_midarest(), do_midardisc(), do_prefixscan(), and do_radargun()
DNS via do_dns()
Packet capture via do_sniff()
MDA traceroute via do_tracelb()
HTTP via do_http()
UDP probes via do_udpprobe()
TCP Behavior Inference via do_tbit()

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.

Alternatively, you can use the standard Python context manager interface:

from scamper import ScamperFile, ScamperTrace

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

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

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.

It is possible to use Python’s context manager interface, as with ScamperFile, to use with / as syntax:

from scamper import ScamperCtrl, ScamperFile

with ScamperFile("foo.warts.gz", 'w') as outfile, \
     ScamperCtrl(remote_dir="/path/to/sockets", outfile=outfile) as ctrl:
     ctrl.do_ping('192.0.2.1', sync=True)

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.

Each of the ScamperCtrl do_ methods may also raise exceptions. These methods will raise RuntimeError if the ScamperInst passed in the inst parameter has signalled end-of-file, as there is no way for the instance to return results. These methods will raise RuntimeError when there is no ScamperInst managed by the ScamperCtrl, as there is no instance to do the measurement. Similarly, these methods will raise RuntimeError when there are multiple ScamperInst managed by the ScamperCtrl, but the caller did not specify which ScamperInst to use. These methods will also raise RuntimeError if the command could not be scheduled. Finally, these methods will raise a TypeError if the caller passes the wrong type to one of the parameters, or a ValueError if the caller passes the correct type but an invalid value.

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, qclass=None, qtype=None, attempts=None, rd=None, wait_timeout=None, tcp=None, nsid=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. qclass specifies the class of query to make (‘in’ or ‘ch’); by default, this is ‘in’. qtype specifies the type of query to make (‘a’, ‘aaaa’, ‘ptr’, ‘mx’, ‘ns’, ‘soa’, ‘txt’); by default, the query will be ‘ptr’ if an address is provided, else it will be an ‘a’ query. attempts specifies the number of queries to send before stopping. rd, if True, signals to the DNS server that this is a recursive query. tcp, if True, signals that the measurement should use TCP instead of UDP. nsid, if True, signals that the query should request the server embed an NSID OPT record in the response. 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, attempts=None, stop_count=None, 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.

attempts specifies the number of probes to send before stopping. stop_count specifies the number of probes that need a response before stopping.

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.

do_tbit(dst, method=None, url=None, userid=None, inst=None, sync-False)¶

Conduct a TBIT (TCP Behavior Inference) test 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. It is highly recommended that a caller provides values for both method and url.

method specifies the TBIT test type to use: pmtud, ecn, null, sack-rcvr, icw, blind-rst, blind-syn, blind-data, or blind-fin. url specifies an HTTP URL to use – if the URL starts with https, then the TBIT test begins with a TLS handshake.

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

`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.

is_eof()¶: returns True if the ScamperInst has signalled end-of-file – that it has no further data 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.

`ScamperInstError`¶

exception scamper.ScamperInstError¶

Raised when a scamper process rejects a measurement request because either the measurement is unsupported, or the parameters are invalid. The exception will report the raw error message that scamper sent.

inst¶: The ScamperInst on which the scamper error message was received.

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 str or bytes representation of the address. The ScamperAddr class implements methods for rendering string representations of the address, sorting, and hashing.

# create an IPv4 address from a string
addr = ScamperAddr('192.0.2.1')
# create the same IPv4 address using a bytes object
addr = ScamperAddr(b'\xc0\x00\x02\x01')
# create an IPv6 address using a bytes object
addr = ScamperAddr(b'\x20\x01\x0d\xb8\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01')
# compare the last address with a string representation of the address
if addr == '2001:db8::1':
  print('this is a documentation address')

packed¶: 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.

stop_hop¶: the index of the hop that would have caused scamper to stop probing. stop_hop can be less than hop_count when the traceroute probed consecutive hops in parallel. scamper will probe multiple hops in parallel when the squeries parameter to do_trace() is greater than one.

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.

addrs(reserved=True)¶: return a list of unique addresses in the path up to stop_hop. if reserved is False then any addresses where scamper.ScamperAddr.is_reserved() would return True are not included.

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. Note that ScamperPing stores all responses received to a given probe, even if they are not from the target. For this reason, you should call is_from_target() before assuming the reply is from the target.

src()¶: a ScamperAddr containing the IP address that replied to a probe.

is_from_target()¶: True if the reply came from the target, i.e., the source address of the response is the same as the destination address of the probe, or if the probe was a UDP probe and the response is an ICMP port unreachable.

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.

rx¶: a datetime for when the response was received. This value is computed by adding rtt to tx. If scamper did not record tx, then rx will be None.

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.

ifname¶: the name of the interface that received the response, if available.

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.

link_count¶: the number of unique links in the graph.

links()¶: an Iterator to step through recorded links.

link(i)¶: 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.

link_count¶: the number of links from this node.

link(i)¶: obtain the ScamperTracelbLink at index i attached to this node.

links()¶: return an Iterator to step through ScamperTracelbLink from this node.

`ScamperTracelbLink`¶

class scamper.ScamperTracelbLink¶

This class provides information about a link observed in an MDA traceroute graph. It also provides a str method to render the node as a simple string.

near¶: the ScamperTracelbNode at the near side of the link.

far¶: the ScamperTracelbNode at the far side of the link.

length¶: the length of the link, in hops. most links in a typical graph will have a length of 1.

probeset(i)¶: obtain a ScamperTracelbProbeset for part of a link.

`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. Note that ScamperDealias stores all responses received to a given probe, even if they are not the desired response type from the target. For this reason, you should call is_from_target() before assuming the reply is from the target.

src()¶: a ScamperAddr containing the IP address that replied to a probe.

is_from_target()¶: True if the reply came from the target, i.e., the source address of the response is the same as the destination address of the probe, or if the probe was a UDP probe and the response is an ICMP port unreachable.

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. The rcode is encoded as a string, and is one of the RCODE names registered in the IANA DNS parameters database.

rcode_num¶: the DNS rcode value obtained in the response, as a number, if the query obtained a response.

tx¶: a datetime for when the first query with a response was sent.

rx¶: a datetime for when the first query with a response was received.

rtt¶: a timedelta containing the round-trip-time for the first query with 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(rrtypes=None)¶: obtain an Iterator over the ScamperHostRR in the AN section of the first query with a response. rrtypes is an optional list of RR types, identified by a string (e.g., ‘a’, ‘ptr’), to return.

ans_addrs()¶: return a list of all ScamperAddr from the AN section of the first query with a response.

ans_nses()¶: return a list of all nameservers from the AN section of the first query with a response.

ans_txts()¶: return a list of all TXT records from the AN section of the first query with a response.

ans_ptrs()¶: return a list of all PTR records 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(rrtypes=None)¶: obtain an Iterator over the ScamperHostRR in the NS section of the first query with a response. rrtypes is an optional list of RR types, identified by a string (e.g., ‘ns’, ‘a’) to return.

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(rrtypes=None)¶: obtain an Iterator over the ScamperHostRR in the AR section of the first query with a response. rrtypes is an optional list of RR types, identified by a string (e.g., ‘a’, ‘aaaa’) to return.

udpsize¶: the UDP payload size reported in the OPT record found in the AR section of the first query with a response.

ends_version¶: the EDNS version reported in the OPT record found in the AR section of the first query with a response.

edns_do¶: True if the EDNS DO flag is set in the OPT record in the AR section of the first query with a response.

extended_rcode¶: the DNS extended rcode value obtained in the response, if the query obtained a response. The extended value includes the bits in an OPT record, if present. The rcode is encoded as a string, and is one of the RCODE names registered by IANA.

extended_rcode_num¶: the DNS rcode value obtained in the response, as a number, if the query obtained a response. The extended value includes the bits in an OPT record, if present.

`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.

opt¶: a ScamperHostOPT containing information recorded in a OPT record, if the RR reported an OPT. otherwise, None.

udpsize¶: the UDP size value reported in the RR, if the RR is an OPT record. otherwise, None.

edns_version¶: the EDNS version reported in the RR, if the RR is an OPT record. otherwise, None.

edns_do¶: the value (True or False) of the DO flag reported in the RR, if the RR is an OPT record. 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.

`ScamperHostTXT`¶

class scamper.ScamperHostTXT¶

This class provides information about a DNS TXT resource record from a ScamperHost reply. It also provides an interator that iterates over the strings in the TXT record.

strc¶: the number of strings in this TXT record.

str(i)¶: return the string at index i, starting at zero.

`ScamperHostOPT`¶

class scamper.ScamperHostOPT¶

This class provides information about a DNS OPT resource record from a ScamperHost reply. It also provides an interator that iterates over the elements in the OPT record. Each of the elements are provided as a ScamperHostOPTElem object.

elemc¶: the number of elements in this OPT record.

elem(i)¶: return the element at index i in the OPT record, starting at zero. The element is provided as a ScamperHostOPTElem object.

`ScamperHostOPTElem`¶

class scamper.ScamperHostOPTElem¶

This class provides information about an element found in a DNS OPT record.

code_num¶: the code of the OPT element, as a number. For example, if the OPT record is an NSID, the value will be 4.

code¶: the code of the OPT element, as a string. The code is one of the EDNS0 Option Codes registered in the IANA DNS parameters database.

data¶: a bytes object containing the data in the OPT record element, if any. If there is no data in the element, this attribute will be None.

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 ScamperUdpprobeProbe records.

for p in udpprobe:
  print(f"{p.tx} {p.sport}")
  for r in p:
    print(f"{p.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 was provided to this measurement.

dport¶: the destination TCP port that scamper used in the exchange.

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.

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

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.

probe_sent¶: the number of probes sent in this measurement.

probe(i)¶: return the ScamperUdpprobeProbe at index i, starting at zero.

replies()¶: return an Iterator that contains the replies obtained during this measurement. Each object is a ScamperUdpprobeReply.

`ScamperUdpprobeProbe`¶

class scamper.ScamperUdpprobeProbe¶

This class provides information about a single probe made in a ScamperUdpprobe measurement.

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

sport¶: the source TCP port that scamper used in the exchange.

reply_count¶: the number of replies recorded for this probe.

reply(i)¶: return the ScamperUdpprobeReply at index i, starting at zero.

`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.

ifname¶: the name of the interface that received the response, if available.

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.

TCP Behavior Inference¶

`ScamperTbit`¶

class scamper.ScamperTbit¶

This class provides information about a TCP Behaviour Inference (TBIT) test collected by scamper. Both ScamperCtrl and ScamperFile objects provide TBIT measurement objects via ScamperTbit. The class provides an Iterator that returns all captured packets in ScamperTbitPkt objects.

for p in tbit:
  print(f"{p.timestamp} {len(p.data)}")

These first attributes and methods report parameters provided to the TBIT 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.

client_mss¶: the TBIT client’s maximum segment size (MSS) used in this measurement.

client_wscale¶: the TBIT client’s window scale parameter used in this measurement.

client_ipttl¶: the TBIT client’s IP TTL parameter used in this measurement.

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

result¶: a string reporting the result of the measurement.

pkt_count¶: the number of packets exchanged in this measurement.

`ScamperTbitPkt`¶

class scamper.ScamperTbitPkt¶

This class provides information about a packet exchanged in a TBIT test.

timestamp¶: a datetime reporting when this packet was transmitted or received by scamper.

data¶: a bytes object containing the IP header, TCP header, and any payload.

is_tx()¶: True if this packet was transmitted by scamper to the server.

is_rx()¶: True if this packet was received by scamper from the server.