DSPAM STREAMLINED BLACKHOLE LIST SERVER v1.0
Copyright (c) 2004 Network Dweebs Corporation
http://www.nuclearelephant.com/projects/sbl/

LICENSE

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

TABLE OF CONTENTS

General Server Information

  1.0 About SBL Server
  1.1 Installation
  1.2 Running the Server
  1.3 Zone Files

1.0 ABOUT SBL SERVER

The DSPAM SBL Server is an open-source, freely available streamlined blackhole
list server.  The DSPAM SBL is also the first such type blacklisting service,
so a definition of an SBL is necessary. A streamlined blackhole list is a 
blacklisting service whereby reporting networks can provide information about 
malicious ip addresses using an automated, machine-based approach where the
actual blacklisting is based on network spread rather than number of complaints.

In the case of the DSPAM SBL, the machine automation is performed by any 
statistical filter capable of dynamically identifying spam, its source network 
address, and using the SBL.  This doesn't mean, however, that the SBL server 
should be limited to tracking only spammers.  The DSPAM SBL can easily be 
adapted to track any kind of network-based phenomenon over a large spread or 
even redesigned to track viruses.

The advantages to using a streamlined blackhole list include:

- The ability to take advantage of your existing statistical filters and
  actually conserve resources on your network.

- Help facilitate change by rejecting hosts that are sending spam

- The short-term blacklisting approach (24 hours) is designed specifically
  around the dynamic nature of spammers, and as a result provides a way to
  blacklist new hosts within minutes, and not need worry about poorly
  maintained lists or delisting of obsolete networks.

- Information on a per-host basis, allowing precision blacklisting.

1.1 INSTALLATION

To install the SBL server, run:

./configure && make && make install

You will then want to copy the sample server configuration (sbl_server.conf) 
to a secure location on your system.  

1.2 RUNNING THE SERVER

To run the server, edit the server configuration to meet your needs.  While
read-only clients may connect arbitrarily, read-write clients will require
an account on the system.  You can create an account by using the USER
token as shown in the configuration.  Each account must have a unique user
id.

  AUTHENTICATION
  Authentication is performed using challenge-response and shared secrets.
  Both the client and server must share the same shared secret for that
  particular uid.  When the client attempts to authenticate, it will send its
  uid.  The server will then send back a random 16-byte string of characters.
  The client will then create a checksum based on this string and the shared
  secret and submit the checksum ot the server.  If the checksums match on
  both sides, the user is authenticated.

1.3 ZONE FILES

The SBL server can write zone files of blacklisted addresses which your name
server can then use to serve DNS requests for. This requires the setting of 
two configuration parameters:

ZoneTemplate  /var/named/sbl.mydomain.com.template
ZoneOutput    /var/named/sbl.mydomain.com

The file sbl.mydomain.com.template is the input used and should contain a
basic SOA header. You may also want to add a record for 127.0.0.2, as this
is used by most blacklist users to test the blacklist. You may substitute
the serial number for @serial@, which will be replaced with a timestamp when
the zone file is written. The output, ZONE_OUTPUT, should point to the 
desired destination for the zone file. You'll need to HUP your name server
every now and then to ensure that the zone is being re-read. The zone file
is written every cleanup cycle.

BUGS AND FEEDBACK

The SBL Server is still in its infancy, and this version is purely a 
development release.  Please report any bugs, constructive feedback, and code
to jonathan@nuclearelephant.com.

TODO

Implement Distributed Architecture

