Overview

Every YaaS service potentially deals with personal data. Therefore, the Audit Ingestion service and the Audit Retrieval service enable YasS services to create appropriate audit logs. You can easily access these audit logs, which are unified by the data subjects.

The Audit Retrieval service supports three categories of audit logs:

  • security event logs - logged security events, such as attempts to change address information without sufficient permissions
  • personal data change logs - logged events of any personal data amendments, such as an email address change
  • configuration change logs - logged events of configuration changes, such as assigning a new user to a project

The Audit Retrieval service allows you to query all your audit logs.


API Reference

/queries

/queries

post

Creates a query requesting audit logs.

get

Gets all the the queries created for a certain sourceType and source. Please note that the caller of the query must fullfill the same yaas authorization requirements as the original query.

/queries/{queryId}

get

Gets the information for certain query. Please note that the caller of the query must fulfill the same YaaS authorization requirements as the original query.


Security

As a data owner, you are responsible for providing logs for events related to personal data to the data subject or data controller, for auditing purposes. The Audit Retrieval service enables YaaS services to make personal data related logs accessible to the data subjects in a unified way.

The Audit Retrieval service cannot handle sensitive personal data.


Use the service

The Audit Retrieval endpoints allow you to gather audit logs from the system in a convenient way.

Get audit logs

There are three types of audit logs. The logs must be always retrieved per type through these endpoints:

  • /personal-data-changes - personal data change events.
  • /configuration-changes - configuration change event.
  • /security-event-changes - security-related events.

You can retrieve audit logs through:

  • tenant - for all the audit logs owned by a certain tenant. In this case the sourceType for the query should be tenant and the source should be the hybris-tenant. In order to get the logs for certain tenant, you must provide a token with the hybris-tenant having the same value as the source field, and a scope of hybris.audit_view.
  • organization - for all the audit logs owned by a certain organization. In this case the sourceType for the query should be organization and the source should be the hybris-org. In order to get the logs for certain organization, you must provide a token with the hybris-org having the same value as the source field, and a scope of hybris.audit_view.
  • account - for all the audit logs owned by a certain yaas account. In this case the sourceType for the query should be account and the source should be the hybris-user-id. In order to get the logs for certain user, you must provide a token with the hybris-user-id having the same value as the source field, and a scope of hybris.audit_view.

You can also query audit logs for a certain period of time, by providing the following query parameters:

  • startTime - from which point in time to retrieve the audit logs. You must provide this as an ISO 8601 date including time. startTime is always required.
  • endTime - to which point in time to retrieve the audit logs. You must provide this as an ISO 8601 date including time. If you do not specify an endTime the system will retrieve the logs up to the current time.

To retrieve the audit logs, you must create a new query with all the information for the request. The system will process this query asynchronously, and you can inquire as to its status through another endpoint. For example, to create a query to retrieve all the personal data changes for tenant shoes2sell for the 5th and 6th of June 2017, make the following call:

POST /query
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Content-Type: application/json

{
  "auditType": "personal-data-change",
  "sourceType": "tenant",
  "source": "shoes2sell",
  "startTime": "2017-07-05T00:00:00Z",
  "endTime": "2017-07-06T23:59:59.999Z"
}

Calling this endpoint creates a query resource and starts the asynchronous execution of the retrieval query. The system gives a 201 - Created response with a URI to query the status of the audit logs being prepared. Example:

HTTP/1.1 201 Created
Location: /query/d781e7dh17817hd8h19hdsudh8h

Get the status of an audit log retrieval query

In order to get the status of an audit log retrieval query, use the /query/{queryId} endpoint. You see a result of 200 - OK with a JSON payload and a status field. The status field value is:

  • processing The system is still processing the retrieval. For example:
GET /query/d781e7dh17817hd8h19hdsudh8h
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auditType": "personal-data-changes",
  "sourceType": "tenant",
  "source": "shoes2sell",
  "startTime": "2017-07-05T00:00:00Z",
  "endTime": "2017-07-06T23:59:59.999Z",
  "createdAt": "2017-10-15T15:00:00Z",
  "status": "processing"
}
  • failed: The retrieval query has failed. This is always accompanied by an error field with a message string describing the error. For example:
GET /query/d781e7dh17817hd8h19hdsudh8h
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auditType": "personal-data-changes",
  "sourceType": "tenant",
  "source": "shoes2sell",
  "startTime": "2017-07-05T00:00:00Z",
  "endTime": "2017-07-06T23:59:59.999Z",
  "createdAt": "2017-10-15T15:00:00Z",
  "status": "failed",
  "error": {
    "type": "service_temporarily_unavailable"
    "message": "The logs can not be currently retrieved. Please try again later."
    "moreInfo" : "https://pattern.yaas.io/errortypes.html"
  }
}
  • done: The retrieval query has finished and the queried logs are ready to be downloaded. This is always accompanied by a downloadUri field with the URI to download the query results. For example:
GET /query/d781e7dh17817hd8h19hdsudh8h
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auditType": "personal-data-changes",
  "sourceType": "tenant",
  "source": "shoes2sell",
  "startTime": "2017-07-05T00:00:00Z",
  "endTime": "2017-07-06T23:59:59.999Z",
  "createdAt": "2017-10-15T15:00:00Z",
  "status": "done"
  "downloadUri": "https://s3.amazonaws.com/someAmazonS3Bucket"
}
The call to the retrieval query status endpoint must contain a token with the same permissions as the originating request. The system makes query results available to download only for a certain number of hours once created. Also, the status of the query is only available for a certain number of hours.

Get the audit log retrieval query results

The downloadUri is a link to an S3 URI, where you can download the actual file with the audit logs. The audit log file is a compressed json payload containing a list of the audit logs, formatted using the schema that the Audit Ingestion Service defines.

The response from S3 contains the following headers according to the payload's format:
  • Content-Encoding: gzip
  • Content-Type: application/json

For example:

GET /someAmazonS3Bucket

HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json

[
  {
    "source": "shoes2sell",
    "sourceType": "tenant",
    "userId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
    "objectId": "c34497a9-bc13-4c7b-b80e-af1dfc2ceb0f",
    "objectType": "order",
    "dataSubjectId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
    "dataSubjectType": "yaas-account",
    "attributes": [
      {
        "name": "name",
        "value": "James",
        "operation": "change"
      }
    ],
    "serviceBasePath": "hybris/order/v1",
    "serviceRegion": "us",
    "time": "2017-07-05T17:30:00.52Z"
  },
  {
      "source": "shoes2sell",
      "sourceType": "tenant",
      "userId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
      "objectId": "c34497a9-bc13-4c7b-b80e-af1dfc2ceb0f",
      "objectType": "order",
      "dataSubjectId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
      "dataSubjectType": "yaas-account",
      "attributes": [
        {
          "name": "address",
          "oldValue": "Other Street 1",
          "value": "Some Street 1",
          "operation": "change"
        }
      ],
      "serviceBasePath": "hybris/order/v1",
      "serviceRegion": "us",
      "time": "2017-07-05T20:30:00.52Z"
    }
]

The call to the retrieval query result download endpoint must contain a token with the same permissions as the originating request.

Get the list of queries created for a certain audit logs source

To get the list of all the log queries created for a certain sourceType and source pair, use the /queries/{sourceType}/{source} endpoint. The call results in a 200 - OK with a JSON payload containing the list of queries created for the sourceType and source pair. You can further refine the query can by specifying the auditType, status, from and to optional query parameters.

For example:

GET /queries?sourceType=tenant&source=shoes2sell&auditType=personal-data-changes&status=done&from=2017-10-15T14%3A00%3A00Z&to=2017-10-15T17%3A00%3A00Z
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
      "auditType": "personal-data-changes",
      "sourceType": "tenant",
      "source": "shoes2sell",
      "startTime": "2017-07-05T00:00:00Z",
      "endTime": "2017-07-06T23:59:59.999Z",
      "createdAt": "2017-10-15T15:00:00Z",
      "status": "done",
      "downloadUri": "/query/d781e7dh17817hd8h19hdsudh8h/result"
    },
    {
      "auditType": "personal-data-changes",
      "sourceType": "tenant",
      "source": "shoes2sell",
      "startTime": "2017-07-09T00:00:00Z",
      "endTime": "2017-07-010T23:59:59.999Z"
      "createdAt": "2017-10-15T16:00:00Z",
      "status": "done",
      "downloadUri": "/query/hdsa7dsah8dsadsa8dashsadh3/result"
    }
]
The call to this endpoint must contain a token with the same permissions as the originating request. The system makes query results available to download only for a certain number of hours once created, so you cannot use this endpoint to get a historical view of the queries for a certain source.


Security

As a data owner, you are responsible for providing logs for events related to personal data to the data subject or data controller, for auditing purposes. The Audit Retrieval service enables YaaS services to make personal data related logs accessible to the data subjects in a unified way.

The Audit Retrieval service cannot handle sensitive personal data.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.