| 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 |