DQS Requests

Query Format

DNSBL queries (and, as such, DQS queries) are simply A queries for a certain hostname within the DNSBL zone.

The zones provided by DQS can be divided in three groups

  • sbl, xbl, sbl-xbl, pbl, AuthBL and zen, that provide information about IP addresses

  • dbl and zrd, that provide information on hostnames and domains

  • hbl and its components, that provide information on cryptographic hashes represented as strings

One must avoid to send IP queries to domain databases or domain queries to hash databases, and similar.

The hostname to be queried in order to know if a certain resource is listed is specific to the type of resource being queried:

  • Queries for IPv4 addresses. If the resource to be queried is an IPv4 address, the four octets of the IP addresses need to be inverted, then prepended to the DQS zone of choice. For instance, to query sbl about the listing status of 203.0.113.79 one would perform an A DNS query for the hostname 79.113.0.203.<key>.sbl.dq.spamhaus.net

  • Queries for IPv6 addresses. If the IP address to be queried is IPv6, it must be transformed into a nibble format, which means all the hex digits of the expanded IPv6 address in reverse order and separated by dots. Then, such string needs to be prepended to the zone. For instance, to query sbl about the listing status of 2001:db8:7ca6:22::45 one would use 5.4.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.2.0.0.6.a.c.7.8.b.d.0.1.0.0.2.<key>.sbl.dq.spamhaus.net

The format used to represent IP addresses in DNSBL queries is the same used by the in-addr.arpa and ip6.arpa zones to represent reverse DNS lookups

  • Queries for domains or hostnames. In this query the domain/hostname is simply prepended to the dbl (or zrd) DNSBL zone name, like in example.com.<key>.dbl.dq.spamhaus.net or www.example.net.<key>.zrd.dq.spamhaus.net

It must be emphasized that both dbl and zrd are wildcarded zones that do not consider the hostname part of fully qualified domain names. Therefore, fully qualified domain names can be inserted as they are in the DNS queries, without having to strip away the domain part.

  • Queries for cryptographic hashes. The reference representation used by Spamhaus uses SHA256 hashes encoded as a BASE32 string in order to compress it and make it fit the maximum size for a DNS label. Things to note are that

    • it’s (obviously) the value of the hash that needs to be encoded as BASE32, and not the string

    • a few variants of BASE32 exist, the one in use is the one defined by RFC (specifically, RFC4648)
      For some contexts, SHA1 hashes are also supported, to ensure compatibility with existing software. In this case SHA1 hashes are represented as HEX strings. In both cases, the lookup key is composed by concatenating the hash value and its context; an example is a query for KADTR46EPIEQVM7C3GEODZCTXO2HUQSO34T3YYLVBCMPOAA3GSBA._file.<key>.hbl.dq.spamhaus.net in which one would retrieve information for a file (therefore in the _file context) with a hash of KADTR46EPIEQVM7C3GEODZCTXO2HUQSO34T3YYLVBCMPOAA3GSBA. More information can be found in the HBL-specific documentation.

Return Codes

For all datasets, a reply providing one or more A records within 127.0.0.0/16 is considered a positive reply (meaning the queries resource is listed), whereas an NXDOMAIN (host not found) represents a negative reply (resource not listed). Return codes within 127.255.255.0/24 are used to notify errors.

Querying code is expected to go through all the A records provided by a positive reply and act accordingly to each one, as opposed to just picking up the first entry, as that single reply may not be the one the specific check was supposed to trigger upon.

Therefore, for example, checking the IP 177.129.247.146 against the zen zone may return the following:

146.247.129.177.<key>.zen.dq.spamhaus.net. 60 IN A 127.0.0.9
146.247.129.177.<key>.zen.dq.spamhaus.net. 60 IN A 127.0.0.2
146.247.129.177.<key>.zen.dq.spamhaus.net. 60 IN A 127.0.0.3
146.247.129.177.<key>.zen.dq.spamhaus.net. 60 IN A 127.0.0.4

Indicating that this IP is listed in SBL (127.0.0.2), in the CSS component of SBL (127.0.0.3), it is part of a DROP IP range (127.0.0.9) and is listed in the CBL (part of XBL) as well (127.0.0.4). It is not listed on PBL.

Queries returning IPs outside 127.0.0.0/8 are absolutely not expected and mean something is interfering with the DNS resolution process. Such replies must be discarded and the DNS resolution chain investigated to exclude the misbehaving actor.