FWLOGWATCH(8)

FWLOGWATCH(8) 💖

System Manager's Manual — aka the fwlogwatch page, part one of two, and bestie we have SO much to get through, buckle up 🎀

---

✨ NAME ✨

fwlogwatch — a firewall log analyzer and realtime response agent 🦋

---

✨ SYNOPSIS ✨

fwlogwatch [options] [input_files]

---

✨ DESCRIPTION ✨

okay so. fwlogwatch produces log summary reports in plain text AND HTML form, and it does it for a whole little friend group of log formats: Linux ipchains, Linux netfilter/iptables, Solaris/BSD/IRIX/HP-UX ipfilter, ipfw, Cisco IOS, Cisco PIX/ASA, NetScreen, Elsa Lancom router and Snort IDS. 💅

It has a lot of options to analyze and display relevant patterns. And it doesn't just sit there reading logs like a boring little guy — it can also run as a daemon (with a web interface, hello??) doing realtime log monitoring, reporting anomalies, and starting attack countermeasures. main character energy fr fr 👑

---

✨ GENERAL OPTIONS ✨

These ones are independent from the main modes of operation. They just vibe on their own.

• -h — Show the available options. your little menu of possibilities 🫶
• -L — Show time of the first and the last log entry. The input file(s) can be compressed or plain log file(s). 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. two different clocks bestie, don't get it twisted ⏰
• -V — Show version and copyright information and the options used to compile fwlogwatch. receipts 🧾

---

✨ GLOBAL OPTIONS ✨

The global options for all modes are:

• -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). if your log doesn't carry that info, it simply cannot give it to you 😭
• -c config — Use the alternate configuration file config instead of the default configuration file /etc/fwlogwatch/fwlogwatch.config (which does not need to exist). Only options not specified in the files can be overridden by command line options. so like, the file gets first dibs on the ones it sets 🌸
• -D — Do not differentiate destination IP addresses. Useful for finding scans in whole subnets. this is the "zoom out and see the whole pattern" button 🔍
• -d — Differentiate destination ports.
• -E format — Specific hosts, ports, chains and branches (targets) can be selected or excluded, selections and exclusions can be added and combined. The format is composed of one of the functions i include or e exclude, then one of the parameters h host, p port, c chain or b branch. In case of a host or port a third parameter for s source or d destination is needed. Finally, the object is directly appended, in case of a host this is an IP address (networks can be specified in CIDR format), port is a number and chain and branch are strings. To show entries with destination port 25 you would use -Eipd25 and to exclude entries which have the class C network 192.168.1.0 as source or belong to the chain INPUT: -Eehs192.168.1.0/24 -EecINPUT. okay this one is a whole little language, read it twice, it's giving ✨grammar✨
• -i file — If your logs contain private IP addresses that are not resolvable through DNS but you want reports with meaningful host names or you have any other reason to influence the host names in reports you can initialize the DNS cache with your own list of IP/name pairs. The file should be in the same format as /etc/hosts and will not be modified. it's read-only bestie, we are respectful 🙈
• -M number — If you only want to see a fixed maximum amount of entries (e.g. the "top 20") this option will trim the output for you. ✂️
• -m count — When analyzing large amounts of data you usually aren't interested in entries that have a small count. You can hide entries below a certain threshold with this option.
• -N — Enable service lookups. The service name for a specific port number and protocol will be looked up in /etc/services.
• -n — Enable DNS lookups. Host names will be resolved (reverse and forward lookup with a warning if they don't match). If this makes summary generation very slow (this happens when a lot of different hosts appear in the log file) you should use a version of fwlogwatch compiled with GNU adns support. Resolved host names are cached in memory for as long as fwlogwatch is running, the DNS cache can be initialized with the -i option. slow DNS is the villain of this story 💀
• -O order — This is the sort order of the summary and packet cache. 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 in summary mode 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. The realtime response mode default is cd ( ta is not built in). 🎀
• -P format — Only use certain parsers, where the log format can be one or a combination of: i ipchains, n netfilter, f ipfilter, b ipfw, c Cisco IOS, p Cisco PIX/ASA, e NetScreen, l Elsa Lancom and s Snort. The default is to use all parsers except the ones for NetScreen, Elsa Lancom and Snort logs. pick your fighters 💅
• -p — Differentiate protocols. This is activated automatically if you differentiate source and/or destination ports.
• -s — Differentiate source ports.
• -U title — Set title as title of the report and status page.
• -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. little secret codes, iykyk 🔤
• -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). rip Cisco IOS SYNs 😭

---

✨ LOG SUMMARY MODE ✨

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

• -C email — A carbon copy of the summary will be sent by email to this address. cc'd, bestie 💌
• -e — Show timestamp of the last packet logged for this entry. End times are only available if there is more than one packet log entry with unique characteristics.
• -F email — Set the sender address of the email.
• -l time — Process recent events only. See TIME FORMAT below for the time options.
• -o file — Specify an output file.
• -S — Do not differentiate source IP addresses.
• -T email — The summary will be sent by email to this address. If HTML output is selected the report will be embedded as attachment so HTML-aware mail clients can show it directly. fancy 💅
• -t — Show timestamp of the first packet logged for this entry.
• -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. be nice to the registry, they're doing their best 🫶
• -w — Produce output in HTML format (XHTML 1.1 with CSS).
• -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.

---

✨ REALTIME RESPONSE MODE ✨

• -R — Enter realtime response mode. This means: detach and run as daemon until the TERM signal (kill) is received. The HUP signal forces a reload of the configuration file, the USR1 signal forces fwlogwatch to reopen and read the input file from the beginning (useful e.g. for log rotation). All output can be followed in the system log. it just goes and lives its daemon life 🦋
• -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. protected list, do not touch 🛡️
• -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. Using the example script fwlw_respond this will block the attacking host 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 example scripts contain actions for ipchains and netfilter, you can modify them or add others as you like. this one is the "fight back" button 🔥
• -X port — Activate the internal web server to monitor and control the current status of the daemon. It listens on the specified port and by default only allows connections from localhost. The default user name is admin and the default password is fwlogwat (since DES can only encrypt 8 characters). All options related to the status web server can be changed in the configuration file. 👑 and yes the password is really that, DES said 8 chars max, not our fault

---

✨ INPUT FILES ✨

You can specify one or more input files (if none is given it 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 where they don't make sense anyway). The '-' sign may be used for reading from standard input (stdin). In realtime response mode the file needs to be specified with an absolute path since the daemon uses the file system root (/) as working directory. absolute paths only in daemon mode bestie, it's a whole thing 📁

---

✨ TIME FORMAT ✨

Time is specified as nx where n is a natural number and x is one of the following: s for seconds (this is the default), m for minutes, h for hours, d for days, w for weeks, M for months and y for years. ⏳

---

✨ FILES ✨

• /etc/fwlogwatch/fwlogwatch.config — Default configuration file.
• /var/log/messages — Default input log file.
• /run/fwlogwatch.pid — Default PID file generated by the daemon in realtime response mode if configured to do so.

---

and that's just part one, bestie — there's more coming, don't go anywhere 🌸

✨ FEATURES ONLY IN CONFIGURATION FILE ✨

okay so these next ones are only available in the configuration file, not on the command line. they're presented and explained in more detail in the sample configuration file. iykyk 💅

---

🎨 HTML colors and stylesheet 🎨

bestie, you can customize the colors of the HTML output and the status page, and you can reference an external cascading stylesheet. it's giving full aesthetic control ✨🎀

🕹️ Realtime response options 🕹️

these can all be configured:

• Verification of ipchains rules
• PID file handling
• the user fwlogwatch should run as
• the location of the notification and response scripts
• which address the status web server listens on
• which host can connect
• the refresh interval of the status page
• the admin name and password

---

🔒 SECURITY 🔒

okay so because fwlogwatch is literally a security tool, special care was taken to make it secure. periodt. 🔥

You can and should run it with user permissions for most functions, and you can make it setgid for a group that /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 rule analysis needs superuser permissions, but you might also need them to write the PID file, for actions in the response script and for binding the default status port. 😭

However, you can configure fwlogwatch to drop root privileges as soon as possible after allocating these resources — and heads up, the notification and response scripts will still be executed with user privileges and log rotation might not work. 💀

---

👑 AUTHOR 👑

Boris Wesslowski <bw@inside-security.de> — the legend behind this whole page. 💖✨

---

and that's a wrap on FWLOGWATCH(8)! page date: November 11, 2011. bye bestie, stay iconic 💅✨🦋