                                                  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: <v0421010fb3d4df16d86f@[131.161.38.117]>
    References: <199908091140.RAA03109@fountainhead.vipul.net>
    Date: Mon, 9 Aug 1999 12:40:23 -0700
    To: hackworth@vipul.net
    From: Chris Barrus <netadmin@friends.net>
    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: <v04210108b3d4e6e12b85@[131.161.38.126]>
    References: <199908091140.RAA03109@fountainhead.vipul.net>
    Date: Mon, 9 Aug 1999 13:13:58 -0700
    To: hackworth@vipul.net
    From: Neil Ticktin <ceo@xplain.com>
    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 <mail@vipul.net>. Andrew  Pam
    <xanni@glasswings.com.au>, Ralf  Hildebrandt  <r.hildebrandt@tu-bs.de>
    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


