mvmf: darp man page
mvmf: darp man page
DARP(1) General Commands Manual DARP(1)
NAME
darp - DMARC Aggregate Report Processor
SYNOPSIS
darp [-c] [-f input-file] [-m] [-n report-name] [-p print-file] [-r
archive-root] [-t input-type] [-x] [input-file]
DESCRIPTION
darp processes DMARC aggregate reports in some way.
Options which may be given are as follows:
-c Says that the input xml document should be archived according to
the cataloging method described here.
-f input-file
Gives the name of the input file.
-m Says that the input file contains an email message, to which the
xml report is attached. This is an idea which is unlikely to be
implemented, so we won't mention it here.
-n report-name
Gives the name of the report, formatted in the way that the name
of a report attached to an email message is formatted per the ag-
gregate reporting RFC. The name is built of certain components
separated by "!" characters. It is used in cataloging the report
(e.g. for archiving). It doesn't matter where the name comes
from. It could simply be invented from the report parameters, or
taken verbatim from the attachment name in an email that contains
the report.
-p print-file
Where to print a summary of the aggregate report. print-file may
be specified as "-" to print to stdout.
-r archive-root
Specifies an alternative to the path where summary reports are
catalogued and archived. The archive-root is prefix rather than
a directory. If the archive-root is "/tmp" then a report file
named "report" would be filed as /tmpreport and not /tmp/report.
That is, for a directory name the archive-root should be given
with a directory syntax (e.g. on *nix systems, terminated with a
"/") if it's intended to be a directory.
A file would not be catalogued as "report" -- the archive name is
built from parameters about the report, taken from the report-
name.
-t input-type
Says what type the input report is. Types are:
zip,tar,... a file recognized by libarchive as containing file
members. It's expected that the archive will contain
exactly one file, with a filename (in the archive)
that is formatted according to the method referred to
along with "report-name." For this type of input, the
report-name is taken from the filename in the
archive, and should not be given with a separate "-n"
option.
gzip The input is a gzipped .xml file. If needed (e.g. for
cataloging), a "report-name" should be given with
"-n" option.
-x Increment debugging level
The input-file may be given via the -f flag or as an optional command
line argument. If this is omitted, input is taken from stdin. The in-
put-file may also be given as "-" (a single hyphen) to indicate stdin.
OPERATION
darp reads and parses the DMARC aggregate report (an xml file) given to
it and does one or more of these things with it, depending on the invo-
cation:
report
print a summary report to a file or to stdout. This is the default oper-
ation if no other thing is requested. A report file may be specified
with the "-p" option. If none has been specified and a report is being
printed, it is printed to stdout.
catalog
store a copy of the xml report file into a proper place in a hierarchy
of reports. This cataloging is requested by using the "-c" command line
option. Reports are filed relative to an archive root prefix (also
known as a catalog root). A default prefix is built into the darp pro-
gram, but an alternate may be set with the "-r" command line option.
Note again that since it's just a prefix, you need to indicate syntacti-
cally (e.g. with trailing "/") that it's a directory if you intend it to
be interpreted as a root directory. The report files are stored accord-
ing to a hierarchy like:
sender/receiver/yyyy
which string is appended to the archive root, and where
sender is the sending domain,
receiver is the receiving domain, and
yyyy is the year the report started.
Each file itself is stored into this hierarchy with a name of the form
start-end.xml
where start and end are dates representing the range covered by the re-
port. Both the start and the end dates in this filename use a yyyym-
mdd.hhmmss form (year, month, day, hour, minute, second).
darp can of course be used to print a report from a file in the catalog.
You just have to tell it where that xml file is, using this classifica-
tion scheme.
store into database
File the report into a SQL database. (Minor note: this is an unimple-
mented idea for future enhancement.)
FILING INCOMING DMARC AGGREGATE REPORTS
The intent of the "-c" option, which says to catalog xml reports, is to
process incoming mail messages containing such reports. Here's an exam-
ple shell script that uses the mvmda mail delivery agent to deliver a
report to darp for that purpose.
#!/bin/bash
if [ $# -ne 0 ]; then
echo "extra stuff on command line"
exit 1
fi
/usr/local/bin/mvmda <(cat <<'EOF'
sieve { require "fileinto"; }
string reproot = "/some/place/DMARC/aggregate-reports/";
string repcmd = "|/usr/local/bin/darp -c -r " + reproot;
unsigned char searchingF = 1;
unsigned char doneF = 0;
unsigned char attemptedF = 0;
string name;
string subtype;
int w() {
$msgpart_go_top();
while ( searchingF ) {
if ( $msgpart_mime_type() == "application" ) {
subtype = $msgpart_mime_subtype();
if ( subtype == "zip" ) {
doneF = sieve { fileinto :part :body [repcmd + " -t zip"]; };
}
else if ( subtype == "gzip" ) {
name = $msgpart_mime_filename();
if ( ( name == "" ) ||
( name !=? "*.xml.gz" ) )
continue;
name = $str_match(1) + ".xml";
doneF = sieve { fileinto :part :body [repcmd + " -t gzip -n " + name]; };
}
else {
}
attemptedF = 1;
break;
}
// Iterative step to next in messagepart tree.
// child first, sibling next, then parent* sibling.
if ( ! $msgpart_go_child() ) {
while ( searchingF && !$msgpart_go_next() )
searchingF = $msgpart_go_parent();
}
}
return doneF;
};
w();
reproot = "DMARC/aggregate-reports/";
if ( attemptedF )
sieve { fileinto [ reproot + "handled" ]; }
else {
doneF = sieve { fileinto [ reproot + "unhandled" ]; };
if ( !doneF )
sieve { fileinto [ reproot + "failed" ]; }
}
EOF
)
exit 0
SEE ALSO
http://www.mvmf.org/ -- the mvmf web site.
CREDITS TO
M. Mallett (mem@mvmf.org) 2024-2025
BUGS
You tell me..
DARP(1)