DNS Probe

Prometheus probe to monitor DNS zones.

Installation

Simple setup

python -m venv env
env/bin/pip install git+https://git.bksp.space/hannaeko/dns-probe.git
env/bin/dns-probe -l 127.0.0.1:8953

Using a dedicated WSGI server

python -m venv env
env/bin/pip install 'git+https://git.bksp.space/hannaeko/dns-probe.git#egg=dns_probe[gunicorn]'
env/bin/gunicorn -b 127.0.0.1:8953 --workers 4 'dns_probe:make_app()'

Usage

Examples

# Let the probe find the nameserver list
curl '127.0.0.1:8953/probe?zone=bksp.space'

# Disable IPv6 (both IPv4 and IPv6 are enabled by default)
curl '127.0.0.1:8953/probe?zone=bksp.space&ipv6=no'

# Specify a custom list of nameservers
curl '127.0.0.1:8953/probe?zone=bksp.space&nameservers[]=9.9.9.9&nameservers[]=2620:fe::fe'

API

• GET /probe

  Probe a zone and output Prometheus metrics

  Query parameters:

  • zone (required) the zone to probe.
  • ipv6 (default: yes) enable IPv6, valid values: yes/no.
  • ipv4 (default: yes) enable IPv4, valid values: yes/no.
  • query_timeout (default: 2) timeout for DNS query in seconds.
  • nameservers[] (optional) a list of nameserver to query for the zone. You can repeat this parameter to query multiple servers, if none are provided the probe will try to resolve the nameservers itself. Valid values: IP addresses.

  List of returned metrics:

  Name	Type
  dns_probe_resolve_nameservers_success{zone}	Gauge (boolean)
  dns_probe_ns_set{nameserver,target,zone}	Gauge (info)
  dns_probe_soa_serial{nameserver,zone}	Gauge
  dns_probe_soa_rrsig_expiration{keytag,nameserver,zone}	Gauge (timestamp)
  dns_probe_query_success{name,nameserver,type}	Gauge (boolean)
  dns_probe_dnssec_delegation_status{zone,status}	Gauge (info, status = {secure, bogus, unsecure})
  dns_probe_dnssec_ds_has_key{zone,keytag,digest}	Gauge (boolean)
  dns_probe_dnssec_dnskey_signature_status{zone,nameserver}	Gauge (boolean)

Prometheus configuration

scrape_configs:
  - job_name: dns-probe
    scrape_interval: 1m
    metrics_path: /probe
    static_configs:
    - targets:
      - bksp.space
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_zone
      - source_labels: [__param_zone]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:8953

Development

Run alert unit tests:

./promtool test rules --diff rules.test.yml

Build and publish package:

pip install twine build

python -m build
python -m twine upload --repository bksp dist/*