.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-04-02 "perl v5.38.2" "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 DNS blocklist queries.
.IP "Common OPTS 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 OPTS 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 RULE check_hashbl_emails('bl.example.invalid/A', 'OPTS', 'HEADERS', '^127\e.')" 4
.IX Item "header RULE check_hashbl_emails('bl.example.invalid/A', 'OPTS', 'HEADERS', '^127.')"
Check email addresses from DNS list.  Note that "body" can be specified
along with headers to search message body for emails.  Rule type must always
be "header".
.Sp
Optional DNS query type can be appended to list with /A (default) or /TXT.
.Sp
Default OPTS: sha1/notag/noquote/max=10/shuffle
.Sp
Additional supported OPTS:
.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 HEADERS: ALLFROM/Reply\-To/body
.Sp
HEADERS 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 HEADERS is empty ('') or missing, default is used.
.Sp
Optional subtest regexp to match DNS 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 RULE check_hashbl_uris('bl.example.invalid/A', 'OPTS', '^127\e.')" 4
.IX Item "header RULE check_hashbl_uris('bl.example.invalid/A', 'OPTS', '^127.')"
Check all URIs parsed from message from DNS list.
.Sp
Optional DNS query type can be appended to list with /A (default) or /TXT.
.Sp
Default OPTS: sha1/max=10/shuffle
.Sp
Optional subtest regexp to match DNS answer (default: '^127\e.').
.IP "[raw]body RULE check_hashbl_bodyre('bl.example.invalid/A', 'OPTS', '\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 "body" or
"rawbody".
.Sp
Optional DNS query type can be appended to list with /A (default) or /TXT.
.Sp
Default OPTS: sha1/max=10/shuffle
.Sp
Additional supported OPTS:
.Sp
.Vb 1
\&  num      remove the chars from the match that are not numbers
.Ve
.Sp
Optional subtest regexp to match DNS answer (default: '^127\e.').
.IP "header RULE check_hashbl_tag('bl.example.invalid/A', 'OPTS', 'TAGNAME', '^127\e.')" 4
.IX Item "header RULE check_hashbl_tag('bl.example.invalid/A', 'OPTS', 'TAGNAME', '^127.')"
Query value of SpamAssassin tag _TAGNAME_ from DNS list.
.Sp
Optional DNS query type can be appended to list with /A (default) or /TXT.
.Sp
Default OPTS: sha1/max=10/shuffle
.Sp
Additional supported OPTS:
.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 DNS answer (default: '^127\e.').
.IP "header RULE check_hashbl_attachments('bl.example.invalid/A', 'OPTS', '^127\e.')" 4
.IX Item "header RULE check_hashbl_attachments('bl.example.invalid/A', 'OPTS', '^127.')"
Check all all message attachments (mimeparts) from DNS list.
.Sp
Optional DNS query type can be appended to list with /A (default) or /TXT.
.Sp
Default OPTS: sha1/max=10/shuffle
.Sp
Additional supported OPTS:
.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 DNS answer (default: '^127\e.').
.Sp
Specific attachment filenames can be skipped with \f(CW\*(C`hashbl_ignore\*(C'\fR.  For
example "hashbl_ignore safe.pdf".
.Sp
Specific mime types can be skipped with \f(CW\*(C`hashbl_ignore\*(C'\fR.  For example
"hashbl_ignore text/plain".
.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.