.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Plugin::HashBL 3pm"
.TH Mail::SpamAssassin::Plugin::HashBL 3pm "2022-09-10" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HashBL \- query hashed (and unhashed) DNS blocklists
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  loadplugin Mail::SpamAssassin::Plugin::HashBL
\&
\&  # NON\-WORKING usage examples below, replace xxx.example.invalid with real list
\&  # See documentation below for detailed usage
\&
\&  header   HASHBL_EMAIL eval:check_hashbl_emails(\*(Aqebl.example.invalid\*(Aq)
\&  describe HASHBL_EMAIL Message contains email address found on EBL
\&  tflags   HASHBL_EMAIL net
\&
\&  # rewrite googlemail.com \-> gmail.com, applied before acl/welcomelist
\&  hashbl_email_domain_alias gmail.com googlemail.com
\&  # only query gmail.com addresses
\&  hashbl_acl_freemail gmail.com
\&  header   HASHBL_OSENDR eval:check_hashbl_emails(\*(Aqrbl.example.invalid/A\*(Aq, \*(Aqmd5/max=10/shuffle\*(Aq, \*(AqX\-Original\-Sender\*(Aq, \*(Aq^127\e.\*(Aq, \*(Aqfreemail\*(Aq)
\&  describe HASHBL_OSENDR Message contains email address found on HASHBL
\&  tflags   HASHBL_OSENDR net
\&
\&  body     HASHBL_BTC eval:check_hashbl_bodyre(\*(Aqbtcbl.example.invalid\*(Aq, \*(Aqsha1/max=10/shuffle\*(Aq, \*(Aq\eb([13][a\-km\-zA\-HJ\-NP\-Z1\-9]{25,34})\eb\*(Aq)
\&  describe HASHBL_BTC Message contains BTC address found on BTCBL
\&  tflags   HASHBL_BTC net
\&
\&  header   HASHBL_URI eval:check_hashbl_uris(\*(Aqrbl.example.invalid\*(Aq, \*(Aqsha1\*(Aq, \*(Aq^127\e.0\e.0\e.32$\*(Aq)
\&  describe HASHBL_URI Message contains uri found on rbl
\&  tflags   HASHBL_URI net
\&
\&  body     HASHBL_ATTACHMENT eval:check_hashbl_attachments(\*(Aqattbl.example.invalid\*(Aq, \*(Aqsha256\*(Aq)
\&  describe HASHBL_ATTACHMENT Message contains attachment found on attbl
\&  tflags   HASHBL_ATTACHMENT net
\&
\&  # Capture tag using SA 4.0 regex named capture feature
\&  header   _\|_X_SOME_ID X\-Some\-ID =~ /^(?<XSOMEID>\ed{10,20})$/
\&  # Query the tag value as is from a DNSBL
\&  header   HASHBL_TAG eval:check_hashbl_tag(\*(Aqidbl.example.invalid/A\*(Aq, \*(Aqraw\*(Aq, \*(AqXSOMEID\*(Aq, \*(Aq^127\e.\*(Aq)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin supports multiple types of hashed or unhashed \s-1DNS\s0 blocklist queries.
.IP "Common \s-1OPTS\s0 that apply to all functions:" 4
.IX Item "Common OPTS that apply to all functions:"
.Vb 7
\&  raw      no hashing, query as is (can break if value is not valid DNS label)
\&  md5      hash query with MD5
\&  sha1     hash query with SHA1
\&  sha256   hash query with Base32 encoded SHA256
\&  case     keep case before hashing, default is to lowercase
\&  max=x    maximum number of queries (defaults to 10 if not specified)
\&  shuffle  if max exceeded, random shuffle queries before truncating to limit
.Ve
.Sp
Multiple options can be separated with slash.
.Sp
When rule \s-1OPTS\s0 is empty ('') or missing, default is used as documented by
each query type.  If any options are defined, then all needed options must
be explicitly defined.
.IP "header \s-1RULE\s0 check_hashbl_emails('bl.example.invalid/A', '\s-1OPTS\s0', '\s-1HEADERS\s0', '^127\e.')" 4
.IX Item "header RULE check_hashbl_emails('bl.example.invalid/A', 'OPTS', 'HEADERS', '^127.')"
Check email addresses from \s-1DNS\s0 list.  Note that \*(L"body\*(R" can be specified
along with headers to search message body for emails.  Rule type must always
be \*(L"header\*(R".
.Sp
Optional \s-1DNS\s0 query type can be appended to list with /A (default) or /TXT.
.Sp
Default \s-1OPTS:\s0 sha1/notag/noquote/max=10/shuffle
.Sp
Additional supported \s-1OPTS:\s0
.Sp
.Vb 7
\&  nodot    strip username dots from email
\&  notag    strip username tags from email
\&  nouri    ignore emails inside uris
\&  noquote  ignore emails inside < > or possible quotings
\&  user     query userpart of email only
\&  host     query hostpart of email only
\&  domain   query domain of email only (hostpart+trim_domain)
.Ve
.Sp
Default \s-1HEADERS:\s0 ALLFROM/Reply\-To/body
.Sp
\&\s-1HEADERS\s0 refers to slash separated list of Headers to process:
.Sp
.Vb 5
\&  ALL           all headers
\&  ALLFROM       all From headers as returned by $pms\->all_from_addrs()
\&  EnvelopeFrom  message envelope from (Return\-Path etc)
\&  <HeaderName>  any header as used with header rules or $pms\->get()
\&  body          all emails found in message body
.Ve
.Sp
If \s-1HEADERS\s0 is empty ('') or missing, default is used.
.Sp
Optional subtest regexp to match \s-1DNS\s0 answer (default: '^127\e.').
.Sp
For existing public email blocklist, see: http://msbl.org/ebl.html
.Sp
.Vb 4
\&  # Working example, see https://msbl.org/ebl.html before usage
\&  header   HASHBL_EMAIL eval:check_hashbl_emails(\*(Aqebl.msbl.org\*(Aq)
\&  describe HASHBL_EMAIL Message contains email address found on EBL
\&  tflags   HASHBL_EMAIL net
.Ve
.Sp
Default regex for matching and capturing emails can be overridden with
\&\f(CW\*(C`hashbl_email_regex\*(C'\fR.  Likewise, the default welcomelist can be changed with
\&\f(CW\*(C`hashbl_email_welcomelist\*(C'\fR.  Only change if you know what you are doing, see
plugin source code for the defaults.  Example: hashbl_email_regex \eS+@\eS+.com
.IP "header \s-1RULE\s0 check_hashbl_uris('bl.example.invalid/A', '\s-1OPTS\s0', '^127\e.')" 4
.IX Item "header RULE check_hashbl_uris('bl.example.invalid/A', 'OPTS', '^127.')"
Check all URIs parsed from message from \s-1DNS\s0 list.
.Sp
Optional \s-1DNS\s0 query type can be appended to list with /A (default) or /TXT.
.Sp
Default \s-1OPTS:\s0 sha1/max=10/shuffle
.Sp
Optional subtest regexp to match \s-1DNS\s0 answer (default: '^127\e.').
.IP "[raw]body \s-1RULE\s0 check_hashbl_bodyre('bl.example.invalid/A', '\s-1OPTS\s0', '\eb(match)\eb', '^127\e.')" 4
.IX Item "[raw]body RULE check_hashbl_bodyre('bl.example.invalid/A', 'OPTS', 'b(match)b', '^127.')"
Search body for matching regexp and query the string captured.  Regexp must
have a single capture ( ) for the string ($1).  Rule type must be \*(L"body\*(R" or
\&\*(L"rawbody\*(R".
.Sp
Optional \s-1DNS\s0 query type can be appended to list with /A (default) or /TXT.
.Sp
Default \s-1OPTS:\s0 sha1/max=10/shuffle
.Sp
Optional subtest regexp to match \s-1DNS\s0 answer (default: '^127\e.').
.IP "header \s-1RULE\s0 check_hashbl_tag('bl.example.invalid/A', '\s-1OPTS\s0', '\s-1TAGNAME\s0', '^127\e.')" 4
.IX Item "header RULE check_hashbl_tag('bl.example.invalid/A', 'OPTS', 'TAGNAME', '^127.')"
Query value of SpamAssassin tag _TAGNAME_ from \s-1DNS\s0 list.
.Sp
Optional \s-1DNS\s0 query type can be appended to list with /A (default) or /TXT.
.Sp
Default \s-1OPTS:\s0 sha1/max=10/shuffle
.Sp
Additional supported \s-1OPTS:\s0
.Sp
.Vb 7
\&  ip        only query if value is valid IPv4/IPv6 address
\&  ipv4      only query if value is valid IPv4 address
\&  ipv6      only query if value is valid IPv6 address
\&  revip     reverse IP before query
\&  fqdn      only query if value is valid FQDN (is_fqdn_valid)
\&  tld       only query if value has valid TLD (is_domain_valid)
\&  trim      trim name from hostname to domain (trim_domain)
\&
\&  If both ip/ipv4/ipv6 and fqdn/tld are enabled, only either of them is
\&  required to match.  Both fqdn and tld are needed for complete FQDN+TLD
\&  check.
.Ve
.Sp
Optional subtest regexp to match \s-1DNS\s0 answer (default: '^127\e.').
.IP "header \s-1RULE\s0 check_hashbl_attachments('bl.example.invalid/A', '\s-1OPTS\s0', '^127\e.')" 4
.IX Item "header RULE check_hashbl_attachments('bl.example.invalid/A', 'OPTS', '^127.')"
Check all all message attachments (mimeparts) from \s-1DNS\s0 list.
.Sp
Optional \s-1DNS\s0 query type can be appended to list with /A (default) or /TXT.
.Sp
Default \s-1OPTS:\s0 sha1/max=10/shuffle
.Sp
Additional supported \s-1OPTS:\s0
.Sp
.Vb 2
\&  minsize=x  skip any parts smaller than x bytes
\&  maxsize=x  skip any parts larger than x bytes
.Ve
.Sp
Optional subtest regexp to match \s-1DNS\s0 answer (default: '^127\e.').
.Sp
Specific attachment filenames can be skipped with \f(CW\*(C`hashbl_ignore\*(C'\fR.  For
example \*(L"hashbl_ignore safe.pdf\*(R".
.Sp
Specific mime types can be skipped with \f(CW\*(C`hashbl_ignore\*(C'\fR.  For example
\&\*(L"hashbl_ignore text/plain\*(R".
.IP "hashbl_ignore value [value...]" 4
.IX Item "hashbl_ignore value [value...]"
Skip any type of query, if either the hash or original value (email for
example) matches.  Multiple values can be defined, separated by whitespace. 
Matching is case-insensitive.
.Sp
Any host or its domain part matching uridnsbl_skip_domains is also ignored
by default.