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.

Dataset Download

This API endpoint allows the download of an entire current dataset, in compressed format. Access to this API endpoint is only granted to customers who have subscribed for enterprise access to that specific dataset.

The query URL is:

  • GET /api/intel/v1/download/ext/<DATASET>

Arguments list:

  • DATASET - identifies the dataset to download. Currently supported dataset values are: bcl, xbl, css

Usage example:

# get eBCL full dataset export file
wget --header="Authorization: Bearer <AUTH TOKEN>" \
   --output-document=bcl.tgz \
   https://api.spamhaus.org/api/intel/v1/download/ext/bcl

This API will return binary data. The output is a compressed file with tar and gzip (.tgz extension).