AIDE for Debian
---------------

Debian's aide packages add some value and functionality to AIDE. Most
of this functionality is delivered by scripts and is configured via
the Debian configuration file in /etc/default/aide. That file is
extensively commented.

In normal use, aide runs unattended as a daily cron job
(/etc/cron.daily/aide, which is explained below). In its default
setup, it sends out daily reports.


Installation
^^^^^^^^^^^^
On installation, debconf questions are asked at medium priority 
to query the user whether to initialize the AIDE database and whether
to automatically place the new database at a place where aide can
pick it up as a reference. aideinit, the script used to initialize
the database, has a man page, and can be invoked at the users'
discretion at a later time.


Configuring AIDE the Debian way
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AIDE's Debian default configuration takes a very paranoid stance and
is likely to report more changes than you will need to focus your
attention on.

The AIDE configuration used by the Debian scripts is maintained in
/etc/aide/aide.conf and makes use of the @@x_include feature to pull in
snippets from /etc/aide/aide.conf.d. The databases are kept in
/var/lib/aide by default.

After changing your aide configuration, you might want to re-build
your database either by using the aideinit script, or aide itself via
aide --init or aide --update. Otherwise, you will on the next run get
a spurious comparison between a newly generated database and the old
reference database. Doing this update with aide --update is generally
recommended since this gives you a chance to spot changes in the file
system that were done between the last aide run and re-building of the
database.


Writing rules
^^^^^^^^^^^^^
We try to write high quality rules. If you write your own rules, and they're
sufficiently general to be of use for other uses of a package, please
consider submitting them to us via a wishlist bug or, probably better,
to the package in question. We are also open to an improvement for the
rules we deliver with the package.

aide rules should be delivered in /etc/aide/aide.conf.d. The filenames are
modeled like ordernr_sourcepackage_name with ordernr being a two-digit
number controlling in which order the rules are read. The second component
of the name is the name of the source package the rule file is delivered
from. This prevents name space conflicts and eases the migration from
an aide-delivered rule to a probable package-delivered rule. Only file names
that honor the Debian cron script namespace restrictions (see run-parts(8))
are read.

All rules that do not include complete directory names should be restricted to
a certain file type. A rule delivered with this package that does not have a
restriction is a bug. Please report it. Please write all new rules with this
suggestion in mind.
 
Rules with the x-bit set are not included verbatim, but are executed
instead and their output is taken as configuration. To prevent privilege
escalation, aide refuses to execute files that are writeable by a user
other than the one running aide. You need to pay attention to the directory
permissions yourself! If an executable rule is a shell script, we try to
only include scripts that are written in a robust way and pass shellcheck(1)
cleanly. If you find scripts that are not shellcheck clean, that's a bug,
please report it (and send a patch if you feel like it). Yes, they're
currently plenty of them.

Common configuration issues
^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, aide checks the entire file system, including /home. This
may be undesirable for a system with actively used shell accounts.
You might want to exclude the home directories of your active shell
users explicitly, which will cut down aide run time severely for big
home directories.

Aide's default configuration includes rule files for the most common
packages. For a more comprehensive set of rules, users of other
packages are encouraged to submit their rules for inclusion in the
aide distribution. Aide rules can both be included with aide, or with
the respective package. From a security point of view, it is desirable
to have the aide rules come with the respective package, since this
makes sure that the only files excluded from the aide check are those
that are actually in use on the system. This approach minimizes the
amount of unneeded aide rules being in place in normal system
operation, but needs the cooperation of the other maintainers.

Aide rules that come with other packages should be placed as
/etc/aide/aide.conf.d/nn_foo_rulename, with foo being the name of the
package that contains them, to minimize the potential of conflict.
Fellow Debian maintainers, if you include aide rules in your package,
please file a bug against aide, so that the respective rules can be
removed from the aide package. Users, if you detect a conflict between
a rule in the aide package and a rule from another package, please
file a bug against aide so that the issue can be cleared up. Of
course, the local admin of a system can locally resolve the rule
conflict by editing the files - they are dpkg-conffiles.

Administrators who would like to have full control about their rules
can - for example - modify the @@x_include statement at the bottom of
/etc/aide.conf to read from a different directory such as
/etc/aide/aide.conf.local.d populated with the rules that they really want.
Symlinks are accepted, so it is possible to take advantage of future
rule updates by symlinking from /etc/aide/aide.conf.d.


the daily AIDE cron job
^^^^^^^^^^^^^^^^^^^^^^^
Main work of the aide package happens in a daily cron job, which is
installed to /etc/cron.daily/aide and thus runs as part of cron.daily
processing.

The daily cron job invokes aide and captures standard output
and standard error to files. The actual command which is invoked is
controlled by the COMMAND variable in /etc/default/aide, and
additional parameters can be passed in via AIDEARGS in
/etc/default/aide. Standard output ends up in /var/log/aide/aide.log,
and standard error in /var/log/aide/error.log. Both files are rotated,
so that older reports stay available.

After running aide, the newly generated database which was created
with COMMAND="update" is optionally copied over the old reference
database. This might be necessary for the ANF/ARF feature to properly
handle logs that have been rotated multiple times. COPYNEWDB="no" is
the default because automatically copying the database unconditionally
(COPYNEWDB="yes") might be dangerous since detected changes are only
reported once. If you use COPYNEWDB="yes" and do not manually increase
the verbosity level by setting (for example) AIDEARGS="-V5" in
/etc/default/aide, you lose the possibility of inspecting the changes
more closely. A third option, COPYNEWDB="ifnochange" only copies the
new database over the old one if aide has not detected any changes. In
this case, you need to manually copy over the databases after the
first report showing changes, or your ANF+ARF rules (including rotated
log files etc) are going to stop working.

The cron job then mails aide's output to the address configured as
MAILTO if either
  - reportable changes have been found or
  - no reportable changes have been found and QUIETREPORTS is not
    set to "yes".
These mails go to root by default.

That means, that if QUIETREPORTS="yes", no message with contents "no
changes detected, everything is fine" will be sent.

Error and standard output are truncated to the first LINES lines each
in the e-mail message.  If the output was truncated, this is
prominently visible in the e-mail. Also, if aide returned a non-zero
exit value, this is mentioned in the e-mail as this is usually a sign
of things having gone very wrong.

MAILTO is run through one stage of shell evaluation, so it is possible
to have the message mailed to recipients depending on variable values,
such as the host name.

If NOISE is set to a regular expression, lines matching are filtered
out in the e-mail report. This is commonly used in environments where
some changes are not important enough to be part of the e-mail
report that is read by humans, but should be in the log nevertheless
for future reference. A second, not de-noised copy of the output is
included as well.


Using aide for your own ideas
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you intend to use AIDE for your own use, please note that aide is compiled
to neither having a default configuration file nor a default configuration
file, so you _always_ need to give a --config option with the path to a
configuration file. This is to prevent an accidental invocation of aide from
messing with the Debian database.


error mmap'ing some/file
^^^^^^^^^^^^^^^^^^^^^^^^
aide performs an mmap() on files that it scans in order to perform its
various checksums more quickly. Some special files, however, may not
be mmap()ed. The new default config excludes these files in
particular.


statically linked
^^^^^^^^^^^^^^^^^
Also note that aide is statically linked by default. This is because of the
possibility of an attacker modifying libc or the like, wrapping system calls
and compromising the integrity of aide's reports even if the binary and data-
base are sitting on physically write-protected media. Of course this could
be done at the kernel level as well, but changing the currently running kernel
results in a lot more disruption (i.e. reboot) than sneaking a new libc in.
It's a security tool, of course we're paranoid ;).


Low Memory Systems
~~~~~~~~~~~~~~~~~~
AIDE keeps its database and some additional information in memory at
run-time. Please make sure that an adequate amount of physical memory
and swap is available when aide runs. If adding more memory and/or
swap is not possible, it might be helpful to exclude bigger parts of
the file system using a "!" directive. Please note that this
sacrifices some security as parts of the file system remain unchecked.


authors
^^^^^^^
This file is maintained by Marc Haber, starting from the README.Debian
by Mike Markley <mike@markley.org>, last changed on Fri, 19 Dec 2003
02:47:49 -0800.

See /usr/share/doc/aide/changelog.Debian.gz for an actual changelog
and current timestamps for package and docs.