IP reputation data

Search by CIDR

This API endpoint allows the request of either current or historic listing information for a specific network block.

The query URL is:

  • GET /api/intel/v1/byobject/cidr/<DATASET>/<MODE>/<QTY><IPADDRESS>[/<MASK>][?get_arguments..]

Arguments:

  • DATASET - identifies the dataset where the search can be performed. Allowed values are: XBL, CSS, BCL or ALL

  • MODE - search CIDR mode. Can have two different values:

    • listed search all submissions contained within specified netmask

    • listings search all submissions that contains specified netmask (this should only be used when querying a dataset that allows listings of variable sizes. This will be implemented in the future.)

  • TYPE - can either be “live” or “history”:

    • live only returns listings that are still “active”, i.e., they are currently listed and haven’t expired from the Spamhaus datasets yet

    • history returns any record seen within the (implicit or explicit) time window, including expired data

  • IPADDRESS - IP address to look for

  • MASK - optional netmask to use. It defaults to 32 for IPv4 or 64 for IPv6; its maximum value can be 24 or 56 for IPv4 and IPv6 searches respectively

Available GET arguments:

  • limit - constrain the number of rows returned by the query. Default is 500 and max value is 2000. If you pass a value greater thatn 2000, an error is returned.

  • since - extract results with a timestamp greater than or equal to ‘since’ (unix timestamp); default is 12 months before since if not passed

  • until - extract results with a timestamp less than or equal to ‘until’ (unix timestamp); defaults to the current timestamp if not passed

NOTE: When querying for historical data, the maximum timeframe allowed is 12 months; passing a larger interval will result in an error code. If a larger timespan is required, multiple queries are needed.

Some usage examples:

Get active listings for 45.150.206.114 in XBL

curl -s https://api.spamhaus.org/api/intel/v1/byobject/cidr/XBL/listed/live/45.150.206.114 \
	-H 'Authorization: Bearer <AUTH TOKEN>'

Get last 10 listing events for IPs in 45.150.206.0/24 from XBL

curl -s https://api.spamhaus.org/api/intel/v1/byobject/cidr/XBL/listed/history/45.150.206.0/24?limit=10 \
	-H 'Authorization: Bearer <AUTH TOKEN>'

Get submissions from a specified time range for 45.150.206.0/24

curl -s 'https://api.spamhaus.org/api/intel/v1/byobject/cidr/XBL/listed/history/45.150.206.0/24?since=1606600000&until=1606750000' \
	-H 'Authorization: Bearer <AUTH TOKEN>'

Output

Independent of the type of query against the data, all successful queries will return a JSON object composed of a code with the same value as the HTTP status code at the HTTP protocol layer.

Here is an example of a query returning no data:

{"code":404}

If the query results in data being returned, the JSON object provides an array named results with all the records returned by the query.

For example: https://api.spamhaus.org/api/intel/v1/byobject/cidr/XBL/listed/history/74.77.66.227?limit=2 would return an object like the following:

{
  "code": 200,
  "results": [
    {
      "dataset": "XBL",
      "ipaddress": "74.77.66.227",
      "asn": "11351",
      "cc": "US",
      "listed": 1606757120,
      "seen": 1606757113,
      "valid_until": 1607361913,
      "rule": "01a400d5",
      "botname": "unknown",
      "detection": "SMTP impersonation",
      "dstport": 25,
      "helo": "outlook.com",
      "heuristic": "IMPERSONATE",
      "lat": 43.0505,
      "lon": -78.853,
      "srcip": "74.77.66.227"
    },
    {
      "dataset": "XBL",
      "ipaddress": "74.77.66.227",
      "asn": "11351",
      "cc": "US",
      "listed": 1606063971,
      "seen": 1606063960,
      "valid_until": 1606668760,
      "rule": "01a400d5",
      "botname": "unknown",
      "detection": "SMTP impersonation",
      "dstport": 25,
      "helo": "outlook.com",
      "heuristic": "IMPERSONATE",
      "lat": 43.0505,
      "lon": -78.853,
      "srcip": "74.77.66.227"
    }
  ]
}

For details of the fields included in each record, please refer to the relevant dataset’s documentation.