API Documentation

Forward DNS lookups are lookups which start with a hostname and return the for the DNS A (IPv4) and AAAA (IPv6) records for that host. Driftnet collects forward-DNS lookups for every hostname it encounters.

The simplest possible search is for the DNS records associated with a subdomain:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/domain/fdns?host=driftnet.io' \
  | jq . \
  | less -S

{
  "page": 0,
  "pages": 1,
  "result_count": 6,
  "results": [
    {
      "date": "2019-05-13",
      "id": "a61RNzK3QzKCv24gt1HQoA",
      "items": [
        {
          "context": "",
          "is_metadata": true,
          "type": "host",
          "value": "example.driftnet.io"
        },
        {
          "context": "dns-a",
          "is_metadata": false,
          "type": "ip",
          "value": "199.36.158.100"
        },
        {
          "context": "dns-ns",
          "is_metadata": false,
          "type": "host",
          "value": "alexis.ns.cloudflare.com"
        }
      ]
    },
    ...

This tells us that a lookup for example.driftnet.io returned a particular IP address (context dns-a), and that the return came from a particular nameserver (context dns-ns).

It can often be interesting to perform the inverse search, and determine which domain names are associated with an IP address. We can reverse-search using the IP parameter. For example, to find all the domain names pointed at 8.8.8.8 — there are a lot! — then we could call

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/domain/fdns?ip=8.8.8.8' \
  | jq . \
  | less -S

We can also reverse-search by nameserver:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/domain/fdns?nameserver=icann.org' \
  | jq . \
  | less -S

It is often useful to roll up the results of a search. To get all the domain names served up by an *.icann.org DNS server, we might call

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/domain/fdns?nameserver=icann.org&summarize=host&summary_context=dns-a' \
  | jq . \
  | less -S

{
  "summary": {
    "other": 1122,
    "values": {
      "62.schedule.icann.org": 3,
      "64.schedule.icann.org": 3,
      "65.schedule.icann.org": 4,
      ...

The summary options works in the same way as described in the Internet Scans section; see that section for more details.

The domain/fdns endpoint also accepts the expression=, from=, to=, filter=, and page= parameters. Again, these work exactly as described in the Internet Scans section.

To see only the most recent DNS lookup results, set the most_recent=true parameter.