10 releases (6 breaking)
|0.7.0||Feb 19, 2021|
|0.6.1||Feb 5, 2021|
|0.6.0||Nov 15, 2020|
|0.5.1||Sep 27, 2020|
|0.1.0||Sep 13, 2020|
#78 in Command-line interface
58 downloads per month
CLI tool for pulling known malicious domains into a blackhole list. Primarily meant to be used with PDNS Recursor. The tool can pull in blackholed domains from multiple adlist sources and output them into multiple places in various formats.
Requires a stable build of Rust, preferably the latest one. I haven't checked what is the minimum stable version the tool builds on.
- From crates.io:
cargo install singularity
- From source:
cargo install --path .
- Basic usage:
All CLI options can be seen with the
--help flag. The options are:
--verbose: enable additional debug output to stdout
--config: a custom configuration file to use instead of the default
--timeout: timeout in milliseconds to wait for each HTTP request to succeed (default: 1000)
By default, the tool will use a confiuration file in the current system-dependent location. On Linux, this is
$HOME/.config/singularity/singularity.conf. The file will be created if it doesn't exist and will contain empty values.
Complete example configuration file:
whitelist = ["my-cool-domain.com"] [[adlist]] source = "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts" format = "hosts" [[adlist]] source = "file:/absolute/path" format = "domains" [[output]] type = "hosts" destination = "/etc/powerdns/hosts" blackhole-address = "0.0.0.0" include = ["extra-hosts"] [[output]] type = "pdns-lua" destination = "/etc/powerdns/blackhole.lua" blackhole-address = "::" output_metric = true metric_name = "blocked-queries"
An array of domains you wish to not include in the final output. These are matched exactly, so
google.com will match only
google.com, but not any of its subdomains. The configuration option can be left out entirely for a default empty whitelist.
An array of objects describing adlist sources. They have two keys:
source: URL to the source of the adlist. The URL scheme can be
file. If it's a
fileURL, its path will be interpreted as an absolute filesystem path in the local system.
format: the format the adlist's entries are in. This option can be omitted for the default
hostsvalue. The value can be either:
0.0.0.0 malicious.domain. It is assumed the address in each entry is the unspecfied
0.0.0.0IP address. Entries that have a different IP address or have an IP address as the domain are ignored.
domains: each line is just a domain name:
Regardless of the source or format, any lines in an adlist beginning with a
# are ignored and will not be included in the output.
An array of objects describing where and how to output the blackholed domains. The type of each output is specified with the
type key. The possible types are:
hosts: output a standard hosts-format where each line is in the format of
<blackhole-address> <name>. Other hosts-files can be included in the output by settings their paths in the
pdns-lua: output a Lua script that can be used with the
lua-dns-scriptconfiguration option in PDNS Recursor. The script will have each blackholed domain hardcoded into it. By using the
preresolve()function, the script will respond to queries for the blackholed domains with either an
A-record or an
AAAA-record containing the
blackhole-address. The type of the record depends on whether the
blackhole-addressis an IPv4- or an IPv6-address. By default, the script will output a metric called
blocked-queriesthat is incremented every time the script responds to a blocked domain. It is accessible through the same means as every other Recursor metric. It can be disabled with the
output_metricsetting, and the metric's name can be customised with the
metric_namesetting. Both settings can be omitted for their default values.
In all output types, the default
0.0.0.0 and can be changed per-output.