Workspot Splunk/SIEM API User Guide

Description

 Workspot collects events data from various sources that include end user and admin actions. These events are viewed from the “Events” tab of Workspot Control console. Workspot also provides REST APIs for fetching this event data from Workspot Control.

This document describes the SIEM (Security Information and Event Management) API built into Workspot Control.

Workspot also has Splunk app described at Workspot Configuration Guide for Splunk.

 Authentication

 Security Credentials

 The Security credentials required for authentication are found in Workspot Control under “Setup > Splunk.”

The required credentials are URL (the Control Splunk API), “Key Id” and “Secret Key.”

 

 

Authentication Scheme

  • The Workspot SIEM API uses HMAC (Hash based Message Authentication Code) for authenticating the REST requests.

  • Selected parts of the request are concatenated, and a string is generated. Then MAC (message authentication code) is generated for that string using the Secret Key and hash function, HMAC-SHA256. An example is provided in a test script at the end of this document.

  • The key identifier along with the generated MAC, which is encoded using Base64, is combined and sent in the authorization header.

REST API Endpoints

 

The Workspot SIEM API provides REST endpoints to validate the configuration and fetch events data. Once configuration is validated, the APIs need to be invoked in the order below to fetch events:

  1. Submit Request for events data.

  2. Poll for submitted request until data is ready.

  3. Once data is ready, fetch the events data

Details are provided in the individual API endpoint description. A sample python script is also provided at the end of this document that shows the usage of these REST APIs.

Validate the Configuration

Description

  • The Client submits a test request to Workspot Control (https://control.workspot.com). Control validates the credentials and the submitted request and sends the validation output in response.

Endpoint

  • POST /services/data/v2/event

  • Success Response:

    • 200 OK.

Sample Request

  • Method: POST

  • URI: /services/data/v2/event

  • Request headers:

Content-type: application/json; charset=UTF-8 Authorization: WSEvents

OTdTTzZlMnFzU0RBSTlwbFo1TnFyOjZjWTBVeU50VmtvSGdWS25CbW4xMXdUcXh6bkN0NjZNb3 ZhQ1lMVk9KNzg9

  • Request Body:

{"version":"3.0","provider":"Splunk","test":"true"}

Sample Response

HTTP/1.1 200 OK

  • Response headers: Default headers

  • Response body: Empty

Submit Request for Events Data

 

Description

  • The Client submits a request to Control at the URL on the “Setup > Splunk” page to get events data.

  • The request body includes a checkpoint previously returned by Control that indicates the state of events data that the Client already has. The initial value of the checkpoint (for first request) is zero.

  • Control responds with a polling URL while it prepares the requested events data. The Client should use the polling URL to check the status of events data.

Endpoint

  • POST /services/data/v2/event

  • Success Response:

    • 202 Accepted.

Sample Request

  • Method: POST

  • URI: /services/data/v2/event

  • Request headers:

Content-type: application/json; charset=UTF-8 Authorization: WSEvents

OTdTTzZlMnFzU0RBSTlwbFo1TnFyOjZjWTBVeU50VmtvSGdWS25CbW4xMXdUcXh6bkN0NjZNb3 ZhQ1lMVk9KNzg9

  • Request Body:

{"version":"3.0","provider":"Splunk","checkpoint":"236432"}

Sample Response

  • Success Response:

    • HTTP/1.1 202 Accepted

  • Response headers:

Content-Type: application/json

  • Response Body:

{"poll":"/services/data/v2/request/dcaf3c2f-2ff4-4f28-b487-588754463734"}

 

Polling after Submitting Requests

 

Description

  • Use the Polling URL that the Client received from Control to check the status of events data preparation. Polling uses a HEAD request.

  • When polling reveals that the data isn't ready, wait 30 seconds before polling again.

Endpoint

  • HEAD /services/data/v2/request/{requestToken}

  • Success Response

    • 202 Accepted (Still preparing data)

    • 200 OK (data is ready)

Sample Request

  • Method: HEAD

  • URI: /services/data/v2/request/dcaf3c2f-2ff4-4f28-b487-588754463734

  • Request headers:

Authorization: WSEvents

OTdTTzZlMnFzU0RBSTlwbFo1TnFyOjZjWTBVeU50VmtvSGdWS25CbW4xMXdUcXh6bkN0NjZNb3 ZhQ1lMVk9KNzg9

  • Request Body: Not Applicable

Sample Response

  • HTTP/1.1 200 OK

  • Response headers: Default headers.

  • Response Body:

{"poll":"/services/data/v2/request/dcaf3c2f-2ff4-4f28-b487-588754463734"}

 

Get Events Data

 

Description

  • Once polling returns a 200 response, use the same polling URL with a GET request to fetch the events data.

  • Control sends data in batches of 1000 events per one request/response.

  • The response includes 1000 events as Json.

  • Includes the new checkpoint in the "X-Ws-Checkpoint" response header.

  • Number of events returned in the response is in "X-Ws-Num-Rec" header.

  • Wait 15 minutes before checking for new data under the following conditions:

    • 204 (no more new data) response is received for this GET request.

    • The value of X-Ws-Num-Rec header, that contains the number of events included in response is less than 1000. Since the number of events are less than the normal batch size (1000), there are no more new events as of the time when the response was sent.

​​​​​​​Endpoint

  • GET /services/data/v2/request/{requestToken}

  • Success Response:

    • 204 No Content (No more new data from last checkpoint)

    • 200 OK (includes data in response)

Sample Request

  • Method: GET

  • URI: /services/data/v2/request/dcaf3c2f-2ff4-4f28-b487-588754463734

  • Request headers:

Authorization: WSEvents

OTdTTzZlMnFzU0RBSTlwbFo1TnFyOjZjWTBVeU50VmtvSGdWS25CbW4xMXdUcXh6bkN0NjZNb3 ZhQ1lMVk9KNzg9

  • Request Body: Not Applicable

Sample Response

  • HTTP/1.1 200 OK

  • Response headers:

Content-Type: application/json X-Ws-Num-Rec: 1000 X-Ws-Checkpoint: 237816

  • Response Body

{"events":[{{"username": "John Doe", "description": "John Doe updated DesktopPool \"TestPool\": changed 'Desktop Number update' from \"20\" to \"50\"", "eventType": "Admin", "dateTime": "06/18/2019 08:59:09.875", "eventName": "General", "location": "California", "device": "Browser", "email": "[email protected]", "severity": "Info"}]}

 

Example Python Script

 

A sample Python test script, EventsTestScript.py is attached to this document as a .zip file.

EventsTestScript
3.06 KB