Driftnet API

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:

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

{
  "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.

Searching by CIDR

To get a simple summary of open TCP ports aggregated across the entire CIDR, call scan/ports. Alternatively to see the ports broken down per IP address use scan/ipports

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/ports?ip=162.216.148.0/22' \
  | jq .

{
    "other": 0,
    "values": {
        "10023": 1,
        "10098": 1,
        "10118": 1,
        "12088": 1,
        "15200": 1,
        "16668": 1,
        "18081": 1,
        "18980": 1,
        "49587": 1,
        "60019": 1,
        "9100": 227
    }
}

The values object in the return contains the extracted values (port numbers), together with their observation counts with the values coming from some IP address in the provided CIDR.

The returned object may also contain an additional key "honeypot": true. The presence of this key indicates that at least one IP address in the provided CIDR 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.

Searching by CIDR per IP

To get a summary of open TCP ports from a CIDR shown per IP, call scan/ipports. Alternatively for a simple summary use scan/ports.

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/ipports?ip=162.216.148.0/22' \
  | jq .

{
    "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.

Each IP 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 of IPs is limited to a maximum of 1024 values (ip addresses); if there are more unique values than this, then the total count of non-summarized values is placed in the top level other property. Each IP ports summary is 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 the other property for that IP.

If you need to search a large CIDR, and find other has a non zero value, split up the CIDR into smaller ranges and make multiple queries.