uptimeify-dnsbl

A lightweight, purely functional helper for checking if an IP is blocklisted. We handle the math and the mapping, you handle the network.

What is this?

Checking DNS blocklists (DNSBL/RBL) usually involves three annoying steps:

1. Reversing the IP address (e.g. 1.2.3.4 -> 4.3.2.1 or the complex IPv6 nibble format).
2. Knowing which lists to check and what their specific return codes mean.
3. Making the DNS queries.

uptimeify-dnsbl solves #1 and #2. We give you the exact domains to query and parse the confusing result codes (like 127.0.0.4) into human-readable reasons.

We intentionally do not perform the DNS lookups internally. This allows you to use your preferred DNS resolver, manage timeouts, handle concurrency, and cache results exactly how your app needs it.

Features

• IPv4 & IPv6 Support: Correctly handles IP reversal for both protocols.
• Result Parsing: Translates cryptic return codes (127.0.0.2, 127.0.0.10) into actual messages ("Listed in SBL", "ISP Policy").
• Delisting Links: Provides direct URLs to removal forms when available.
• Zero Dependencies: Just pure Javascript logic.

Included Lists

We maintain definitions for the most reliable and widely used lists:

• Spamhaus ZEN (SBL, CSS, XBL, PBL) - The gold standard
• Spamhaus DQS (ZEN) - Same result parsing, but query via Spamhaus DQS (requires a DQS key)
• Barracuda (BRBL)
• SpamCop
• SORBS (Aggregate)
• UCEPROTECT (Level 1)
• Hostkarma
• Backscatterer
• Invaluement SIP
• SpamCannibal
• DroneBL
• Spam Eating Monkey (SEM-BLACK)
• URIBL Black
• RV-SOFT Technology
• ZapBL
• Suomispam Reputation
• Kempt.net
• Korea Services
• NiX Spam
• Passive Spam Block List (PSBL)
• InterServer RBL
• Spamhaus SBL
• all.s5h.net
• Abuse.ch Combined
• UCEPROTECT Level 2
• Abuse.ch Drone
• 0spam RBL
• Singular TTK PTE
• SpamRats Spam
• Spamsources Fabel
• Virus RBL JP
• Woody's SMTP Blacklist
• WPBL
• UCEPROTECT Level 3
• Gweep Proxy
• Gweep Relays
• Abuse.ch Spam
• Digibase Spambot
• Lashback UBL
• WormRBL
• 0spam Blocklist
• Team Cymru Bogons
• SpamRats Dyna
• SpamRats NoPtr
• Nether.net Relays
• Imp.ch Spam RBL
• Mailspike Z
• Anonmails.de
• Pedantic.org
• GBUdb Truncate
• LashBack UBL

How to use it

1. Install

npm install uptimeify-dnsbl

2. Check an IP

import { getLookupDomains, parseLookupResult } from "uptimeify-dnsbl";
import { resolve4 } from "node:dns/promises";

async function check(ip) {
	// 1. Get the list of domains to query
	const checks = getLookupDomains(ip, {
		spamhaus: {
			// Default: "zen" (public). Use "dqs" to query Spamhaus via DQS.
			mode: process.env.SPAMHAUS_DQS_KEY ? "dqs" : "zen",
			dqsKey: process.env.SPAMHAUS_DQS_KEY,
		},
	});
	// Returns array: [{ address: "4.3.2.1.zen.spamhaus.org", listKey: "zen.spamhaus.org" }, ...]
	// Or with DQS:   [{ address: "4.3.2.1.<DQS_KEY>.zen.dq.spamhaus.net", listKey: "zen.dq.spamhaus.net" }, ...]

	// 2. Run your DNS lookups
	// We use typical Promise handling here, but you can use any async pattern
	const results = await Promise.allSettled(
		checks.map(async ({ address, listKey }) => {
			// A successful DNS A-record lookup means the IP is listed.
			// If the IP is clean, resolve4 throws ENOTFOUND.
			const [code] = await resolve4(address);
			return parseLookupResult(listKey, code);
		}),
	);

	// 3. Process results
	const listings = results
		.filter((r) => r.status === "fulfilled") // Successful lookup = Listed
		.map((r) => r.value);

	if (listings.length > 0) {
		console.log(`❌ IP ${ip} is listed on:`);
		listings.forEach((listing) => {
			console.log(`   - ${listing.name}`);
			console.log(`     Reason: ${listing.reason}`);
			console.log(`     Delist: ${listing.delistUrl}`);
		});
	} else {
		console.log(`✅ IP ${ip} is clean.`);
	}
}

check("127.0.0.2");

API

getLookupDomains(ip, options?)

Returns an array of objects containing the fully qualified domain to query (address) and the identifier key (listKey).

Spamhaus DQS

You can switch Spamhaus from the public DNSBL hostnames to Spamhaus DQS by passing an options object.

const checks = getLookupDomains("1.2.3.4", {
	spamhaus: {
		mode: "dqs",
		dqsKey: process.env.SPAMHAUS_DQS_KEY,
	},
});

Notes:

• When mode: "dqs" is set, this library will generate DQS lookup domains for Spamhaus (and will not query the public Spamhaus DNSBL hostnames).
• Keep the DQS key secret (don’t commit it to git or log it).

parseLookupResult(listKey, resultCode)

Takes the list identifier and the IP address returned by the DNS query (e.g., 127.0.0.2) and returns a rich object with the listing name, reason, and delist URL.

parseLookupResultJson(listKey, resultCode)

Same as parseLookupResult, but returns a stringified JSON representation of the result.