README.md

   1 # nice-lad
   2
   3 ## Introduction
   4 Narcissistic, Incredible, Completely Exceptional Logger of Access Denials
   5
   6 ### Project goals
   7 Nice-lad is a tool to collect and aggregate logs of access denials in system.
   8 The source of data are audit messages from DAC, Smack, Cynara and netfilter.
   9
  10 The purpose of nice-lad is to collect and normalize the selected audit logs
  11 and make them readable by unprivileged user. This might be helpful during
  12 debugging applications accessing restricted resources.
  13
  14 Nice-lad works as an [audispd][1] plugin.
  15
  16 [1]: http://linux.die.net/man/8/audispd "audispd"
  17
  18 ### Project history
  19 Nice-lad was first introduced in July 2015.
  20
  21 ### Contact information
  22 | Name            | E-mail                  | Function              |
  23 |-----------------|-------------------------|-----------------------|
  24 | Aleksander Zdyb | [a.zdyb@samsung.com][2] | Developer, Maintainer |
  25
  26 [2]: mailto:a.zdyb@samsung.com "Aleksander Zdyb"
  27
  28 ### Sources
  29 The equivalent places, nice-lad can be obtained from:
  30
  31 * [Tizen](https://review.tizen.org/gerrit/gitweb?p=platform/core/security/nice-lad.git)
  32 * [GitHub](https://github.com/Samsung/nice-lad)
  33
  34 ## Features
  35 Nice-lad, as an audisp plugin, is fed with audit events. It parses and filters
  36 them to obtain and aggregate information useful in context of logging of access
  37 denials.
  38
  39 At the moment, the supported subsystems are:
  40
  41 * DAC denials on given groups,
  42 * Smack denials,
  43 * [Cynara][3] denials,
  44 * Netfilter denials (supported by [Nether][4]).
  45
  46 [3]: https://github.com/Samsung/cynara "Cynara"
  47 [4]: https://github.com/Samsung/nether "Nether"
  48
  49 ### Implanted standards
  50 Nice-lad uses:
  51
  52 * libauparse to parse audit events,
  53 * [Security Manager][5] (where available) to obtain resource groups to monitor,
  54 * journald (where available) or syslog to put aggregated logs.
  55
  56 [5]: https://github.com/Samsung/security-manager "Security Manager"
  57
  58 ## Running and configuration
  59 Please refer to INSTALL.md file for installation and configuration guide.
  60
  61 ### Reading the logs
  62 Nice-lad will log access denials to journald (if available) or syslog with
  63 informational level. Below, are some examples:
  64
  65 ```
  66 Jul 10 10:11:04 HOSTNAME nice-lad: ACCESS DENIED ON SYSCALL syscall=open filename=/tmp/test exit=-13(Permission denied) gid=unknown(1234) object=test subject=_
  67 Jul 10 10:11:09 HOSTNAME nice-lad: ACCESS DENIED ON SMACK object="test" subject="_" access=r
  68 Jul 10 10:11:26 HOSTNAME nice-lad: ACCESS DENIED ON CYNARA client="test_client" user="test_user" privilege="http://tizen.org/privilege/account.read"
  69 Jul 10 10:11:51 HOSTNAME nice-lad: ACCESS DENIED ON NETFILTER obj=User outif=eth0 proto=tcp saddr=10.0.2.16 sport=54460 daddr=198.145.20.7 dport=443
  70 ```
  71
  72 ### Testing
  73 Nice-lad comes with a set of unit tests written in [gmock][6]. By adding new
  74 features or fixing bugs, please add or update tests.
  75
  76 [6]: http://gmock.org/ "Gmock"
  77
  78 ## Usage
  79 Nice-lad is automatically started by audispd service. To disable auto-starting
  80 by audispd service, change "active" to "no" in nice-lad.conf file in audisp
  81 plugins directory: "/etc/audisp/plugins.d/nice_lad.conf"[^1].
  82 To change collector (backend) log level, set "arg = -l LOG_LEVEL". Possible log
  83 levels are defined in [syslog(3)][7]. Default collector log level is LOG_INFO.
  84 Nice-lad can be manually started with -h/--help parameter to print help message.
  85 If ran with invalid parameter, it will be terminated and error will be logged to
  86 journald or syslog[^2].
  87
  88 [^1]: Paths are distribution-specific and resolved at building time.
  89 [^2]: Depends on backend resolved at building time.
  90
  91 [7]: http://linux.die.net/man/3/syslog "syslog(3)"