File: fwlogwatch.8

package info (click to toggle)
fwlogwatch 1.4-2
  • links: PTS
  • area: main
  • in suites: bullseye, sid
  • size: 996 kB
  • sloc: ansic: 5,288; lex: 1,747; php: 706; sh: 437; makefile: 160
file content (342 lines) | stat: -rw-r--r-- 11,811 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
.\" Copyright (C) 2000-2013 Boris Wesslowski
.\" $Id: fwlogwatch.8 731 2013-05-17 14:15:23Z bw $
.TH FWLOGWATCH 8 "November 11, 2011" "Boris Wesslowski"

.SH NAME
fwlogwatch \- a firewall log analyzer and realtime response agent

.SH SYNOPSIS
.B fwlogwatch
.RI [ options ]\ [ input_files ]

.SH DESCRIPTION
.B fwlogwatch
produces Linux ipchains, Linux netfilter/iptables, Solaris/BSD/IRIX/HP-UX
ipfilter, ipfw, Cisco IOS, Cisco PIX/ASA, NetScreen, Elsa Lancom router and
Snort IDS log summary reports in plain text and HTML form and has a lot of
options to analyze and display relevant patterns. It also can run as daemon
(with web interface) doing realtime log monitoring and reporting anomalies
or starting attack countermeasures.

.SH "GENERAL OPTIONS"
These options are independent from the main modes of operation.
.IP \-h
Show the available options.
.IP \-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.
.IP \-V
Show version and copyright information and the options used to compile
fwlogwatch.

.SH "GLOBAL OPTIONS"
The global options for all modes are:
.IP \-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).
.IP \-c\ \fIconfig\fR
Use the alternate configuration file
.IR config
instead of the default configuration file
.B /etc/fwlogwatch/fwlogwatch.config
(which does not need to exist). Only options not specified in the files can
be overridden by command line options.
.IP \-D
Do not differentiate destination IP addresses. Useful for finding scans in
whole subnets.
.IP \-d
Differentiate destination ports.
.IP \-E\ \fIformat\fR
Specific hosts, ports, chains and branches (targets) can be selected or
excluded, selections an exclusions can be added and combined. The
.I format
is composed of one of the functions
.I i
include or
.I e
exclude, then one of the parameters
.I h
host,
.I p
port,
.I c
chain or
.I b
branch. In case of a host or port a third parameter for
.I s
source or
.I 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
.B -Eipd25
and to exclude entries which have the class C network 192.168.1.0 as source
or belong to the chain INPUT:
.B -Eehs192.168.1.0/24 -EecINPUT
.IP \-i\ \fIfile\fR
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.
.IP \-M\ \fInumber\fR
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.
.IP \-m\ \fIcount\fR
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.
.IP \-N
Enable service lookups. The service name for a specific port number and
protocol will be looked up in /etc/services.
.IP \-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.
.IP \-O\ \fIorder\fR
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
.B ab
where
.B a
is the sort criteria:
.I c
count,
.I t
start time,
.I e
end time,
.I z
duration,
.I n
target name,
.I p
protocol,
.I b
byte count (sum of total packet lengths),
.I S
source host,
.I s
source port,
.I D
destination host and
.I d
destination port.
.B b
is the direction:
.I a
ascending and
.I d
descending.
Sorting is done in the order specified, so the last option is the primary
criteria. The default in summary mode is
.I tacd
(start with the highest count, if two counts match list the one earlier in
time first) of which
.I 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
.I cd
(
.I ta
is not built in).
.IP \-P\ \fIformat\fR
Only use certain parsers, where the log
.I format
can be one or a combination of:
.I i
ipchains,
.I n
netfilter,
.I f
ipfilter,
.I b
ipfw,
.I c
Cisco IOS,
.I p
Cisco PIX/ASA,
.I e
NetScreen,
.I l
Elsa Lancom and
.I s
Snort. The default is to use all parsers except the ones for NetScreen,
Elsa Lancom and Snort logs.
.IP \-p
Differentiate protocols. This is activated automatically if you
differentiate source and/or destination ports.
.IP \-s
Differentiate source ports.
.IP \-U\ \fItitle\fR
Set
.I title
as title of the report and status page.
.IP \-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.
.IP \-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).

.SH "LOG SUMMARY MODE"
This are additional options that are only available in log summary mode:
.IP \-C\ \fIemail\fR
A carbon copy of the summary will be sent by email to this address.
.IP \-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.
.IP \-F\ \fIemail\fR
Set the sender address of the email.
.IP \-l\ \fItime\fR
Process recent events only. See
.B TIME FORMAT
below for the time options.
.IP \-o\ \fIfile\fR
Specify an output file.
.IP \-S
Do not differentiate source IP addresses.
.IP \-T\ \fIemail\fR
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.
.IP \-t
Show timestamp of the first packet logged for this entry.
.IP \-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.
.IP \-w
Produce output in HTML format (XHTML 1.1 with CSS).
.IP \-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.

.SH "REALTIME RESPONSE MODE"
.IP \-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.
.IP \-a\ \fIcount\fR
Alert threshold. Notify or start countermeasures if this limit is reached.
Defaults to 5.
.IP \-l\ \fItime\fR
Forget events that happened this long ago (defaults to 1 day). See
.B TIME FORMAT
below for the time options.
.IP \-k\ \fIIP/net\fR
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.
.IP \-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.
.IP \-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.
.IP \-X\ \fIport\fR
Activate the internal web server to monitor and control the current status
of the daemon. It listens on the specified
.I port
and by default only allows connections from localhost. The default user
name is
.B admin
and the default password is
.B fwlogwat
(since DES can only encrypt 8 characters). All options related to the
status web server can be changed in the configuration file.

.SH "INPUT FILES"
You can specify one or more input files (if none is given it defaults to
.B /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.

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

.SH FILES
.IP \fB/etc/fwlogwatch/fwlogwatch.config\fR
Default configuration file.
.IP \fB/var/log/messages\fR
Default input log file.
.IP \fB/run/fwlogwatch.pid\fR
Default PID file generated by the daemon in realtime response mode if
configured to do so.

.SH "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 more detail in the
sample configuration file.
.IP HTML\ colors\ and\ stylesheet
The colors of the HTML output and status page can be customized, an
external cascading stylesheet can be referenced.
.IP Realtime\ response\ options
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 and the admin name and password can be
configured.

.SH SECURITY
Since fwlogwatch is a security tool special care was taken to make it
secure. You can and should run it with user permissions for most functions,
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 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 (the notification and response scripts will still be
executed with user privileges and log rotation might not work).

.SH AUTHOR
Boris Wesslowski <bw@inside-security.de>