blib/lib/Mail/DMARC/Report/Aggregate.pm untested

filter: Statementstmt 0.0% 0 / 117 Branchbran 0.0% 0 / 40 Conditioncond 0.0% 0 / 27 MC/DCmcdc 0.0% 0 / 16 Subroutinesub 0.0% 0 / 18 Podpod 0.0% 0 / 10 totaltotal 0.0% 0 / 228 CC 21 SCAR 29.7
CC
21
Cov
0%
get_identifiers_as_xml
56.0
record
20.0
get_auth_results_as_xml
20.0
CRAP 19.4
1 package Mail::DMARC::Report::Aggregate;
2 use strict;
3 use warnings;
4 use feature 'signatures';
5  
6 our $VERSION = '2.20260827';
7  
8 use Carp;
9 use Data::Dumper;
10 use XML::LibXML;
11  
12 use parent 'Mail::DMARC::Base';
13 use Mail::DMARC::Report::Aggregate::Metadata;
14  
15 sub metadata($self) {
16 return $self->{metadata} if ref $self->{metadata};
17 return $self->{metadata} = Mail::DMARC::Report::Aggregate::Metadata->new;
18 }
19  
20 sub policy_published( $self, $policy = undef ) {
21 return $self->{policy_published} if !$policy;
22 croak "not a policy object!" if 'Mail::DMARC::Policy' ne ref $policy;
23 return $self->{policy_published} = $policy;
24 }
25  
26 sub record( $self, $record = undef, @extra ) { ## no critic (Ambiguous)
27 if ( !$record ) {
28 return $self->{record} || [];
29 }
30  
31 if (@extra) { croak "invalid args"; }
32  
33 if ( 'Mail::DMARC::Report::Aggregate::Record' ne ref $record ) {
34 croak "not a record object";
35 }
36  
37 $self->{record} ||= [];
38  
39 push @{ $self->{record} }, $record;
40  
41 return $self->{record};
42 }
43  
44 sub dump_report($self) {
45 carp Dumper( $self->{metadata}, $self->{policy_published}, $self->{record} );
46 return;
47 }
48  
49 sub as_xml($self) {
50 my $meta = $self->metadata->as_xml;
51 my $pubp = $self->get_policy_published_as_xml;
52 my $reco = $self->get_record_as_xml;
53  
54 return <<"EO_XML"
55 <?xml version="1.0"?>
56 <feedback xmlns="urn:ietf:params:xml:ns:dmarc-2.0">
57 $meta
58 $pubp
59 $reco</feedback>
60 EO_XML
61 ;
62 }
63  
64 sub get_record_as_xml($self) {
65  
66 my $rec_xml = '';
67 foreach my $rec ( @{ $self->{record} } ) {
68 $rec_xml .= "\t<record>\n";
69 my $ip = $rec->{row}{source_ip} or croak "no source IP!?";
70 my $count = $rec->{row}{count} or croak "no count!?";
71 $rec->{row}{policy_evaluated}{disposition} or croak "no disposition?";
72 $ip = XML::LibXML::Text->new($ip)->toString();
73 $count = XML::LibXML::Text->new($count)->toString();
74 $rec_xml
75 .= "\t\t<row>\n"
76 . "\t\t\t<source_ip>$ip</source_ip>\n"
77 . "\t\t\t<count>$count</count>\n"
78 . $self->get_policy_evaluated_as_xml($rec)
79 . "\t\t</row>\n"
80 . $self->get_identifiers_as_xml($rec)
81 . $self->get_auth_results_as_xml($rec);
82 $rec_xml .= "\t</record>\n";
83 }
84 return $rec_xml;
85 }
86  
87 sub get_identifiers_as_xml( $self, $rec ) {
88 my $id = "\t\t<identifiers>\n";
89 foreach my $f (qw/ envelope_to envelope_from header_from /) {
90 if ( $f eq 'header_from' ) { # min occurs = 1
91 croak "missing header_from!" if !$rec->{identifiers}{$f};
92 }
93 elsif ( $f eq 'envelope_from' ) { # min occurs = 1
94 $rec->{identifiers}{$f} = '' if !$rec->{identifiers}{$f};
95 }
96 elsif ( $f eq 'envelope_to' ) { # min occurs = 0
97 next if !$rec->{identifiers}{$f};
98 }
99  
100 my $val = XML::LibXML::Text->new( $rec->{identifiers}{$f} )->toString();
101 $id .= "\t\t\t<$f>$val</$f>\n";
102 }
103 $id .= "\t\t</identifiers>\n";
104 return $id;
105 }
106  
107 sub get_auth_results_as_xml( $self, $rec ) {
108 my $ar = "\t\t<auth_results>\n";
109  
110 foreach my $dkim_sig ( @{ $rec->{auth_results}{dkim} } ) {
111 $ar .= "\t\t\t<dkim>\n";
112 foreach my $g (qw/ domain selector result human_result /) {
113 next if !defined $dkim_sig->{$g} && $g ne 'selector';
114 my $val
115 = defined $dkim_sig->{$g}
116 ? XML::LibXML::Text->new( $dkim_sig->{$g} )->toString()
117 : '';
118 $ar .= "\t\t\t\t<$g>$val</$g>\n";
119 }
120 $ar .= "\t\t\t</dkim>\n";
121 }
122  
123 foreach my $spf ( @{ $rec->{auth_results}{spf} } ) {
124 $ar .= "\t\t\t<spf>\n";
125 foreach my $g (qw/ domain scope result /) {
126 next if !defined $spf->{$g};
127 my $val = XML::LibXML::Text->new( $spf->{$g} )->toString();
128 $ar .= "\t\t\t\t<$g>$val</$g>\n";
129 }
130 $ar .= "\t\t\t</spf>\n";
131 }
132  
133 $ar .= "\t\t</auth_results>\n";
134 return $ar;
135 }
136  
137 sub get_policy_published_as_xml($self) {
138 my $pp = $self->policy_published or return '';
139 my $xml = "\t<policy_published>\n\t\t<domain>$pp->{domain}</domain>\n";
140 foreach my $f (qw/ adkim aspf p sp np t psd fo discovery_method /) {
141 my $v = $pp->{$f};
142  
143 # Set some default values for missing optional fields if necessary
144 if ( $f eq 'sp' && !defined $v ) {
145 $v = $pp->{'p'};
146 }
147 if ( $f eq 'fo' && !defined $v ) {
148 $v = '0';
149 }
150 next if !defined $v;
151 $v = XML::LibXML::Text->new($v)->toString();
152 $xml .= "\t\t<$f>$v</$f>\n";
153 }
154 $xml .= "\t</policy_published>";
155 return $xml;
156 }
157  
158 sub get_policy_evaluated_as_xml( $self, $rec ) {
159 my $pe = "\t\t\t<policy_evaluated>\n";
160  
161 foreach my $f (qw/ disposition dkim spf /) {
162 my $val = XML::LibXML::Text->new( $rec->{row}{policy_evaluated}{$f} )
163 ->toString();
164 $pe .= "\t\t\t\t<$f>$val</$f>\n";
165 }
166  
167 my $reasons = $rec->{row}{policy_evaluated}{reason};
168 if ( $reasons && scalar @$reasons ) {
169 foreach my $reason (@$reasons) {
170 my $typeval = XML::LibXML::Text->new( $reason->{type} )->toString();
171 $pe .= "\t\t\t\t<reason>\n";
172 $pe .= "\t\t\t\t\t<type>$typeval</type>\n";
173  
174 # comment is minOccurs=0 in the RFC 7489 schema; only emit when present
175 if ( defined $reason->{comment} && $reason->{comment} =~ /\S/ ) {
176 my $commentval
177 = XML::LibXML::Text->new( $reason->{comment} )->toString();
178 $pe .= "\t\t\t\t\t<comment>$commentval</comment>\n";
179 }
180 $pe .= "\t\t\t\t</reason>\n";
181 }
182 }
183 $pe .= "\t\t\t</policy_evaluated>\n";
184 return $pe;
185 }
186  
187 1;
188  
189 __END__
190  
191 =pod
192  
193 =head1 NAME
194  
195 Mail::DMARC::Report::Aggregate - aggregate report object
196  
197 =head1 VERSION
198  
199 version 2.20260827
200  
201 =head1 DESCRIPTION
202  
203 This class is used as the canonization of an aggregate report.
204  
205 When reports are received, the XML is parsed into an L<Aggregate|Mail::DMARC::Report::Aggregate> object, which then gets passed to the Report::Store and saved. When sending DMARC reports, data is extracted from the L<Store|Mail::DMARC::Report::Store> as an Aggregate object, exported as XML, and sent.
206  
207 =head1 2013 Draft Description
208  
209 AGGREGATE REPORTS
210  
211 The report SHOULD include the following data:
212  
213 o Enough information for the report consumer to re-calculate DMARC
214 disposition based on the published policy, message disposition, and
215 SPF, DKIM, and identifier alignment results. {R12}
216  
217 o Data for each sender subdomain separately from mail from the
218 sender's organizational domain, even if no subdomain policy is
219 applied. {R13}
220  
221 o Sending and receiving domains {R17}
222  
223 o The policy requested by the Domain Owner and the policy actually
224 applied (if different) {R18}
225  
226 o The number of successful authentications {R19}
227  
228 o The counts of messages based on all messages received even if
229 their delivery is ultimately blocked by other filtering agents {R20}
230  
231 Aggregate reports are most useful when they all cover a common time
232 period. By contrast, correlation of these reports from multiple
233 generators when they cover incongruous time periods is difficult or
234 impossible. Report generators SHOULD, wherever possible, adhere to
235 hour boundaries for the reporting period they are using. For
236 example, starting a per-day report at 00:00; starting per-hour
237 reports at 00:00, 01:00, 02:00; et cetera. Report Generators using a
238 24-hour report period are strongly encouraged to begin that period at
239 00:00 UTC, regardless of local timezone or time of report production,
240 in order to facilitate correlation.
241  
242 =head1 Report Structure
243  
244 This is a translation of the XML report format in the 2013 Draft, converted to perl data structures.
245  
246 feedback => {
247 version => 1.0, # decimal
248 report_metadata => { # info about DMARC reporter
249 report_id => string
250 org_name => 'Art Farm',
251 email => 'no-reply@theartfarm.com',
252 extra_contact_info => string # min 0
253 date_range => {
254 begin => epoch time,
255 end => epoch time,
256 },
257 error => string, # min 0, max unbounded
258 },
259 policy_published => {
260 domain => string
261 adkim => r, s
262 aspf => r, s
263 p => none, quarantine, reject
264 sp => none, quarantine, reject
265 pct => integer
266 fo => string
267 },
268 record => [
269 { row => {
270 source_ip => # IPAddress
271 count => # integer
272 policy_evaluated => { # min=1
273 disposition => # none, quarantine, reject
274 dkim => # pass, fail
275 spf => # pass, fail
276 reason => [ # min 0, max unbounded
277 { type => # forwarded sampled_out, trusted_forwarder, mailing_list, local_policy, other
278 comment => # string, min 0
279 },
280 ],
281 }
282 },
283 identifiers => {
284 envelope_to min=0
285 envelope_from min=1
286 header_from min=1
287 },
288 auth_results => {
289 spf => [ # min 1, max unbounded
290 { domain => # min 1
291 scope => # min 1, helo, mfrom
292 result => # min 1, none neutral pass fail softfail temperror permerror
293 }
294 ] # ( unknown -> temperror, error -> permerror )
295 dkim => [ # min 0, max unbounded
296 { domain => , # min 1, the d= parameter in the signature
297 selector => , # min 0, string
298 result => , # none pass fail policy neutral temperror permerror
299 human_result => # min 0, string
300 },
301 ],
302 },
303 ]
304 },
305 };
306  
307 =head1 AUTHORS
308  
309 =over 4
310  
311 =item *
312  
313 Matt Simerson <msimerson@cpan.org>
314  
315 =item *
316  
317 Davide Migliavacca <shari@cpan.org>
318  
319 =item *
320  
321 Marc Bradshaw <marc@marcbradshaw.net>
322  
323 =back
324  
325 =head1 COPYRIGHT AND LICENSE
326  
327 This software is copyright (c) 2026 by Matt Simerson.
328  
329 This is free software; you can redistribute it and/or modify it under
330 the same terms as the Perl 5 programming language system itself.
331  
332 =cut