DNS QUERY INTERFACE

Query the DNSBL blacklist using standard DNS protocols

OVERVIEW

The dnsbl.io service provides DNS-based blacklist queries for both IPv4 and IPv6 addresses. This allows integration with mail servers, firewalls, and other network security tools using standard DNS protocols.

DNS ZONE:

dnsbl.io

IPv4 ADDRESS QUERIES

Standard reverse IP notation

QUERY FORMAT:

<reversed-ip>.bl.dnsbl.io

EXAMPLE:

To check if 192.0.2.100 is blacklisted:

# Command line query:

$ dig 100.2.0.192.bl.dnsbl.io A

# Or using host:

$ host 100.2.0.192.bl.dnsbl.io

# Or using nslookup:

$ nslookup 100.2.0.192.bl.dnsbl.io

RESPONSE CODES:

CODE	MEANING	SEVERITY
127.0.0.2	Listed - Low severity	LOW
127.0.0.3	Listed - Medium severity	MEDIUM
127.0.0.4	Listed - High severity	HIGH
127.0.0.5	Listed - Critical severity	CRITICAL
NXDOMAIN	Not listed	CLEAN

IPv6 ADDRESS QUERIES

Nibble-reversed notation

QUERY FORMAT:

<nibble-reversed-ipv6>.bl6.dnsbl.io

EXAMPLE:

To check if 2001:db8::1 is blacklisted:

# Expand to full notation:

2001:0db8:0000:0000:0000:0000:0000:0001

# Reverse nibbles (each hex digit):

1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.bl6.dnsbl.io

# Query:

$ dig 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.bl6.dnsbl.io A

NOTE:

IPv6 queries use the same response codes as IPv4 (127.0.0.2 through 127.0.0.5)

INTEGRATION EXAMPLES

POSTFIX MAIL SERVER

# /etc/postfix/main.cf
smtpd_recipient_restrictions =
    permit_mynetworks,
    reject_rbl_client dnsbl.io,
    permit

# Reload configuration
$ sudo postfix reload

EXIM MAIL SERVER

# /etc/exim4/exim4.conf.template
acl_check_rcpt:
  deny
    message = Rejected - IP listed in dnsbl.io
    dnslists = dnsbl.io

FAIL2BAN INTEGRATION

# /etc/fail2ban/action.d/dnsbl-report.conf
[Definition]
actionban = curl -X POST https://dnsbl.io/api/xarf \
            -H "Content-Type: application/json" \
            -d '{"source": "<ip>", "category": "abuse", "type": "login-attack"}'

actionunban =

[Init]
name = dnsbl-report

PYTHON SCRIPT

import socket

def check_dnsbl(ip):
    # Reverse IPv4
    reversed_ip = '.'.join(reversed(ip.split('.')))
    query = f"{reversed_ip}.bl.dnsbl.io"
    
    try:
        result = socket.gethostbyname(query)
        severity_map = {
            '127.0.0.2': 'LOW',
            '127.0.0.3': 'MEDIUM',
            '127.0.0.4': 'HIGH',
            '127.0.0.5': 'CRITICAL'
        }
        return severity_map.get(result, 'LISTED')
    except socket.gaierror:
        return 'CLEAN'

# Usage
status = check_dnsbl('192.0.2.100')
print(f"Status: {status}")

TXT RECORD INFORMATION

Additional details via DNS TXT records

Query TXT records to get detailed information about a listing:

$ dig 100.2.0.192.bl.dnsbl.io TXT

TXT record format:

"category=port-scan severity=medium reports=3 first_seen=2025-01-15 url=https://dnsbl.io/lookup?ip=192.0.2.100"

RATE LIMITS & POLICIES

DNS queries: Unlimited (standard DNS caching applies)
No authentication required for DNS queries
Cached responses: 300 seconds (5 minutes)
For programmatic access and bulk lookups, use the REST API with an API key
This service is completely free for all users