Description

The warnlist plugin accepts a list of malicious or otherwise undesirable domains and emits a log entry and Prometheus metrics when a domain (or subdomain) is requested.

Prohibited domains can be loaded from a local file or a URL and can be automatically reloaded after a specified period.

warnlist can be thought of as a non-blocking blacklist/blocklist/denylist/badlist. When used with a curated data source, the plugin can surface simplistic low-noise alerts without the need to ship and inspect DNS logs.

Refer to the project README for more info.

An unofficial coredns image with this plugin already compiled is hosted by Giant Swarm on Quay and Docker Hub, as [quay.io/]giantswarm/coredns-warnlist-plugin.

Syntax

warnlist {
    <source type> <source path> <file format>
    reload <reload period>
    match_subdomains <true | false>
}

The warnlist plugin accepts the following arguments:

• <source type>: Type of the domain list. Either url or file.
• <source path>: Where to load the list from. Either a URL or file path.
• <file format>: Format of the file to expect. Either hostfile or text.
• <reload period>: (Optional) Go Duration after which the list will be regenerated*.
• <match subdomains>: (Optional) If true (default), the plugin will also check and match subdomains of those explicitly listed. Either true or false.

* A jitter of +/- 30% is automatically added. When automatically reloading from a URL, please be friendly to the service hosting the file.

Example

Sample Corefile using a URL data source, reloading every ~60 minutes:

. {
    log
    warnlist {
        url https://urlhaus.abuse.ch/downloads/hostfile/ hostfile
        reload 60m
    }
    prometheus
    forward . /etc/resolv.conf
}

Metrics

If the prometheus plugin is also enabled, this plugin emits the following metrics:

• warnlist_hits_total{server, requestor, domain} - counts the number of warnlisted domains requested. The host and domain are included as labels.
• warnlist_failed_reloads_count{server} - counts the number of times the plugin has failed to reload.
• warnlist_cache_check_duration_seconds{server} - summary for determining the average time it takes to check the warnlist.
• warnlist_warnlisted_items_count{server} - current number of domains stored in the warnlist.