SYNOPSIS
========
Logcheck-database provides the egrep patterns required by the
package "logcheck"; they are used to filter recent log messages
(collected using "logtail") into a mailed news summary.
SETS OF RULES
=============
There are three layers of sets of filtering rules, all of which are
normal egrep pattern-matches, applied in turn.
1. the "SECURITY ALERTS" layer, designed to detect the traces of active
intrusion attempts.
Patterns raising the alarm go in "/etc/logcheck/cracking.d"; any
event that matches one of these patterns turns the report
into an urgent "Security Alerts" report, with the relevant
event moved to a special section. The cracking.d standard
keywords file is seeded with known symptoms of hostile
activity (see logcheck's README.keywords file).
Patterns cancelling such maximum-priority alarms are not used in
the default logcheck configuration, but if the local
administrator enables this layer of filtering in
logcheck.conf, then the rules go in the directory
"/etc/logcheck/cracking.ignore.d". Matches with
cracking.ignore rules will then reclassify the alert as a
false alarm (compare violations.ignore below). Note that
this means they are totally ignored - log messages handled
at one layer are not carried over to lower layers.
2. the "SECURITY EVENTS" layer, designed to detect less critical
events still considered worthy of special attention.
Patterns raising the alarm go in "/etc/logcheck/violations.d";
matches with these result in a "Security Events" alert,
with the relevant event moved to a special section.
Patterns cancelling such alarms go in the standard directory
"/etc/logcheck/violations.ignore.d"; apparent "Security
Events" that match with violations.ignore patterns are
discarded as false alarms.
3. the "SYSTEM EVENTS" layer, handling leftover log messages.
This layer doesn't have an equivalent to the alarm-raising
cracking.d and violations.d; instead _all_ remaining lines
from the logfiles are considered for inclusion in the main
"System Events" section.
Patterns in the three "/etc/logcheck/ignore.d.*" directories
again function to overrule alerts; the log messages that
match them are excluded from the report as trivial. The
specific directories consulted depend on the prevailing
logcheck "REPORTLEVEL" (for details see the corresponding
README for logcheck). The bare minimum is the set of
filters in ignore.d.paranoid.
When _no_ logged events make it through the filters no report is
mailed.
FILES WITHIN EACH DIRECTORY
===========================
Each of the rules-directories can contain pattern files of the
following kinds:
./<packagename>
The rule filename must only contain characters compatible with
run-parts(8). As of this writing, this includes alphanumeric characters,
underscore, and hyphen.
Contains filters relevant to only one Debian package - for example
if "fooserver" logs suspicious events like this:
"$DATE $HOSTNAME fooserver[$PID]: $USER is up to no good"
then a line in "/etc/logcheck/violations.d/fooserver" with an
appropriate pattern will promote it from a mere "System Event"
to a full "Security Event" in a subsection of the mailing headed
"fooserver". Or then again if that kind of log message is more
trivial than it looks (maybe "foo" is a networked game of
spy-and-counterspy) then a line in
"/etc/logcheck/ignore.d.server/fooserver" will turn it into a
nonevent for all but the most assiduous of administrators.
Sometimes a package will have not only special alarm calls which
_do_ need to be "Security Events" triggers but also exceptional
variants which _don't_ - maybe it logs either
"$DATE $HOSTNAME fooserver[$PID]: $USER barred"
or
"$DATE $HOSTNAME fooserver[$PID]: none barred".
In this situation the alarm can be overruled by a
violations.ignore rulefile named "fooserver" which filters
"none barred". This will _not_ affect other "Security Events"
featuring the words "none barred" (that might allow crackers to
use those words to cover attacks on ssh). Instead, any
<packagename> ignore-files only affect the log messages that
would have been in that package-specific report section. Apart
from anything else this limitation reduces the number of rules
that need to be processed.
./logcheck or ./logcheck-<packagename>
Standard "generic" rules go in each directory's "./logcheck" file;
thus for instance any log message at all matching "ATTACK"
(listed in "/etc/logcheck/cracking.d/logcheck") _always_ triggers
a "Security Alert", unless you deliberately tamper with
"cracking.ignore.d" rules.
** Debian Note: we emptied out ./logcheck and merged all
./logcheck-<packagename> files into the ignore.d.*/<packagename>
files. This was done because the standard rules in ./logcheck matched
too many false positives (see e.g. #449028) and resulted in a lot of
rule duplication (#254542).
Remember that package-specific "ignore" filters will _not_ override
non-package-specific "flagging" patterns! Thus for instance if
"fooserver" outputs syslog messages like this:
"$DATE $HOSTNAME fooserver[$PID]: 3 attempts 0 rejected"
then the standard keyword "reject" listed in the generic
"/etc/logcheck/violations.d/logcheck" file will trigger frequent
"Security Events" reports. Putting a filtering pattern in
"/etc/logcheck/violations.ignore.d/fooserver" won't help here!
The solution is to use a file named in the specially-privileged
./logcheck-<packagename> format:
"/etc/logcheck/violations.ignore.d/logcheck-fooserver".
This can contain patterns provided by that particular package
which nonetheless need to take precedence over the generic rules.
./local or ./local-<packagename>
Sysadmins can use the "local-*" filenames to create their own
additions to the "logcheck-*" pattern lists. If you have "ippl"
logging network connections verbosely into syslog then you can put
custom "Security Events" keywords in
"/etc/logcheck/violations.d/local-ippl" and exceptions in
"/etc/logcheck/violations.ignore.d/local-ippl".
WRITING RULES
=============
Be careful when editing local rule files; logcheck will preprocess
them to eliminate dangerous blanks (since "egrep '' syslog" matches
every line) and comment lines, but some attention is needed when
composing custom patterns to avoid excessively generous filtering.
The objective in logcheck rules is to match precisely the target log
messages and no more, using all the resources of Extended Regular
Expressions. If you're sick of reading log messages like this:
Apr 6 19:30:24 oempc wwwoffled[11763]: WWWOFFLE Online.
Apr 6 19:31:54 oempc wwwoffled[11763]: WWWOFFLE Offline.
...then the local ignore pattern you need is something like this:
^\w{3} [ :0-9]{11} oempc wwwoffled\[[0-9]+\]: WWWOFFLE (On|Off)line\.$
The characters ".?*+[](){}^$|\" are "special" in extended-regexps,
so they need to be escaped if intended literally (like the final
stop in the example above). Be especially wary of unbalanced
brackets, which can choke egrep.
Local administrators can afford to be more specific than the package
maintainers who provide filters for "fooserver" etc. You can take
the locale for granted, saying "[a-zA-Z]" where package maintainers
should be using "[[:alpha:]]"; and you can write out things like
hostnames explicitly - hence "oempc" above, rather than the pattern
"[._[:alnum:]-]+".
TESTING RULES
=============
To test new rules, you can grep your log file, and remove trailing
space with something like this:
sed -e 's/[[:space:]]*$//' /var/log/syslog | egrep \
'^\w{3} [ :0-9]{11} oempc wwwoffled\[[0-9]+\]: WWWOFFLE (On|Off)line\.$'
If the log line is displayed, then your regex works.
Pass all rules files through "sort -u" to simplify maintenance, then
ensure they have a final end-of-line carriage return so that they
"cat" nicely. Since System Events aren't subdivided by package, it
makes no difference whether ignore.d.*/local rules are split up into
"local-x", "local-y" and "local-z" or merged into one "local" file;
use whatever's convenient.
Another safety-net is provided by the fact that the process that
collates all the applicable rules uses "run-parts", the standard
Debian utility also used for iterating through "/etc/cron.d",
"/etc/ppp/ip-up.d" etcetera. It therefore automatically ignores
files with names such as "fooserver.disabled" or "local~".
SUBMITTING RULES
================
If there are messages which are not ignored by logcheck that should be,
file a bug against the package logcheck-database in the Debian Bug
Tracking System (BTS).
If you're new to the reporting bugs using the Debian BTS, you can
learn more at:
http://www.debian.org/Bugs/Reporting
Unfortunately, we don't have the time to add and update rules for
everything, therefore the following exceptions apply:
* Debug messages
* Messages produced by software not included in Debian
* Temporary messages which are due to a bug in the package
* Messages related to daemon startups and shutdowns
Please do not file bugs related to these messages.
# vim:tw=70
