Implementation Guidelines

Here are some brief guidelines for applications using our intelligence datasets.

1. Extract URIs from your application. (Extraction of URIs from your application should ideally include full resolution of redirections into the final target domain or subomain)
2. Extract domains or subdomains from those URIs. When using the wildcarded version of multi (e.g., for public DNS queries), it is not necessary to reduce domains to a specific level.  Due to wildcards, subdomains of a blacklisted domain will match a blacklisted domain.  For matching queries against the non-wildcarded version of multi, domains will need to be reduced in order to match the level of blacklisted domains.  We recommend and use the wildcarded version of multi for DNS.
3. Perform NO name resolution on the extracted domains. 
4. Look up the domain name in the dataset by prepending it to the name of the lookup domain, e.g., domainundertest.com.multi.surbl.org, then doing Address (A) record DNS resolution on the resulting combined name. A non-result (NXDOMAIN) indicates lack of inclusion in the list. An Address result indicates list inclusion. Positive matches also have a TXT record associated with them containing a descriptive reason for list inclusion, but the A record is the strongly preferred response for automated use.

   ---

   Using the combined list multi.surbl.org, results will be bitmasked as described in the Lists section. In this case, membership in multiple lists is encoded according to respective bit positions in the returned Address value, and programs should decode these results into their respective individual lists.

   ---

5. Handle numeric IPs in URIs similarly, but reverse the octet ordering before comparison against the DNSBL. This is a standard practice for DNSBLs. For example, http://10.20.30.40/ is checked as 40.30.20.10.multi.surbl.org. Numeric addresses should be in base-10 representation. If other representations of numeric IP addresses appear in messages, then they should be converted into four, reversed-order, dotted, base-10 octets before checking.
6. Include a local whitelist function to exclude certain known whitehat domains or IPs from our intelligence checking. This is very important since it prevents many unnecessary queries against common domains like yahoo.com, w3.org, google.com, etc., which will never be blacklisted. It's described further in the FAQ.
7. An increasing number of DNS services are being deployed to protect end users against typo, malware, phishing and unsolicited message web sites by redirecting web service to an alternate site. Generally they do this by changing the IP address or NXDOMAIN responses to DNS queries. Unfortunately these changes can adversely affect DNS responses and create false positives or false negatives. One way to test for this is to make sure that responses to DNS queries are in 127/8, in other words that 127 is its first octet. While this won't fully determine correct results, it's still a recommended and good basic input verification test. A good administrative solution is to run a local caching nameserver for DNS resolution, which can also improve performance. More information is in our FAQ.
8. If you get a result of 127.0.0.1 when doing a DNS query into the public nameservers, then it means your access is blocked. Please see our Usage Policy and sign up for Sponsored Data Service (SDS).

Our lists somewhat unusually have both names and numbers in the same list. For example, 2.0.0.127 and test.surbl.org and similar actual unsolicited message URI domains and IP addresses both appear in our lists. IP addresses appearing in our intelligence datasets are not the result of applying name resolution to domain names. Numbered addresses in our intelligence are actually seen in apoplication flows with the uri presented as numbers, e.g.: literally http://10.20.30.40/. Additional test points are mentioned in the FAQ. For more information about list data please also see the Lists section.

Please do not use our intelligence to check sender IP addresses. Also do not resolve domains on our lists and make blacklists of the resulting IPs. These may result in unexpected false positives, for example for services hosted on shared IP web or mail servers.