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