FWLOGWATCH(8)

NAME
fwlogwatch - a firewall log analyzer, report generator and realtime response agent

SYNOPSIS
fwlogwatch [options]

DESCRIPTION
fwlogwatch produces ipchains, netfilter/iptables, cisco IOS, cisco PIX and ipfilter log summary reports in text and HTML form and has a lot of options to find and display relevant patterns in packet logs. With the data found it can produce customizable incident reports from a template and send them to abuse contacts at offending sites or CERT coordination centers. Finally, it can also run as daemon and report anomalies or start countermeasures.

OPTIONS
The global options for all modes (at least where they make sense) are:

-c config
    Use the alternate configuration file config. If you use the default configuration file /usr/local/etc/fwlogwatch.config command line parameters override the options specified in the file. If you specify an alternate configuration file only options not specified in the file can be overridden by command line options.

-D  Do not differentiate destination IP addresses. Useful for finding scans in whole subnets.

-d  Differentiate destination ports.

-e  Show timestamp of last packet logged. End times are only available if there is more than one packet log entry with unique characteristics.

-f file
    Specify an input file (defaults to /var/log/messages ). Relevant entries are automatically detected so combined log files (e.g. from a log host) are no problem. Compressed files are supported (except in realtime response mode). The '-' sign may be used for reading from standard input (stdin). In realtime response mode the file needs to be specified with full path since the daemon is rooted in /.

-h  Show the available options.

-L file
    Show time of the first and the last log entry in the input file which can be a compressed or plain log file. Summary mode will show the time of the first and last packet log entry, this log times mode will show the time of the first and last entry overall.

-l time
    Process recent events only. See TIME FORMAT below for the time options.

-N  Enable service lookups. Port numbers will be resolved from /usr/local/etc/services.

-n  Enable DNS lookups. Host names will be resolved (reverse and forward lookup with a warning if they don't match). This makes summary generation very slow if a lot of different hosts appear in the log file. Resolved host names are cached.

-P format
    Only use certain parsers, where the log format can be one or a combination of: i ipchains, n netfilter, c cisco IOS, p cisco PIX and f ipfilter.

-p  Differentiate protocols. This is activated automatically if you differentiate source and/or destination ports.

-S  Do not differentiate source IP addresses.

-s  Differentiate source ports.

-t  Show timestamp of first packet logged.

-V  Show version and copyright information.

-v  Be verbose. You can specify it twice for more information. In very verbose mode while parsing the log file you will see "." for relevant packet filter log entries, "r" for 'last message repeated' entries concerning packet filter logs, "o" for packet filter log entries that are too old and "_" for entries that are not packet filter logs.

-y  Differentiate TCP options. All packets with a SYN are listed separately, other TCP flags are shown in full format if they are available (ipchains does not log them, netfilter and ipfilter do, cisco IOS doesn't even log SYNs).

-z  Show time interval between start and end time of packet log entries. This is only available if there is more than one packet log entry with unique characteristics.

LOG SUMMARY MODE
This are additional options that are only available in log summary mode:

-b  Show the amount of data in bytes this entry represents, this is the sum of total packet lengths of packets matching this rule (obviously only available for log formats that contain this information).

-m count
    When analyzing large log files you usually aren't interested in entries that have a small count. You can hide entries below a certain threshold with this option.

-o file
    Specify an output file.

-O order
    This is the sort order of the summary. Since entries often are equal in certain fields you can sort by several fields one after another (the sort algorithm is stable, so equal entries will remain sorted in the order they were sorted before). The sort string can be composed of up to 11 fields of the form ab where a is the sort criteria: c count, t start time, e end time, z duration, n target name, p protocol, b byte count (sum of total packet lengths), S source host, s source port, D destination host and d destination port. b is the direction: a ascending and d descending. Sorting is done in the order specified, so the last option is the primary criteria. The default is tacd (start with the highest count, if two counts match list the one earlier in time first) of which ta is built in, so if you specify an empty sort string or everything else is equal entries will be sorted ascending by time.

-w  Produce output in HTML format.

-W  Look up information about the source addresses in the whois database. This is slow, please don't stress the registry with too many queries.

INTERACTIVE REPORT MODE

-i count
    Enter interactive report mode. count is the minimum number of log entries you want to start reporting at. A summary of the corresponding entries will be shown and a report generated for each one. The more of the options above you use the more fields of the report will be filled in.

-F email
    This is the address the email containing the report will be sent from.

-T email
    This is the email address of the abuse contact or CERT the report will be sent to.

-C email
    These email recipients will get a carbon copy of the report (e.g. for your archives).

-I file
    Template file for report (defaults to /usr/local/etc/fwlogwatch.template ).

REALTIME RESPONSE MODE

-R  Enter realtime response mode. This means: detach, check if the firewall is configured correctly and run as daemon until the TERM signal (kill) is received. The HUP signal forces a reload of the input file (useful e.g. for log rotation). All output can be followed in the system log.

-a count
    Alert threshold. Notify or start countermeasures if this limit is reached. Defaults to 5.

-l time
    Forget events that happened this long ago (defaults to 1 day). See TIME FORMAT below for the time options.

-k IP/net
    This option defines a host or network in CIDR notation that will never be blocked or other actions taken against. To specify more than one, use the -k parameter again for each IP address or network you want to add.

-A  The notification script is invoked when the threshold is reached. A few examples of possible notifications are included in fwlw_notify, you can add your own ones as you see fit.

-B  The response script is invoked when the threshold is reached. This will usually block the attacking host completely with a new firewall rule. A new chain for fwlogwatch actions is inserted in the input chain and block rules added as needed. The chain and its content is removed if fwlogwatch is terminated normally. The default scripts contain actions for ipchains and netfilter, you can modify them or add others as you like.

-X  Activate the internal web server to monitor the current status of the program. Use the configuration file to change it's options. The default user name is admin and the default password is fwlogwat since DES can only encrypt 8 characters. By default it listens on port 888 and only allows connections from localhost.

TIME FORMAT
Time is specified as nx where n is a natural number and x is one of the following: s for seconds (default if you don't specify anything), m for minutes, h for hours, d for days, w for weeks, M for months and y for years.

FILES

/usr/local/etc/fwlogwatch.config
    Default configuration file.

/usr/local/etc/fwlogwatch.template
    Default template for incident reports.

/var/log/messages
    Default input log file.

/var/run/fwlogwatch.pid
    PID file generated by the daemon in realtime response mode.

FEATURES ONLY IN CONFIGURATION FILE
The following features are only available in the configuration file and not on the command line, they are presented and explained in the sample configuration file.

HTML colors
    The colors of the HTML output page can be customized.

realtime response options
    The host that can access the web interface, the port it listens on, the user and password and the pid file handling can be changed.

host and port selection and exclusion
    Hosts and ports to be summarized can be selected or excluded.

NETFILTER, IPFILTER AND CISCO SUPPORT
fwlogwatch also features iptables/netfilter, ipfilter and cisco IOS/PIX log file support, it can even combine or 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. Realtime response has predefined actions for ipchains and netfilter, you can add whatever you want done to the fwlw_respond script. You will need to deactivate the ipchains parser if you want to use realtime response mode on a system without ipchains.

SECURITY
Since fwlogwatch is a security tool and needs superuser permissions for certain tasks special care was taken to make it secure. You can run it with user permissions for most functions or you can make it setgid for a group /var/log/messages is in if all you need is to be able to read this file. Only the realtime response mode with activated ipchains parser needs superuser permissions to analyze the firewall rules. You might also need them for the response script and for binding the default status port.

AUTHOR
Boris Wesslowski <Boris.Wesslowski@RUS.Uni-Stuttgart.DE>, RUS-CERT http://cert.uni-stuttgart.de