/ 
Email-Abuse-Investigator-0.09
/ submit_abuse_report

NAME

submit_abuse_report -- analyse a spam/phishing email and send abuse reports to all relevant parties

SYNOPSIS

submit_abuse_report [options] spam.eml
submit_abuse_report [options] < spam.eml

OPTIONS

--dry-run

Analyse the message and print a full description of what would be sent and to whom, but do not connect to any mail server or send anything. Useful for reviewing before committing to sending.

-i, --interactive

Prompt for confirmation before sending each abuse report, similar to rm -i. For each recipient the address and the reason for contacting them are displayed, followed by a Send? [y/N] prompt. Only reports where the user answers y (case-insensitive) are sent; all others are skipped and counted in the summary. Has no effect in --dry-run mode.

--bcc

Send a blind carbon copy of every report to the --from address. The most common use case: keep a personal record of every report sent without specifying a separate address.

--bcc-to ADDRESS

Send a blind carbon copy of every report to ADDRESS. Use this when the monitoring address differs from --from. The BCC recipient receives the same ARF-compliant message as the primary abuse contact but their address is not visible to the recipient (it is added as a separate SMTP RCPT TO envelope recipient without a Bcc: header in the message). In --dry-run mode the BCC address is shown in the output but no mail is sent.

--from ADDRESS

The envelope sender and From: address for all outgoing reports. Required unless --dry-run is used.

--smtp HOST[:PORT]

SMTP relay to use for sending. Defaults to localhost:25. Supply a port by appending it after a colon, e.g. mail.example.com:587.

--trusted CIDR

A trusted relay IP or CIDR block to skip when identifying the true originating IP. List your own mail server infrastructure here. The option may be repeated for multiple relays:

--trusted 10.0.0.0/8 --trusted 192.168.1.1
--timeout SECS

Network timeout in seconds for DNS, WHOIS, RDAP, and SMTP operations. Default: 15.

--verbose

Print analysis progress messages to STDERR.

--help

Print this help text and exit.

DESCRIPTION

Reads a raw RFC 2822 spam or phishing email (from a file or STDIN), analyses it using Email::Abuse::Investigator, and sends an abuse report to each identified contact: the sending ISP, URL hosts, domain registrars, account providers, DKIM signers, and ESPs.

Each outgoing report is a fully RFC 5965 compliant ARF (Abuse Reporting Format) message. The three-part multipart/report structure is:

Part 1 -- text/plain

The human-readable abuse report generated by Email::Abuse::Investigator::abuse_report_text(), including risk level, red flags, originating IP, and a list of all abuse contacts found. Readable by any mail client, including low-end ticketing systems.

Part 2 -- message/feedback-report

The machine-readable ARF metadata part (RFC 5965 s.3), containing structured fields including Feedback-Type, Source-IP, Original-Mail-From, Original-Rcpt-To, Arrival-Date, Reported-Domain, Reported-Uri, and Authentication-Results. Parsed automatically by ARF-aware abuse desk systems and feedback loops.

Part 3 -- message/rfc822

The original spam or phishing message verbatim, as an attachment named original_message.eml. Required by RFC 5965 s.2. ISP abuse teams use the full Received: headers to locate the SMTP session in their logs; without this part a report is rarely actionable.

The envelope sender is set to the null reverse-path (MAIL FROM:<>) per RFC 6650 s.3, which prevents mail loops and DSN storms. The From: header still carries the reporter's address for human reply purposes.

All recipients receive identical report content. The subject line includes the risk level and originating IP for easy triage.

Use --dry-run first to review the analysis, confirm the recipients, and inspect both the ARF metadata fields and the first 20 lines of the original message attachment before committing to sending.

RFC 5965 COMPLIANCE (ARF)

This script generates fully compliant ARF (Abuse Reporting Format) messages as defined by RFC 5965. Compliance covers:

  • multipart/report; report-type=feedback-report outer MIME type (s.2).

  • message/feedback-report second part with Feedback-Type: abuse, Version: 1, User-Agent, Source-IP, Original-Mail-From, Original-Rcpt-To, Arrival-Date, Reported-Domain, Reported-Uri (one per URL), and Authentication-Results (s.3).

  • message/rfc822 third part containing the verbatim original message, which RFC 5965 s.2 states MUST be included (s.2 item (d)).

  • Null reverse-path envelope sender (MAIL FROM:<>) per RFC 6650 s.3 to prevent DSN storms and mail loops.

  • message/feedback-report part encoded as 7bit ASCII as required by the MIME type registration in RFC 5965 s.7.1.

The one deviation from strict RFC 5965 s.2(f) is that the Subject: header of the report is not identical to the subject of the original spam message -- it is set to a descriptive summary including the risk level and originating IP. This is intentional: abuse desk triage is served better by a consistent, informative subject than by reproducing the spam subject verbatim.

EXIT STATUS

0   All reports sent successfully (or --dry-run completed).
1   One or more reports failed to send.
2   Bad command-line options or missing required argument.

With --interactive, skipped reports (answered N) are not counted as failures; exit status 0 is returned if all attempted sends succeeded.

DEPENDENCIES

Email::Abuse::Investigator
Net::SMTP          (core since Perl 5)
Getopt::Long       (core since Perl 5)
Pod::Usage         (core since Perl 5.6)
POSIX              (core since Perl 5)

SEE ALSO

Email::Abuse::Investigator

RFC 5965 -- An Extensible Format for Email Feedback Reports (ARF): https://datatracker.ietf.org/doc/html/rfc5965

RFC 6650 -- Creation and Use of Email Feedback Reports (ARF applicability): https://datatracker.ietf.org/doc/html/rfc6650