NAME¶
AskDNS - form a DNS query using tag values, and look up the DNSxL lists
SYNOPSIS¶
loadplugin Mail::SpamAssassin::Plugin::AskDNS
askdns D_IN_DWL _DKIMDOMAIN_._vouch.dwl.spamhaus.org TXT /\b(transaction|list|all)\b/
DESCRIPTION¶
Using a DNS query template as specified in a parameter of a askdns rule, the
plugin replaces tag names as found in the template with their values and
launches DNS queries as soon as tag values become available. When DNS
responses trickle in, filters them according to the requested DNS resource
record type and optional subrule filtering expression, yielding a rule hit if
a response meets filtering conditions.
USER SETTINGS¶
- rbl_timeout t [t_min] [zone] (default: 15 3)
- The rbl_timeout setting is common to all DNS querying rules
(as implemented by other plugins). It can specify a DNS query timeout
globally, or individually for each zone. When the zone parameter is
specified, the settings affects DNS queries when their query domain equals
the specified zone, or is its subdomain. See the
"Mail::SpamAssassin::Conf" POD for details on
"rbl_timeout".
RULE DEFINITIONS¶
- askdns NAME_OF_RULE query_template [rr_type
[subqueryfilter]]
- A query template is a string which will be expanded to
produce a domain name to be used in a DNS query. The template may include
SpamAssassin tag names, which will be replaced by their values to form a
final query domain. The final query domain must adhere to rules governing
DNS domains, i.e. must consist of fields each up to 63 characters long,
delimited by dots. There may be a trailing dot at the end, but it is
redundant / carries no semantics, because SpamAssassin uses a
Net::DSN::Resolver::send method for querying DNS, which ignores any
'search' or 'domain' DNS resolver options. Domain names in DNS queries are
case-insensitive.
A tag name is a string of capital letters, preceded and followed by an
underscore character. This syntax mirrors the add_header setting, except
that tags cannot have parameters in parenthesis when used in askdns
templates. Tag names may appear anywhere in the template - each queried
DNS zone prescribes how a query should be formed.
A query template may contain any number of tag names including none,
although in the most common anticipated scenario exactly one tag name
would appear in each askdns rule. Specified tag names are considered
dependencies. Askdns rules with dependencies on the same set of tags are
grouped, and all queries in a group are launched as soon as all their
dependencies are met, i.e. when the last of the awaited tag values becomes
available by a call to set_tag() from some other plugin or
elsewhere in the SpamAssassin code.
Launched queries from all askdns rules are grouped too according to a pair
of: query type and an expanded query domain name. Even if there are
multiple rules producing the same type/domain pair, only one DNS query is
launched, and a reply to such query contributes to all the constituent
rules.
A tag may produce none, one or multiple values. Askdns rules awaiting for a
tag which never receives its value never result in a DNS query. Tags which
produce multiple values will result in multiple queries launched, each
with an expanded template using one of the tag values. An example is a
DKIMDOMAIN tag which yields a list of signing domains, one for each valid
signature in a signed message.
When more than one distinct tag name appears in a template, each potentially
resulting in multiple values, a Cartesian product is formed, and each
tuple results in a launch of one DNS query (duplicates excluded). For
example, a query template _A_._B_.example._A_.com where tag A is a list
(11,22) and B is (xx,yy,zz), will result in queries: 11.xx.example.11.com,
22.xx.example.22.com, 11.yy.example.11.com, 22.yy.example.22.com,
11.zz.example.11.com, 22.zz.example.22.com .
A parameter rr_type following the query template is a comma-separated list
of expected DNS resource record (RR) types. Missing rr_type parameter
implies an 'A'. A DNS result may bring resource records of multiple types,
but only resource records of a type found in the rr_type parameter list
are considered, other resource records found in the answer section of a
DNS reply are ignored for this rule. A value ANY in the rr_type parameter
list matches any resource record type. An empty DNS answer section does
not match ANY.
The rr_type parameter not only provides a filter for RR types found in the
DNS answer, but also determines the DNS query type. If only a single RR
type is specified in the parameter (e.g. TXT), than this is also the RR
type of a query. When more than one RR type is specified (e.g. A, AAAA,
TXT) or if ANY is specified, then the DNS query type will be ANY and the
rr_type parameter will only act as a filter on a result.
Currently recognized RR types in the rr_type parameter are: ANY, A, AAAA,
MX, TXT, PTR, NAPTR, NS, SOA, CERT, CNAME, DNAME, DHCID, HINFO, MINFO, RP,
HIP, IPSECKEY, KX, LOC, SRV, SSHFP, SPF.
http://www.iana.org/assignments/dns-parameters/dns-parameters.xml
The last optional parameter of a rule is a filtering expression, a.k.a. a
subrule. Its function is much like the subrule in URIDNSBL plugin rules,
or in the check_rbl eval rules. The main difference is that with askdns
rules there is no need to manually group rules according to their queried
zone, as the grouping is automatic and duplicate queries are implicitly
eliminated.
The subrule filtering parameter can be: a plain string, a regular
expression, a single numerical value or a pair of numerical values, or a
list of rcodes (DNS status codes of a response). Absence of the filtering
parameter implies no filtering, i.e. any positive DNS response
(rcode=NOERROR) of the requested RR type will result in a rule hit,
regardless of the RR value returned with the response.
When a plain string is used as a filter, it must be enclosed in single or
double quotes. For the rule to hit, the response must match the filtering
string exactly, and a RR type of a response must match the query type.
Typical use is an exact text string for TXT queries, or an exact
quad-dotted IPv4 address. In case of a TXT or SPF resource record which
can return multiple character-strings (as defined in Section 3.3 of
[RFC1035]), these strings are concatenated with no delimiters before
comparing the result to the filtering string. This follows requirements of
several documents, such as RFC 5518, RFC 4408, RFC 4871, RFC 5617.
Examples of a plain text filtering parameter: "127.0.0.1",
"transaction", 'list' .
A regular expression follows a familiar perl syntax like /.../ or m{...}
optionally followed by regexp flags (such as 'i' for case-insensitivity).
If a DNS response matches the requested RR type and the regular
expression, the rule hits. Examples: /^127\.0\.0\.\d+$/, m{\bdial up\b}i .
A single numerical value can be a decimal number, or a hexadecimal number
prefixed by 0x. Such numeric filtering expression is typically used with
RR type-A DNS queries. The returned value (an IPv4 address) is masked with
a specified filtering value and tested to fall within a 127.0.0.0/8
network range - the rule hits if the result is nonzero: ((r & n) != 0)
&& ((r & 0xff000000) == 0x7f000000). An example: 0x10 .
A pair of numerical values (each a decimal, hexadecimal or quad-dotted)
delimited by a '-' specifies an IPv4 address range, and a pair of values
delimited by a '/' specifies an IPv4 address followed by a bitmask. Again,
this type of filtering expression is primarily intended with RR type-A DNS
queries. The rule hits if the RR type matches, and the returned IP address
falls within the specified range: (r >= n1 && r <= n2), or
masked with a bitmask matches the specified value: (r & m) == (n &
m) .
As a shorthand notation, a single quad-dotted value is equivalent to a n-n
form, i.e. it must match the returned value exactly with all its bits.
Some typical examples of a numeric filtering parameter are: 127.0.1.2,
127.0.1.20-127.0.1.39, 127.0.1.0/255.255.255.0, 0.0.0.16/0.0.0.16,
0x10/0x10, 16, 0x10 .
Lastly, the filtering parameter can be a comma-separated list of DNS status
codes (rcode), enclosed in square brackets. Rcodes can be represented
either by their numeric decimal values (0=NOERROR, 3=NXDOMAIN, ...), or
their names. See http://www.iana.org/assignments/dns-parameters for the
list of names. When testing for a rcode where rcode is nonzero, a RR type
parameter is ignored as a filter, as there is typically no answer section
in a DNS reply when rcode indicates an error. Example: [NXDOMAIN], or
[FormErr,ServFail,4,5] .