=head1 NAME
Mail::SpamAssassin::Plugin::SPF - perform SPF verification tests
=head1 SYNOPSIS
loadplugin Mail::SpamAssassin::Plugin::SPF
=head1 DESCRIPTION
This plugin checks a message against Sender Policy Framework (SPF)
records published by the domain owners in DNS to fight email address
forgery and make it easier to identify spams.
=cut
package Mail::SpamAssassin::Plugin::SPF;
use Mail::SpamAssassin::Plugin;
use Mail::SpamAssassin::Logger;
use Mail::SpamAssassin::Timeout;
use strict;
use warnings;
use bytes;
use vars qw(@ISA);
@ISA = qw(Mail::SpamAssassin::Plugin);
sub new {
my $class = shift;
my $mailsaobject = shift;
$class = ref($class) || $class;
my $self = $class->SUPER::new($mailsaobject);
bless ($self, $class);
$self->register_eval_rule ("check_for_spf_pass");
$self->register_eval_rule ("check_for_spf_neutral");
$self->register_eval_rule ("check_for_spf_fail");
$self->register_eval_rule ("check_for_spf_softfail");
$self->register_eval_rule ("check_for_spf_helo_pass");
$self->register_eval_rule ("check_for_spf_helo_neutral");
$self->register_eval_rule ("check_for_spf_helo_fail");
$self->register_eval_rule ("check_for_spf_helo_softfail");
$self->register_eval_rule ("check_for_spf_whitelist_from");
$self->register_eval_rule ("check_for_def_spf_whitelist_from");
$self->set_config($mailsaobject->{conf});
return $self;
}
sub set_config {
my($self, $conf) = @_;
my @cmds = ();
=head1 USER SETTINGS
=over 4
=item whitelist_from_spf add@ress.com
Use this to supplement the whitelist_from addresses with a check against the
domain's SPF record. Aside from the name 'whitelist_from_spf', the syntax is
exactly the same as the syntax for 'whitelist_from'.
Just like whitelist_from, multiple addresses per line, separated by spaces,
are OK. Multiple C<whitelist_from_spf> lines are also OK.
The headers checked for whitelist_from_spf addresses are the same headers
used for SPF checks (Envelope-From, Return-Path, X-Envelope-From, etc).
Since this whitelist requires an SPF check to be made network tests must be
enabled. It is also required that your trust path be correctly configured.
See the section on C<trusted_networks> for more info on trust paths.
e.g.
whitelist_from_spf joe@example.com fred@example.com
whitelist_from_spf *@example.com
=item def_whitelist_from_spf add@ress.com
Same as C<whitelist_from_spf>, but used for the default whitelist entries
in the SpamAssassin distribution. The whitelist score is lower, because
these are often targets for spammer spoofing.
=cut
push (@cmds, {
setting => 'whitelist_from_spf',
type => $Mail::SpamAssassin::Conf::CONF_TYPE_ADDRLIST
});
push (@cmds, {
setting => 'def_whitelist_from_spf',
type => $Mail::SpamAssassin::Conf::CONF_TYPE_ADDRLIST
});
=back
=head1 ADMINISTRATOR OPTIONS
=over 4
=item spf_timeout n (default: 5)
How many seconds to wait for an SPF query to complete, before scanning
continues without the SPF result.
=cut
push (@cmds, {
setting => 'spf_timeout',
is_admin => 1,
default => 5,
type => $Mail::SpamAssassin::Conf::CONF_TYPE_NUMERIC
});
=item do_not_use_mail_spf (0|1) (default: 0)
By default the plugin will try to use the Mail::SPF module for SPF checks if
it can be loaded. If Mail::SPF cannot be used the plugin will fall back to
using the legacy Mail::SPF::Query module if it can be loaded.
Use this option to stop the plugin from using Mail::SPF and cause it to try to
use Mail::SPF::Query instead.
=cut
push(@cmds, {
setting => 'do_not_use_mail_spf',
is_admin => 1,
default => 0,
type => $Mail::SpamAssassin::Conf::CONF_TYPE_BOOL,
});
=item do_not_use_mail_spq_query (0|1) (default: 0)
As above, but instead stop the plugin from trying to use Mail::SPF::Query and
cause it to only try to use Mail::SPF.
=cut
push(@cmds, {
setting => 'do_not_use_mail_spf_query',
is_admin => 1,
default => 0,
type => $Mail::SpamAssassin::Conf::CONF_TYPE_BOOL,
});
=item ignore_received_spf_header (0|1) (default: 0)
By default, to avoid unnecessary DNS lookups, the plugin will try to use the
SPF results found in any C<Received-SPF> headers it finds in the message that
could only have been added by an internal relay.
Set this option to 1 to ignore any C<Received-SPF> headers present and to have
the plugin perform the SPF check itself.
Note that unless the plugin finds an C<identity=helo>, or some unsupported
identity, it will assume that the result is a mfrom SPF check result. The
only identities supported are C<mfrom>, C<mailfrom> and C<helo>.
=cut
push(@cmds, {
setting => 'ignore_received_spf_header',
is_admin => 1,
default => 0,
type => $Mail::SpamAssassin::Conf::CONF_TYPE_BOOL,
});
=item use_newest_received_spf_header (0|1) (default: 0)
By default, when using C<Received-SPF> headers, the plugin will attempt to use
the oldest (bottom most) C<Received-SPF> headers, that were added by internal
relays, that it can parse results from since they are the most likely to be
accurate. This is done so that if you have an incoming mail setup where one
of your primary MXes doesn't know about a secondary MX (or your MXes don't
know about some sort of forwarding relay that SA considers trusted+internal)
but SA is aware of the actual domain boundary (internal_networks setting) SA
will use the results that are most accurate.
Use this option to start with the newest (top most) C<Received-SPF> headers,
working downwards until results are successfully parsed.
=cut
push(@cmds, {
setting => 'use_newest_received_spf_header',
is_admin => 1,
default => 0,
type => $Mail::SpamAssassin::Conf::CONF_TYPE_BOOL,
});
$conf->{parser}->register_commands(\@cmds);
}
sub check_for_spf_pass {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 0) unless $scanner->{spf_checked};
$scanner->{spf_pass};
}
sub check_for_spf_neutral {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 0) unless $scanner->{spf_checked};
$scanner->{spf_neutral};
}
sub check_for_spf_fail {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 0) unless $scanner->{spf_checked};
if ($scanner->{spf_failure_comment}) {
$scanner->test_log ($scanner->{spf_failure_comment});
}
$scanner->{spf_fail};
}
sub check_for_spf_softfail {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 0) unless $scanner->{spf_checked};
$scanner->{spf_softfail};
}
sub check_for_spf_helo_pass {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 1) unless $scanner->{spf_helo_checked};
$scanner->{spf_helo_pass};
}
sub check_for_spf_helo_neutral {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 1) unless $scanner->{spf_helo_checked};
$scanner->{spf_helo_neutral};
}
sub check_for_spf_helo_fail {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 1) unless $scanner->{spf_helo_checked};
if ($scanner->{spf_helo_failure_comment}) {
$scanner->test_log ($scanner->{spf_helo_failure_comment});
}
$scanner->{spf_helo_fail};
}
sub check_for_spf_helo_softfail {
my ($self, $scanner) = @_;
$self->_check_spf ($scanner, 1) unless $scanner->{spf_helo_checked};
$scanner->{spf_helo_softfail};
}
sub check_for_spf_whitelist_from {
my ($self, $scanner) = @_;
$self->_check_spf_whitelist($scanner) unless $scanner->{spf_whitelist_from_checked};
$scanner->{spf_whitelist_from};
}
sub check_for_def_spf_whitelist_from {
my ($self, $scanner) = @_;
$self->_check_def_spf_whitelist($scanner) unless $scanner->{def_spf_whitelist_from_checked};
$scanner->{def_spf_whitelist_from};
}
sub _check_spf {
my ($self, $scanner, $ishelo) = @_;
if ($scanner->{conf}->{ignore_received_spf_header}) {
dbg("spf: ignoring any Received-SPF headers from internal hosts, by admin setting");
} elsif ($scanner->{checked_for_received_spf_header}) {
dbg("spf: already checked for Received-SPF headers, proceeding with DNS based checks");
} else {
$scanner->{checked_for_received_spf_header} = 1;
dbg("spf: checking to see if the message has a Received-SPF header that we can use");
my @internal_hdrs = split("\n", $scanner->get('ALL-INTERNAL'));
unless ($scanner->{conf}->{use_newest_received_spf_header}) {
@internal_hdrs = reverse(@internal_hdrs);
} else {
dbg("spf: starting with the newest Received-SPF headers first");
}
foreach my $hdr (@internal_hdrs) {
if ($hdr =~ /^received-spf: /i) {
dbg("spf: found a Received-SPF header added by an internal host: $hdr");
if ($hdr =~ /^received-spf:\s+(pass|neutral|(?:soft)?fail|none)\b(?:.*\bidentity=(\S+?);?\b)?/i) {
my $result = lc($1);
my $identity = ''; if (defined $2) {
$identity = lc($2);
if ($identity eq 'mfrom' || $identity eq 'mailfrom') {
next if $scanner->{spf_checked};
$identity = '';
} elsif ($identity eq 'helo') {
next if $scanner->{spf_helo_checked};
$identity = 'helo_';
} else {
dbg("spf: found unknown identity value, cannot use: $identity");
next; }
} else {
next if $scanner->{spf_checked};
}
$scanner->{"spf_${identity}checked"} = 1;
$scanner->{"spf_${identity}pass"} = 0;
$scanner->{"spf_${identity}neutral"} = 0;
$scanner->{"spf_${identity}fail"} = 0;
$scanner->{"spf_${identity}softfail"} = 0;
$scanner->{"spf_${identity}failure_comment"} = undef;
$scanner->{"spf_${identity}${result}"} = 1;
dbg("spf: re-using ".($identity ? 'helo' : 'mfrom')." result from Received-SPF header: $result");
return if ($scanner->{spf_checked} && $scanner->{spf_helo_checked});
} else {
dbg("spf: could not parse result from existing Received-SPF header");
}
}
}
return if ( ($ishelo && $scanner->{spf_helo_checked}) ||
(!$ishelo && $scanner->{spf_checked}) );
}
return unless $scanner->is_dns_available();
return if $self->{no_spf_module};
unless (defined $self->{has_mail_spf}) {
eval {
die("Mail::SPF disabled by admin setting\n") if $scanner->{conf}->{do_not_use_mail_spf};
require Mail::SPF;
if (!defined $Mail::SPF::VERSION || $Mail::SPF::VERSION < 2.001) {
die "Mail::SPF 2.001 or later required, this is ".
(defined $Mail::SPF::VERSION ? $Mail::SPF::VERSION : 'unknown')."\n";
}
$self->{spf_server} = Mail::SPF::Server->new(
hostname => $scanner->get_tag('HOSTNAME'),
dns_resolver => $self->{main}->{resolver} );
};
unless ($@) {
dbg("spf: using Mail::SPF for SPF checks");
$self->{has_mail_spf} = 1;
} else {
$@ =~ s dbg("spf: cannot load Mail::SPF module or create Mail::SPF::Server object: $@");
dbg("spf: attempting to use legacy Mail::SPF::Query module instead");
eval {
die("Mail::SPF::Query disabled by admin setting\n") if $scanner->{conf}->{do_not_use_mail_spf_query};
require Mail::SPF::Query;
if (!defined $Mail::SPF::Query::VERSION || $Mail::SPF::Query::VERSION < 1.996) {
die "Mail::SPF::Query 1.996 or later required, this is ".
(defined $Mail::SPF::Query::VERSION ? $Mail::SPF::Query::VERSION : 'unknown')."\n";
}
};
unless ($@) {
dbg("spf: using Mail::SPF::Query for SPF checks");
$self->{has_mail_spf} = 0;
} else {
dbg("spf: cannot load Mail::SPF::Query module: $@");
dbg("spf: one of Mail::SPF or Mail::SPF::Query is required for SPF checks, SPF checks disabled");
$self->{no_spf_module} = 1;
return;
}
}
}
return if $scanner->check_for_from_dns();
if ($ishelo) {
$scanner->{spf_helo_checked} = 1;
$scanner->{spf_helo_pass} = 0;
$scanner->{spf_helo_neutral} = 0;
$scanner->{spf_helo_fail} = 0;
$scanner->{spf_helo_softfail} = 0;
$scanner->{spf_helo_failure_comment} = undef;
} else {
$scanner->{spf_checked} = 1;
$scanner->{spf_pass} = 0;
$scanner->{spf_neutral} = 0;
$scanner->{spf_fail} = 0;
$scanner->{spf_softfail} = 0;
$scanner->{spf_failure_comment} = undef;
}
my $lasthop = $self->_get_relay($scanner);
if (!defined $lasthop) {
dbg("spf: no suitable relay for spf use found, skipping SPF". ($ishelo ? '-helo' : '') ." check");
return;
}
my $ip = $lasthop->{ip}; my $helo = $lasthop->{helo}; $scanner->{sender} = '' unless $scanner->{sender_got};
if ($ishelo) {
unless ($helo) {
dbg("spf: cannot check HELO, HELO value unknown");
return;
}
dbg("spf: checking HELO (helo=$helo, ip=$ip)");
} else {
$self->_get_sender($scanner) unless $scanner->{sender_got};
if (!$scanner->{sender}) {
return;
}
dbg("spf: checking EnvelopeFrom (helo=".($helo ? $helo : '').", ip=$ip, envfrom=$scanner->{sender})");
}
if ($ishelo && ($helo =~ /^[\[!]?\d+\.\d+\.\d+\.\d+[\]!]?$/ || $helo =~ /^[^.]+$/)) {
dbg("spf: cannot check HELO of '$helo', skipping");
return;
}
if ($helo && $scanner->server_failed_to_respond_for_domain($helo)) {
dbg("spf: we had a previous timeout on '$helo', skipping");
return;
}
my ($result, $comment, $text, $err);
if ($self->{has_mail_spf}) {
my $identity = $ishelo ? $helo : ($scanner->{sender});
unless ($identity) {
dbg("spf: cannot determine ".($ishelo ? 'helo' : 'mfrom').
" identity, skipping ".($ishelo ? 'helo' : 'mfrom')." SPF check");
return;
}
$helo ||= 'unknown';
my $request;
eval {
$request = Mail::SPF::Request->new( scope => $ishelo ? 'helo' : 'mfrom',
identity => $identity,
ip_address => $ip,
helo_identity => $helo );
};
if ($@) {
dbg("spf: cannot create Mail::SPF::Request object ($@)");
return;
}
my $timeout = $scanner->{conf}->{spf_timeout};
my $timer = Mail::SpamAssassin::Timeout->new({ secs => $timeout });
$err = $timer->run_and_catch(sub {
my $query = $self->{spf_server}->process($request);
$result = $query->code;
$comment = $query->authority_explanation if $query->can("authority_explanation");
$text = $query->text;
});
} else {
if (!$helo) {
dbg("spf: cannot get HELO, cannot use Mail::SPF::Query, consider installing Mail::SPF");
return;
}
my $query;
eval {
$query = Mail::SPF::Query->new (ip => $ip,
sender => $scanner->{sender},
helo => $helo,
debug => 0,
trusted => 0);
};
if ($@) {
dbg("spf: cannot create Mail::SPF::Query object ($@)");
return;
}
my $timeout = $scanner->{conf}->{spf_timeout};
my $timer = Mail::SpamAssassin::Timeout->new({ secs => $timeout });
$err = $timer->run_and_catch(sub {
($result, $comment) = $query->result();
});
}
if ($err) {
chomp $err;
warn("spf: lookup failed: $err\n");
return 0;
}
$result ||= 'timeout'; $comment ||= '';
$comment =~ s/\s+/ /gs; $text ||= '';
$text =~ s/\s+/ /gs;
if ($ishelo) {
if ($result eq 'pass') { $scanner->{spf_helo_pass} = 1; }
elsif ($result eq 'neutral') { $scanner->{spf_helo_neutral} = 1; }
elsif ($result eq 'fail') { $scanner->{spf_helo_fail} = 1; }
elsif ($result eq 'softfail') { $scanner->{spf_helo_softfail} = 1; }
if ($result eq 'fail') { $scanner->{spf_helo_failure_comment} = "SPF failed: $comment";
}
} else {
if ($result eq 'pass') { $scanner->{spf_pass} = 1; }
elsif ($result eq 'neutral') { $scanner->{spf_neutral} = 1; }
elsif ($result eq 'fail') { $scanner->{spf_fail} = 1; }
elsif ($result eq 'softfail') { $scanner->{spf_softfail} = 1; }
if ($result eq 'fail') { $scanner->{spf_failure_comment} = "SPF failed: $comment";
}
}
dbg("spf: query for $scanner->{sender}/$ip/$helo: result: $result, comment: $comment, text: $text");
}
sub _get_relay {
my ($self, $scanner) = @_;
return $scanner->{relays_external}->[0];
}
sub _get_sender {
my ($self, $scanner) = @_;
my $sender;
$scanner->{sender_got} = 1;
$scanner->{sender} = '';
my $relay = $self->_get_relay($scanner);
if (defined $relay) {
$sender = $relay->{envfrom};
}
if ($sender) {
dbg("spf: found Envelope-From in first external Received header");
}
else {
if ($scanner->{num_relays_trusted} > 0 && !$scanner->{conf}->{always_trust_envelope_sender}) {
dbg("spf: relayed through one or more trusted relays, cannot use header-based Envelope-From, skipping");
return;
}
$sender = $scanner->get ("EnvelopeFrom:addr");
}
if (!$sender) {
dbg("spf: cannot get Envelope-From, cannot use SPF");
return; }
return $scanner->{sender} = lc $sender;
}
sub _check_spf_whitelist {
my ($self, $scanner) = @_;
$scanner->{spf_whitelist_from_checked} = 1;
$scanner->{spf_whitelist_from} = 0;
if ($scanner->{spf_checked} && !$scanner->{spf_pass}) {
dbg("spf: whitelist_from_spf: already checked spf and didn't get pass, skipping whitelist check");
return;
}
$self->_get_sender($scanner) unless $scanner->{sender_got};
unless ($scanner->{sender}) {
dbg("spf: spf_whitelist_from: could not find useable envelope sender");
return;
}
$scanner->{spf_whitelist_from} = $self->_wlcheck($scanner,'whitelist_from_spf');
if (!$scanner->{spf_whitelist_from}) {
$scanner->{spf_whitelist_from} = $self->_wlcheck($scanner, 'whitelist_auth');
}
if ($scanner->{spf_whitelist_from}) {
if ($self->check_for_spf_pass($scanner)) {
dbg("spf: whitelist_from_spf: $scanner->{sender} is in user's WHITELIST_FROM_SPF and passed SPF check");
} else {
dbg("spf: whitelist_from_spf: $scanner->{sender} is in user's WHITELIST_FROM_SPF but failed SPF check");
$scanner->{spf_whitelist_from} = 0;
}
} else {
dbg("spf: whitelist_from_spf: $scanner->{sender} is not in user's WHITELIST_FROM_SPF");
}
}
sub _check_def_spf_whitelist {
my ($self, $scanner) = @_;
$scanner->{def_spf_whitelist_from_checked} = 1;
$scanner->{def_spf_whitelist_from} = 0;
if ($scanner->{spf_checked} && !$scanner->{spf_pass}) {
dbg("spf: def_spf_whitelist_from: already checked spf and didn't get pass, skipping whitelist check");
return;
}
$self->_get_sender($scanner) unless $scanner->{sender_got};
unless ($scanner->{sender}) {
dbg("spf: def_spf_whitelist_from: could not find useable envelope sender");
return;
}
$scanner->{def_spf_whitelist_from} = $self->_wlcheck($scanner,'def_whitelist_from_spf');
if (!$scanner->{def_spf_whitelist_from}) {
$scanner->{def_spf_whitelist_from} = $self->_wlcheck($scanner, 'def_whitelist_auth');
}
if ($scanner->{def_spf_whitelist_from}) {
if ($self->check_for_spf_pass($scanner)) {
dbg("spf: def_whitelist_from_spf: $scanner->{sender} is in DEF_WHITELIST_FROM_SPF and passed SPF check");
} else {
dbg("spf: def_whitelist_from_spf: $scanner->{sender} is in DEF_WHITELIST_FROM_SPF but failed SPF check");
$scanner->{def_spf_whitelist_from} = 0;
}
} else {
dbg("spf: def_whitelist_from_spf: $scanner->{sender} is not in DEF_WHITELIST_FROM_SPF");
}
}
sub _wlcheck {
my ($self, $scanner, $param) = @_;
if (defined ($scanner->{conf}->{$param}->{$scanner->{sender}})) {
return 1;
} else {
study $scanner->{sender};
foreach my $regexp (values %{$scanner->{conf}->{$param}}) {
if ($scanner->{sender} =~ qr/$regexp/i) {
return 1;
}
}
}
return 0;
}
1;
=back
=cut