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]

Name	Type	Occurs	Description
self	string	1	A URL linking to this resource.
auditRecords	AuditRecordCollection	1	Collection of all audit records.
auditRecordsForType	AuditRecordCollection URI template	1	Read-only collection of all audit records of a particular type (placeholder {type}).
auditRecordsForUser	AuditRecordCollection URI template	1	Read-only collection of all audit records for a particular user (placeholder {user}).
auditRecordsForApplication	AuditRecordCollection URI template	1	Read-only collection of all audit records for a particular application (placeholder {application}).
auditRecordsForUserAndType	AuditRecordCollection URI template	1	Read-only collection of all audit records of a particular user and type (placeholder {user} and {type}).
auditRecords ForUserAndApplication	AuditRecordCollection URI template	1	Read-only collection of all audit records for a particular user and application (placeholder {user} and {application}).
auditRecords ForTypeAndApplication	AuditRecordCollection URI template	1	Read-only collection of all audit records of a particular type and application (placeholder {type} and {application}).
auditRecords ForTypeAndUserAndApplication	AuditRecordCollection URI template	1	Read-only collection of all audit records of a particular type, user and application (placeholder {type}, {user} and {application}).

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]

Name	Type	Occurs	Description
self	string	1	A URI linking to this resource.
auditRecords	array	0..n	List of audit records, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of audit records.
next	string	0..1	A URI linking to a potential next page of audit records.

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 by default in order from the newest to the oldest.

It is possible to change the order by adding query parameter “revert=false” to the request URL. An example request would be: “«url»/audit/auditRecords?dateFrom=2019-09-01&dateTo=2019-09-06T08:26:42%2B02:00&revert=false”.

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

Important: This method has been deprecated and will be removed completely with the July 2020 release (10.6.6). With Cumulocity IoT >= 10.6.6 the deletion of audit logs will no longer be permitted. All DELETE requests to the audit API will return the error 405 Method not allowed. Note that retention rules still apply to audit logs and will delete audit log records older than the specified retention time.

Audit record

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

Name	Type	Occurs	Description	Mandatory for PUT/POST
id	string	1	Uniquely identifies this audit record.	No
self	string	1	A URI linking to this resource.	No
creationTime	datetime	1	Time when audit record was created in the database.	No
type	string	1	Identifies the type of this audit record.	POST: Yes PUT: No
time	datetime	1	Time of the audit record.	POST: Yes PUT: No
text	String	1	Text description of the audit record.	POST: Yes PUT: No
source	ManagedObject	1	An optional ManagedObject that the audit record originated from, as object containing properties “id” and “self”.	No
user	string	1	The user responsible for the audited action.	No
application	string	1	The application used to carry out the audited action.	No
activity	string	1	The activity that was carried out.	POST: Yes PUT: No
severity	string	1	The severity of action: critical, major, minor, warning or information.	No
changes	array	0..1	An optional collection of objects describing the changes that were carried out.	No
*	Object	0..n	Additional properties of the audit record.	No

Info: source can contain a ManagedObject with id and self properties. Also, in case of “Operation” type, it can contain an operation id. In case of “Alarm” type, an alarm id. In both cases, the self link in source is not correct, but it is kept there to not break the clients that expect to get a 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"
}