$Id: README,v 1.2 2000/08/13 23:10:46 thomas Exp thomas $

README for nabou
===================================



Introduction
------------

This is the script called "nabou". Parts of it
are based on another script called "thor.pl".

I used thor.pl on several servers but realized
many bugs and found many things, that could be
solved much better. Since the app-record of thor.pl
on freshmeat does no more exist, I decided to
take the script, give it another name and enhance
it myself.
The result is nabou. If you are wondering about its
name - did you ever see episode I ? If yes, you should
know...

Nabou is a system integrity checker. That means, it
runs every night and watches for changes on files.
If a file has changed in any way, it will inform you
by email(if you prefer that). Beside of that it can
also look for changed or added user accounts, cronjobs,
and suid files.

It stores the properties for each file in a dbm database
and will warn you if something has been changed on a
file. The most important thing to check for, is the
MD5-checksum. This checksum will never be the same if
the file content has changed even if only one letter
has changed. But you can also look for some other
properties, like ownership or filemode. See the section
"Configuration" for more details on that!





Installation
------------

Installation is quite simple, just unpack the tarball,
which you have already done if are reading this file.
Copy the file "nabou" to somewhere, i.e. "/root/bin"
and change its permissions. I suggest the following mode:
rwx------ root  root  nabou.
If you have an ext2 filesystem you might also protect
it using chattr: "chattr +i nabou", this makes it
immutable(read only).

Copy the provided sample-configuration to a convenient
place, i.e. "/root/.nabourc" and edit this file (read
more on  configuration later in this README).

Create a new directory, where nabou can store it's
databases, i.e. "/var/log/sysdb" and chmod it:
"chmod 700 sysdb".

Nabou reguires the following perl module to be installed
which is not part of the standard perl installation:
Digest::MD5. You can find it on every CPAN mirror.

That's all about installation :-)




Configuration
-------------

Nabou uses a config file format similar to the well
known apache-configuration format. Lines starting with
a "#" and empty lines will be ignored. Additional, you
can place a comment after an option, i.e.:
	useshadow	1 # we are using shadow support
You can comment out large blocks using a C-style comment:
/*
passwd  /etc/passwd
shadow  /etc/shadow
shells  /etc/shells
*/

The configuration is devided into several sections. There
are some main-options and some blocks for a special purpose.
Most of the options are simply switches, where a value of
"1" turns it on and "0" turns it off.


The main options:

useshadow	1 turns shadow support on, 0 turns it off,
		which is the default.

usemail		A value of 1 causes nabou to mail the report
		to someone (specified within the mail block,
		see below).
		A value of 0 causes nabou to print the report
		to STDOUT, which is the default.

passwd		specifies the location of the file passwd,
		this option is required.
shadow		specifies the location of the file shadow (or
		master.passwd on BSD), it is required if
		useshadow is turned on.
shells		specifies the location of the shells file,
		which contains a list of all valid shells,
		it is required.
	
check_cron	check for changes in user crontabs.
check_user	check for changed/new/remved useraccounts.
check_root	check for uid/gid root accounts.
check_suid	check for changes/addition/removal of suid/sgid
		files. This check will be performed over the
		whole filesystem but /proc! Look for the <suid>
		blockoptions below too!
check_md5	check for changes of files. nabou can check for
		several attributes of a file not only the md5
		checksum.


The database block options:

The db block starts with "<db>" and ends with "</db>".
An example:
<db>
        basedir          /home/thomas/nabou/db
        pwdDB            thorpwd
        sugidDB          thorsugid
        csumDB           thorcsum
        cronDB           thorcron
        miscDB           thormisc
</db>

The following attributes must exist:
basedir		define the base directory which contains
		the databases.
pwdDB		the user account database.
sugidDB		the suid/sgid database.
csumDB		the checksum/file-attributes database.
cronDB		the crontab database.
miscDB		this database contains checksums of nabou
		itself and some internals.


The mail block options:

The mail block starts with "<mail>" and ends with "</mail>".
An example:
<mail>
        rcpt            root
        from            root
        subject         report from nabou
</mail>

The mailblock is required if you turned "usemail" on.
The following attributes must exist:
rcpt		the receipient of the report email.
from   		the sender address of the email.
subject		the subject of the email.


The binary block options:

The binary block starts with "<bin>" and ends with "</bin>".
An example:
<bin>
        sendmail        /usr/sbin/sendmail
        crontab         /usr/bin/crontab
</bin>

sendmail	the location of the program sendmail, which
		is used to mail the report and only required
		if you turn on "usemail".
crontab		the location of the program crontab, which
		is used to check user crontabs and only
		required if you turn on "check_cron".


The suid block options:

The suidblock starts with <suid> and ends with </suid>.
It will only be used by nabou if you turned on suid-checking
by setting chaeck_suid to 1.
The suid block defines what attributes should be checked for
suid sgid files. If there is no suid block configuration or
if the suid block contains no appropriate attributes, then
nabou will use defaults, which is MD5 check and file-mode
check. You can use all chk_* attributes described below in
the directory block. You can set chk_all to 1 if you want
to perform all available checks.
The suid block does not support the exclude, include, inherit
or recursive attributes. An example:
<suid>
	chk_mode	1
	chk_size	1
	chk_uid		1
	chk_gid		1
</suid>




Finaly, the directory blocks. These are the most important
things in the configuration. Each directory block defines
various options for one directory. Thus , you are able to
define different attributes to be checked for each directory.
In general, a directory block stars with:
<directory /some/dir>
and ends with
</directory>
You may define as many directory blocks as you need. There
are several options, which are the default. If you don't
specify any attributes, i.e.:
<directory /etc>
</directory>
then nabou will make a check on md5 checksums on each file
within that directory and it will _not_ recurse on that dir!

These are the options you may define:

recursive	If turned on, then nabou will also check all
		files in subdirectories under that directory.
		The default is 0(off).

exclude		you may specify a filename which nabou shall
		ignore. You may specify multiple exclude lines
		one for one file. You may use shell-wildcards
		for filenames. An example:
		<directory /dev>
			exclude tt*
			exclude pt*
		</directory>
		If you want to ignore files under a subdirectory,
		then you are required to specify this file/dir
		relative to the directoy block. An example:
		<dir /usr/local>
			exclude share/blackbox/*
		</directory>
		In the example below, /usr/local/share/blackbox/*
		will be ignored.
		The "exclude" attribute cannot used together
		with the "include" attriute (see above).

include		You may specify one or more include lines.
		If an include attribute occurs within a directory
		block (or more than one), then nabou will only 
		look for the file(s) specified by include. It
		will ignore all other files under that directory!
		You cannot use shell-wildcards with the include-
		attribute! An example:
		<directory /home/vasall>
			include .history
			include todo
		</directory>
		The "include" attribute cannot be used together
		with the "exclude" attribute. 

inherit		This is a very special attribute. It takes a
		directory name as argument, which must be defined
		as a directory block somewhere in the configuration.
		It causes the directory to inherit all attributes
		defined from the specified directory block. Please
		note, that you cannot specify additional attributes
		if you are using "inherit", because all attributes
		are used from the inheritted block! An example:
		<directory /bin>
			chk_md5	 	1
			recursive	1
		</directory>
		<directory /sbin>
			inherit		/bin
		</directory>
		In this example, nabou will do an md5-checksum
		lookup and do a recursive lookup for the directory
		/sbin.
		If the "inherit" attribute refers to a directory,
		which is not defined within the configuration, then
		nabou will warn you about this and use the default 
		attributes chk_md5=1 and recursive=0.

You can specify one or more file attributes nabou shall look for:
chk_md5		check for changes on MD5 checksums.
chk_size	check for changes on the file size.
chk_mtime	check for changes of the modification time.
chk_uid		check if owner of the files has changed.
chk_gid		check if group of the files has changed.
chk_nlinks	check if the number of links to a file has
		changed.
chk_mode	check if the mode of files has changed.
chk_ino		check if the filesystem inode has changed.

The attributes below will be used, if you turn on "chk_all"!

The followng attributes can also be checked:
chk_dev		the device number of the filesystem
chk_ctime	inode change time
chk_blocks	the number of blocks allocated on a filesystem.

The following file attributes cannot be checked with nabou:
access time: that's senceless, because, the accesstime changes
when nabou calls stat(2) on a file! And the attributes rdev,
and blcksize. See the manpage of stat(2) for details or look
at the file dbformat.txt shipped with the nabou tarball.

There is a very special and useful parameter which allows you
include another file:
<<include /root/anotherfile>>
nabou reads its contents on this position as if is was written
overthere. An example:
--- mail.rc ---
<mail>
	rcpt	tom@daemon.de 
	from	root@localhost
	subject	nabou report
</mail>
--- end ---

--- nabou.rc ---
<<include mail.rc>>
...
--- end ---

If you run nabou in multiple instances, say one checks only for
suid files once a week and another one checks only for files
every day, but both instances shall to use identical mailoptions,
you can use the construction above.



Nabou does not follow links (at the moment, this may change
in a future release).

You can see a complete configuration example in the file nabourc
shipped with the nabou tarball.




Running nabou
-------------

Before you can install nabou as a daily cronjob, you need to
run it once with the -i or --init commandline flag. This causes
nabou to initialize it's databases based on your configuration.
An example:
	nabou --init --config /root/.nabourc

If the -i or --init flag is supplied, nabou will not mail out
a report even if usemail is turned on.

Now you are ready to install it as a daily cronjob. An example:

30 0 * * * /root/bin/nabou --config /root/.nabourc > /dev/null 2>&1

This crontab entry runs nabou 00:30 every day.


There is another commandline option which you can use to re-
initialize it's database: -r or --reset. But be very careful with
this option.

You can also run multiple instances of nabou, but better use
different databases for every instance. If every instance should
use some identical config options, you might make use of the
include statement mentioned earlier in the "Configuration" section.


You can view the contents of a nabou database by using the command
line flag "-d" or "--dump". Thi flag requires the database name as
argument and dumps out a comma separated list, one line for one file.
the meanings of each field are described in the file dbformat.txt.
The dump will be a little bit formatted, time values will be
converted to human-readable values (just as the date command tells
you), uid and gid values will be converted to their representations
(i.e. 0 = root and so on).
If you prefer to get the raw contents unformatted then you can use
the flag "--raw" in addition to the --dump or -d flag.




Availabitily
------------

You can find the latest versions of nabou on one of the following
locations:
http://www.daemon.de/software.html
http://www.0x49.org/nabou





Support and Feedback
--------------------

If you encounter any problems using nabou or if you have some
suggestions or bug reports, feel free to drop me an email:

Thomas Linden <tom@daemon.de>.




Finaly, thanks for choosing nabou - keep the world secure!

