Endpoint

/3.0/dnsbl

Description

Get information about listed ip-addresses. A POST request is required for this to work (officially). However, one (unsupported) command does the same: /3.0/dnsbl/request/ip/<address>

Parameters

{
  "flags":["resolve"]
}

Examples

{"ip":["44.11.12.77","18.33.14.30"]}

        "dnsblResponse": [
            {
                "ip": "44.11.12.77",
                "typebit": "84",
                "discovered": "2017-12-16 16:06:03",
                "typestring": "torexit",
                "deleted": "2018-06-30 05:00:18",
                "lastchange": "2018-06-30 05:00:18"
            },
            {
                "ip": "18.33.14.30",
                "typebit": "84",
                "discovered": "2017-11-03 20:53:54",
                "typestring": "phishing",
                "deleted": "0000-00-00 00:00:00",
                "lastchange": "2017-11-03 20:53:54"
            }
        ]

As you can see, one of the hosts above are also marked as deleted by the deleted-string. This means that is has been removed from the DNS service and therefore won't shop up in a DNS request. This kind of flags is used to show - in removal tools - that the host has been listed but is now removed.

Looking for networks (CIDR-scanning)

If you need to look for addresses in a larger network, without requesten each one manually, you can request a list with addresses for a specific CIDR-block. If a network is smaller than a CLASS A network (/8 CIDR-blocks, with a count of 16777216 addresses,  consumes too much output data to be healthy for the system) the request will give a whole lot of results in the response.

It is only your imagination (or your network) that sets the search limit here, as long as you keep yourself over the CIDR-block limit. This feature does not exist in APIv2.

{
    "ip":["44.11.0.0/16"]
}

IPv6 support

For ipv6, something like this should work:

{
    "ip":["2001:41d0::/32"]
}

As IPv6 networks are still friendlier the prefix length does not consume as much power as IPv4 ranges even if a /32-range in the IPv6 world is about 79228162514264337593543950336 addresses.

Can I add or delete CIDR-block based ranges?

No. Not in the current state. As the system is based on DNS requests, such API calls would fill the database with way too much information.

Flags

It is possible to add extra flags to some requests (as mentioned above). For example, to get a "getListed"-response with the resolved hosts of the blacklisted addresses, you can for example send a request like this:

{
    "ip":"67.212.160.0/19",
    "flags":["resolve"]
}

The output response will in this case transform into:

{
	"dnsblResponse": [{
		"ip": "67.212.167.146",
		"typebit": "84",
		"discovered": "2018-03-18 11:07:18",
		"typestring": "phishing",
		"deleted": "0000-00-00 00:00:00",
		"lastchange": "2018-03-18 11:07:18",
		"hostname": "server2.himmelstein.com",
		"resolved": "1521368263",
		"hasResolveFlag": "1",
		"resolve": "server2.himmelstein.com",
		"lastResolve": "server2.himmelstein.com",
		"lastResolveTime": "1521368263",
		"constants": [
			"IP_PHISHING",
			"IP_MAILSERVER_SPAM",
			"IP_ABUSE_NO_SMTP"
		]
	}]
}

Where hasResolveFlag set to 1 (true) to tell the remote requester that the boths keys resolve and lastResolve will contain a resolved hostname of the ip-address. The resolve-key is a realtime hostname resolve of the ip-addresser and the lastResolve-key indicates what hostname the address had the last time it was resolved in unix timestamp formatting (hosts are periodically checked this way as a way to handle special whitelisting cases). The unix timestamp are returned in the key lastResolveTime.

Exceptions

When the API find no blacklisted hosts

As of APIv3, exceptions are thrown in the response interface if nothing is found as listed. This should make it easier to detect errors together with unlisted addresses, instead of looking for empty response arrays. This is what's thrown, when this occurs.

{
    "response": [],
    "errors": {
        "code": "404",
        "success": "",
        "faultstring": "Nothing found as listed"
    }
}