lib/Mail/DMARC/Report.pm

filter: Statementstmt 97.9% 48 / 49 Branchbran 78.5% 11 / 14 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 93.7% 15 / 16 Podpod 0.0% 0 / 9 totaltotal 84.0% 74 / 88 CC 8 SCAR 5.6
CC
8
Cov
94%
compress
3.1
receive
2.0
aggregate
2.0
CRAP 1.8
« blib/lib/Mail/DMARC/Test/Transport.pm ↑ Summary lib/Mail/DMARC/Report/Store/SQL/Grammars/SQLite.pm »
1 package Mail::DMARC::Report;
2 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 10 ▶use feature 'signatures';
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 10 our $VERSION = '2.20260827';
7  
8 10 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 10 ▶use IO::Compress::Gzip;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 10 ▶use IO::Compress::Zip;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 10 ▶use parent 'Mail::DMARC::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 10 require Mail::DMARC::Report::URI;
15  
16 11 ▶sub compress( $self, $xml_ref ) {
Subroutine compress: called CC=3 SCAR=11.2
Pod undocumented
17 11 ▶ croak "xml is not a reference!" if 'SCALAR' ne ref $xml_ref;
Branch: 1 branch
BranchTrueFalseTotal
if "SCALAR" ne ref $xml_ref 0 11 11
18 11 my $shrunk;
19 11 my $zipper = {
20 gz => \&IO::Compress::Gzip::gzip, # 2013 draft
21 zip => \&IO::Compress::Zip::zip, # legacy format
22 };
23  
24 # WARNING: changes here MAY require updates in SMTP::assemble_message
25 11 my $cf = 'gz';
26 11 ▶ $zipper->{$cf}->( $xml_ref, \$shrunk ) or croak "unable to compress: $!";
Branch: 1 branch
BranchTrueFalseTotal
$zipper->{$cf}->($xml_ref, \$shrunk) or croak("unable to compress: $!") 11 0 11
27 11 return $shrunk;
28 }
29  
30 1 ▶sub init($self) {
Subroutine init: called CC=1 SCAR=0.0
Pod undocumented
31 1 delete $self->{dmarc};
32 1 delete $self->{aggregate};
33 1 return;
34 }
35  
36 80 ▶sub aggregate($self) {
Subroutine aggregate: called CC=2 SCAR=6.9
Pod undocumented
37 80 ▶ return $self->{aggregate} if ref $self->{aggregate};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"aggregate"} 59 21 80
38 21 require Mail::DMARC::Report::Aggregate;
39 21 return $self->{aggregate} = Mail::DMARC::Report::Aggregate->new();
40 }
41  
42 0 ▶sub dmarc($self) {
Subroutine dmarc: not called CC=1 SCAR=6.9
Pod undocumented
43 0 return $self->{dmarc};
44 }
45  
46 1 ▶sub receive($self) {
Subroutine receive: called CC=2 SCAR=7.1
Pod undocumented
47 1 ▶ return $self->{receive} if ref $self->{receive};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"receive"} 0 1 1
48 1 require Mail::DMARC::Report::Receive;
49 1 return $self->{receive} = Mail::DMARC::Report::Receive->new;
50 }
51  
52 42 ▶sub sendit($self) {
Subroutine sendit: called CC=2 SCAR=6.9
Pod undocumented
53 42 ▶ return $self->{sendit} if ref $self->{sendit};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"sendit"} 1 41 42
54 41 require Mail::DMARC::Report::Send;
55 41 return $self->{sendit} = Mail::DMARC::Report::Send->new();
56 }
57  
58 52 ▶sub store($self) {
Subroutine store: called CC=2 SCAR=6.9
Pod undocumented
59 52 ▶ return $self->{store} if ref $self->{store};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"store"} 25 27 52
60 27 require Mail::DMARC::Report::Store;
61 27 return $self->{store} = Mail::DMARC::Report::Store->new();
62 }
63  
64 49 ▶sub uri($self) {
Subroutine uri: called CC=2 SCAR=6.9
Pod undocumented
65 49 ▶ return $self->{uri} if ref $self->{uri};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"uri"} 24 25 49
66 25 return $self->{uri} = Mail::DMARC::Report::URI->new();
67 }
68  
69 11 ▶sub save_aggregate($self) {
Subroutine save_aggregate: called CC=1 SCAR=0.0
Pod undocumented
70 11 return $self->store->backend->save_aggregate( $self->aggregate );
71 }
72  
73 10 1;
74  
75 __END__
76  
77 =pod
78  
79 =head1 NAME
80  
81 Mail::DMARC::Report - A DMARC report interface
82  
83 =head1 VERSION
84  
85 version 2.20260827
86  
87 =head1 DESCRIPTION
88  
89 DMARC reports are information that a DMARC implementing Mail Transfer Agent (MTA) sends to Author Domains and also something that an Author Domain owner receives from other DMARC implementing MTAs. Mail::DMARC supports both roles, as a sender and a receiver.
90  
91 There are two report types, L<aggregate|Mail::DMARC::Report::Aggregate> and forensic.
92  
93 =head1 Aggregate Reports
94  
95 See L<Mail::DMARC::Report::Aggregate>
96  
97 =head2 Forensic Reports
98  
99 TODO
100  
101 =head2 Report Sender
102  
103 See L<Mail::DMARC::Report::Send>
104  
105 1. store reports
106 2. bundle aggregated reports
107 3. format report in XML
108 4. gzip the XML
109 5. deliver report to Author Domain
110  
111 =head2 Report Receiver
112  
113 See L<Mail::DMARC::Report::Receive>
114  
115 1. accept reports via HTTP or SMTP
116 2. parse the compressed XML message
117 3. store the report
118 4. present stored data
119  
120 =head2 Verify External Destinations
121  
122 1. Extract the host portion of the authority component of the URI.
123 Call this the "destination host".
124  
125 2. Prepend the string "_report._dmarc".
126  
127 3. Prepend the domain name from which the policy was retrieved.
128  
129 4. Query the DNS for a TXT record at the constructed name. If the
130 result of this request is a temporary DNS error of some kind
131 (e.g., a timeout), the Mail Receiver MAY elect to temporarily
132 fail the delivery so the verification test can be repeated later.
133  
134 5. If the result includes no TXT resource records or multiple TXT
135 resource records, a positive determination of the external
136 reporting relationship cannot be made; stop.
137  
138 6. Parse the result, if any, as a series of "tag=value" pairs, i.e.,
139 the same overall format as the policy record. In particular, the
140 "v=DMARC1" tag is mandatory and MUST appear first in the list.
141 If at least that tag is present and the record overall is
142 syntactically valid per Section 6.3, then the external reporting
143 arrangement was authorized by the destination ADMD.
144  
145 7. If a "rua" or "ruf" tag is thus discovered, replace the
146 corresponding value extracted from the domain's DMARC policy
147 record with the one found in this record. This permits the
148 report receiver to override the report destination. However, to
149 prevent loops or indirect abuse, the overriding URI MUST use the
150 same destination host from the first step.
151  
152 =head1 ERROR REPORTS
153  
154 12.2.4. Error Reports
155  
156 When a Mail Receiver is unable to complete delivery of a report via
157 any of the URIs listed by the Domain Owner, the Mail Receiver SHOULD
158 generate an error message. An attempt MUST be made to send this
159 report to all listed "mailto" URIs and MAY also be sent to any or all
160 other listed URIs.
161  
162 The error report MUST be formatted per [MIME]. A text/plain part
163 MUST be included that contains field-value pairs such as those found
164 in Section 2 of [DSN]. The fields required, which may appear in any
165 order, are:
166  
167 Report-Date: A [MAIL]-formatted date expression indicating when the transport failure occurred.
168  
169 Report-Domain: The domain-name about which the failed report was generated.
170  
171 Report-ID: The Report-ID: that the report tried to use.
172  
173 Report-Size: The size, in bytes, of the report that was unable to be
174 sent. This MUST represent the number of bytes that the Mail
175 Receiver attempted to send. Where more than one transport system
176 was attempted, the sizes may be different; in such cases, separate
177 error reports MUST be generated so that this value matches the
178 actual attempt that was made. For example, a "mailto" error
179 report would be sent to the "mailto" URIs with one size, while the
180 "https" reports might be POSTed to those URIs with a different
181 size, as they have different transport and encoding requirements.
182  
183 Submitter: The domain-name representing the Mail Receiver that generated, but was unable to submit, the report.
184  
185 Submitting-URI: The URI(s) to which the Mail Receiver tried, but failed, to submit the report.
186  
187 An additional text/plain part MAY be included that gives a human-
188 readable explanation of the above, and MAY also include a URI that
189 can be used to seek assistance.
190  
191 [NOTE: A more rigorous syntax specification, including ABNF and
192 possible registration of a new media type, will be added here when
193 more operational experience is acquired.]
194  
195 =head1 AFRF reports
196  
197 =head1 IODEF reports
198  
199 https://datatracker.ietf.org/doc/draft-kucherawy-dmarc-base/?include_text=1
200  
201 Section 3.5 Out of Scope:
202  
203 This first version of DMARC supports only a single reporting format.
204  
205 =head1 AUTHORS
206  
207 =over 4
208  
209 =item *
210  
211 Matt Simerson <msimerson@cpan.org>
212  
213 =item *
214  
215 Davide Migliavacca <shari@cpan.org>
216  
217 =item *
218  
219 Marc Bradshaw <marc@marcbradshaw.net>
220  
221 =back
222  
223 =head1 COPYRIGHT AND LICENSE
224  
225 This software is copyright (c) 2026 by Matt Simerson.
226  
227 This is free software; you can redistribute it and/or modify it under
228 the same terms as the Perl 5 programming language system itself.
229  
230 =cut
« blib/lib/Mail/DMARC/Test/Transport.pm ↑ Summary lib/Mail/DMARC/Report/Store/SQL/Grammars/SQLite.pm »