API Documentation

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.

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.

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

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

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.

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.