README

   1 This is some background information about the Linux Auditing Framework.
   2
   3 LICENSE
   4 =======
   5 The audit daemon is released as GPL'd code. The audit daemon's libraries
   6 libaudit.* and libauparse.* are released under LGPL so that it may be
   7 linked with 3rd party software.
   8
   9 BUILDING
  10 ========
  11 See the README-install File.
  12
  13 USAGE
  14 =====
  15 See the man pages for audit, auditctl, audit.rules, ausearch, and aureport.
  16
  17 DISCUSSION
  18 ==========
  19 Original lkml thread(s):
  20      http://marc.theaimsgroup.com/?t=107815888100001&r=1&w=2
  21      http://marc.theaimsgroup.com/?t=107901570800002&r=1&w=2
  22
  23 There is a linux audit mail list where any question whether kernel design,
  24 setup and configuration, or usage can be discussed:
  25 http://www.redhat.com/mailman/listinfo/linux-audit
  26
  27
  28 DESIGN INFO (Very old)
  29 =====================
  30 The main goals were to provide system call auditing with 1) as low
  31 overhead as possible, and 2) without duplicating functionality that is
  32 already provided by SELinux (and/or other security infrastructures).
  33 This framework will work "stand-alone", but is not designed to provide,
  34 e.g., CAPP functionality without another security component in place.
  35
  36 There are two main parts, one that is always on (generic logging in
  37 audit.c) and one that you can disable at boot- or run-time
  38 (per-system-call auditing in auditsc.c).  The patch includes changes to
  39 security/selinux/avc.c as an example of how system-call auditing can be
  40 integrated with other code that identifies auditable events.
  41
  42 Logging:
  43     1) Uses a netlink socket for communication with user-space.  All
  44        messages are logged via the netlink socket if a user-space daemon
  45        is listening.  If not, the messages are logged via printk to the
  46        syslog daemon (by default).
  47     2) Messages can be dropped (optionally) based on message rate or
  48        memory use (this isn't fully integrated into the selinux/avc.c
  49        part of the patch: the avc.c code that currently does this can be
  50        eliminated).
  51     3) When some part of the kernel generates part of an audit record,
  52        the partial record is sent immediately to user-space, AND the
  53        system call "auditable" flag is automatically set for that call
  54        -- thereby producing extra information at syscall exit (if
  55        syscall auditing is enabled).
  56
  57 System-call auditing:
  58     1) At task-creation time, an audit context is allocated and linked
  59        off the task structure.
  60     2) At syscall entry time, if the audit context exists, information
  61        is filled in (syscall number, timestamp; but not arguments).
  62     3) During the system call, calls to getname() and path_lookup() are
  63        intercepted.  These routines are called when the kernel is
  64        actually looking up information that will be used to make the
  65        decision about whether the syscall will succeed or fail.  An
  66        effort has been made to avoid copying the information that
  67        getname generates, since getname is already making a
  68        kernel-private copy of the information.  [Note that storing
  69        copies of all syscall arguments requires complexity and overhead
  70        that arguably isn't needed.  With this patch, for example, if
  71        chroot("foo") fails because you are not root, "foo" will not
  72        appear in the audit record because the kernel determined the
  73        syscall cannot proceed before it ever needed to look up "foo".
  74        This approach avoids storing user-supplied information that could
  75        be misleading or unreliable (e.g., due to a cooperative
  76        shared-memory attack) in favor of reporting information actually
  77        used by the kernel.]
  78     4) At syscall exit time, if the "auditable" flag has been set (e.g.,
  79        because SELinux generated an avc record; or some other part of
  80        the kernel detected an auditable event), the syscall-part of the
  81        audit record is generated, including file names and inode numbers
  82        (if available).  Some of this information is currently
  83        complementary to the information that selinux/avc.c generates
  84        (e.g., file names and some inode numbers), but some is less
  85        complete (e.g., getname doesn't return a fully-qualified path,
  86        and this patch does not add the overhead of determining one).
  87        [Note that the complete audit record comes to userspace in
  88        pieces, which eliminates the need to store messages for
  89        arbitrarily long periods inside the kernel.]
  90     5) At task-exit time, the audit context is destroyed.
  91
  92     At steps 1, 2, and 4, simple filtering can be done (e.g., a database
  93     role uid might have syscall auditing disabled for performance
  94     reasons).  The filtering is simple and could be made more complex.
  95     However, I tried to implement as much filtering as possible without
  96     adding significant overhead (e.g., d_path()).  In general, the audit
  97     framework should rely on some other kernel component (e.g., SELinux)
  98     to make the majority of the decisions about what is and is not
  99     auditable.