DNS Block List Checker

dnsblchk is an open-source Python service for monitoring IP addresses and derived domains against DNS block lists. It performs IP-based RBL checks and domain-based DBL checks, writes structured CSV reports, and can notify by email or webhook.

Features

• RBL checks for IP addresses from config/ips.txt.
• DBL checks for PTR hostnames and registrable apex domains derived from those IPs.
• Structured CSV reports with IP, PTR, and APEX rows.
• Email and webhook notifications.
• Optional API-based IP list refresh before each run.
• Local runner scripts for Linux/macOS/WSL, Windows, and cross-platform Python.
• Docker, RPM, and DEB deployment support.

Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run.py

For Windows:

python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt
run.bat

Minimal Configuration

run_once: true
rbls_file: "config/rbls.txt"
dbls_file: "config/dbls.txt"
ips_file: "config/ips.txt"
report_dir: "logs/"
nameservers:
  - "208.67.222.222"
  - "208.67.220.220"

The tracked local config uses relative paths and run-once mode. The default checked IP list uses documentation-reserved addresses. Replace config/ips.txt with the IPs you want to monitor.

Running

python main.py config/config-local.yaml
./run.sh --config config/config-local.yaml
python run.py --config config/config-local.yaml
dnsblchk /etc/dnsblchk/config.yaml

Docker:

docker compose up -d
docker compose logs -f

Documentation

• Documentation Guide: where to start.
• Quick Start: local setup and first run.
• Configuration: full config reference.
• Reports: CSV output, RBL/DBL behavior, and notifications.
• Runner Scripts: run.sh, run.bat, and run.py.
• Packaging: RPM, DEB, Docker, and release builds.

Packaging

The package version is defined in pyproject.toml. Build a Debian package with:

bash build-deb.sh

See doc/PACKAGING.md for complete packaging instructions. The project now targets Python 3.14.6.

Contributing

Run the test suite before submitting changes:

PYTHONPATH=. pytest -q
PYTHONPATH=. pytest --cov -q