$Id: README,v 1.32 2002/03/25 22:35:09 bw Exp $

fwlogwatch is a security tool written in C by Boris Wesslowski for
RUS-CERT. It is a packet filter/firewall log analyzer with support for a
lot of log formats and analysis options. It also features incident report
and realtime response capabilities, a web interface and internationalization.

It is available from the RUS-CERT website
http://cert.uni-stuttgart.de/projects/fwlogwatch/
and from
http://www.kyb.uni-stuttgart.de/boris/software.shtml

The inter-release changes in the source can be reviewed with
cvsweb at SourceForge: http://sourceforge.net/projects/fwlogwatch/


FEATURES
- General Features:
  - Can detect and process log entries in the following formats:
    Linux ipchains, Linux netfilter/iptables,
    Solaris/BSD/Irix/HP-UX ipfilter, Cisco IOS, Cisco PIX and
    Windows XP firewall.
  - Entries can be parsed in combined log files, the parsers to be used
    can be selected.
  - Gzip-compressed logs are supported.
  - Can separate recent from old entries and detects timewarps in log files.
  - Can recognize 'last message repeated' entries concerning the firewall.
  - Integrated resolver for protocols, services and host names.
  - Can do lookups in the whois database.
  - Own DNS and whois information cache for faster lookups.
  - Hosts, ports, chains and branches (targets) can be selected or
    excluded as needed.
  - Support for internationalization (available in English, German,
    Portuguese, simplified and traditional Chinese and Swedish).

- Log summary mode:
  - A lot of options to find and display relevant patterns in connection
    attempts.
  - Intelligent selection of certain fields (e.g. the host name column is
    omitted and the host mentioned in the header of the summary if the
    log is from a single host, the same happens with the chains, targets
    and interfaces).
  - Plain text and HTML (with CSS) output with many sort options.

- Interactive report mode:
  - The integrated report generator fills and presents a
    report that can be sent to abuse contacts of attacking sites or
    computer emergency response teams (CERTs).
  - Supports templates and incident number generation.
  - All fields can be adjusted as needed interactively.

- Realtime response mode:
  - The program detaches and stays in the background as a daemon.
  - Detection of the necessary ipchains rules with logging turned on can be
    configured.
  - Response can be a notification (in form of a log file entry, an email,
    a remote winpopup message or whatever you can put into a shell script),
    or a customizable firewall modification.
  - The included response script adds a new chain for fwlogwatch to
    ipchains or netfilter setups and attackers are blocked with
    new firewall rules.
  - Supports trusted hosts (anti-spoofing).
  - The current status of the program can be followed through a web
    interface.

The commented configuration file supports and explains all options and will
get you started quickly. Please read the man page for details on the
command line options.


PARSER NOTES
  Cisco PIX support focuses on denied packets and ignores all other kinds
  of PIX log entries. PIX OS version 6 is not supported yet.
  The ipfilter parser does not support logs with resolved service names
  and tcp/udp entries without ports.


INSTALLATION
- General
  The Makefile assumes you use Linux, to compile on Solaris, OpenBSD,
  FreeBSD or IRIX look for the corresponding lines at the top of the
  Makefile. You may want to have a look at main.h if you want to change
  some default values.

  You will need the zlib compression library (version 1.0.9 or newer) and
  it's header files to compile fwlogwatch.

  A simple 'make' should be enough to obtain a working binary. If you use
  the realtime response mode you will need to install fwlogwatch with
  superuser permissions for certain configurations. If all you need is read
  access to the system's standard log file (e.g. /var/log/messages) you can
  use group permissions. You can also bind a nonprivileged port for the
  status server. 'make install' will install the binary (in
  /usr/local/sbin) and the man page, 'make install-config' will also
  install a sample configuration file and template in /etc.

  You can define the TMPDIR environment variable if you don't want
  fwlogwatch to create it's temporary files (only needed in report mode)
  in /tmp.

- Linux
  For ipchains you will need at least kernel 2.2.10 (which you should have
  updated for security reasons anyway), kernel versions before 2.2.10 don't
  log enough.

- FreeBSD/OpenBSD
  Because of the internationalization support you will need to have the
  gettext package (sometimes with it's surroundings libtool, GNU m4,
  autoconf and automake) installed to compile fwlogwatch.


BASICS (with examples for ipchains)
- Create a packet filter with ACCEPT rules for all connections you need, as
  tight as possible.

- Your default policies should be DENY:

    ipchains -P input DENY
    ipchains -P forward DENY

  although with ipchains they won't be needed since all prohibited traffic
  will be intercepted by the following logging rules:

    ipchains -A input -l -j DENY
    ipchains -A forward -l -j DENY

  so the last line in your input, forward and custom chains should be

    target     prot opt     source                destination           ports
    DENY       all  ----l-  anywhere              anywhere              n/a

- You can also specify rules for the output chain but you should use the
  target REJECT (you/your users will notice faster what the problem is when
  trying something the policy forbids).

- If you have a persistent log spammer drop his packets by inserting a DENY
  rule before the logging rule above (or use the block response mode).


CONFIGURATION AND EXAMPLES
- You should make a configuration file for each function you want, look at
  the included sample file, it should be easy to adapt to your needs.

- Example (the options are in the order they are mentioned in the text):
  If you want very verbose generation of a HTML summary in the file
  'log.html' of all packet filter entries at most one day old representing
  at least two connection attempts logged to the file 'messages' with
  output including start and end timestamps, time intervals, resolved IP
  addresses and service names and with connections separated by protocol,
  source and destination ports and TCP options you would use the command

  fwlogwatch -v -v -w -o log.html -l 1d -m 2 -f messages -t -e -z -n -N -p -s -d -y

- If you want to use fwlogwatch as a CGI, e.g. to have a quick look at
  what happened in the last hour when you get a notification:
  Copy the file fwlogsummary_small.cgi to a place where your web server
  can execute it (fwlogwatch must be reachable and have enough
  permissions to read the log file).

- A script for generation of 8 general summaries (fwlogsummary.cgi) is also
  included. You can use it as above or if you comment a few lines also on
  the command line or from cron. It will use the output directory
  /var/www/html/fwlogwatch as default. Look at the index.html file to
  select the level of detail you want.

- An sample init file (for Red Hat Linux systems) for starting fwlogwatch
  in realtime response mode at system start is also included.

- You might want to replace your /etc/services file by the one supplied
  with nmap (http://www.insecure.org/nmap/), a lot more services will be
  recognized, you can also add the ICMP types (don't assign one to type 0
  since it is the ipchains default). The same applies to /etc/protocols,
  you can use RFC 1700 (Assigned Numbers) to extend your version.


FEEDBACK
  If you find a bug or have an idea for a new feature please send an email
  to Wesslowski@CERT.Uni-Stuttgart.DE
  If you want to report a parser problem please specify which log format you
  are trying to parse, the version of the log generator and fwlogwatch you
  are using and provide a sample incuding log lines for which parsing fails.
