dnsrbl-exporter

Introduction

A DNS-based Realtime Blacklist (DNSRBL) checker with a Prometheus metrics endpoint. Written in Go.

This tool allows you to monitor your IP addresses against multiple DNS blacklists and expose the results as Prometheus metrics for alerting and monitoring.

Features

• 📊 Prometheus metrics endpoint
• 🔍 Support for multiple DNSRBL servers
• 🐳 Multi-architecture Docker images (amd64, arm64)
• ⚙️ Configurable via environment variables
• 🛠️ Includes verify-lists utility to test DNSRBL server responsiveness

Building

Build the main exporter

go build -o dnsrbl-exporter ./cmd/dnsrbl-exporter

Build the verify-lists utility

go build -o verify-lists ./cmd/verify-lists

Build all binaries

go build -o dnsrbl-exporter ./cmd/dnsrbl-exporter
go build -o verify-lists ./cmd/verify-lists

Running Locally

Run the exporter

./dnsrbl-exporter

Check version:

./dnsrbl-exporter -version

Verify DNSRBL lists

The verify-lists utility tests all DNSRBL servers listed in lists.txt to ensure they are responsive:

./verify-lists

Docker

Pull the image

docker pull ghcr.io/runningman84/dnsrbl-exporter:latest
# or
docker pull runningman84/dnsrbl-exporter:latest

Run the container

docker run -d -p 8000:8000 ghcr.io/runningman84/dnsrbl-exporter:latest

Configuration

The container can be configured using these environment variables:

Variable	Description	Default
DNSRBL_HTTP_BL_ACCESS_KEY	API Key for https://www.projecthoneypot.org	None
DNSRBL_DELAY_REQUESTS	Sleep time between two subsequent requests (single list check)	1
DNSRBL_DELAY_RUNS	Sleep time between two subsequent runs (full list check)	60
DNSRBL_LISTS	Space separated list of RBLs (e.g., "dnsbl.httpbl.org zen.spamhaus.org")	None
DNSRBL_LISTS_FILENAME	Filename containing list of RBLs, one per line	lists.txt
DNSRBL_CHECK_IP	IP address to be checked (auto-discovery if not set)	None
DNSRBL_PORT	Listener port for metrics server	8000

Metrics

Prometheus metrics are exposed at http://localhost:8000/metrics

Kubernetes / Helm

For Flux CD users, see the flux/helm-release.yaml file for a complete example configuration using the app-template chart with ServiceMonitor integration.

Testing

Run the test suite:

go test ./...

Run tests with coverage:

go test -cover ./...

License

See LICENSE file for details.