DNS Blacklisting API

OpenNIC implemented a DNS blacklisting API for Tier 2 operators to block certain domains from being resolved. The reason for this is mostly to stop spreading malware and stopping highly illegal or abusive behavior on the domain level that would otherwise negatively affect the reputation of the OpenNIC project. DNS blacklisting finds its use mainly on TLDs where a direct zone control is not possible or not wanted (due to OpenNICs no-censorship policy) like the .bit TLD where domains are often used to spread malware due to its anonymity which causes a negative IP rating on certain IP blacklist on DNS blacklists like the Spamhaus Block List.

The APIs base URL is at https://api.opennicproject.org/acl/filter/

This wiki page is a clone of this email from Shdwdrgn with some fancy tables and extra glitter added.

The default output format for the API is

[spamhaus:sbl] malware.bit # SBL123
[other:list] abusive.com # custom comment

This format changes with custom parameters applied, see the table below for other examples.

URL Parameters are appended to the base URL separated by a question mark (?), all parameters are separated by ampersand (&), parameter key/value pairs are separated by an equal sign (=).

Example: https://api.opennicproject.org/acl/filter/?cat=spamhaus:sbl for the parameter key cat and value spamhaus:sbl


Parameter Example Value Description Example output fromat (if changed)
cat spamhaus:sbl Filter the returned blacklists by the defined category
Enables BIND9 zonefile compatible format
zone "malware.bit" {type master; file "db.opennic_filter.spamhaus:sbl";}; # SBL12
path /var/named Prepends the value given to the file parameter in the BIND9 zonefile compatible format
Requires a cat parameter
zone "malware.bit" {type master; file "/var/named/db.opennic_filter.spamhaus:sbl";}; # SBL12

Within the folder where you store your zone files (perhaps using the path you specified to the API), create a file named db.opennic_filter.spamhaus:sbl and put in the following contents:

; Blacklisted domains that should be blocked from resolving
$TTL 3600
@                       IN      SOA     ns1.example.com. hostmaster (
                                2017082300 ; serial
                                3600 ; refresh
                                180 ; retry
                                86400 ; expire
                                3600 ; default TTL
                        IN      NS
                        IN      A
*                       IN      A
                        IN      AAAA    ::1
*                       IN      AAAA    ::1

Save the data from the API page in the same location as named.conf, giving it a name such as named.blacklisted.

And finally, you need to update your named.conf to include the API data page by adding a line such as this:

include "/etc/bind/named.blacklisted";

Now you can restart BIND9 and test that the blackholed domains return to your queries. Note that the API was written so we can create blacklists under different names, allowing admins to choose which information they wish to use. The zone file is saved using the name of the blacklist, so you could have different lists give different responses.