dnsbl

Query DNS-based blackhole lists

Supports both IPv4 and IPv6 queries.

Usage

pnpm add dnsbl

import {lookup, batch} from "dnsbl";

await lookup("127.0.0.2", "zen.spamhaus.org");
// true

await lookup("127.0.0.2", "zen.spamhaus.org", {includeTxt: true});
// {
//   listed: true,
//   txt: [["some txt"], ["another txt"]]
// }

await batch(["1.2.3.4", "5.6.7.8"], ["dnsbl.somelist.net", "dnsbl.someotherlist.net"]);
// [
//   {address: "1.2.3.4", blacklist: "dnsbl.somelist.net", listed: true},
//   {address: "1.2.3.4", blacklist: "dnsbl.someotherlist.net", listed: true},
//   {address: "5.6.7.8", blacklist: "dnsbl.somelist.net", listed: false},
//   {address: "5.6.7.8", blacklist: "dnsbl.someotherlist.net", listed: false}
// ]

API

lookup(address, blacklist, [options])

• address: string an IP address.
• blacklist: string the hostname of the blacklist to query.

Returns a Promise that resolves to true or false, indicating if the address is listed (i.e. the DNS query returned a non-empty result). DNS errors and timeouts resolve to false, or to {listed: false, txt: []} if includeTxt is set. A failed TXT query yields txt: [] without affecting listed. An invalid address or server rejects.

If the includeTxt option is set, it will return an Object with these properties:

• listed boolean - a boolean indicating if the address is listed on the blacklist.
• txt string[][] - an array of resolved TXT records for the address.

batch(addresses, blacklists, [options])

• addresses string or Array - one or more IP addresses.
• blacklists string or Array - one or more blacklist hostnames.

Returns a Promise that resolves to a results object (see below).

options object

• servers string or Array - DNS servers to use. Pass a falsy value to use the system resolvers. Default: ["208.67.220.220", "208.67.222.222", "2620:119:35::35", "2620:119:53::53"].
• timeout number - timeout in milliseconds. Default: 5000.
• concurrency number - number of concurrent queries. Default: 64.
• includeTxt boolean - include txt records if IP is blacklisted. Default: false.

results object

The results object is an array of objects with these properties:

• address string - the IP address.
• blacklist string - the blacklist hostname.
• listed boolean - a boolean indicating if the address is listed on the blacklist.
• txt string[][] - an array of resolved TXT records for the address, only present if includeTxt is set.

© silverwind, distributed under BSD licence