Skip to content

Latest commit

 

History

History
45 lines (32 loc) · 1.81 KB

API.md

File metadata and controls

45 lines (32 loc) · 1.81 KB

Documentation

This is the documentation for the high-level DNS measurements API using Starlark

For this project, we are using the capabilities of starlark and its Python-like syntax to define DNS measurements, using primitives to send DNS queries and parse DNS responses.

Principles

  • All scripts are short-lived and resource-constrained.
  • If you need to save state, need to save it in the key-value store provided via the state object
  • There is no waiting

Results format

  • Measurement code will return a dictionary with the following structure ** timestamp, identify when the data ** ProbeId, a string identified which probe ran the code ** result, with the raw payload as generated by the measurement ** tag, a string to identify the collection

Sending DNS queries

At the moment there is one working implementation of a measurement provider using dig. The plan is to create more providers that will transparently interact with RIPE Atlas, Scamper, and other platforms.

To send a DNS query and retrieve the results, use

dns_result = measure.dig('NS .')

where dns_result will be a dictionary with the parts of a typical DNS response TODO Add more detail here

Primitives

There is a library of primitives to handle and extract useful information from DNS responses. To use a primitive function in your measurement code, you can import by adding

load("primitives.star", "name_of_function")

Examples

Under the code-runner directory there are some example scripts implementing generic DNS measurements

  • serialchecker.star: Checks for the serial number of the root zone (.) across all root servers
  • recursive.star: implements recursive resolution of google.com by following delegations from the root zone
  • propagation.star: monitors how long a zone takes to be propagated across all their nameservers