README FOR RICOCHET 0.97 Table Of Contents DESCRIPTION .................................................... SECTION 0 What Is Ricochet? .................................................. 0.0 How Does It Work? .................................................. 0.1 Ricochet Web Site .................................................. 0.2 DOWNLOAD AND INSTALLATION ...................................... SECTION 1 Download Information ............................................... 1.0 Requirements ....................................................... 1.1 Installation ....................................................... 1.2 Platforms .......................................................... 1.3 Files .............................................................. 1.4 CONFIGURATION AND USAGE ........................................ SECTION 2 Usage .............................................................. 2.0 Command Line Parameters ............................................ 2.1 Config File ........................................................ 2.2 Abuse Contacts File ................................................ 2.3 Abuse.net Database ................................................. 2.31 Skip List .......................................................... 2.4 Complaint Template ................................................. 2.5 How Are Forged Headers Handled ..................................... 2.6 INVOKING RICOCHET FROM OTHER APPS .............................. SECTION 3 Binding Ricochet To A Key In "Mutt" ................................ 3.0 CREDITS, FEEDBACK, ETC. ........................................ SECTION 4 Author Information ................................................. 4.0 Software License ................................................... 4.1 Feedback ........................................................... 4.2 Ricochet Developers' Mailing List .................................. 4.3 Ricochet Announce List ............................................. 4.4 ------------------------------------------------------------ DESCRIPTION = SECTION 0 === 0.0 What Is Ricochet? Ricochet is an automated agent for tracing and reporting internet junk mail (a.k.a Spam). Ricochet analyses the headers of a spam to identity the machines used for its injection, looks up the email addresses of the machine owners and mails out a complaint to them. Ricochet uses various network information resources like nameserver records, MX records and Whois databases worldwide to collect and verify this information. 0.1 How Does It Work? Ricochet looks at the originating information encoded in various headers, most significantly, in the 'Received' headers -- which are appended by SMTP relays and contain the routing information. The information extracted is verified with nslookup, MX and PTR queries. Ricochet then consults a list of abuse report addresses (see Section 2.3) for email addresses of abuse administrators of the originating systems. If corresponding information is not present in the abuse file, ricochet does 'whois' queries on the domain names associated with these machines to generate a list of complaint addresses. Finally, a complaint is mailed to these addresses. 0.3 Ricochet Web Site. Ricochet web site URL is http://www.vipul.net/ricochet/. ---------------------------------------------- DOWNLOAD AND INSTALLATION = SECTION 1 ================= 1.0 Download Information. Latest version of Ricochet and this README file can be downloaded from the Ricochet web site at http://vipul.net/ricochet/download.html. 1.1 Requirements. Ricochet was written in Perl 5.004 and has been tested on OS environments listed in Section 1.3. Ricochet needs the following modules: o Mail::Internet (GBARR/MailTools-v.vv.tar.gz) o Net::DNS (MFUHR/Net-DNS-v.vv.tar.gz) o Text::Template (MJD/Text-Template-v.vv.tar.gz) o Net::XWhois (V/VI/VIPUL/Net-XWhois-v.vv.tar.gz) Version 0.60+ o LWP::UserAgent If these are not already installed on the system, the install program will try to automatically fetch and make them using CPAN.pm. On some systems CPAN doesn't bootstrap from the install script. See the CPAN manual page ('man CPAN') for instructions on installing the modules manually in case the install fails. 1.2 Installation. Ricochet comes with an interactive install program that creates a directory ($HOME/.ricochet) for helper files, builds the required config (see Section 2.2) and installs the ricochet script in the specified directory. Untar and gunzip the ricochet archive and execute the "install" script. 1.3 Platforms. o Linux. o HP-UX 9.03 (GNU-ified) 1.4 Files. /usr/local/bin/ricochet Ricochet Script. $HOME/bin/ricochet Ricochet Script. $HOME/.ricochet/ricochetrc See Section 2.2. $HOME/.ricochet/skip-list See Section 2.4. $HOME/.ricochet/abuse-contacts See Section 2.3. $HOME/.ricochet/logs See Section 2.1. $HOME/.ricochet/complaint-template See Section 2.5. $HOME/.ricochet/README This file. $HOME/.ricochet/CHANGES Change log. $HOME/.ricochet/ARTISTIC Ricochet Licensing. $HOME/.ricochet/TODO The Todo List. The default directory for Ricochet files is $HOME/.ricochet. If your helper files, including the "ricochetrc" are located elsewhere, you can specify the alternate location through "RICOCHET" environment variable. To set helper dir to /usr/local/ricochet/ use, bash$ export RICOCHET=/usr/local/ricochet ------------------------------------------------ CONFIGURATION AND USAGE = SECTION 2 =============== 2.0 Usage. You can either 'pipe' the spam mail through ricochet or provide the file containing the spam as an argument to the script. If you are doing this from with-in your Mail User Agent, ensure it pipes all the headers along with the mail. Ricochet will exit without processing if the 'received' headers are missing. 2.1 Command Line Parameters. Command line parameters are evaluated as binary flags by ricochet. Flags can be switched 'on' by specifying -FLAG on the command line, and switched 'off' by -FLAG=0. -DEBUG Prints tracing results on STDOUT. Default is Off. -BACKGROUND Forks ricochet and returns immediately. Mutually exclusive to -INTERACTIVE. The debug information is written to $HOME/.ricochet/logs if -DEBUG is 'on'. Default is Off. -INTERACTIVE Prompts the user to add/remove entries from the list of hosts to query and list of addresses to complain to. Mutually exclusive to -BACKGROUND. Default is Off. -DONT_SEND Useful for testing ricochet with a particular spam. Doesn't send complain, prints on STDOUT instead. Default is Off. -GUESS Force to generate 'abuse' and 'postmaster' addresses for domains that fail Whois Lookups. Default is On. -AC Force ricochet to consult the Abuse Contacts File (see Section 2.3) for contact addresses. Default is On. -ABUSENET From version 0.90 onwards ricochet can lookup the Abuse.net contact database if this option is enabled. Default is On. -NOSEC Ricochet won't do second level of whois lookups on nameserver domains if this option is set. Default is off. -FROM_HEADERS Ricochet will BCC to addresses found in "From" and "Reply-To" headers of the spam when this option is present. Default is off. 2.2 Config File. Ricochet's behaviour can be configured through the "ricochetrc" config file located in the Ricochet helper directory (see Section 1.4). An entry in ricochetrc comprises of two parts, Field and Value separated by a ":". Besides the command line flags, ricochet can import following variable from "ricochetrc" -- FROM_EMAIL Your e-mail address. This will be used as the "From" field of out-going complaints. TEMPLATE Path of the Complaint Template. (see Section 2.5). Default is $HOME/.ricochet/complaint-template. LOG Path of the Log File. (see Section 2.1 - BACKGROUND). Default is $HOME/.ricochet/logs. ABUSECONTACTS Path of the Abuse Contacts File. (see Section 2.3). Default is $HOME/.ricochet/abuse-contacts. SKIPLIST Path of the Skip List. (see Section 2.4). Default is $HOME/.ricochet/skip-list. SENDMAIL Path of the MTA binary with flags for parsing a RFC822 message piped to it. Default is /sbin/sendmail -t. WHOIS_CACHE Cache directory for Whois records. 2.3 Abuse Contacts File. The Abuse Contacts file, by default $HOME/.ricochet/abuse-contacts contains host/domain names and associated abuse contact's email address, one per line. An entry looks like "zoom.com: kristen@zoom.com". Everything on a line, preceding a "#" is ignored. Alternate name and location of the file can be specified in ricochetrc (see Section 2.2). 2.31 Abuse.net Database. If a reporting address in not found in the local Abuse Contacts list, ricochet looks up the online database of abuse contact addresses at http://www.abuse.net/lookup.phtml. 2.4 Skip List. Ricochet will not complain to hosts, domains and email addresses listed in this file. You would want to put the name of your ISP's machine here, since a lot of spam is relayed directly from the originating machine to your ISP. The skip-list feature is provided to strike a balance between correct and excessive reporting and should be used generously. The default location of skip-list is $HOME/.ricochet/skip-list and can be changed in the ricochetrc (see Section 2.2). 2.5 Complaint Template. Ricochet uses an RFC822 template to 'build' a complaint message. It contains text as well as embedded perl code which is eval()-ed and replaced with it's return value every time a complaint is sent. This is used for 'filling in' the variable parts (like 'To' headers) of the template. Ricochet exports a verbatim copy of the Spam::Ricochet object when eval()-ing this code, therefore it's possible to access instance data and methods of the object from within this template. Default location is $HOME/.ricochet/complaint-template and can be changed in the ricochetrc (see Section 2.2). 2.6 How Are Forged Headers Handled? Spammers often insert anything ranging from complete junk to carefully crafted header messages in order to mislead tracing attempts. These headers are often refered to as Fake or Forged headers and this section describes how Ricochet deals with them. The SMTP protocol doesn't provide a method for describing route authentication in mail headers. A receiving SMTP server/agent, therefore, cannot assume with certainity that any machine listed in the route actually participated in mail's relay; the only network identity it can authenticate is that of the immediate sender machine. In other words, it is impossible, due to lack of authentication data in the mail, to evaluate "truthness" of all "Received" headers; A sufficiently well forged header cannot be told apart from a real header without consulting the mail logs on the alleged machines. When ricochet is looking for fake headers it's really computing syntatic and semantic correctness of headers and the information encoded in them. The headers that don't confirm with RFC822 are assumed fake and discarded. Syntatically correct headers go through a phase of semantic verification, which ensures that the machines listed in the header actually exist and provide mail transport services. Headers that pass the second phase are assumed "real" and processed further. If a real header turns out to be fake, the contacts of the faked relays are informed of the spam. The contacts generally want to know if they are being abused in this manner and are very likely help you get to the real origins. Some recent communication with network admins at friends.net & plain.com about a spam that originated from psi.net illustrates this: X-Sender: netadmin@mail.friends.net Message-Id: References: <199908091140.RAA03109@fountainhead.vipul.net> Date: Mon, 9 Aug 1999 12:40:23 -0700 To: hackworth@vipul.net From: Chris Barrus Subject: Re: Reporting Spam/UBE/UCE from your site. [Maxmize & Enhance Your WWW ROI Now . . .] At 5:10 PM +0530 on 8/9/99 you wrote: >The spammer below is either using your resources to send out bulk >unsolicited commercial email ("spam") or is deceptively trying to >make it look like he is. In either case, a legitimate firm like >yours probably would not approve. The information below should be >all you need. My apologies for the spam. I've already fired off appropriate threats to all involved. The spam actually originated at a psi.net address using a forged address here. I'll append the relevant parts of my email to them below. Cheers, Chris Barrus friends.net NetAdmin ---CLIP--- FLASH.NET: The attached UCE (spam) was apparently relayed through your system (stargazer.flash.net [209.30.0.107]) or originated from one of your downstream customers. Please take action to prevent further acts of net abuse. PSI.NET: The attached UCE (spam) - along with a second copy I received sent to a different email address - apparently originated from a dialup on your system (ip144.lansing2.mi.pub-ip.psi.net [38.27.94.144]). Please investigate and take action to prevent this dialup user from using your system to commit further acts of net abuse ("action"=blam!blam!blam!blam!blam!bleed!bleed!bleed!bleed!bleed!). SPRINTLINK.NET: The attached UCE (spam) advertises a URL on your system (http://208.12.66.208/henry.html) . Please take action to prevent this customer from using your system to commit or benefit from further acts of net abuse. Please note that continuing to host this customer's web site may result in your system being place on one or more "blacklists". For more information, please see the MAPS RBL web page at http://maps.vix.com/rbl/candidacy.html. Message-Id: References: <199908091140.RAA03109@fountainhead.vipul.net> Date: Mon, 9 Aug 1999 13:13:58 -0700 To: hackworth@vipul.net From: Neil Ticktin Subject: Re: Reporting Spam/UBE/UCE from your site. [Maxmize & Enhance Your WWW ROI Now . . .] Hackworth, Yep -- they are spoofing us and pissing us off. We're on them already, but thanks for the heads up. It's a wonderful Monday, :) Neil -------------------------------------- INVOKING RICOCHET FROM OTHER APPS = SECTION 3 ========================= 3.0 Binding Ricochet To A Key In "Mutt". Add this line to your .muttrc to bind piping the mail to ricochet (while being in the index) to the key "S": macro index S "|/usr/local/bin/ricochet -BACKGROUND -DEBUG\n" ------------------------------------------------ CREDITS, FEEDBACK, ETC. = SECTION 4 =============== 4.0 Author And Contributors. Ricochet is written by Vipul Ved Prakash . Andrew Pam , Ralf Hildebrandt and others (see the CHANGES file) have helped with patches and bug- reports. 4.1 Software License. Ricochet is copyright Vipul Ved Prakash. It is distributed under the Artistic License (see the ARTISTIC file). 4.2 Feedback. Please include the -DEBUG log with bug-reports. All mail regarding ricochet should be sent to ricochet@vipul.net. 4.3 Ricochet Developers' Mailing List. This is a list of ricochet development and beta-testing. To join send a "subscribe me" request to ricochet@vipul.net. 4.4 Ricochet Announcement List. To receive ricochet announcements, add your e-mail address to the announce list at http://vipul.net/ricochet/download.html