File Coverage

File:bin/dmarc-report.pl
Coverage:87.9%

linestmtbrancondsubtimecode
1#!/usr/bin/env perl
2#
3# dmarc-report - summarise DMARC aggregate reports, and flag every source
4# address that is not the host we expect to be sending as our domains.
5#
6# Aggregate reports arrive as XML, sometimes gzipped, and often several at a
7# time, so this reads a whole directory rather than one file: every report
8# that parses is summarised, then the totals per source address are given, and
9# anything that did not come from the expected host is marked.  The exit
10# status is the part a cron job can act on - 0 when every message came from
11# the expected host and authenticated, 1 when something else did - so it can
12# run unattended over a reports directory.
13#
14# Namespace: some reporters put the report in a namespace and some do not, so
15# every lookup is by local-name() rather than by the plain element name.
16
17
30
30
30
64731
24
497
use strict;
18
30
30
30
44
22
637
use warnings;
19
20
30
30
30
55
23
1099
use File::Basename qw(basename);
21
30
30
30
49
31
237
use File::Spec;
22
30
30
30
9282
138744
59
use Getopt::Long qw(GetOptions);
23
30
30
30
10143
553885
1558
use IO::Uncompress::Gunzip qw(gunzip $GunzipError);
24
30
30
30
8505
197684
1607
use IO::Uncompress::Unzip qw($UnzipError);
25
30
30
30
5938
99284
69
use POSIX qw(strftime);
26
30
30
30
25630
48436
778
use Readonly;
27
30
30
30
6661
738288
1293
use Pod::Usage qw(pod2usage);
28
30
30
30
7298
766725
67993
use XML::PP;
29
30# The hosts that are expected to send as these domains; everything else is a
31# finding.  There is no built-in address, so they come from --expected or from
32# DMARC_EXPECTED, given as a comma or space separated list.
33
34
30
1947818
my $home = $ENV{'HOME'} || (getpwuid($<))[7] || '.';
35
30
120
my $DEFAULT_DIR = $ENV{'DMARC_DIR'} || "$home/Downloads";
36
37
30
39
my (@dirs, @expected, $file_list, $help);
38
30
138
GetOptions(
39        'dir|d=s' => \@dirs,
40        'expected|e=s' => \@expected,
41        'file-list=s' => \$file_list,
42        'help|h' => \$help,
43) or pod2usage(-exitval => 2, -verbose => 0);
44
30
13525
pod2usage(-exitval => 0, -verbose => 1) if($help);
45
46
30
59
@dirs = ($DEFAULT_DIR) unless(@dirs);
47
30
53
unless(@expected) {
48
29
28
125
45
        @expected = grep { length } split(/[\s,]+/, $ENV{'DMARC_EXPECTED'} // '');
49
29
98
        pod2usage(
50                -exitval => 2, -verbose => 0,
51                -message => "No expected sender: give --expected IP, or set DMARC_EXPECTED to one or more IPs.\n",
52        ) unless(@expected);
53}
54
29
30
92
117
my %expected = map { $_ => 1 } @expected;
55
56
29
32
my @files;
57
29
51
foreach my $dir (@dirs) {
58
29
401
        die "Not a directory: $dir\n" unless(-d $dir);
59        # Only the shapes a report arrives in.  A bare *.gz would also match
60        # anything else parked in the same directory - a tarball, a downloaded
61        # data set - and trying to parse those is both slow and misleading.
62
27
42
        foreach my $pattern ('*.xml', '*.xml.gz', '*.zip') {
63
81
2610
                push @files, glob(File::Spec->catfile($dir, $pattern));
64        }
65}
66
27
30
my %seen;
67
27
32
33
88
@files = sort grep { !$seen{$_}++ } @files;
68
27
45
die "No reports found in: @dirs\n" unless(@files);
69
70# Read one report, gunzipping it if it is compressed.  Reports are small, so
71# they are parsed in memory and there is no need to unpack them onto disc.
72# Reports are kilobytes.  Capping what is opened at all keeps a downloads
73# directory usable: it holds installers, archives and data sets, and one of
74# them is 13 GB, so matching on the extension alone is not enough.
75
25
112
Readonly::Scalar my $MAX_FILE_BYTES => 10 * 1024 * 1024;
76
25
549
Readonly::Scalar my $MAX_XML_BYTES => 20 * 1024 * 1024;
77
78sub read_report
79{
80
32
30
        my $path = shift;
81
82
32
129
        my $size = -s $path;
83
32
108
        die "too large to be a report ($size bytes)\n" if(defined($size) && $size > $MAX_FILE_BYTES);
84
85
31
26
        my $xml;
86
31
122
        if($path =~ /\.zip\z/) {
87
2
4
                $xml = read_zipped_xml($path);
88        } elsif($path =~ /\.gz\z/) {
89
3
6
                $xml = read_gzipped_xml($path);
90        } else {
91
26
503
                open(my $fh, '<', $path) or die "Cannot read $path: $!\n";
92
26
76
                local $/;
93
26
284
                $xml = <$fh>;
94
26
141
                close($fh);
95        }
96
97        # A DMARC report is a <feedback> document.  Saying so is clearer than
98        # letting the XML parser complain about a CSV or a tarball.
99
31
333
        die "not a DMARC report\n" unless(index($xml, '<feedback') >= 0);
100
101        # XML::PP is pure Perl, so it installs where XML::PP does not (Windows).
102        # It returns the root element; wrap it so that, as with a document, the root
103        # is itself something to search for.
104
29
162
        my $root = XML::PP->new()->parse($xml);
105
29
114280
        die "not a DMARC report\n" unless(ref($root) eq 'HASH' && defined($root->{'name'}));
106
107
29
78
        return { 'children' => [ $root ] };
108}
109
110# Every element below $node, in document order, with the given name.  The
111# namespace prefix is not part of the name XML::PP gives, so this matches on
112# the local name, as the reports' differing prefixes require.
113sub descendants
114{
115
8352
4453
        my ($node, $name) = @_;
116
117
8352
3626
        my @found;
118
8352
8352
3635
5533
        foreach my $child (@{$node->{'children'} || []}) {
119
13224
8026
                next unless(defined($child->{'name'}));
120
7511
4542
                push @found, $child if($child->{'name'} eq $name);
121
7511
3994
                push @found, descendants($child, $name);
122        }
123
124
8352
4935
        return @found;
125}
126
127# Only the direct children with the given name.
128sub children_named
129{
130
58
52
        my ($node, $name) = @_;
131
132
58
116
58
110
199
94
        return grep { defined($_->{'name'}) && $_->{'name'} eq $name } @{$node->{'children'} || []};
133}
134
135# All the text under a node, as textContent gave it.
136sub text_content
137{
138
638
316
        my $node = shift;
139
140
638
638
638
301
900
509
        return join('', map { defined($_->{'name'}) ? text_content($_) : ($_->{'text'} // '') } @{$node->{'children'} || []});
141}
142
143sub read_gzipped_xml
144{
145
3
3
        my $path = shift;
146
147
3
20
        my $gz = IO::Uncompress::Gunzip->new($path) or die "Cannot gunzip $path: $GunzipError\n";
148
149
3
4141
        return _read_bounded($gz, $path);
150}
151
152# Reporters that send a .zip put the report inside, sometimes beside a
153# signature file, so the first member ending in .xml is the one to read.
154sub read_zipped_xml
155{
156
2
1
        my $path = shift;
157
158
2
23
        my $zip = IO::Uncompress::Unzip->new($path) or die "Cannot open $path: $UnzipError\n";
159
160
2
2420
        my $status = 1;
161
2
3
        while($status > 0) {
162
2
10
                my $name = $zip->getHeaderInfo()->{'Name'} || '';
163
2
15
                return _read_bounded($zip, $path) if($name =~ /\.xml\z/i);
164
0
0
                $status = $zip->nextStream();
165        }
166
167
0
0
        die "No XML inside $path\n";
168}
169
170# Read to the end of the current stream, giving up rather than filling memory
171# with something that turned out not to be a report.
172sub _read_bounded
173{
174
5
6
        my ($handle, $path) = @_;
175
176
5
6
        my $xml = '';
177
5
6
        while(1) {
178
10
14
                my $read = $handle->read(my $chunk, 65536);
179
10
157
                die "Cannot read $path: ", $handle->error(), "\n" if(!defined($read));
180
10
14
                last if($read == 0);
181
5
5
                $xml .= $chunk;
182
5
8
                die "expands beyond $MAX_XML_BYTES bytes; not a report\n" if(length($xml) > $MAX_XML_BYTES);
183        }
184
185
5
22
        return $xml;
186}
187
188# The first non-empty text under a named child.  Used for the single-valued
189# fields, where a reporter that repeats an element would otherwise make the
190# concatenated text look like a value.
191sub text_in
192{
193
638
419
        my ($node, $name) = @_;
194
195
638
408
        return '' unless($node);
196
197
638
394
        foreach my $found (descendants($node, $name)) {
198
638
418
                my $text = text_content($found);
199
638
457
                $text =~ s/\A\s+//;
200
638
368
                $text =~ s/\s+\z//;
201
638
933
                return $text if(length($text));
202        }
203
204
0
0
        return '';
205}
206
207sub when
208{
209
58
48
        my $epoch = shift;
210
211
58
155
        return '?' unless(defined($epoch) && $epoch =~ /\A\d+\z/);
212
213
58
1091
        return strftime('%Y-%m-%d %H:%M UTC', gmtime($epoch));
214}
215
216# Totals per reported domain and source address, across every report.  One
217# address spread over several reports is one problem, not several - but the
218# reports for every domain arrive at the same mailbox, so their figures must
219# not be added together: an address that legitimately sends for one domain is
220# not thereby legitimate for another.
221
25
213
my %by_domain;
222my @read_files;
223
25
29
my ($total_messages, $total_records, $reports_read) = (0, 0, 0);
224
25
24
my $unexpected_messages = 0;
225# Messages the policy quarantined or rejected that should not have been:
226# either they authenticated, or they came from an expected host.
227
25
26
my $misfiled_messages = 0;
228
25
21
my %misfiled;
229
230
25
35
foreach my $path (@files) {
231
32
32
29
63
        my $doc = eval { read_report($path) };
232
32
64
        if(!$doc) {
233
3
6
                my ($why) = split(/\n/, "$@");
234                # "not a report" is the normal case in a downloads directory, so it is
235                # passed over; anything else means a report we could not read.
236
3
17
                warn 'Skipping ', basename($path), ": $why\n" unless($why =~ /not a (DMARC )?report|too large|expands beyond/);
237
3
7
                next;
238        }
239
29
30
        $reports_read++;
240
29
414
        push @read_files, File::Spec->rel2abs($path);
241
242
29
66
        my ($meta) = descendants($doc, 'report_metadata');
243
29
48
        my ($policy) = descendants($doc, 'policy_published');
244
245
29
71
        my ($date_range) = $meta ? descendants($meta, 'date_range') : ();
246
29
66
        my $begin = text_in($date_range, 'begin');
247
29
39
        my $end = text_in($date_range, 'end');
248
249
29
122
        print '=' x 78, "\n";
250
29
1065
        print basename($path), "\n";
251
29
53
        printf "  reporter : %s   report_id: %s\n", text_in($meta, 'org_name'), text_in($meta, 'report_id');
252
29
64
        printf "  period   : %s -> %s\n", when($begin), when($end);
253
29
51
        printf "  domain   : %s   p=%s sp=%s adkim=%s aspf=%s pct=%s\n",
254                text_in($policy, 'domain'), text_in($policy, 'p'), text_in($policy, 'sp'),
255                text_in($policy, 'adkim'), text_in($policy, 'aspf'), text_in($policy, 'pct');
256
257
29
56
        my $reported_domain = text_in($policy, 'domain');
258
259
29
50
        my @records = descendants($doc, 'record');
260
29
44
        if(!@records) {
261
0
0
                print "  (no records in this report)\n";
262
0
0
                next;
263        }
264
265
29
36
        foreach my $record (@records) {
266
29
37
                my ($row) = descendants($record, 'row');
267
29
31
                my ($evaluated) = descendants($record, 'policy_evaluated');
268
269
29
45
                my $ip = text_in($row, 'source_ip');
270
29
47
                my $count = text_in($row, 'count') || 0;
271
29
46
                my $disposition = text_in($evaluated, 'disposition');
272
29
47
                my $dkim_verdict = text_in($evaluated, 'dkim');
273
29
35
                my $spf_verdict = text_in($evaluated, 'spf');
274
29
41
                my $header_from = text_in($record, 'header_from');
275
276                # The addresses actually seen, which is what says whether a message
277                # carried a signature at all rather than merely failing its check.
278
29
32
                my (@dkim_auth, @spf_auth);
279
29
36
                foreach my $results (descendants($record, 'auth_results')) {
280
29
46
                        foreach my $dkim (children_named($results, 'dkim')) {
281
29
55
                                push @dkim_auth, sprintf('%s/%s=%s',
282                                        text_in($dkim, 'domain'), (text_in($dkim, 'selector') || '-'), text_in($dkim, 'result'));
283                        }
284
29
42
                        foreach my $spf (children_named($results, 'spf')) {
285
29
34
                                push @spf_auth, sprintf('%s=%s', text_in($spf, 'domain'), text_in($spf, 'result'));
286                        }
287                }
288
289                # A reporter that leaves policy_published out is grouped by the From
290                # domain of the record instead, so nothing falls into a shared bucket.
291
29
58
                my $domain = $reported_domain || $header_from || '(unknown)';
292
293
29
59
                my $passed = ($dkim_verdict eq 'pass') || ($spf_verdict eq 'pass');
294
295                # Two failures worth naming as they happen, because neither shows up in
296                # the per-address totals: mail that authenticated and was filed anyway,
297                # and mail of ours that the policy filed.
298
29
57
                my $filed = ($disposition eq 'quarantine' || $disposition eq 'reject');
299
29
45
                my $word = ($disposition eq 'reject') ? 'rejected' : 'quarantined';
300
301
29
30
                my @flags;
302
29
85
                if(!$expected{$ip}) {
303
10
19
                        push @flags, 'NOT ' . join('/', @expected);
304
10
14
                        $unexpected_messages += $count;
305                } elsif(!$passed) {
306
3
3
                        push @flags, 'expected host, not authenticating';
307                }
308
309
29
149
                if($filed && $passed && $expected{$ip}) {
310
1
1
                        push @flags, "expected sender, $word though authenticated";
311                } elsif($filed && $passed) {
312
1
1
                        push @flags, "authenticated, but $word";
313                } elsif($filed && $expected{$ip}) {
314
1
1
                        push @flags, "expected sender, $word";
315                }
316
317
29
63
                if($filed && ($passed || $expected{$ip})) {
318
3
20
                        my $finding = $misfiled{join("\t", $domain, $ip, $disposition)} ||= {
319                                'domain' => $domain, 'ip' => $ip, 'disposition' => $disposition,
320                                'count' => 0, 'passed' => 0, 'expected' => 0,
321                                'dkim' => {}, 'spf' => {},
322                        };
323
3
5
                        $finding->{'count'} += $count;
324
3
6
                        $finding->{'passed'} = 1 if($passed);
325
3
7
                        $finding->{'expected'} = 1 if($expected{$ip});
326
3
3
                        $finding->{'dkim'}{$dkim_verdict} = 1;
327
3
4
                        $finding->{'spf'}{$spf_verdict} = 1;
328
3
2
                        $misfiled_messages += $count;
329                }
330
331
29
60
                my $flag = @flags ? '  <== ' . join('; ', @flags) : '';
332
333
29
91
                printf "  %-16s %5d  dkim=%-5s spf=%-8s %-9s from=%s%s\n",
334                        $ip, $count, $dkim_verdict, $spf_verdict, $disposition, $header_from, $flag;
335
29
70
                printf "      dkim seen: %s\n", (@dkim_auth ? join(', ', @dkim_auth) : 'none');
336
29
61
                printf "      spf  seen: %s\n", (@spf_auth ? join(', ', @spf_auth) : 'none');
337
338
29
39
                $total_records++;
339
29
23
                $total_messages += $count;
340
341                my $entry = $by_domain{$domain}{$ip} ||= {
342                        'count' => 0, 'pass' => 0, 'fail' => 0,
343
29
182
                        'unexpected' => (!$expected{$ip} ? 1 : 0),
344                        'dkim_seen' => {},
345                };
346
29
42
                $entry->{'count'} += $count;
347
29
44
                $entry->{'pass'} += $count if($passed);
348
29
39
                $entry->{'fail'} += $count if(!$passed);
349
29
449
                $entry->{'dkim_seen'}{$_} = 1 foreach(@dkim_auth);
350        }
351}
352
353# Named before the summary is printed, so a caller that moves the files aside
354# knows exactly which ones were summarised - and which were merely in the way.
355
25
36
if(defined($file_list)) {
356
11
480
        open(my $fh, '>', $file_list) or die "Cannot write $file_list: $!\n";
357
11
13
16
59
        print $fh map { "$_\n" } @read_files;
358
11
890
        close($fh) or die "Cannot close $file_list: $!\n";
359}
360
361
25
51
print '=' x 78, "\n";
362
25
54
printf "Totals over %d report(s): %d record(s), %d message(s)\n",
363        $reports_read, $total_records, $total_messages;
364
25
65
foreach my $domain (sort keys %by_domain) {
365
27
30
        my $by_ip = $by_domain{$domain};
366
367
27
39
        my ($messages, $unexpected) = (0, 0);
368
27
27
24
37
        foreach my $ip (keys %{$by_ip}) {
369
29
35
                $messages += $by_ip->{$ip}{'count'};
370
29
70
                $unexpected += $by_ip->{$ip}{'count'} if($by_ip->{$ip}{'unexpected'});
371        }
372
373
27
48
        printf "\n%s: %d message(s)", $domain, $messages;
374
27
61
        printf ", %d not from %s", $unexpected, join('/', @expected) if($unexpected);
375
27
38
        print "\n";
376
377
27
74
        printf "  %-16s %8s %8s %8s  %s\n", 'source_ip', 'messages', 'passed', 'failed', 'status';
378
27
2
27
27
24
47
        foreach my $ip (sort { $by_ip->{$b}{'count'} <=> $by_ip->{$a}{'count'} || $a cmp $b } keys %{$by_ip}) {
379
29
37
                my $entry = $by_ip->{$ip};
380
29
79
                my $status = $entry->{'unexpected'} ? 'UNEXPECTED SOURCE' : ($entry->{'fail'} ? 'expected, failing auth' : 'expected, authenticating');
381
29
71
                printf "  %-16s %8d %8d %8d  %s\n", $ip, $entry->{'count'}, $entry->{'pass'}, $entry->{'fail'}, $status;
382
29
29
33
70
                my @dkim = sort keys %{$entry->{'dkim_seen'}};
383
29
82
                printf "  %-16s   dkim: %s\n", '', (@dkim ? join(', ', @dkim) : 'no signature seen');
384        }
385}
386
387# Named after the totals, so the figures that explain them come first.
388
25
41
if(%misfiled) {
389
3
3
        print '=' x 78, "\n";
390
3
3
        printf "Filed by policy although it should not have been: %d message(s)\n", $misfiled_messages;
391
3
4
        printf "  %-22s %-16s %-11s %8s  %s\n", 'domain', 'source_ip', 'disposition', 'messages', 'why';
392
3
5
        foreach my $finding (sort {
393
0
0
                $a->{'domain'} cmp $b->{'domain'} || $b->{'count'} <=> $a->{'count'} || $a->{'ip'} cmp $b->{'ip'}
394        } values %misfiled) {
395                my $reason = $finding->{'expected'}
396
3
8
                        ? ($finding->{'passed'} ? 'expected sender, and authenticated' : 'expected sender')
397                        : 'authenticated';
398
3
7
                $reason .= ($finding->{'disposition'} eq 'reject') ? ', yet rejected' : ', yet quarantined';
399                printf "  %-22s %-16s %-11s %8d  %s (dkim=%s spf=%s)\n",
400                        $finding->{'domain'}, $finding->{'ip'}, $finding->{'disposition'},
401                        $finding->{'count'}, $reason,
402
3
3
3
5
4
8
                        join('/', sort keys %{$finding->{'dkim'}}), join('/', sort keys %{$finding->{'spf'}});
403        }
404}
405
406
25
28
print "\n";
407
25
35
if(%misfiled) {
408
3
4
        printf "%d message(s) were quarantined or rejected although they should not have been.\n", $misfiled_messages;
409}
410
25
36
if($unexpected_messages) {
411
10
16
        printf "%d message(s) came from addresses that are not %s.\n", $unexpected_messages, join('/', @expected);
412
10
0
        exit(1);
413}
414
15
29
exit(1) if(%misfiled);
415
13
24
print "Every message came from ", join('/', @expected), ", and none was filed by policy.\n";
416
13
0
exit(0);
417