API Documentation

Many web servers respond differently when a domain name is presented to them. The same server can be configured to provide a different TLS certificate and/or HTTP response for each of potentially very many domain names.

To cover off this case, Driftnet uses DNS data to match up domain names to IPs, and then presents those domain names during the scan process.

This feature is particularly important in discovering cloud-hosted services, where the only indication that a particular server is in use by a particular company is the domain name.

Domain scan searches use the scan/domains endpoint, which works in a very similar way to the scan/protocols endpoint:

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

{
  "page": 0,
  "pages": 1,
  "result_count": 28,
  "results": [
    {
      "date": "2019-05-13",
      "id": "xqdCDXoHSX-E1_V0rhGw_g",
      "items": [
        {
          "context": "",
          "is_metadata": true,
          "type": "ip",
          "value": "104.26.6.233"
        },
        {
          "context": "",
          "is_metadata": true,
          "type": "port-tcp",
          "value": "443"
        },
        ...

Note the third item, which has an empty context and a type of host. This is the domain name that was presented to the remote server during the scan.

By default, a search by host will only match cases where the host being searched is the one that was scanned. You might also want to look for a type of host in any context, i.e. including results with some other reference to the host searched for. To get these results, add the indirect=true qualifier:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/domains?host=driftnet.io&indirect=true' \
  | jq . \
  | less -S

{
  "page": 0,
  "pages": 3,
  "result_count": 292,
  "results": [
    {
      "date": "2019-05-13",
      "id": "fAGY0axPRdurv8T9WqAtsQ",
      "items": [
        {
          "context": "",
          "is_metadata": true,
          "type": "ip",
          "value": "151.101.65.195"
        },
        {
          "context": "",
          "is_metadata": true,
          "type": "port-tcp",
          "value": "443"
        },
        {
          "context": "",
          "is_metadata": true,
          "type": "host",
          "value": "example.com"
        },
        ...

With the indirect=true parameter set we include results which present a certificate that is valid for host driftnet.io, but where driftnet.io was not the hostname presented in the scan. This often occurs when a CDN has bundled many unrelated hostnames into a single certificate.

Driftnet stores results as a time series. Often, you only want to know the most recent result for an {ip, port, domain} tuple. To obtain only this data, set most_recent=true:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/domains?host=google.com&most_recent=true' \
  | jq . \
  | less -S

All other features described in the Internet Scans section are also available for the scan/domains endpoint, including filtering, boolean searches and summarization. Prioritization is also available, and works in a similar way.

Body searches are not currently available for domain scan data.