Driftnet
Data
Documentation
Pricing

API Documentation

Overview

Calls to scan/protocols and scan/protocols/body return results when Driftnet is able to perform a protocol-level exchange. Driftnet also records the simple fact-of an open TCP port, even when protocol data could not be obtained.

Calls to both open ports endpoints scan/ports and scan/ipports take the following query parameters:

  • ip: IP address or CIDR to search.
  • from: Date to begin the search after.
  • to: Date to end the search before.

If omitted from and to will use defaults which will search for observations in the past 30 days.

Searching by IP

To get a simple summary of open TCP ports on an IP address, call scan/ports:

Example Request
curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/ports?ip=8.8.8.8' \
  | jq .
Example Response
{
  "other": 0,
  "values": {
    "443": 10,
    "53": 4,
    "853": 1
  }
}

The values object in the return contains the extracted values (port numbers), together with their observation counts.

The returned object may also contain an additional key "honeypot": true. The presence of this key indicates that the IP address exhibits unusual open-port behavior and may be a network monitoring device or scan honeypot.

The summary is limited to a maximum of 100 values; if there are more unique values than this, then the total count of non-summarized values is placed in other. In the case of more than 100 unique values the values with the highest observation count will be returned.

Passing a CIDR to scan/ports will show a summary of ports across the entire CIDR.

Searching by CIDR, with per-IP results

To get a summary of open TCP ports from a CIDR shown per IP, call scan/ipports:

Example Request
curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/ipports?ip=162.216.148.0/22' \
| jq .
Example Response
{
  "other": 0,
  "values": {
    ...
    "162.216.149.102": {
      "other": 0,
      "values": {
          "9100": 1
        }
    },
    "162.216.149.103": {
        "other": 0,
        "values": {
            "16668": 1
        }
    },
    "162.216.149.105": {
        "other": 0,
        "values": {
            "9100": 1
        }
    },
    ...

The top level values object in the return contains the extracted values (ip addresses) found with open ports in the provided CIDR. Each IP contains an object whose values contain the extracted port numbers for this IP address, together with their observation counts.

The summary of IPs is limited to a maximum of 1024 IP addresses. Each IP ports summary is is limited to a maximum of 100 values. If you need to search a large CIDR, and find other has a non-zero value, consider splitting up the CIDR into smaller ranges and making multiple queries.