CoreDNS plugin which periodically updates a cache of domains, and exposes metrics and logs when a listed domain is requested. It does not block the request. This plugin is intended to facilitate low-noise alerting based on DNS requests for known malicious domains.
This plugin was previously referred to as malicious-domains
.
This project is under development and has not been tested for heavy production workloads.
We host a coredns image including this plugin at quay.io/giantswarm/coredns-warnlist-plugin
. While we will try to keep this up to date on a best-effort basis, this is not an official image and may become behind or out of sync with the official image.
Alternatively, you can build an image yourself from the upstream codebase using the instructions in the Compilation section below.
The warnlist
plugin takes the following arguments:
- the source type for the warnlist: either
url
orfile
- the path to the source: either a url or file path
- the format of the file to expect: either
hostfile
ortext
(see below) - the reload period: an optional Go Duration after which time (+/- 30% jitter) the warnlist will be regenerated*
- whether or not to match subdomains:
true
(default) orfalse
(see Subdomains)
* when automatically reloading from a URL, please be friendly to the service hosting the file.
In your Corefile, the plugin options follow the format:
warnlist {
<source type> <source path> <file format>
reload <reload period>
match_subdomains <true | false>
}
Sample Corefile configuration snippet (URL):
warnlist {
url https://urlhaus.abuse.ch/downloads/hostfile/ hostfile
reload 60m
}
Sample Corefile configuration snippet (file):
warnlist {
file domains.txt text
reload 5m
match_subdomains true
}
The plugin can read files either as a list of individual domains (text mode) or in a hostfile format.
Both formats treat lines starting with #
as comments and will disregard them.
Each domain is assumed to be a FQDN from the global origin (i.e. names are transformed to include a trailing .
if one is not present).
In text
mode, the domain file should include one domain name per line.
text
Mode Sample:
example.org
somethingbad.biz
onlydanger.us
hostfile
Mode Sample (from abuse.ch
):
################################################################
# abuse.ch URLhaus Host file #
# Last updated: 2020-06-24 14:05:05 (UTC) #
# #
# Terms Of Use: https://urlhaus.abuse.ch/api/ #
# For questions please contact urlhaus [at] abuse.ch #
################################################################
#
127.0.0.1 123evdenevenakliyat.com
127.0.0.1 1home.az
127.0.0.1 1sp1d.club
127.0.0.1 1sp2d.club
127.0.0.1 1sp3d.club
This plugin can optionally check requests for subdomains of those explicitly listed on the warnlist. For example, using a warnlist containing very.evil
, requesting something.very.evil
would also trigger a match.
This feature (enabled by default) uses a radix tree to attempt to reduce the complexity of finding matches. This might affect the performance of the plugin more than the alternative Go map implementation (which can not match subdomains), but we don't yet have enough data to report how much impact can be expected.
This plugin must be compiled with coredns
-- it cannot be added to an existing coredns
binary or Docker image.
A simple way to consume this plugin is by adding the following to plugin.cfg and recompiling it as detailed on coredns.io.
...
errors:errors
log:log
warnlist:github.com/giantswarm/coredns-warnlist-plugin # Add this line
dnstap:dnstap
acl:acl
...
Then you can compile coredns with:
go generate
go build
Or you can instead use make:
make
To compile using a local copy of the plugin, you can add a replace
directive to go.mod
:
replace github.com/giantswarm/coredns-warnlist-plugin => /path/to/go/src/github.com/giantswarm/coredns-warnlist-plugin
You can then run coredns
locally with ./coredns -dns.port "1053"
If monitoring is enabled (via the prometheus directive) the following metrics are exported:
warnlist_hits_total{server, requestor, domain}
- counts the number of warnlisted domains requestedwarnlist_failed_reloads_count{server}
- counts the number of times the plugin has failed to reload its warnlistwarnlist_cache_check_duration_seconds{server}
- summary exposing count and sum for determining the average time it takes to check the cachewarnlist_warnlisted_items_count{server}
- current number of domains stored in the warnlist
The server
label indicated which server handled the request.
The requestor
label indicates the IP which requested the domain.
The domain
label indicates the actual domain which was requested.
See the metrics plugin for more details.
By default, you can see the exported Prometheus metrics at http://localhost:9153/metrics
when coredns
is running.
This plugin reports readiness to the ready plugin. It will be immediately ready.
Sample Corefile
. {
log
warnlist {
url https://urlhaus.abuse.ch/downloads/hostfile/ hostfile
reload 60m
}
prometheus
forward . /etc/resolv.conf
}
If running the server locally on port 1053, you can use
dig +nocmd @localhost mx example.org -p1053 +noall +additional +tcp
to send a request.
Using the domain warnlist above, this will trigger a warnlist hit.
See the manual.