diff --git a/COPYING b/COPYING new file mode 100644 index 0000000000000000000000000000000000000000..4f72d35e709024529fe95e2f039e0f36fea115e2 --- /dev/null +++ b/COPYING @@ -0,0 +1,20 @@ +Copyright (c) 2014, <ale@incal.net> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..78f8a6d6f472d97e855b1c9b0d16146e78c17414 --- /dev/null +++ b/README.rst @@ -0,0 +1,61 @@ ++++++++++++++++ +A/I Audit Suite ++++++++++++++++ + +This software implements a distributed collection framework for +*user audit* logs, which consist of high-level management events +related to specific user accounts. Such logs are generated at a +relatively low rate, but they are very important and must not be lost. +On the other hand, this data doesn't have to be real-time: some delay +in the collection pipeline is acceptable (after all, these logs are +primarily useful long-term). + +An interface to query the audit database is also provided, with a very +simple *key = value* syntax. + + +Overview +======== + +An audit *message* is a schema-less JSON dictionary describing a +specific event. The meanings of its attributes are determined by +convention, but a message must include at least the *user*, *message* +and *stamp* attributes. + +The design aims to be as lightweight as possible, since audit +functionality has to be added to many diverse applications. It also +needs to tolerate failure at any stage of the collection pipeline, to +avoid dependencies on highly-available network and databases. It works +as follows: + +* When an audit client application wants to log a message, it tries + first to deliver it to the local audit daemon (via a UNIX socket). + If this fails, it will store the message in a spool directory on the + local filesystem. + +* The local audit daemon, which runs on every machine where audit logs + are generated, is a lightweight daemon that implements the + store-and-forward retry logic: when it receives an incoming message, + it tries to send it to the main audit daemon, and if this fails, it + stores the message in the local spool directory. It also + periodically scans the spool directory and attempts to deliver + messages to the main audit daemon. + +* The main audit daemon receives messages and stores them in the + database. + + +Authentication +============== + +The suite is meant to be deployed along an X509-based authentication +infrastructure where a trusted Certification Authority assigns a +certificate to each machine. The local audit daemons will use the +machine certificates to authenticate themselves to the main audit +daemon, which will consider valid any certificate signed by the CA. + +Client authorization is managed using UNIX permissions: the local +audit socket and spool directories are owned by the *audit* group, so +in order to allow an application to log audit events one should simply +add the user it's running as to the *audit* group. +