auditing

Contents

Description

Contrail Auditing provides infrastructure for creating, storing and retrieving audit events. It consists of following modules:

  • auditing
  • storage-manager
  • auditing-api
  • audit-manager

The auditing module provides functionality for creating audit events, Java model for writing audit events in accordance with the CADF specification and publishing audit events to RabbitMQ.
The storage-manager listens on RabbitMQ, accepts audit events and stores them to MongoDB database.
The auditing-api provides REST API on a provider level for retrieving audit events from the MongoDB database using search criteria.
The audit-manager provides REST API on a federation level for retrieving audit events and collects them from all providers by calling corresponding auditing-apis.

Prerequsities

  • RabbitMQ Server
  • MongoDB
  • Apache Tomcat

Module auditing

Installation

The auditing module is provided as a library (jar) which can be included in a Java project. For Maven projects:
<dependency>
  <groupId>org.ow2.contrail.resource</groupId>
  <artifactId>auditing</artifactId>
  <version>0.1-SNAPSHOT</version>
</dependency>

Auditing Web Applications

The auditing module provides servlet filter called WebAppAuditingFilter which audits incoming http requests with corresponding response received by the web application. The servlet filter can be enabled in the web.xml deployment descriptor file:

<filter>
  <description>Auditing</description>
  <filter-name>Auditing</filter-name>
  <filter-class>org.ow2.contrail.resource.auditing.WebAppAuditingFilter</filter-class>
  <init-param>
     <param-name>configuration-file</param-name>
     <param-value>path-to-the-configuration-file</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>Auditing</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

The init parameter configuration-file specifies the path to the configuration file which contains following configuration options:

# WebAppAuditingFilter configuration
auditing.rabbitMQHost=rabbitmq.xlab.si
auditing.rabbitMQPort=5672
auditing.auditRequestData=true
auditing.auditRequestData.sizeLimit=512
auditing.auditResponseData=true
auditing.auditResponseData.sizeLimit=1024
auditing.localID=CN=auditing-demo, O=XLAB, ST=Slovenia, C=SI

The WebAppAuditingFilter creates an audit event based on the data in the HttpServletRequest and HttpServletResponse objects. The event is then published to the RabbitMQ in the json format.

An example audit event:

{
  "action" : "create",
  "attachments" : [
      {
        "content" :
         {
           "content" : "{\"providerUuid\" : \"92084a80-3c1a-11e3-aa6e-0800200c9a66\",\"sids\" : [\"host001.test.com\"],\"metrics\" : [\"cpu.load_one\"],\"startTime\" : \"2013-06-01T12:00:00+0200\",\"endTime\" : \"2013-06-01T12:03:00+0200\",\"numberOfIntervals\" : 3}",
           "contentType" : "application/json; charset=UTF-8",
           "method" : "POST",
           "url" : "https://contrail.xlab.si:8443/federation-accounting/reports/host_metrics_history"
         },
        "contentType" : "application/json",
        "name" : "http_request_data"
      },
      {
        "content" :
         {
           "content" : "{\"location\":\"https:\\/\\/contrail.xlab.si:8443\\/federation-accounting\\/reports\\/host_metrics_history\\/7f5a36e7-19d8-4308-9019-82387458180c\"}",
           "contentType" : "application/json",
           "statusCode" : 201
         },
        "contentType" : "application/json",
        "name" : "http_response_data"
      }
   ],
  "eventTime" : 1382895017000,
  "eventType" : "activity",
  "id" : "d8d46856-dcca-45af-8f58-65f72041cdd3",
  "initiator" :
   {
     "id" : "CN=federation-api, O=XLAB, ST=Slovenia, C=SI",
     "oauthAccessToken" : "19c2590d-d418-3812-a96c-7efd97716135",
     "typeURI" : "contrail:initiator"
   },
  "outcome" : "success",
  "target" :
   {
     "domain" : "contrail.xlab.si",
     "id" : "contrail-federation-accounting"
   },
  "typeURI" : "http://schemas.dmtf.org/cloud/audit/1.0/event"
}

Module storage-manager

Description

The storage-manager listens on RabbitMQ, accepts audit events and stores them to MongoDB database.

Download and Extract

Download and extract contrail-storage-manager.tar.gz package.

Package structure:

/etc/contrail/contrail-provider-storage-manager/
    * storage-manager.cfg
/usr/share/contrail/provider/storage-manager/
    * storage-manager-0.1-SNAPSHOT.jar
    * lib/

Configuration Files

storage-manager.cfg

Start the Application

java -cp "/usr/share/contrail/provider/storage-manager/:/usr/share/contrail/provider/storage-manager/lib/*" \
org.ow2.contrail.provider.storagemanager.Main \
--config /etc/contrail/contrail-provider-storage-manager/storage-manager.cfg

Module auditing-api

Description

The auditing-api provides REST API for retrieving audit events stored in the MongoDB database.

Installation

Download and Extract

Download and extract contrail-auditing-api.tar.gz package. Deploy auditing-api.war webapp to Apache Tomcat server.

Package structure:

/etc/contrail/contrail-auditing-api/
    * auditing-api.cfg
/var/lib/tomcat6/webapps/
    * auditing-api.war

Configuration Files

web.xml

After the war package is deployed to Tomcat and unpacked, make the following configuration:

  • configuration-file parameter: specifies the path to the configuration file auditing-api.cfg
<context-param>
  <param-name>configuration-file</param-name>
  <param-value>/etc/contrail/contrail-auditing-api/auditing-api.cfg</param-value>
</context-param>

auditing-api.cfg

mongodb.connectionString=mongodb://localhost
mongodb.database=monitoring

Configuration parameters:

  • mongodb.connectionString: connection string to the MongoDB instance where the audit events are stored
  • mongodb.database: database name

REST API

Get Audit Events

Description
Retrieves audit events that match the specified search criteria.

Request
POST /audit_events
Content-Type: application/json

POST parameters:

  • searchCriteria
  • startTime
  • endTime
  • offset
  • limit

Response
Returns JSON array of audit events matching the specified search criteria.

Response status codes:

  • 200 OK
  • 404 Bad Request

Example request
POST https://contrail.xlab.si:8443/auditing-api/audit_events
Content-Type: application/json
{
  "searchCriteria" :
   {
     "initiator.id" : "CN=auditing-demo, O=XLAB, ST=Slovenia, C=SI"
   },
  "startTime" : "2013-10-25T00:00:00+0200",
  "endTime" : "2013-10-26T00:00:00+0200",
  "offset" : 0,
  "limit" : 10
}

Example response
Status Code: 200 OK
Content-Type: application/json
[
   {
     "typeURI" : "http://schemas.dmtf.org/cloud/audit/1.0/event",
     "id" : "c9295eb2-e23c-4363-920a-cc2c269aeb09",
     "eventType" : "activity",
     "eventTime" : 1382698549000,
      ...
   },
   ...
]

Module audit-manager

Description

The audit-manager provides REST API for retrieving audit events on a federation level. The audit events are collected from cloud providers by calling corresponding auditing-apis.

Installation

Download and Extract

Download and extract contrail-audit-manager.tar.gz package. Deploy audit-manager.war webapp to Apache Tomcat server.

Package structure:

/etc/contrail/contrail-audit-manager/
    * audit-manager.cfg
/var/lib/tomcat6/webapps/
    * audit-manager.war

Configuration Files

web.xml

After the war package is deployed to Tomcat and unpacked, make the following configuration:

  • configuration-file parameter: specifies the path to the configuration file audit-manager.cfg
<context-param>
  <param-name>configuration-file</param-name>
  <param-value>/etc/contrail/contrail-audit-manager/audit-manager.cfg</param-value>
</context-param>

audit-manager.cfg

mongodb.connectionString=mongodb://localhost
mongodb.database=audit_manager

scheduler.pool.size=3

Configuration parameters:

  • mongodb.connectionString: connection string to the MongoDB instance for caching audit events reports
  • mongodb.database: database name
  • scheduler.pool.size: maximum number of jobs that can run concurrently

REST API

Create Audit Events Report

Description
Retrieves audit events that match specified search criteria by querying all cloud providers. The method works asynchronously. It initiates collecting of events and returns report location.

Request
POST /audit_events
Content-Type: application/json

POST parameters:

  • searchCriteria
  • startTime
  • endTime

Response
Returns location header with URL of audit events report status.

Response status codes:

  • 201 Created
  • 404 Bad Request

Example request
POST https://contrail.xlab.si:8443/audit-manager/audit_events
Content-Type: application/json
{
  "searchCriteria" :
   {
     "initiator.id" : "CN=auditing-demo, O=XLAB, ST=Slovenia, C=SI",
     "outcome":"success"
   },
  "startTime" : "2013-10-25T00:00:00+0200",
  "endTime" : "2013-10-26T00:00:00+0200"
}

Example response
Status Code: 201 Created
Location: https://contrail.xlab.si:8443/audit-manager/audit_events/reports/f37ae2cd-ddd9-4768-ba58-5dd308efc3e3

Get Audit Events Report Info

Description
Returns info of the audit events report which includes following information:

  • jobStatus: QUEUED, RUNNING, FAILED, ERROR, CANCELLED or SUCCESS
  • executionTime: execution time of the report in seconds
  • reportUri: URL where the report content is available. This attribute is shown only if the report status is SUCCESS.
  • errorMsg: error message in case the report failed

Request
GET /audit_events/reports/{reportID}

Response
Returns report info in JSON format.

Response status codes:

  • 200 OK

Example request
GET https://contrail.xlab.si:8443/audit-manager/audit_events/reports/f37ae2cd-ddd9-4768-ba58-5dd308efc3e3

Example response
Status Code: 200 OK
{
  "jobStatus" : "SUCCESS",
  "executionTime" : 0.528,
  "reportUri" : "https://contrail.xlab.si:8443/audit-manager/audit_events/reports/f37ae2cd-ddd9-4768-ba58-5dd308efc3e3/content"
}

Get Audit Events Report Content

Description
Returns audit events collected by the report. The results can be paginated by using query string parameters offset and limit.

Request
GET /audit_events/reports/{reportID}?query_string

Query string parameters:

  • offset: index of the first item
  • limit: maximum number of items to return

Response
Returns JSON array of audit events collected by the report.
Response status codes:

  • 200 OK

Example request
GET https://contrail.xlab.si:8443/audit-manager/audit_events/reports/f37ae2cd-ddd9-4768-ba58-5dd308efc3e3/content?offset=0&limit=10

Example response
Status Code: 200 OK
Content-Type: application/json
[
   {
     "typeURI" : "http://schemas.dmtf.org/cloud/audit/1.0/event",
     "id" : "c9295eb2-e23c-4363-920a-cc2c269aeb09",
     "eventType" : "activity",
     "eventTime" : 1382698549000,
      ...
   },
   ...
]

Auditing Demo

Description

The auditing-demo is a console application that demonstrates

  • auditing
  • accounting
  • OAuth 2.0 client credentials flow 

Prerequisites

Following Contrail components are required for this demo:

  • federation-api
  • provider-accounting and federation-accounting
  • auditing-api and audit-manager
  • oauth-as
  • storage-manager

Installation

Installing the Package

Download the contrail-auditing-demo.tar.gz package from the repository:
http://repository.ow2.org

Package structure:

/etc/contrail/auditing-demo/

  • auditing-demo.properties
    /usr/share/contrail/auditing-demo/
  • log4j.properties
  • lib/
  • (jar files)

Extract the package and copy files to their correct location.

Digital Certificate

Obtain a digital certificate for the auditing-demo application signed by the Contrail root CA. Import the certificate into the java key store (jks file) and copy it to /etc/contrail/auditing-demo/ directory.
Copy java trust store with Contrail root CA certificate to /etc/contrail/auditing-demo/.