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 scamper module has two related halves – classes for interacting with running scamper processes (through ScamperCtrl and related classes) and classes 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 the scamper module include ping, traceroute, alias resolution, DNS queries, HTTP, UDP probes, and packet capture.

Interacting with Scamper Processes¶

It is possible to interact with local and remote scamper processes. A local scamper process is a process running on the same system as the Python script that controls it. Local scamper processes can be available via a unix domain socket:

$ scamper -U /path/to/socket

Local scamper processes can be available via a port bound to a loopback interface:

$ scamper -P 31337

Remote scamper processes can be connected to a local controller that presents interfaces to local users. The following allows remote scamper processes to connect to port 31338 on the local machine, and provides access to the VPs via a multiplexed interface via a unix domain socket.

$ sc_remoted -P 31338 -M /path/to/mux

The controller can also present individual unix domain sockets that correspond to individual remote scamper processes.

$ sc_remoted -P 31338 -M /path/to/mux -U /path/to/socket-dir

Scripts shoud use the multiplexed interface whenever possible, as the multiplexed interface can provide meta-data for the remote scamper processes, and scales better.

Simple Parallel Measurement: Shortest Ping¶

The following example implements the well-known shortest-ping 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 unix domain socket that provides a multiplexed interface to a set of ScamperVp objects, each of which represents a vantage point running scamper. The ScamperCtrl object provides a list of available vantage points annotated with metadata via vps(). The script adds all of the ScamperVp to the ScamperCtrl object when it calls add_vps(). These VPs become ScamperInst objects, each of which represents an open channel to the VP, which can then be used to conduct measurements and collect their results. The script then conducts a ping measurement via each of the ScamperInst objects returned by instances(). These ping measurements operate in parallel – the ping measurements on each of the nodes operate asynchronously. The script then collects the results of the measurements, noting the minimum observed delay, and the vantage point where it came from. The script passes a 10-second timeout to responses() so that if a vantage point experiences an outage, it does not hold up the whole experiment. Finally, the script prints the result of the measurement.

import sys
from datetime import timedelta
from scamper import ScamperCtrl

if len(sys.argv) != 3:
  print('usage: shortest-ping.py $mux $ip')
  sys.exit(-1)

with ScamperCtrl(mux=sys.argv[1]) as ctrl:
  ctrl.add_vps(ctrl.vps())
  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: RTTs to Authoritative Nameservers¶

The next example shows a more complex measurement. This script measures the RTTs to the authoritative name servers for a zone from a single vantage point. This script takes two parameters – a single vantage point, and the name of the zone to study. The script opens an interface to that VP by specifying a unix domain socket that maps to that single VP, and issues 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 to 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 scamper module also supports a more dynamic approach to interacting with many vantage points that each signal their desire for more work. The following script maintains a list of addresses per vantage point to ping. The vps dictionary maintains a mapping of ScamperInst to that list of addresses. The morecb parameter references a callback function that the ScamperCtrl calls when a ScamperInst signals that it is ready for more work. The callback has three parameters: the overall ScamperCtrl, the specific ScamperInst that wants another measurement, and the param that the script specified when it created the ScamperCtrl object.

import sys
from scamper import ScamperCtrl
from datetime import timedelta

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

def _main(mux_path):
  vps = {}
  ctrl = ScamperCtrl(morecb=_feedme, param=vps, mux=mux_path)
  ctrl.add_vps(ctrl.vps())
  for inst in ctrl.instances():
    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 scamper 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 script illustrates the overall approach:

from scamper import ScamperFile, ScamperTrace

addrs = set()
inf = ScamperFile('foo.warts.gz')
for obj in inf:
  if isinstance(obj, ScamperTrace):
    for hop in obj.hops():
      if hop is not None:
        addrs.add(hop.src)
file.close()

for addr in sorted(addrs):
  print(addr)

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

Alternatively, you can use the standard Python context manager interface, and the filter_types() method to filter ScamperTrace objects:

from scamper import ScamperFile, ScamperTrace

addrs = set()
with ScamperFile('foo.warts.gz', filter_types=[ScamperTrace]) as inf:
  for obj in inf:
    for hop in obj.hops():
      if hop is not None:
        addrs.add(hop.src)

for addr in sorted(addrs):
  print(addr)

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.

To save measurement results collected via a ScamperCtrl, first open a file, and then pass a reference to the file to the ScamperCtrl constructor.

from scamper import ScamperCtrl, ScamperFile

outfile = ScamperFile('foo.warts.gz', 'w')
ctrl = ScamperCtrl(mux='/path/to/mux', 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, mux=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 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 morecb function can be changed during a measurement using the morecb attribute.

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 eofcb function can be changed during a measurement using the eofcb attribute.

The param parameter is the user-supplied parameter that will be passed to morecb and eofcb. The param value can be changed during a measurement using the param attribute.

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 outfile value can be changed during a measurement using the outfile attribute.

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 mux parameter identifies the path to a unix domain socket representing a set of remote scamper instances, all accessible over the single socket.

The remote_dir parameter identifies the path to a directory in the file system containing multiple unix domain sockets, each of which represents 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(mux='/path/to/mux', outfile=outfile) as ctrl:
     ctrl.add_vps(ctrl.vps())
     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 that 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 object.

It is also possible to 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_mux(path)¶

Add a multiplexing socket to the ScamperCtrl object. Currently, no value is returned from this method call. Adding a multiplexing socket does not automatically add individual ScamperInst for each of the available instances. Obtain a list of the available vantage points by calling vps(), and add vantage points of interest by calling add_vps().

You can also connect to a multiplexing socket constructing the ScamperCtrl object by passing the path to the path 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.

vps()¶

Returns a list of ScamperVp available through the ScamperCtrl object. Each ScamperVp object may have metadata that is useful when selecting vantage points to use.

# get a list of all VPs
vps = ctrl.vps()

# select VPs within NZ
vps = [vp for vp in ctrl.vps() if vp.cc == 'NZ']

# select VPs within the US and CA
vps = [vp for vp in ctrl.vps() if vp.cc in ('US', 'CA')]

# select VPs with tag 'hw:rpi4'
vps = [vp for vp in ctrl.vps() if 'hw:rpi4' in vp.tags]

add_vps()¶

Add each of the specified ScamperVp to the ScamperCtrl object, making them available as ScamperInst from which you can issue measurements.

# connect to the mux interface
ctrl = ScamperCtrl(mux='/path/to/mux')

# select the VPs to use in the script
vps = ctrl.vps()

# add these VPs to the set managed by ScamperCtrl
ctrl.add_vps(vps)

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.

instances()¶

Return a list of ScamperInst managed by the ScamperCtrl. This provides a convenient interface to issue commands to all available vantage points. If the ScamperInst were obtained from a mux interface, then they are annotated with the same properties as the ScamperVp they were derived from.

# obtain all instances
insts = ctrl.instances()

# do pings from all NZ instances
insts = [vp for vp in ctrl.vps() if vp.cc == 'NZ']
ctrl.do_ping('192.0.2.1', inst=insts)

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 can be provided as a timedelta object. If the parameter is not provided as a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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.

# conduct a traceroute, and collect the result with poll,
# waiting for up to ten seconds
ctrl.do_trace('192.0.2.1')
obj = ctrl.poll(timeout=timedelta(seconds=10))

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 specifies the length of time the responses generator can block before returning, and can be provided as a timedelta object. If the parameter is not provided as a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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.

# conduct pings to two different destinations, and collect
# the responses, waiting for up to ten seconds
ctrl.do_ping('192.0.2.1')
ctrl.do_ping('192.0.2.2')
for obj in ctrl.responses(timeout=timedelta(seconds=10)):
  pass

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.

morecb¶: The 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 (param) that is passed to the callback to use. This attribute provides a setter interface that the caller can use to change the morecb during a measurement.

eofcb¶: The callback function that ScamperCtrl will use when an instance signals that it has finished. The callback takes the same three parameters that morecb does. This attribute provides a setter interface that the caller can use to change the eofcb during a measurement.

param¶: The parameter that will be passed to the morecb and eofcb callback functions. This attribute provides a setter interface that the caller can use to change the parameter during a measurement.

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.

# connect to a local scamper instance and issue a ping
ctrl = ScamperCtrl(unix='/path/to/socket')
ctrl.do_ping('192.0.2.1')

# connect to multiple remote scamper instances and issue pings
# to each instance individually
ctrl = ScamperCtrl(mux='/path/to/mux')
ctrl.add_vps(ctrl.vps())
for i in ctrl.instances():
  ctrl.do_ping('192.0.2.1', inst=i)

Specific do_ methods allow the script to pass a list of ScamperInst where the script does the same measurement from a set of cantage points. Those methods are do_ping(), do_trace(), do_tracelb(), do_dns(), do_mercator(), do_radargun(), do_sniff(), do_http(), do_udpprobe().

# connect to multiple remote scamper instances and issue pings
# to each instance
ctrl = ScamperCtrl(mux='/path/to/mux')
ctrl.add_vps(ctrl.vps())
ctrl.do_ping('192.0.2.1', inst=ctrl.instances())

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 named parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults. The scamper module supplies measurement results from this method in a ScamperTrace object.

method specifies the probing strategy to use:

'udp-paris' (default) sends UDP probes while holding the source and destination ports constant.
'icmp-paris' sends ICMP echo probes while holding the ICMP checksum field constant.
'tcp' sends TCP probes with the SYN bit set, holding the source and destination ports constant.
'tck-ack' sends TCP probes with the ACK bit set, holding the source and destination ports constant.
'udp' sends UDP probes holding the source port constant, but incrementing the destination port with each probe.
'icmp' sends ICMP echo probes without holding the ICMP checksum field constant.

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. A script does not normally supply the sport or icmp_sum parameters, leaving scamper to choose these values. It is more common for a measurement to choose a dport according to measurement needs.

# TCP traceroute to HTTPS (port 443)
ctrl.do_trace('192.0.2.1', method='tcp', dport=443)

# specify the ICMP checksum in ICMP Paris probes
ctrl.do_trace('192.0.2.1', method='icmp-paris', icmp_sum=1234)

firsthop specifies the TTL to start probing with. gaplimit specifies how many consecutive unresponsive hops before traceroute should stop. squeries specifies the number of consecutive hops to probe before stopping to wait for a response. By default, scamper starts probing with TTL value 1, stops probing after five consecutive unresponsive hops, and probes one hop at a time. scamper requires that squeries not be larger than gaplimit.

# traceroute with probes to five consecutive hops in flight
ctrl.do_trace('192.0.2.1', method='icmp-paris', squeries=5)

# start probing 3 hops into the path
ctrl.do_trace('192.0.2.1', firsthop=3)

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. By default, scamper waits five seconds before timing out, and does not enforce a minimum length of time between probes. Both parameters can be provided as timedelta objects. If either parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

# timeout of 2 seconds, with 50ms delay between probes.
ctrl.do_trace('192.0.2.1',
              wait_timeout=timedelta(seconds=1),
              wait_probe=timedelta(milliseconds=50))

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. 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. By default, scamper sends up to two probes per hop, and does not attempt to observe all interfaces to any defined confidence value.

# send three-probes per hop
ctrl.do_trace('192.0.2.1', attempts=3, all_attempts=True)

# send repeated probes until achieving 95% confidence
ctrl.do_trace('192.0.2.1', confidence=95)

pmtud, if True, instructs scamper to do Path-MTU probing of the path, to identify MTU changes in the path. This method requires use of UDP probes.

# do path-mtu probing with a UDP-paris traceroute
ctrl.do_trace('192.0.2.1', method='udp-paris', pmtud=True)

ptr, if True, instructs scamper to look up the name of any IP address observed in a response.

# print DNS names of interfaces if available
trace = ctrl.do_trace('192.0.2.1', ptr=True, sync=True)
for i, hop in enumerate(trace.hops()):
  out = f'{i:2}'
  if hop:
    if hop.name:
      print(f'{i:2} {hop.name}')
    else:
      print(f'{i:2} {hop.src}')
  else:
    print(f'{i:2} *')

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.

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.

# identify hops that change the TOS byte in flight, printing
# the byte in bits.
ctrl = ScamperCtrl(unix=sys.argv[1])
tos = int(sys.argv[3])
trace = ctrl.do_trace(sys.argv[2], tos=tos, sync=True)
print(f'trace to {sys.argv[2]} tos {tos:0>8b}')
for i, hop in enumerate(trace.hops()):
  out = f'{i:2}'
  if hop:
    out += f' {hop.src:15}'
    if hop.icmp_q_tos:
      out += f' {hop.icmp_q_tos:0>8b}'
  else:
    out += ' *'
  print(out)

loops specifies the number of loops allowed before traceroute stops.

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 scamper module supplies measurement results from this method in a ScamperTracelb object.

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. By default, scamper waits five seconds before timing out, and sends probes no faster than every 250 milliseconds. Both parameters can be provided as timedelta objects. If either parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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. The scamper module supplies measurement results from this method in a ScamperPing object.

method specifies the probe strategy to use:

'icmp-echo' (default) sends ICMP echo request probes.
'icmp-time' sends ICMP time request probes.
'udp' sends UDP probes while holding the source and destination ports constant,
'udp-dport' sends UDP probes where the destination port changes while the source port is held constant,
'udp-sport' sends UDP probes where the source port changes while the destination port is held constant,
'tcp-syn' and 'tcp-ack' send TCP probes with only the SYN or ACK bit set while holding the source and destination ports constant,
'tcp-syn-sport' and 'tcp-ack-sport' send TCP probes with only the SYN or ACK bit set, where the source port changes while holding the destination port constant,
'tcp-synack' sends TCP probes with both the SYN and ACK bits set, holding the source and destination ports constant.
'tcp-rst' sends TCP probes with the RST bit set, holding the source and destination ports constant.

sport and dport specify the source and destination port values for TCP and UDP probe methods. tcp_seq and tcp_ack specify the values to insert in the TCP sequence and acknowledgment fields. icmp_id, icmp_seq, and icmp_sum specify the ID, sequence, and checksum values to use in the ICMP header.

# send five SYN packets, varying source port, to port 80
ctrl.do_ping('192.0.2.1', method='tcp-syn-sport', dport=80)

attempts specifies the number of probes to send. stop_count specifies the number of probes that need a response before stopping. By default, scamper will send four probes before stopping.

# send up to eight probes, stopping after getting six responses
ctrl.do_ping('192.0.2.1', attempts=8, stop_count=6)

wait_probe and wait_timeout specify the length of time between probes, and how long to wait for a response to a probe. By default, scamper waits 1 second between probes, and applies a 1 second timeout after it has sent the last probe. Both parameters can be provided as timedelta objects. If either parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

# send five probes with a 200ms interval
ctrl.do_ping('192.0.2.1', attempts=5, wait_probe=0.2)

tos and ttl specify the type-of-service and TTL values to use in the IP header. By default, scamper sets the tos byte to zero, and the ttl value to 64.

# send 200 TTL-limited probes, soliciting TTL expired messages
# from the fifth hop
ctrl.do_ping('192.0.2.1', attempts=200, ttl=5)

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. 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, otherwise it will return a ScamperTask representing the scheduled measurement.

do_dns(qname, server=None, qclass=None, qtype=None, attempts=None, rd=None, wait_timeout=None, tcp=None, nsid=None, ecs=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. The scamper module supplies measurement results from this method in a ScamperHost object.

attempts specifies the number of queries to send before stopping. By default, scamper sends the query once.

wait_timeout specifies the length of time to wait for a response. By default, scamper waits five seconds for a response before timing out. wait_timeout can be provided as a timedelta object. If it is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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, scamper will issue a 'ptr' query if the qname is an address, else scamper will issue an 'a' query.

# issue a PTR query for 192.0.2.1
ctrl.do_dns('192.0.2.1')

# issue an A query for www.example.com
ctrl.do_dns('www.example.com')

# issue an IPv6 address query for www.example.com
ctrl.do_dns('www.example.com', qtype='aaaa')

server specifies the IP address of the DNS server to use. By defauly, scamper will issue queries to the DNS server specified as the VP’s local resolver.

# send a chaos txt query to f-root to obtain the name of the
# server that answers
ctrl.do_dns('hostname.bind', qclass='ch', qtype='txt',
            server='2001:500:2f::f')

rd, if True, signals to the DNS server that this is a recursive query. By default, scamper issues recursive queries.

# issue a non-recursive NS query for 'com' to 202.12.27.33
ctrl.do_dns('com', qtype='ns', rd=False, server='202.12.27.33')

# issue a recursive query for 'www.caida.org' to 8.8.8.8
ctrl.do_dns('www.caida.org', rd=True, server='8.8.8.8')

tcp, if True, signals that the measurement should use TCP instead of UDP. This is useful if the response to a UDP query is truncated.

# issue a query for 'locations.publicdns.goog' over TCP using
# the local resolver
ctrl.do_dns('locations.publicdns.goog', qtype='txt', tcp=True)

nsid, if True, signals that the query should request the server embed an NSID OPT record in the response.

# issue a query for example.com to 192.5.5.241, soliciting an
# NSID record
ctrl.do_dns('example.com', nsid=True, server='192.5.5.241')

ecs specifies the EDNS-client-subnet (ECS) option to include in the query.

# issue a query for example.com with ECS option for 192.0.2.0/24
ctrl.do_dns('example.com', ecs='192.0.2.0/24')

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. The scamper module supplies measurement results from this method in a ScamperHttp object.

# do a simple HTTP query
ctrl.do_http('192.0.2.1', 'https://www.example.com/')

# HTTP query to a system listening on port 8080
ctrl.do_http('192.0.2.1', 'http://www.example.com:8080/')

headers specifies a dictionary that maps header names to values to include in the GET request.

# provide a header in the HTTP request
ctrl.do_http('192.0.2.1', 'https://www.example.com/',
             headers = {'Hello-World': 'true',
                        'Referer', 'https://www.caida.org/~mjl/'})

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. By default, scamper waits 60 seconds. limit_time cannot be less than 1 second or greater than 60 seconds. limit_time can be provided as a timedelta object. If it is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

# limit the exchange to 30 seconds, provided as integer
ctrl.do_http('192.0.2.1', 'https://www.example.com/',
             limit_time = 30)

# limit the exchange to 30 seconds, provided as timedelta
ctrl.do_http(''192.0.2.1', 'https://www.example.com/',
             limit_time = datetime.timedelta(seconds=30))

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, src=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. The other named parameters are optional; if they are not specified, then the scamper process that does the measurement will use its defaults. The scamper module supplies measurement results from this method in a ScamperUdpprobe object.

# send an SNMPv3 query
snmpq = bytes.fromhex('303a020103300f02024a69020300ffe304010402010304'
                      '10300e0400020100020100040004000400301204000400'
                      'a00c020237f00201000201003000')
ctrl.do_udpprobe('192.0.2.1', 161, snmpq)

attempts specifies the number of probes to send before stopping. src specifies the source IP address to use in probes. 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. Ally infers that two IP addresses are aliases if the the IPIDs embedded in responses appear to have been derived from the same counter. The scamper module supplies measurement results from this method in a ScamperDealias object.

# infer if 192.0.2.1 and 192.0.2.2 are aliases
test = ctrl.do_ally('192.0.2.1', '192.0.2.2', sync=True)
print(test.has_aliases())

method specifies the probing strategy to use:

'udp' (default) sends UDP probes while holding the source and destination ports constant.
'udp-dport' sends UDP probes holding the source port constant, but incrementing the destination port with each probe.
'tcp-ack' sends TCP probes with the ACK bit set, holding the source and destination ports constant.
'tcp-syn-sport' and 'tcp-ack-sport' send TCP probes with only the SYN or ACK bit set, where the source port changes while holding the destination port constant.
'icmp-echo' sends ICMP echo request probes.

The fudge value specifies the maximum difference between IPID values to still consider as possibly from the same counter. If fudge is zero, then the only requirement is for the IPID values to possibly be in sequence. By default, scamper uses a fudge of 200.

# infer if 192.0.2.1 and 192.0.2.2 are aliases, with a fudge of 1000
ctrl.do_ally('192.0.2.1', '192.0.2.2', fudge=1000)

# infer if 192.0.2.1 and 192.0.2.2 are aliases, because the
# IPIDs could be interpreted as in-sequence
ctrl.do_ally('192.0.2.1', '192.0.2.2', fudge=0)

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.

attempts specifies the total number of probes to send in this measurement. By default, scamper sends five packets in total.

wait_probe and wait_timeout specify the length of time between probes, and how long to wait for a response to a probe. By default, scamper sends probes every 150ms, and uses a five second timeout. Both parameters can be provided as timedelta objects. If either parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

# send seven TCP packets at 500ms interval to port 443
ctrl.do_ally('192.0.2.1', '192.0.2.2', method='tcp-ack',
             dport=443, fudge=0, attempts=7,
             wait_timeout=timedelta(seconds=1),
             wait_probe=timedelta(milliseconds=500))

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 scamper module supplies measurement results from this method in a ScamperDealias object.

The rounds parameter specifies how many rounds to conduct. By default, scamper does 30 rounds.

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. By default, scamper sends probes every 150ms, uses a five second timeout, and computes the round-time as a product of the number of packets to send per round and the length of time between probes. These parameters can be provided as timedelta objects. If a parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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. The scamper module supplies measurement results from this method in a ScamperDealias object.

startat specifies when probing should commence, which can be used to synchronize probing among a set of vantage points. The parameter must be a datetime.datetime object.

wait_timeout specifies the length of time to wait for a response to a probe. By default, scamper waits for one second. wait_timeout can be provided as a timedelta object. If it is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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. The scamper module supplies measurement results from this method in a ScamperDealias object.

rounds specifies the number of rounds for this measurement. By default, scamper does 30 rounds over the probedefs.

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. By default, scamper sends probes every 150ms, uses a five second timeout, and computes the round-time as a product of the number of packets to send per round and the length of time between probes. These parameters can be provided as timedelta objects. If a parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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 scamper module supplies measurement results from this method in a ScamperDealias object.

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.

The fudge value specifies the maximum difference between IPID values to still consider as possibly from the same counter. If fudge is zero, then the only requirement is for the IPID values to possibly be in sequence. By default, scamper uses a fudge of 200.

attempts specifies the total number of attempts per probe, before moving onto the next address pair. By default, scamper will try twice if the first probe does not obtain a response.

wait_probe and wait_timeout specify the length of time between probes, and how long to wait for a response to a probe. By default, scamper sends probes every second, and uses a five second timeout. Both parameters can be provided as timedelta objects. If either parameter is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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. The scamper module supplies measurement results from this method in a ScamperSniff object.

limit_pkt_count specifies the maximum number of packets to capture before returning. By default, scamper collects up to 100 packets. limit_pkt_count cannot be less than one, or greater than 5000.

limit_time specifies the maximum length of time to wait before returning. By default, scamper waits up to 60 seconds. limit_time cannot be less than one second or greater than 1200 seconds. limit_time can be provided as a timedelta object. If it is not a timedelta, then the value will internally be converted to a timedelta, with the value interpreted as seconds.

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. The scamper module supplies measurement results from this method in a ScamperTbit object.

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.

shortname¶: a shortened string that identifies the instance in some way, if available.

ipv4¶: a string containing the IPv4 address of the VP, if available.

asn4¶: an integer containing the IPv4 ASN address of the VP, if available.

cc¶: an upper-case string containing the country location of the VP, if available. The string is provided by the platform operator to the controller, and by convention should be an ISO-3166-1 country code. For example, this will be 'US' for a VP in the USA.

st¶: an upper-case string containing the state location of the VP, if available. The string is provided by the platform operator to the controller, and by convention should be an ISO-3166-2 subdivision (province or state) code. For example, this will be 'CA' for a VP in California, USA.

place¶: a string containing the place name of the VP, if available.

loc¶: a pair of floats containing the latitude and longitude of the VP, if available.

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.

`ScamperVp`¶

class scamper.ScamperVp¶

ScamperVp objects provide metadata for remote scamper vantage points available over the multiplexed socket interface.

name¶: a string that identifies the instance in some way.

shortname¶: a shortened string that identifies the instance in some way, if available.

ipv4¶: a string containing the IPv4 address of the VP, if available.

asn4¶: an integer containing the IPv4 ASN address of the VP, if available.

cc¶: an upper-case string containing the country location of the VP, if available. The string is provided by the platform operator to the controller, and by convention should be an ISO-3166-1 country code. For example, this will be 'US' for a VP in the USA.

st¶: an upper-case string containing the state location of the VP, if available. The string is provided by the platform operator to the controller, and by convention should be an ISO-3166-2 subdivision (province or state) code. For example, this will be 'CA' for a VP in California, USA.

place¶: a string containing the place name of the VP, if available.

loc¶: a pair of floats containing the latitude and longitude of the VP, if available.

tags¶: a set of strings containing the tags registered with the VP.

`ScamperTask`¶

class scamper.ScamperTask¶

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.

`ScamperIcmpExts`¶

class scamper.ScamperIcmpExts¶

Scamper records ICMP extension data across different measurement types in ScamperIcmpExts container objects. A single ScamperIcmpExts object can contain one or more ScamperIcmpExt objects. The most common type of ICMP extension is the MPLS extension, and this class provides a short cut attribute to obtain that class of ICMP extension. This class implements methods that allow ScamperIcmpExt objects to be sorted.

ext_count¶: returns the number of ICMP extensions in the ScamperIcmpExts container.

ext(i)¶: returns the ScamperIcmpExt at offset i.

exts()¶: returns an iterator that returns all ScamperIcmpExt in the ScamperIcmpExts container.

mpls¶: returns the first ScamperIcmpExt object recording MPLS extensions, if the ICMP extension structure included that type of extension, or None.

`ScamperIcmpExt`¶

class scamper.ScamperIcmpExt¶

This class records a single ICMP extension found within a ScamperIcmpExts container object. 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.

to_json()¶: Returns a string containing a JSON rendering of this measurement.

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 scamper obtained for each hop, as a ScamperTraceHop. If a hop was unresponsive, then it will have None.

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.

stop_reason¶

returns a ScamperTraceStop enumeration that reports the reason why the traceroute stopped. Possible values are:

ScamperTraceStop.NoReason – the traceroute stopped but there is no reason recorded.
ScamperTraceStop.Completed – the traceroute reached the destination.
ScamperTraceStop.Unreach – the traceroute stopped because it received an ICMP Unreachable message.
ScamperTraceStop.Icmp – the traceroute stopped because it received an ICMP error message that was not an ICMP Unreachable message.
ScamperTraceStop.Loop – the traceroute stopped because it encountered one or more loops.
ScamperTraceStop.GapLimit – the traceroute stopped because it encountered a consecutive series of unresponsive hops.
ScamperTraceStop.Error – the traceroute stopped because scamper encountered an internal error condition.
ScamperTraceStop.HopLimit – the traceroute stopped because it reached the maximum number of permitted hops.
ScamperTraceStop.GSS – the traceroute stopped because it encountered an address in the global stop set.
ScamperTraceStop.Halted – the traceroute stopped because it was told to stop.

stop_reason_str¶

returns a lower-case string that records why the traceroute stopped. the string is provided by the scamper libraries. possible string values are the following, which map to the stop_reason values above:

'none' – the traceroute stopped but there is no reason recorded.
'completed' – the traceroute reached the destination.
'unreach' – the traceroute stopped because it received an ICMP Unreachable message.
'icmp' – the traceroute stopped because it received an ICMP error message that was not an ICMP Unreachable message.
'loop' – the traceroute stopped because it encountered one or more loops.
'gaplimit' – the traceroute stopped because it encountered a consecutive series of unresponsive hops.
'error' – the traceroute stopped because scamper encountered an internal error condition.
'hoplimit' – the traceroute stopped because it reached the maximum number of permitted hops.
'gss' – the traceroute stopped because it encountered an address in the global stop set.
'halted' – the traceroute stopped because it was told to stop.

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.

icmp_exts¶: a ScamperIcmpExts object, if the ICMP response included ICMP extensions.

`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(f'ping from {ping.src} to {ping.dst}')
for i in range(ping.probe_count):
  r = ping.reply(i)
  if r is None:
    print(f'no reply for attempt {i+1}')
  else:
    print(f'reply from {r.src}, attempt {i+1}')

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

# use the iterator without specifying its name
print('ping from {ping.src} to {ping.dst}')
for r in ping:
  print('reply from {r.src}, attempt {r.attempt}')

# use the iterator specified by name
print('ping from {ping.src} to {ping.dst}')
for r in ping.replies():
  print('reply from {r.src}, attempt {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.

to_json()¶: Returns a string containing a JSON rendering of this 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.

replies()¶: returns an iterator that provides the first reply for each probe in the measurement. The iterator does not return objects for probes in the series that obtained no response.

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.

to_json()¶: Returns a string containing a JSON rendering of this measurement.

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.

icmp_exts¶: a ScamperIcmpExts object, if the ICMP response included ICMP extensions.

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.

to_json()¶: Returns a string containing a JSON rendering of this 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.

to_json()¶: Returns a string containing a JSON rendering of this 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 that processes resource records 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 select. This method returns an Iterator that provides ScamperHostRR objects.

# print 'A' records for example.com
dns = ctrl.do_dns('example.com', sync=True)
for rr in dns.ans():
  if rr.addr:
    print(f'{rr.addr}')

# print 'A' records for example.com, with less code
dns = ctrl.do_dns('example.com', sync=True)
for rr in dns.ans(rrtypes=['A']):
  print(f'{rr.addr}')

ans_addrs()¶

return the addresses in the AN section of the first query with a response. This method returns a list of ScamperAddr.

# print 'A' records for example.com, with less code
dns = ctrl.do_dns('example.com', sync=True)
for addr in dns.ans_addrs():
  print(f'{addr}')

ans_mxes()¶: return the MX records in the AN section of the first query with a response. This method returns a list of ScamperHostMX objects.

ans_nses()¶

return a list of all nameservers from the AN section of the first query with a response. This method returns a list of strings.

# print 'NS' records for example.com, with less code
dns = ctrl.do_dns('example.com', qtype='NS', sync=True)
for ns in dns.ans_nses():
  print(ns)

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

ans_ptrs()¶

return a list of all PTR records from the AN section of the first query with a response. This method returns a list of strings.

# print 'PTR' records for 192.0.2.1; PTR is implied by qname
dns = ctrl.do_dns('192.0.2.1', sync=True)
for ptr in dns.ans_ptrs():
  print(ptr)

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.

# print OPT elements in a response
dns = ctrl.do_dns('example.com', nsid=True, sync=True)
for rr in dns.ars(rrtypes=['opt']):
  if rr.opt is None:
    continue
  for elem in rr.opt:
    print(f'{elem.code} {elem.data.hex()}')

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

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

# print MX records for example.com
dns = ctrl.do_dns('example.com', qtype='mx', sync=True)
for mx in dns.ans_mxes():
  print(f'{mx.pref} {mx.exch}')

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 iterator that iterates over the strings in the TXT record.

# print the text strings encoded in TXT records for example.com
dns = ctrl.do_dns('example.com', qtype='txt', sync=True)
for txt in dns.ans_txts():
  for t in txt:
    print(t)

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 iterator 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 element is an NSID, the value will be 3.

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.

`ScamperHostSVCB`¶

class scamper.ScamperHostSVCB¶

This class provides information about a DNS SVCB resource record from a ScamperHost reply. It also provides an iterator that iterates over the parameters in the SVCB record. Each of the parameters are provided as a ScamperHostSVCBParam object.

target¶: the target name in the SVCB record, as a string.

priority¶: the priority recorded in the SVCB record, as a number.

paramc¶: the number of parameters in this SVCB record.

param(i)¶: return the parameter at index i in the SVCB record, starting at zero. The parameter is provided as a ScamperHostSVCBParam object.

`ScamperHostSVCBParam`¶

class scamper.ScamperHostSVCBParam¶

This class provides information about a parameter found in a DNS SVCB record.

key_num¶: the key of the SVCB parameter, as a number. For example, if the SVCB parameter is an ALPN, the value will be 1.

key¶: the key of the SVCB parameter, as a string. The key is one of the values registered in the IANA DNS Service Bindings database.

val¶: a bytes object containing the value in the SVCB parameter, if any. If there is no value 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 HTTP measurement objects. This class provides an iterator over the series of ScamperHttpBuf records that comprised the HTTP exchange.

# use the bufs iterator by name
for b in http.bufs():
  print(f'{b.timestamp} {b.dir_str} {b.type_str} {len(b.payload)}')

# use the bufs iterator without specifying its name
for b in http:
  print(f'{b.timestamp} {b.dir_str} {b.type_str} {len(b.payload)}')

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.

buf_count¶: the number of chunks of data transmitted or received by scamper during the HTTP measurement.

buf(i)¶: returns a ScamperHttpBuf for the nominated chunk of data.

bufs()¶: returns an iterator that provides a series of ScamperHttpBuf recorded during the HTTP measurement.

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

type_str¶: a string representing the type of the chunk. expected values are 'data', 'hdr', and 'tls'.

dir_str¶: a string representing the direction of the chunk. expected values are 'tx' and 'rx'.

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.

to_json()¶: Returns a string containing a JSON rendering of this 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.

to_json()¶: Returns a string containing a JSON rendering of this 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.