Auditing

Overview

The auditing interface consists of three parts:

• The audit API resource returns URIs and URI templates to collections of audit records, so that they can be queried by criteria such as “all records from a particular user”, or “all records from a particular application”.
• The audit record collection resource retrieves audit records and enables creating new audit records.
• The audit record resource represents audit records that are individually queried.

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

Audited informations

• Alarm modifications
• Operation modifications
• Two factor authentication login attempts
• Smart rule modifications
• Complex Event Processing module modifications
• User and group permissions modifications

Audit API

AuditRecords [application/vnd.com.nsn.cumulocity.auditApi+json]

GET the AuditAPI resource

Response body: application/vnd.com.nsn.cumulocity.auditApi+json

Required role: ROLE_AUDIT_READ

Example request: Retrieve AuditAPI resource

GET /audit
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditApi+json;ver=...
Content-Length: ...
 
{
  "self" : "<<AuditAPI URL>>",
  "auditRecords" : { "self" :"<<AuditCollection URL>>" },
  "auditRecordsForType" : "<<AuditCollection URL>>?type={type}",
  "auditRecordsForUser" : "<<AuditCollection URL>>?user={user}",
  "auditRecordsForApplication" : "<<AuditCollection URL>>?application={application}",
  "auditRecordsForUserAndType" : "<<AuditCollection URL>>?user={user}&type={type}",
  "auditRecordsForUserAndApplication" : "<<AuditCollection URL>>?user={user}&application={application}",
  "auditRecordsForTypeAndApplication" : "<<AuditCollection URL>>?type={type}&application={application}",
  "auditRecordsForTypeAndUserAndApplication" : "<<AuditCollection URL>>?type={type}&user={user}&application={application}"
}

Audit record collection

AuditRecordCollection [application/vnd.com.nsn.cumulocity.auditRecordCollection+json]

The “source” object of an audit record contains the properties “id” and “self”.

POST - create a new audit record

Request body: AuditRecord

Response body: AuditRecord

Required role: ROLE_AUDIT_ADMIN

Example request:

POST /audit/auditRecords
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.auditRecord+json;ver=...
{
  "type" : "com_cumulocity_audit_LoginFailure",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Login failed after 3 attempts.",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "login",
  "severity" : "warning"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.auditRecord+json;ver=...
Content-Length: ...
Location: <<URL of new audit record>>
{
  "id" : "123",
  "self" : "<<URL of new audit record>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_audit_LoginFailure",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Login failed after 3 attempts.",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "login",
  "severity" : "warning"
}

The “id” and “creationTime” of the new audit record are generated by the server and returned in the response to the POST operation.

GET audit records

Response body: AuditRecordCollection

Required role: ROLE_AUDIT_READ

Example request: Retrieve audit records

GET /audit/auditRecords
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.auditRecordCollection+json;

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditRecordCollection+json;ver=...
Content-Length: ...
{
  "self" : "",
  "auditRecords" : [
    {
      "id" : "123",
      "self" : "<<AuditRecord 123 URL>>",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_audit_LoginFailure",
      "time" : "2011-09-06T12:03:27.845Z",
      "text" : "Login failed after 3 attempts.",
      "user" : "Spock",
      "application" : "Omniscape",
      "activity" : "login",
      "severity" : "warning"
    }
  ],
  "statistics" : {
    "totalPages" : 3,
    "pageSize" : 5,
    "currentPage" : 1
  }
}

In case of executing range queries on audit logs API, like query by dateFrom and dateTo, audits are returned in order from the last to the latest. It is possible to change the order by adding query parameter “revert=true” to the request URL.

DELETE - delete an collection of auditRecords

The DELETE method allows for deletion of auditRecords collections. Applicable query parameters are equivalent to GET method.

Request body: N/A

Response body: N/A

Required role: ROLE_AUDIT_ADMIN

Example request:

 DELETE: /audit/auditRecords ....
 Host: ...
 Authorization: Basic ...

Example response:

HTTP/1.1  204 NO CONTENT

Audit record

AuditRecord [application/vnd.com.nsn.cumulocity.auditRecord+json]

Please note that the source can contain not only ManagedObject with id and self, but in case of “Operation” type - operation id and in case of Alarm type - alarm Id. In such cases the self link in source is not correct, but it is kept there to not break the clients that expected to get ManagedObject in source.

GET an audit record

Response body: AuditRecord

Required role: ROLE_AUDIT_READ

Example request: Get a specific audit record

GET /audit/auditRecords/<<recordId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.auditRecord+json;

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.auditRecord+json;ver=...
Content-Length: ...
 
{
  "id" : "123",
  "self" : "<<AuditRecord URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_audit_LoginFailure",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Login failed after 3 attempts.",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "login",
  "severity" : "warning"
}