$Id: README,v 1.28 2001/12/02 14:22:42 bw Exp $ fwlogwatch is a security tool written in C by Boris Wesslowski for the RUS-CERT. It is a packet filter/firewall log analyzer with support for linux ipchains, netfilter/iptables, cisco IOS, cisco PIX and ipfilter log files. It also features incident report and realtime response capabilities. 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 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 and Cisco PIX. - 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. - Ports and hosts can be selected or excluded as needed. - Support for internationalization (available in english, german, portuguese and chinese). - 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 output with 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 and coordination centers (CERT/CC). - 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. - The ipchains parser can detect if the necessary ipchains rules with logging turned on exist. - 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 completely 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. IPCHAINS, NETFILTER/IPTABLES, IPFILTER AND IOS/PIX SUPPORT fwlogwatch features ipchains, iptables/netfilter, ipfilter and IOS/PIX log file support, it can even read the combined logs on a log host. You can separate the formats if you activate or deactivate the corresponding parsers. Some restrictions apply because not all fields exist or make sense in all log file types. The included script for realtime response mode supports ipchains and netfilter. The check if correct ipchains rules exist can be activated in the configuration file. Cisco PIX support is restricted to versions before 6 of PIX OS and only focuses on denied packets and ignores all other kinds of PIX log entries. INSTALLATION - General Before compiling you may want to have a look at main.h if you want to change some default values. The default configuration assumes Linux, to compile on Solaris, OpenBSD, FreeBSD or IRIX look for the corresponding lines at the top of the Makefile. You might want to enable short names to save memory if you only parse ipchains logs. 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 it to your needs. - If you want a HTML summary '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 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 fwlogwatch -v -v -s -d -t -e -z -y -n -N -p -w -l 1d -m 2 -o log.html -f messages - 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 redhat 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 Boris.Wesslowski@RUS.Uni-Stuttgart.DE