.\" 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::DecodeShortURLs 3pm" .TH Mail::SpamAssassin::Plugin::DecodeShortURLs 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" 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 \s-1URL\s0 shortening services. Upon finding a matching \s-1URL,\s0 plugin will send a \s-1HTTP\s0 request to the shortening service and retrieve the Location-header which points to the actual shortened \s-1URL.\s0 It then adds this \s-1URL\s0 to the list of URIs extracted by SpamAssassin which can then be accessed by uri rules and plugins such as \&\s-1URIDNSBL.\s0 .PP This plugin will follow chained redirections, where a short \s-1URL\s0 redirects to another short \s-1URL.\s0 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 \s-1HTTP\s0 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 \s-1SYNOPSIS\s0 section. .SH "NOTES" .IX Header "NOTES" This plugin runs at the check_dnsbl hook (priority \-100) so that it may modify the parsed \s-1URI\s0 list prior to normal uri rules or the \s-1URIDNSBL\s0 plugin. .SH "PRIVILEGED SETTINGS" .IX Header "PRIVILEGED SETTINGS" .IP "url_shortener domain [domain...] (default: none)" 4 .IX Item "url_shortener domain [domain...] (default: none)" Domains that should be considered as an \s-1URL\s0 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. \s-1HTTP\s0 request will be done with \s-1GET\s0 method, instead of default \s-1HEAD.\s0 Required for some services like bit.ly to return blocked \s-1URL\s0 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. .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 \s-1DBI\s0 connect string. \&\s-1DBI\s0 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 \s-1DBI\s0 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 \s-1DBI\s0 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. .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 \s-1URL HTTP\s0 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 \s-1HTTP\s0 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 \s-1URL\s0 can generate. .IP "url_shortener_user_agent (default: Mozilla/5.0 (Windows \s-1NT 10.0\s0; Win64; x64) AppleWebKit/537.36 (\s-1KHTML,\s0 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 \s-1HTTP\s0 requests. Some services require it to look like a common browser. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Original DecodeShortURLs plugin was developed by Steve Freegard.