ripe.atlas.sagan 1.1.6

RIPE Atlas Sagan

A parsing library for RIPE Atlas measurement results

$ pip install ripe.atlas.sagan

$ pip install ripe.atlas.sagan[fast,doc]

$ SAGAN_WITHOUT_SSL=1 pip install ripe.atlas.sagan

from ripe.atlas.sagan import PingResult

my_result = PingResult("<result string from RIPE Atlas ping measurement>")

print(my_result.rtt_median)
123.456

print(my_result.af)
6

from ripe.atlas.sagan import PingResult

my_result = PingResult(
    json.loads("<result string from RIPE Atlas ping measurement>")
)

print(my_result.rtt_median)
123.456

print(my_result.af)
6

from ripe.atlas.sagan import Result

my_result = Result.get("<result string from RIPE Atlas ping measurement>")

print(my_result.rtt_median)
123.456

print(my_result.af)
6

from ripe.atlas.sagan import DnsResult

my_dns_result = DnsResult("<result string from a RIPE Atlas DNS measurement>")
my_dns_result.responses[0].abuf  # The entire string
my_dns_result.responses[0].abuf.header.arcount  # Decoded from the abuf

# Ping
ping_result.packets_sent  # Int
ping_result.rtt_median    # Float, rounded to 3 decimal places
ping_result.rtt_average   # Float, rounded to 3 decimal places

# Traceroute
traceroute_result.af                   # 4 or 6
traceroute_result.total_hops           # Int
traceroute_result.destination_address  # An IP address string

# DNS
dns_result.responses                        # A list of Response objects
dns_result.responses[0].response_time       # Float, rounded to 3 decimal places
dns_result.responses[0].headers             # A list of Header objects
dns_result.responses[0].headers[0].nscount  # The NSCOUNT value for the first header
dns_result.responses[0].questions           # A list of Question objects
dns_result.responses[0].questions[0].type   # The TYPE value for the first question
dns_result.responses[0].abuf                # The raw, unparsed abuf string

# SSL Certificates
ssl_result.af                        # 4 or 6
ssl_result.certificates              # A list of Certificate objects
ssl_result.certificates[0].checksum  # The checksum for the first certificate

# HTTP
http_result.af                      # 4 or 6
http_result.uri                     # A URL string
http_result.responses               # A list of Response objects
http_result.responses[0].body_size  # The size of the body of the first response

# NTP
ntp_result.af                          # 4 or 6
ntp_result.stratum                     # Statum id
ntp_result.version                     # Version number
ntp_result.packets[0].final_timestamp  # A float representing a high-precision NTP timestamp
ntp_result.rtt_median                  # Median value for packets sent & received

$ python setup.py test

$ pip install tox
$ tox

Changelog

• 1.1.6

  • Fix for Issue #56 a case where the qbuf value wasn’t being properly captured.

  • Fixed small bug that didn’t accurately capture the DO property from the qbuf.

• 1.1.5

  • We now ignore so-called “late” packets in traceroute results. This will likely be amended later as future probe firmwares are expected to make better use of this value, but until then, Sagan will treat these packets as invalid.

• 1.1.4

  • Added a type attribute to all Result subclasses

  • Added support for a lot of new DNS answer types, including NSEC, PTR, SRV, and more. These answers do not yet have a complete string representation however.

• 1.1.3

  • Changed the name of TracerouteResult.rtt_median to TracerouteResult.last_rtt_median.

  • Modified the DnsResult class to allow the “bubbling up” of error statuses.

• 1.1.2

  • We skipped this number for some reason :-/

• 1.1.1

  • Fixed a string representation bug found by iortiz

• 1.1.0

  • Breaking Change: the Authority and Additional classes were removed, replaced with the appropriate answer types. For the most part, this change should be invisible, as the common properties are the same, but if you were testing code against these class types, you should consider this a breaking change.

  • Breaking Change: The __str__ format for DNS RrsigAnswer to conform the output of a typical dig binary.

  • Added __str__ definitions to DNS answer classes for use with the toolkit.

  • In an effort to make Sagan (along with Cousteau and the toolkit) more portable, we dropped the requirement for the arrow package.

• 1.0.0

  • 1.0! w00t!

  • Breaking Change: the data property of the TxtAnswer class was changed from a string to a list of strings. This is a correction from our own past deviation from the RFC, so we thought it best to conform as part of the move to 1.0.0

  • Fixed a bug where non-ascii characters in DNS TXT answers resulted in an exception.

• 0.8.2

  • Fixed a bug related to non-ascii characters in SSL certificate data.

  • Added a wrapper for json loaders to handle differences between ujson and the default json module.

• 0.8.1

  • Minor fix to make all Result objects properly JSON serialisable.

• 0.8.0

  • Added iortiz’s patch for flags and flags and sections properties on DNS Answer objects.

• 0.7.1

  • Changed README.md to README.rst to play nice with pypi.

• 0.7

  • Added pierky’s new RRSigAnswer class to the dns parser.

• 0.6.3

  • Fixed a bug in how Sagan deals with inappropriate firmware versions

• 0.6.2

  • Added pierky’s fix to fix AD and CD flags parsing in DNS Header

• 0.6.1

  • Added rtt_min, rtt_max, offset_min, and offset_max to NTPResult

• 0.6.0

  • Support for NTP measurements

  • Fixes for how we calculate median values

  • Smarter setup.py

• 0.5.0

  • Complete Python3 support!

• 0.4.0

  • Added better Python3 support. Tests all pass now for ping, traceroute, ssl, and http measurements.

  • Modified traceroute results to make use of destination_ip_responded and last_hop_responded, deprecating target_responded. See the docs for details.

• 0.3.0

  • Added support for making use of some of the pre-calculated values in DNS measurements so you don’t have to parse the abuf if you don’t need it.

  • Fixed a bug in the abuf parser where a variable was being referenced by never defined.

  • Cleaned up some of the abuf parser to better conform to pep8.

• 0.2.8

  • Fixed a bug where DNS TXT results with class IN were missing a .data value.

  • Fixed a problem in the SSL unit tests where \n was being misinterpreted.

• 0.2.7

  • Made abuf more robust in dealing with truncation.

• 0.2.6

  • Replaced SslResult.get_checksum_chain() with the SslResult.checksum_chain property.

  • Added support for catching results with an err property as an actual error.

• 0.2.5

  • Fixed a bug in how the on_error and on_malformation preferences weren’t being passed down into the subcomponents of the results.

• 0.2.4

  • Support for seconds_since_sync across all measurement types

• 0.2.3

  • “Treat a missing Type value in a DNS result as a malformation” (Issue #36)

• 0.2.2

  • Minor bugfixes

• 0.2.1

  • Added a median_rtt value to traceroute Hop objects.

  • Smarter and more consistent error handling in traceroute and HTTP results.

  • Added an error_message property to all objects that is set to None by default.

• 0.2.0

  • Totally reworked error and malformation handling. We now differentiate between a result (or portion thereof) being malformed (and therefore unparsable) and simply containing an error such as a timeout. Look for an is_error property or an is_malformed property on every object to check for it, or simply pass on_malformation=Result.ACTION_FAIL if you’d prefer things to explode with an exception. See the documentation for more details

  • Added lazy-loading features for parsing abuf and qbuf values out of DNS results.

  • Removed the deprecated properties from dns.Response. You must now access values like edns0 from dns.Response.abuf.edns0.

  • More edge cases have been found and accommodated.

• 0.1.15

  • Added a bunch of abuf parsing features from b4ldr with some help from phicoh.

• 0.1.14

  • Fixed the deprecation warnings in DnsResult to point to the right place.

• 0.1.13

  • Better handling of DNSResult errors

  • Rearranged the way abufs were handled in the DnsResult class to make way for qbuf values as well. The old method of accessing header, answers, questions, etc is still available via Response, but this will go away when we move to 0.2. Deprecation warnings are in place.

• 0.1.12

  • Smarter code for checking whether the target was reached in TracerouteResults.

  • We now handle the destination_option_size and hop_by_hop_option_size values in TracerouteResult.

  • Extended support for ICMP header info in traceroute Hop class by introducing a new IcmpHeader class.

• 0.1.8

  • Broader support for SSL checksums. We now make use of md5 and sha1, as well as the original sha256.