Document Cerberus' key notions

The aim of this story is to enhance the Cerberus' documentation
so that developers have a better understanding of what is the
goal of Cerberus, how it has been implemented, what are the key
components

Change-Id: I6e121b74752f2111480847040c4e09b34f9763f6

doc/source/arch.rst

@@ -1,6 +1,6 @@
-=======================
-Cerberus's Architecture
-=======================
+======================
+Cerberus' Architecture
+======================
 
 Cerberus can be cut in two big parts:
 
@@ -14,6 +14,101 @@ Cerberus can be cut in two big parts:
    :alt: Architecture summary
 
 
+Cerberus' API
+=============
+The API is a REST server documented later.
+
+
+Cerberus' manager
+=================
+Cerberus is easy to extend thanks to a plugin system.
+
+The manager has some functions:
+* it loads **plugins**
+* it manages **tasks**
+* it stores **security reports** and **security alarms** in database
+
+
+Plugins
+=======
+
+Plugins are created to communicate with a particular security component.
+They are defined by their:
+* unique identifier (uuid)
+* name
+* version
+* provider
+* type (scanner, SIEM...)
+
+Plugins can subscribe to events sent on the notification topic Cerberus'
+manager listens on. For example, this can be useful to automatically configure
+a tool if a project has been created or if a certain role is granted to an user.
+Plugins may also implement some functions that the manager calls through
+**tasks**.
+
+
+Tasks
+=====
+Cerberus manages tasks.
+In order to create a task, you need to call the Cerberus' API by passing some
+information:
+* The name of the task
+* The plugin uuid handling the task
+* The method to call on this plugin
+* The type (periodic or not, default is not)
+* The period if the task is periodic (for now, period is in seconds only)
+* Persistent (True/False, conditional): tell Cerberus you want this task to be
+stored in database
+
+The tasks may be stopped/started. As such, they have a state (running or not).
+
+
+Security reports
+================
+Cerberus stores security reports provided by the security components.
+These security reports have a predefined schema and Cerberus stores the
+following information:
+
+* The uuid of the security report
+* The uuid of the plugin
+* The report identifier
+* The component identifier
+* The component type
+* The component name
+* The Openstack's project identifier
+* The ticket identifier
+* The title
+* The description
+* The security rating
+* The vulnerabilities
+* The number of vulnerabilities
+* The date of the last report
+
+Security reports may be retrieved by their uuid.
+
+
+Security alarms
+===============
+Cerberus stores security alarms provided by the security components such as
+SIEM.
+These security alarms have a predefined schema and Cerberus stores the
+following information:
+
+* The uuid of the alarm
+* The uuid of the plugin
+* The alarm identifier
+* The component identifier
+* The Openstack's project identifier
+* The ticket identifier
+* The timestamp (date when the notification has been received on oslo bus)
+* The summary
+* The severity
+* The status
+* The description
+
+Security alarms may be retrieved by their uuid.
+
+
 Module loading and extensions
 =============================
 

doc/source/index.rst

@@ -13,6 +13,11 @@ Introduction
 Cerberus is a Security As A Service project aimed at integrating security tools
 inside Openstack.
 
+Cerberus offers a framework to integrate **security components** (scanners of
+vulnerabilities, behavior analysis, IPS, IDS, SIEM) in order to propagate
+changes of the platform to them and to collect security reports and security
+alarms.
+
 Installation
 ============
 

requirements.txt

@@ -10,6 +10,8 @@ lockfile>=0.8,<=0.10.2
 MySQL-python<=1.2.5
 oslo.config>=1.2.0,<1.5
 oslo.messaging>=1.3.0,<1.5
+oslo.utils<2.0.0
+oslo.serialization<1.7.0
 pecan>=0.4.5,<=0.8.3
 posix_ipc
 python-keystoneclient>=0.7.0,<0.12.0