sessionlimit v. 0.2
                     Wed Aug  7 22:12:26 GMT 2002

       Copyright (c) 2002 Klaus Steding-Jessen <jessen@nic.br>
                and Cristine Hoepers <cristine@nic.br>


1. License Information

   sessionlimit is free software.  Please refer to the source code for
   detailed information.

2. What's sessionlimit?

   Basically sessionlimit is a tool designed to interact with OpenBSD
   pf in order to contain the intruders activities after a compromise
   of a honeypot.  It can detect when a scan or DoS is initiated from
   a honeypot -- once the activity is detected a rule is inserted in
   pf to block the outgoing traffic.  This rule is removed after some
   time.

   It is important to note that the original intruder's incoming
   session is not affected by the new rule.  This means that the
   intruder can still interact with the honeupot, but any new outgoing
   connection he tries to intiate will be blocked.

3. Supported Systems

   sessionlimit is a C program and should compile without warnings on
   OpenBSD 3.1.

4. Compiling

   To compile sessionlimit just type make at the shell prompt.

5. Usage

   Once sessionlimit is properly compiled on your system and pf is
   running with your rules, you can invoke it as follows:

   # sessionlimit -H homenet -i ifname

   where `homenet' is your honeynet network range and `ifname' is your
   firewall external network interface.

   The current sessionlimit implementation is limited to deal with a
   class C network only.

   Example:

   # sessionlimit -H 192.0.2.0 -i fxp0

   Important: The pf's rules *must* be configured to create states for
   outgoing connections -- this is required by sessionlimit.

6. Suggested pf Configuration

   We have tested sessionlimit on a machine running OpenBSD 3.1 in
   bridge mode with pf configured to log all incoming and outgoing
   traffic.

   The pf rules in this machine were configured to:

   1. log all incoming and outgoing traffic (header + payload, using
      pflogd -s 1500);

   2. pass all incoming traffic;

   3. normalize all outgoing traffic (scrub);

   4. block all outgoing spoofed traffic;

   5. pass all outgoing traffic (with keep state).  [*REQUIRED*]

   This machine also limits bandwidth using tbrconfig(8), which is
   recomended.

7. How sessionlmit works?

   The sessionlimit program works by monitoring the state table for
   the outgoing sessions.  It blocks source IPs according to one of
   the following criterias:

   1. when the number of states associated with a source IP is
      increasing too fast;

   2. when the source IP has reached a predefined limit of outgoing
      connections.  The default is 20 connections.

   3. when the number of bytes associated with an ICMP state has
      reached a predefined limit.  The default is 65k.  This was
      developed to block stupid DoS attacks, like ping -f victim;

   If any of the above conditions is true sessionlimit inserts a new
   rule at the top of the active ruleset, blocking all traffic from
   the offending IP to the outside.  The offending outgoing traffic
   will be blocked, but it is important to note that the intruder's
   interactive session won't be affected, since he is using an
   incoming keep state rule.

   After some time (the default is 30 minutes), the rule will expire and
   will be removed from the active ruleset.

8. Logging Capabilities

   The program logs to syslog (default facility is local0), as shown
   below:

   Aug  1 05:04:29 fw sessionlimit[29832]: blocking 192.0.2.15 (2 states)
   Aug  1 05:04:29 fw sessionlimit[29832]: 8 state(s) killed from 192.0.2.15
   Aug  1 05:34:29 fw sessionlimit[29832]: expiring 192.0.2.15 after 1800 seconds

9. Limitations

   sessionlimit is an experimental code.  At this time it has some
   limitations:

   1. works only with OpenBSD 3.1;

   2. inserts only OUT rules;

   3. deals only with class C (/24) networks;

   4. uses a lot of CPU;

10. Reports and questions

   Please send comments, questions and bug reports to
   jessen@nic.br and cristine@nic.br.

11. Acknowledgments

   The authors would like to thank the Honeynet.BR Team for their
   ideas and help testing this tool.

### README ends here.