.\" -*- 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::DecodeShortURLs 3pm"
.TH Mail::SpamAssassin::Plugin::DecodeShortURLs 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
DecodeShortURLs \- Check for shortened URLs
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  loadplugin    Mail::SpamAssassin::Plugin::DecodeShortURLs
\&
\&  url_shortener tinyurl.com
\&  url_shortener_get bit.ly
\&
\&  body HAS_SHORT_URL          eval:short_url()
\&  describe HAS_SHORT_URL      Message has one or more shortened URLs
\&
\&  body SHORT_URL_REDIR        eval:short_url_redir()
\&  describe SHORT_URL_REDIR    Message has shortened URL that resulted in a valid redirection
\&
\&  body SHORT_URL_CHAINED      eval:short_url_chained()
\&  describe SHORT_URL_CHAINED  Message has shortened URL chained to other shorteners
\&
\&  body SHORT_URL_MAXCHAIN     eval:short_url_maxchain()
\&  describe SHORT_URL_MAXCHAIN Message has shortened URL that causes too many redirections
\&
\&  body SHORT_URL_LOOP         eval:short_url_loop()
\&  describe SHORT_URL_LOOP     Message has short URL that loops back to itself
\&
\&  body SHORT_URL_200          eval:short_url_code(\*(Aq200\*(Aq) # Can check any non\-redirect HTTP code
\&  describe SHORT_URL_200      Message has shortened URL returning HTTP 200
\&
\&  body SHORT_URL_404          eval:short_url_code(\*(Aq404\*(Aq) # Can check any non\-redirect HTTP code
\&  describe SHORT_URL_404      Message has shortened URL returning HTTP 404
\&
\&  uri URI_TINYURL_BLOCKED      m,https://tinyurl\e.com/app/nospam,
\&  describe URI_TINYURL_BLOCKED Message contains a tinyurl that has been disabled due to abuse
\&
\&  uri URI_BITLY_BLOCKED       m,^https://bitly\e.com/a/blocked,
\&  describe URI_BITLY_BLOCKED  Message contains a bit.ly URL that has been disabled due to abuse
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This plugin looks for URLs shortened by a list of URL shortening services. 
Upon finding a matching URL, plugin will send a HTTP request to the
shortening service and retrieve the Location-header which points to the
actual shortened URL.  It then adds this URL to the list of URIs extracted
by SpamAssassin which can then be accessed by uri rules and plugins such as
URIDNSBL.
.PP
This plugin will follow chained redirections, where a short URL redirects to
another short URL.  Redirection depth limit can be set with
\&\f(CW\*(C`max_short_url_redirections\*(C'\fR.
.PP
Maximum of \f(CW\*(C`max_short_urls\*(C'\fR short URLs are checked in a message (10 by
default).  Setting it to 0 disables HTTP requests, allowing only \fBshort_url()\fR
test to work and report found shorteners.
.PP
All supported rule types for checking short URLs and redirection status are
documented in SYNOPSIS section.
.SH NOTES
.IX Header "NOTES"
This plugin runs at the check_dnsbl hook (priority \-100) so that it may
modify the parsed URI list prior to normal uri rules or the URIDNSBL plugin.
.SH "USER SETTINGS"
.IX Header "USER SETTINGS"
.IP "url_shortener  domain [domain...]     (default: none)" 4
.IX Item "url_shortener domain [domain...] (default: none)"
Domains that should be considered as an URL shortener.  If the domain begins
with a '.', 3rd level tld of the main domain will be checked.
.Sp
Example:
.Sp
.Vb 2
\& url_shortener tinyurl.com
\& url_shortener .page.link
.Ve
.IP "url_shortener_get  domain [domain...]     (default: none)" 4
.IX Item "url_shortener_get domain [domain...] (default: none)"
Alias to \f(CW\*(C`url_shortener\*(C'\fR.  HTTP request will be done with GET method,
instead of default HEAD.  Required for some services like bit.ly to return
blocked URL correctly.
.Sp
Example:
.Sp
.Vb 1
\& url_shortener_get bit.ly
.Ve
.IP "clear_url_shortener  [domain] [domain...]" 4
.IX Item "clear_url_shortener [domain] [domain...]"
Clear configured url_shortener and url_shortener_get domains, for example to
override default settings from an update channel.  If domains are specified,
then only those are removed from list.
.SH "PRIVILEGED SETTINGS"
.IX Header "PRIVILEGED SETTINGS"
.IP "url_shortener_cache_type     (default: none)" 4
.IX Item "url_shortener_cache_type (default: none)"
The cache type that is being utilized.  Currently only supported value is
\&\f(CW\*(C`dbi\*(C'\fR that implies \f(CW\*(C`url_shortener_cache_dsn\*(C'\fR is a DBI connect string.
DBI module is required.
.Sp
Example:
url_shortener_cache_type dbi
.IP "url_shortener_cache_dsn		(default: none)" 4
.IX Item "url_shortener_cache_dsn (default: none)"
The DBI dsn of the database to use.
.Sp
For SQLite, the database will be created automatically if it does not
already exist, the supplied path and file must be read/writable by the
user running spamassassin or spamd.
.Sp
For MySQL/MariaDB or PostgreSQL, see sql-directory for database table
creation clauses.
.Sp
You will need to have the proper DBI module for your database.  For example
DBD::SQLite, DBD::mysql, DBD::MariaDB or DBD::Pg.
.Sp
Minimum required SQLite version is 3.24.0 (available from DBD::SQLite 1.59_01).
.Sp
Examples:
.Sp
.Vb 1
\& url_shortener_cache_dsn dbi:SQLite:dbname=/var/lib/spamassassin/DecodeShortURLs.db
.Ve
.IP "url_shortener_cache_username  (default: none)" 4
.IX Item "url_shortener_cache_username (default: none)"
The username that should be used to connect to the database.  Not used for
SQLite.
.IP "url_shortener_cache_password  (default: none)" 4
.IX Item "url_shortener_cache_password (default: none)"
The password that should be used to connect to the database.  Not used for
SQLite.
.IP "url_shortener_cache_ttl		(default: 86400)" 4
.IX Item "url_shortener_cache_ttl (default: 86400)"
The length of time a cache entry will be valid for in seconds.
Default is 86400 (1 day).
.Sp
See \f(CW\*(C`url_shortener_cache_autoclean\*(C'\fR for database cleaning.
.SH "ADMINISTRATOR SETTINGS"
.IX Header "ADMINISTRATOR SETTINGS"
.IP "url_shortener_cache_autoclean	(default: 1000)" 4
.IX Item "url_shortener_cache_autoclean (default: 1000)"
Automatically purge old entries from database.  Value describes a random run
chance of 1/x.  The default value of 1000 means that cleaning is run
approximately once for every 1000 messages processed.  Value of 1 would mean
database is cleaned every time a message is processed.
.Sp
Set 0 to disable automatic cleaning and to do it manually.
.IP "url_shortener_loginfo           (default: 0 (off))" 4
.IX Item "url_shortener_loginfo (default: 0 (off))"
If this option is enabled (set to 1), then short URLs and the decoded URLs will be logged with info priority.
.IP "url_shortener_timeout     (default: 5)" 4
.IX Item "url_shortener_timeout (default: 5)"
Maximum time a short URL HTTP request can take, in seconds.
.IP "max_short_urls                 (default: 10)" 4
.IX Item "max_short_urls (default: 10)"
Maximum amount of short URLs that will be looked up per message.  Chained
redirections are not counted, only initial short URLs found.
.Sp
Setting it to 0 disables HTTP requests, allowing only \fBshort_url()\fR test to
work and report any found shortener URLs.
.IP "max_short_url_redirections     (default: 10)" 4
.IX Item "max_short_url_redirections (default: 10)"
Maximum depth of chained redirections that a short URL can generate.
.IP "url_shortener_user_agent       (default: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.67 Safari/537.36)" 4
.IX Item "url_shortener_user_agent (default: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.67 Safari/537.36)"
Set User-Agent header for HTTP requests.  Some services require it to look
like a common browser.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
Original DecodeShortURLs plugin was developed by Steve Freegard.