Using Predix Audit Service

On creation, the AuditClient is authenticated by sending an OAuth token to the Predix Audit Service, after which audit messages can be sent to the Predix Audit Service. Compose the audit message to be sent and send it with the audit method of the AuditClient. This section details all the information and methods of the AuditEvent. To create a new AuditEvent, a builder is provided so all other required fields are automatically inserted to the object. The following code example shows the builder:

AuditEvent eventV2 = AuditEventV2.builder()
        .payload("GET: /v2/resources was unsuccessful")
        .classifier(AuditEnums.Classifier.FAILURE)
        .publisherType(AuditEnums.PublisherType.APP_SERVICE)
        .categoryType(AuditEnums.CategoryType.API_CALLS)
        .eventType(AuditEnums.EventType.FAILURE_API_REQUEST)
        .tenantUuid(TENANT)
        .correlationId(CORRELATION_ID)
        .appName(“Application name”)
        .build();
auditClient.audit(eventV2);

The following table describes the various values of Predix canonical model implementation. Note that not all fields are mandatory:

Table 5.

Type	Field Name	Mandatory for user?	Editable?	Default Value	Details
String	messageId	No	Yes	Auto generated in UUID format by AuditEventV2 builder	Maximum 36 characters
int	version	No	No	Auto generated by AuditEventV2 builder with the value "2".	The field is protected. Changing this field may cause an exception.
String	auditServiceId	No	Yes	Auto generated in Audit-Subscriber	The field is an Audit Subscriber Component and should not be used by Audit SDK users
long	timestamp	No	Yes	Auto generated by AuditEventV2 builder with system current time in milliseconds
AuditEnums.Classifier	classifier	Yes	Yes	Auto generated by AuditEventV2 builder to "SUCCESS"	Audit SDK throws a Null Point Exception if AuditEventV2 is initialized without this value
AuditEnums.PublisherType	publisherType	Yes	Yes	The developer must set this in the builder	Audit SDK throws a Null Point Exception if AuditEventV2 is initialized without this value
AuditEnums.CategoryType	categoryType	Yes	Yes	The developer must set this in the builder	Audit SDK throws a Null Point Exception if AuditEventV2 is initialized without this value
AuditEnums.EventType	eventType	Yes	Yes	The developer must set this in the builder	Audit SDK throws a Null Point Exception if AuditEventV2 is initialized without this value
String	payload	No	Yes	Custom field. not mandatory	Maximum 2048 characters
String	correlationId	No	Yes	Not mandatory	Maximum 64 characters
String	tenantUuid	No	Yes	Should be in UUID format	Maximum 254 characters
String	AppName	No	Yes	Defines the application friendly name	Maximum 100 characters

Predix canonical model is a method for making a log standardization in all platform services or application, and thus, the user needs to set all mandatory fields without the default values. Otherwise, a NullPointerException is thrown since those fields are mandatory to canonical model. The development team aimed to simplify the work of the developers and combined the canonical model requirements via the AuditEnums type:

• AuditEnums.Classifier

  Classifier is a field that is created to classify the event, whether it was a success or a failure. Each message is classified automatically as a successful message. Supported types: SUCCESS, FAILURE

• AuditEnums.PublisherType

  This field enables the developer to provide the auditor type. Supported types: NETWORK_DEVICE, DB_SYSTEM, APP_SERVICE, OS

• AuditEnums.CategoryType

  This field mentions which type of category is related to the event. Supported fields: AUDIT_ACCOUNTABILITY, OPERATIONS, ADMINISTRATIONS, AUTHENTICATIONS, AUTHORIZATION, MALICIOUS, DATA_INTEGRITY, API_CALLS

• AuditEnums.EventType

  This field mentions the event in general terms (It is also a provided CUSTOM value in case there is no matching for the client’s needs). Supported fields: CUSTOM, LOG_START, LOG_STOP, LOG_DELETION, LOG_DEACTIVATION, LOG_MODIFICATION, UNAVAILABILITY, EXCEPTION, SERIOUS_ERROR, STARTUP_EVENT, SHUTDOWN_EVENT, START_SERVICE, STOP_SERVICE, ACCOUNT_PRIVILEGE_SUCCESS_MODIFICATION, ACCOUNT_PRIVILEGE_FAILURE_MODIFICATION, ADD_ADMIN_ACCOUNT, CHANGE_PASSWD_SUCCESS, CHANGE_PASSWD_FAILURE, CHANGE_CONFIGURATIONS_SUCCESS, CHANGE_CONFIGURATIONS_FAILURE, ADD_ADMIN_GROUP_ACCOUNT, CHANGE_CONFIGURATIONS, ADD_ROLE, REMOVE_ROLE, SECURITY_POLICY_CHANGE_SUCCESS, SECURITY_POLICY_CHANGE_FAILURE, LOGIN_SUCCESS, LOGIN_FAILURE, ACCOUNT_LOCKOUT, AUTHENTICATION_ERROR, VPN_CONNECTION_ESTABLISHED_SUCCESS, VPN_CONNECTION_ESTABLISHED_FAILURE, CHANGE_CRITICAL_FILE, PRIVILEGE_ACCOUNT_ACTION, CHANGE_CRITICAL_RESOURCE, INBOUND_CONNECTION_DENIED, OUTBOUND_CONNECTION_DENIED, INVALID_INPUTS, INVALID_APP_ABUSE, COMPONENT_INSTALLATION, COMPONENT_MODIFICATION, COMPONENT_DELETION, DOS_ATTACK, EAVSDROPPING_ATTACK, USER_UNAPPROVED_OUTBOUND_TRAFFIC, VIRUS_ALERT, MALWARE_ALERT, ACTION, CREATE, TRIGGER, DROP, INSERT, UPDATE, DELETE, SUCCESS_API_REQUEST, FAILURE_API_REQUEST

• Payload

  The following fields are currently parsed by the Audit Log Viewer UI and can be a part of the Payload string per the consuming application needs: OLDVALUE, NEWVALUE, RESOURCEUUID, RESOURCE, ACTOR, ACTORUUID, ACTORDISPLAYNAME, BATCHUUID, ORIGINATOR, ACTIONTYPE, DESCRIPTION, RESOURCETYPE.

  For example, the following code snippet can be used by a consuming application to ingest data in all the above payload fields:

  try{
    payload = gson.fromJson(this.getPayload(),
                    AuditEventV2Payload.class);
  }catch (Exception e){
    String msg = "error parsing audit payload as JSON: ";
    log.error(msg, e);
    throw new AuditException(msg);
  }
  Audit audit = Audit.builder()
    .resourceUuid(payload.getResourceUuid())
    .resource(payload.getResource())
    .actor(payload.getActor())
    .actorUuid(payload.getActorUuid())
    .actorDisplayName(payload.getActorDisplayName())
    .tenantUuid(this.getTenantUuid())
    .ownerTenant(this.getOwnerTenant())
    .operatorTenant(this.getOperatorTenant())
    .batchUuid(payload.getBatchUuid())
    .originator(payload.getOriginator())
    .actionType(payload.getActionType())
    .description(payload.getDescription())
    .eventAt(""+this.timestamp)
    .resourceType(payload.getResourceType())
    .oldValue(payload.getOldValue())
    .newValue(payload.getNewValue())
    .build();
  return audit;
  

Predix Audit Service provides REST API with query interface for retrieving archived audit events, which are stored in BlobStore, according to transmitted parameters. The developer can use the REST API to control auditing and run secure queries against the audit data.

First, the developer needs to send a request that lists all available files in the Blobstore, which meets the required timeframe in ISO-8601 format (i.e., between startDate and endDate) using the List Request, and afterwards, send the File Request to get that file. The following tables show the parameters that are needed for each request:

Type	Parameter	Description
Mandatory	startDate	The start date of the list in ISO-8601 format
Mandatory	endDate	The end date of the list in ISO-8601 format
Mandatory	version	The version of the audit event message (should be V2)
Optional	pageSize
Optional	page
Optional	tenantUUID	Filters data based on the tenant identifier.

Secure the archived audit data access by setting the HTTP headers with the following headers:

Header	Description
Predix-Zone-Id	Audit Service zone id parameters that represents the AuditService tenant id
Authorization	UAA token

The HTTP response shall include the following parameters:

HTTPS Status	Description
200 ok	Successful
201	Created
401	Unauthorized
403	Forbidden
404	Not Found

For example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' --header 'Predix-Zone-Id: {audit-service-id}' --header 
'Authorization: Bearer {token}' -d '{ 
   "startDate": "2018-01-01", 
   "endDate": "2018-01-31", 
   "version": "V2", 
   "pageSize": 10,  
   "page": 1
   “tenantUUID” : “83fed947-8619-4989-a6bd-ed44378e8cf1” 
 }' 'https://audit-service-sysint-blue-dev.run.aws-usw02-dev.ice.predix.io/v2/archive/list'

Type	Parameter	Description
Mandatory	path	The full path of the archived file.
Optional	tenantId	Filters data based on the tenant identifier.

Secure the archived audit data access by setting the HTTP headers with the following headers:

Header	Description
Predix-Zone-Id	Audit Service zone id parameters that represents the AuditService tenant id
Authorization	UAA toekn

The HTTP response shall include the following parameters:

HTTPS Status	Description
200 ok	Successful
201	Created
401	Unauthorized
403	Forbidden
404	Not Found

For example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' --header 'Predix-Zone-Id: {audit-service-id}' --header 
'Authorization: Bearer {token}' -d '{ 
   "path": "{path/to/your/file}" 
 }' 'https://audit-service-sysint-blue-dev.run.aws-usw02-dev.ice.predix.io/v2/archive/file'

The following update scenarios in Predix Audit service are supported using the update-service API:

• Beta to a Dedicated-A50: A one-time change for existing beta customers.It is recommended for a production environment where a dedicated database is required and the audit events storage volume is considered as medium.

• Beta to a Shared-A10 : A one-time change for existing beta customers.It is recommended for testing and evaluating the Predix Audit service where the required audit events storage volume is considered small and the DB is shared with other tenants.

The following command is an example of how to use the update-service request using the CF CLI:

cf update-service<audit-instance-name-with-old-plan>-p<new-plan>

For example, assuming the user’s audit service instance name is “audit-test”, which is subscribed to a “Beta” plan, and the user wants to update to a Dedicated-A50 plan then he should use the following CF CLI syntax:

cf update-service audit-test -p Dedicated-A50

The user can upgrade its subscription plan from a Shared plan to a Dedicated plan. A dedicated plan includes a dedicated database, enlarged storage, and an extended retention period for the audit events data. In order to achieve that, the user should perform the following steps:

1. Delete the current Audit service instance (either via “Delete Service Instance” option in the Marketplace UI or via CF CLI command)
2. Create a new Audit service instance with Dedicated plan (either via selecting the dedicated subscription plan in the Marketplace UI or via CF CLI command).
3. Perform the instructions on creating a new Predix Audit instance, as seen in the Getting Started section (https://docs.predix.io/en-US/content/service/security/audit/getting-started-with-predix-audit).