1Mail::SpamAssassin::PluUgsienr::CAosnktDrNiSb(u3t)ed PerMlaiDlo:c:uSmpeanmtAastsiaosnsin::Plugin::AskDNS(3)
2
3
4

NAME

6       AskDNS - form a DNS query using tag values, and look up the DNSxL lists
7

SYNOPSIS

9         loadplugin  Mail::SpamAssassin::Plugin::AskDNS
10         askdns D_IN_DWL _DKIMDOMAIN_._vouch.dwl.spamhaus.org TXT /\b(transaction|list|all)\b/
11

DESCRIPTION

13       Using a DNS query template as specified in a parameter of a askdns
14       rule, the plugin replaces tag names as found in the template with their
15       values and launches DNS queries as soon as tag values become available.
16       When DNS responses trickle in, filters them according to the requested
17       DNS resource record type and optional subrule filtering expression,
18       yielding a rule hit if a response meets filtering conditions.
19

USER SETTINGS

21       rbl_timeout t [t_min] [zone]       (default: 15 3)
22           The rbl_timeout setting is common to all DNS querying rules (as
23           implemented by other plugins). It can specify a DNS query timeout
24           globally, or individually for each zone. When the zone parameter is
25           specified, the settings affects DNS queries when their query domain
26           equals the specified zone, or is its subdomain.  See the
27           "Mail::SpamAssassin::Conf" POD for details on "rbl_timeout".
28

RULE DEFINITIONS

30       askdns NAME_OF_RULE query_template [rr_type [subqueryfilter]]
31           A query template is a string which will be expanded to produce a
32           domain name to be used in a DNS query. The template may include
33           SpamAssassin tag names, which will be replaced by their values to
34           form a final query domain.
35
36           The final query domain must adhere to rules governing DNS domains,
37           i.e.  must consist of fields each up to 63 characters long,
38           delimited by dots, not exceeding 255 characters. International
39           domain names (in UTF-8) are allowed and will be encoded to ASCII-
40           compatible encoding (ACE) according to IDN rules. Syntactically
41           invalid resulting queries will be discarded by the DNS resolver
42           code (with some info warnings).
43
44           There may be a trailing dot at the end, but it is redundant /
45           carries no semantics, because SpamAssassin uses a
46           Net::DSN::Resolver::send method for querying DNS, which ignores any
47           'search' or 'domain' DNS resolver options.  Domain names in DNS
48           queries are case-insensitive.
49
50           A tag name is a string of capital letters, preceded and followed by
51           an underscore character.  This syntax mirrors the add_header
52           setting, except that tags cannot have parameters in parenthesis
53           when used in askdns templates (exceptions found below).  Tag names
54           may appear anywhere in the template - each queried DNS zone
55           prescribes how a query should be formed.
56
57           Special supported tag HEADER() can be used to query any header
58           content, using same header names/modifiers that as header rules
59           support.  For example _HEADER(Reply-To:addr:domain)_ can be used to
60           query the trimmed domain part of Reply-To address.  See
61           Mail::SpamAssassin::Conf documentation about header rules.
62
63           A query template may contain any number of tag names including
64           none, although in the most common anticipated scenario exactly one
65           tag name would appear in each askdns rule. Specified tag names are
66           considered dependencies.  Askdns rules with dependencies on the
67           same set of tags are grouped, and all queries in a group are
68           launched as soon as all their dependencies are met, i.e. when the
69           last of the awaited tag values becomes available by a call to
70           set_tag() from some other plugin or elsewhere in the SpamAssassin
71           code.
72
73           Launched queries from all askdns rules are grouped too according to
74           a pair of: query type and an expanded query domain name. Even if
75           there are multiple rules producing the same type/domain pair, only
76           one DNS query is launched, and a reply to such query contributes to
77           all the constituent rules.
78
79           A tag may produce none, one or multiple values. Askdns rules
80           awaiting for a tag which never receives its value never result in a
81           DNS query. Tags which produce multiple values will result in
82           multiple queries launched, each with an expanded template using one
83           of the tag values. An example is a DKIMDOMAIN tag which yields a
84           list of signing domains, one for each valid signature in a signed
85           message.
86
87           When more than one distinct tag name appears in a template, each
88           potentially resulting in multiple values, a Cartesian product is
89           formed, and each tuple results in a launch of one DNS query
90           (duplicates excluded). For example, a query template
91           _A_._B_.example._A_.com where tag A is a list (11,22) and B is
92           (xx,yy,zz), will result in queries: 11.xx.example.11.com,
93           22.xx.example.22.com, 11.yy.example.11.com, 22.yy.example.22.com,
94           11.zz.example.11.com, 22.zz.example.22.com .
95
96           A parameter rr_type following the query template is a comma-
97           separated list of expected DNS resource record (RR) types. Missing
98           rr_type parameter implies an 'A'. A DNS result may bring resource
99           records of multiple types, but only resource records of a type
100           found in the rr_type parameter list are considered, other resource
101           records found in the answer section of a DNS reply are ignored for
102           this rule. A value ANY in the rr_type parameter list matches any
103           resource record type. An empty DNS answer section does not match
104           ANY.
105
106           The rr_type parameter not only provides a filter for RR types found
107           in the DNS answer, but also determines the DNS query type. If only
108           a single RR type is specified in the parameter (e.g. TXT), than
109           this is also the RR type of a query. When more than one RR type is
110           specified (e.g. A, AAAA, TXT) or if ANY is specified, then the DNS
111           query type will be ANY and the rr_type parameter will only act as a
112           filter on a result.
113
114           Currently recognized RR types in the rr_type parameter are: ANY, A,
115           AAAA, MX, TXT, PTR, NAPTR, NS, SOA, CERT, CNAME, DNAME, DHCID,
116           HINFO, MINFO, RP, HIP, IPSECKEY, KX, LOC, GPOS, SRV, OPENPGPKEY,
117           SSHFP, SPF, TLSA, URI, CAA, CSYNC.
118
119           https://www.iana.org/assignments/dns-parameters/dns-parameters.xml
120
121           The last optional parameter of a rule is a filtering expression,
122           a.k.a. a subrule. Its function is much like the subrule in URIDNSBL
123           plugin rules, or in the check_rbl eval rules. The main difference
124           is that with askdns rules there is no need to manually group rules
125           according to their queried zone, as the grouping is automatic and
126           duplicate queries are implicitly eliminated.
127
128           The subrule filtering parameter can be: a plain string, a regular
129           expression, a single numerical value or a pair of numerical values,
130           or a list of rcodes (DNS status codes of a response). Absence of
131           the filtering parameter implies no filtering, i.e. any positive DNS
132           response (rcode=NOERROR) of the requested RR type will result in a
133           rule hit, regardless of the RR value returned with the response.
134
135           When a plain string is used as a filter, it must be enclosed in
136           single or double quotes. For the rule to hit, the response must
137           match the filtering string exactly, and a RR type of a response
138           must match the query type.  Typical use is an exact text string for
139           TXT queries, or an exact quad-dotted IPv4 address. In case of a TXT
140           or SPF resource record which can return multiple character-strings
141           (as defined in Section 3.3 of [RFC1035]), these strings are
142           concatenated with no delimiters before comparing the result to the
143           filtering string. This follows requirements of several documents,
144           such as RFC 5518, RFC 7208, RFC 4871, RFC 5617.  Examples of a
145           plain text filtering parameter: "127.0.0.1", "transaction", 'list'
146           .
147
148           A regular expression follows a familiar perl syntax like /.../ or
149           m{...} optionally followed by regexp flags (such as 'i' for case-
150           insensitivity).  If a DNS response matches the requested RR type
151           and the regular expression, the rule hits.  Examples:
152           /^127\.0\.0\.\d+$/, m{\bdial up\b}i .
153
154           A single numerical value can be a decimal number, or a hexadecimal
155           number prefixed by 0x. Such numeric filtering expression is
156           typically used with RR type-A DNS queries. The returned value (an
157           IPv4 address) is masked with a specified filtering value and tested
158           to fall within a 127.0.0.0/8 network range - the rule hits if the
159           result is nonzero: ((r & n) != 0) && ((r & 0xff000000) ==
160           0x7f000000).  An example: 0x10 .
161
162           A pair of numerical values (each a decimal, hexadecimal or quad-
163           dotted) delimited by a '-' specifies an IPv4 address range, and a
164           pair of values delimited by a '/' specifies an IPv4 address
165           followed by a bitmask. Again, this type of filtering expression is
166           primarily intended with RR type-A DNS queries. The rule hits if the
167           RR type matches, and the returned IP address falls within the
168           specified range: (r >= n1 && r <= n2), or masked with a bitmask
169           matches the specified value: (r & m) == (n & m) .
170
171           As a shorthand notation, a single quad-dotted value is equivalent
172           to a n-n form, i.e. it must match the returned value exactly with
173           all its bits.
174
175           Some typical examples of a numeric filtering parameter are:
176           127.0.1.2, 127.0.1.20-127.0.1.39, 127.0.1.0/255.255.255.0,
177           0.0.0.16/0.0.0.16, 0x10/0x10, 16, 0x10 .
178
179           Lastly, the filtering parameter can be a comma-separated list of
180           DNS status codes (rcode), enclosed in square brackets. Rcodes can
181           be represented either by their numeric decimal values (0=NOERROR,
182           3=NXDOMAIN, ...), or their names.  See
183           https://www.iana.org/assignments/dns-parameters for the list of
184           names. When testing for a rcode where rcode is nonzero, a RR type
185           parameter is ignored as a filter, as there is typically no answer
186           section in a DNS reply when rcode indicates an error.  Example:
187           [NXDOMAIN], or [FormErr,ServFail,4,5] .
188
189
190
191perl v5.36.0                      2023-01-M2a1il::SpamAssassin::Plugin::AskDNS(3)
Impressum