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