README file for the attackwatch package
---------------------------------------

1. Document status and licensing

This document was last updated on April, 21st 2001.

Copyright 2001 Andreas Beck <becka@bedatec.de> All rights reserved. 

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.  

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED `AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS, OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.


So basically you are free to do whatever you wish with this software.
However you are kindly requested to send me patches if you have enhancements
so that I can incorporate them into the package (note, that sending patches
implies that you consent to redistribute them under the above licensing
terms.)


2. Purpose of attackwatch

attackwatch is intended for enhancing the security of small private networks
that are already protected by a restrictively configured firewall but which
still have a few ports open.

attackwatch will analyze the firewall-output in near-realtime and will run
scripts in response to incoming packets that got logged.

It is similar to portsentry in functionality, though it uses a different
method of detecting incoming attacks that doesn't require extra open ports
that portsentry listens to in the firewall.

Note that attackwatch is intended for people that really really know what
they are doing. If you don't know how the IP protocol and all the various
application protocols work, keep your hands off configuring firewalls and
their helper utilities. Go ask someone who knows what he's doing. A badly
configured firewall is worse than none, as it gives you a false feeling of
security.


3. How to use attackwatch

attackwatch is intended to realtime-block hosts that are portscanning you.
Thus it prevents them from filling up your logfiles and it might hinder
them discovering a real security hole you have missed.

As attackwatch works by analyzing kernel output from the firewalling
subsystem, the first thing you have to do is to set up a tight firewall
with a few extra hooks for attackwatch. If you don't know how to do that,
learn it, try it out, then learn ist again, retry and then come back.

When setting up the firewall, create an extra chain called "block" like this:
ipchains -N block

Put that chain as an intermediate target into the input chain like this:
ipchains -A input -j block

You should make sure to place it in a way that suits your purpose. I have
placed it _after_ a few local rules that will ACCEPT some local traffic that
should never be inhibited, even if someone manages to coax attackwatch into
trying to block it, but _before_ all rules that will ACCEPT or DENY external
traffic.

This allows attackwatch to place DENY rules in the "block" chain and thus
completely lock out individual hosts before they even get considered for
being allowed for a service.

Now I said that attackwatch works on the Packet log output from the kernel.
Thus you have to add a line to make sure that packets you do not like get
logged. I personally do this by first allowing everything I want to allow
and then DENY or REJECT a few selected things that I do not even wish to 
have logged (pings e.g.) and then I place a global logging rule like:
ipchains -A input   -l
at the end of the input chain and let the default policy do the rest:
ipchains -P input DENY

Note, that it is a policy decision if you use REJECT or DENY, but whatever
you use, you should use it throughout your setup. DENY has the advantage
that it delays portscans, as the remote side will not get any notification
that you have discarded their packet. REJECT is more polite, as you tell
people that you don't want them to connect, but as it causes an ICMP-
message saying so, it allows them to portscan faster, as they get an answer
and don't have to time out.

The next step is to make sure that attackwatch can see the output from the
firewall setup. The simplest way is to configure attackwatch to read
/var/log/messages. However for efficiency reasons I usually add 

kern.=info		/var/log/packetlog

to /etc/syslogd.conf which will still direct a lot of extra stuff there, but
far less than there is in /var/log/messages.

When you have that running and you have tested that you can still use all
services you want to and that services you want to get blocked get blocked
and that services you want to cause attackwatch to act on get logged you can
start thinking about attackwatch.

Step 1: Look at the source and understand what it does. You will be running
it as root ... If you are the kind of person that installs foreign code that
claims to protect your network without verifying what it does, you have a
security problem that is much bigger than that attackwatch is supposed to
address.

Step 2: Configure it. If you did Step 1, you will know what to enter into
config.h. Note that due to my lazyness you should not change the formatting
of this file, as it is used to autogenerate config.inc which is used for the
make install step later.

Step 3: Compile it. Simply running "make" should do.

Step 4: Install it. su -c "make install" (you didn't compile as root, did
you ?)

Step 5: Customize the behaviour of the blocking scripts.

attackwatch will run 4 different scripts under various circumstances:

$HANDLERDIR/block will be run whenever attackwatch detects more than
MAX_PROBES consecutive log entries from the same host. Like all the
scripts it gets a single argument - the IP of the offending host.

Please note, that this script might get executed multiple times. attackwatch
tries to avoid this, but it may happen (if you get scanned rather rapidly -
look at the code if you think you need to understand why and when this can 
happen). So please write the script like this:

$IPCHAINS -nL block | grep -q "$1" || {
        $IPCHAINS -A block -s "$1" -j DENY
	# whatever else you want
}

Again: If you don't understand what I mean here, attackwatch is not for you.

Make sure that such a block does _NOT_ cause log entries ... attackwatch is
not prepared to handle that situation and it will cause a very
counterproductive effect unless you hacked the source appropriately.

$HANDLERDIR/unblock will get called whenever a log entry from the block
chain itself is received. This is used to unblock a host if you are afraid
that someone might have attacked your server from a dialup port that you
might be using yourself at a later time.

Simply add a rule like this
ipchains -A block -p tcp --destination-port $MAGICPORT -l
to the top of your block chain.

If you don't there is no possibility to trigger the unblock function. This
gives a little more security at the expense of possibly locking yourself out
in the above situation.

If you don't know how the above rule gives you a way to unlock your IP you
might want to reconsider your choice of using attackwatch.

$HANDLERDIR/attack_new is called whenever a source-IP is seen first in the
logs. Further consecutive attempts from the same IP will run
$HANDLERDIR/attack_cont instead.

Note, that attackwatch is easily fooled by a skilled attacker that can
attack from multiple IPs and that coordinates this attack. However this is a
rare scenario, and someone that skilled might as well get through with a
blind attack on the first hit.

Step 6: Running attackwatch.

Attackwatch can run either as foreground program (which is useful for
debugging purposes) and as a daemon: Usually you will want to run
attackwatch with the "-D" flag - the only flag attackwatch understands.

Either give attackwatch its own init.d-script started after the firewall is
up or simply add it at the end of setting up the firewall.

Step 7: Maintaining it.

You may want to check the attackwatch log from time to time, add it to the
logrotate system, set up some way to flush your blocklist from time to time
or when it gets to crowded ...

Step 8: Help improving it.

Send me useful scripts, documentation enhancements, bug reports and yet
better bug fixes, ...


4. Some advice on what to do in the scripts.

block: Block them. Nothing more. Do _not_ counterattack, do not DOS.
Blocking will turn them away - it is not interesting to try to open a box
that seems dead (DENY) or totally locked up (REJECT). However it _is_ 
interesting to show someone who is the better hacker. Don't challenge them. 
Someone out there is better than you and many out there are better than 
an automated tool.

unblock: If you use that feature, make sure you know its implications. Place
the magic port away from important services you want to be protected. A
full range portscan will inevitably touch the magic port. Make sure you don't
compromise the magic port by giving it another rule (REJECT vs. DENY).

attack_new: If you want to know what is going on, you may want to broadcast
a sound there (this is what I do here) and you might want to investigate a
little who is knocking. I do an nslookup here so that I can complain to the
right provider later. However I strongly advise against connecting to the
remote system for such purposes (like using ident). See the section about
block on the reasoning behind that.

attack_cont: I wouldn't do anything there - it's just for completeness.If
you like it noisy, you may want to play a sound.


5. Other traps, pitfalls and weaknesses

Attackwatch is susceptible to spoofed source IP adresses. It relies on the 
kernel log entry. This may be used to cut you off servers you yourself
rely on, like your DNS or Mail servers.

You can guard yourself a little agains these forms of attack by either
making sure that such hosts do not cause log entries at all (by placing
appropriate rules in your firewall configuration) or by modifying the
"block" script to detect these adresses and handle them differently - 
i.e. you may want to keep a "neverblockthese" list and first match the
IP you got against them..

You may want to ignore them (causing overhead as block will get called
repeatedly, then) or you may want to add an explicit ruleset for them that
will silently block further fakes, but still accepts the expected traffic
like DNS or pop-3 or whatever.

If you see fake packets however, this means that someone has not done his
homework. Everyone should have in-/egress Filters nowadays. If you can track
the source of such fake packets, you might want to do the world a favour and
contact the appropriate administrator and ask him to secure his net
properly.


Attackwatch may be abused by attackers that can spoof their IP to slow down
your IP stack. As you will add rules to the block chain and the kernel has
to walk through it for _every_ IP packet it receives, it will take longer
and loger for the kernel to process ip packets.

There are several possible methods to counteract this:

a) if you have a low hitrate, you will want to just manually flush the block
chain from time to time.
b) at higher hitrates you might want to do that with a cronjob.
c) Another possibility is to limit the number of entries in the blocking
chain. A way to do this is to add something along the lines of

NUMENTRIES=$($IPCHAINS -nL block | wc -l)

# note that this gives the real number of entries+2 (or +3 if an unblocking
# rule is in effect)

if [ $NUMENTRIES -gt 500 ] ; then 
	ipchains -D block 1	# use 2 here if you have an unblocking rule
				# at position 1 !
fi

in the block script. This will make sure to delete an entry for every new
one above the limit and will construct a LRU.
