Skip to main content

 

Druva Documentation

Integrate Events API with a SIEM tool

inSync Cloud Editions: File:/tick.png Elite Plus File:/tick.png Elite File:/cross.png Enterprise File:/cross.png Business

You can configure Security Information and Event Management (SIEM) tools like Splunk, ArcSight, and so on to consume inSync events. Events API enables inSync administrators to export inSync events in the following formats: 

  • Common Event Format (CEF)
  • Syslog format

Configure your SIEM tool to ingest inSync events exported in the CEF and Syslog formats for your further analysis.

Proposed Workflow

SIEM Tool.png

  1. Enable the option to export events from the inSync Management Console. For more information, see Enable export of events in inSync.
  2. Generate a token to access Events API. For more information, see Use Events API to export events from inSync.
  3. Access Events API using the script and receive a response in the desired format.
  4. Save the response to a local drive.
  5. Configure your SIEM tool to watch the directory where inSync events are saved and upload it for further processing. For technical assistance, contact Druva Support.
  6. Make successive Events API calls periodically using the Progress cookie received in the previous Events API response to get unique set of new inSync events generated over time. SIEM tool file watcher keeps track of the updated events and exports the events to your SIEM tool.

Pre-requisites

Ensure that the inSync Cloud administrator has enabled the option to export events. For more information, see Configure inSync to export events.

Procedure

Step 1: Generate a token to access Events API

inSync uses HTTP Basic authentication for API requests. inSync Cloud administrator can create the authentication information from the inSync Management Console.

The authentication information consists of the following components:

  • Username: Email ID of the inSync Cloud administrator who creates the authentication token.
  • Password: Authentication token that is generated.

inSync stores the authentication information in the database, that is encrypted with the ekey of your organization. Whenever you request to access the API, you must specify the username and the password.

Procedure

To obtain the authentication information:
  1. Log on to the inSync Management Console as an inSync Cloud administrator.
  2. On the inSync Management Console menu bar, click wheel.png > Settings. The Settings page appears.
  3. Click the inSync APIs tab. The Access token for inSync APIs page appears.
  4. Click Copy Token. The token is copied to your clipboard.
    The Copy Token button is available only when the authentication token is valid. 
  5. If the token has expired, then click Create New Token and run the following steps:
    1. In the Expire on field, specify the expiry date of the authentication token.
    2. Click Done.
  6. Copy the token and retain it for requesting access to the API.

Note: By default, the token is valid for 30 days. The token's expiry date can be anywhere between 1 day to 365 days. You can create a new token even if the existing token is valid, if you feel that the token is compromised.

Step 2: Access Events API through script

inSync uses basic authentication, where an inSync Cloud administrator has to provide username and password to authenticate each Events API request.

Access Events API

Access Events API by running a query to get response in CEF or Syslog format.

Header Request for APIs

Following is a sample query to access the Events API in CEF format:

requests.get('https://cloud.druva.com/api/events/v1?format=CEF', auth=('<Username>', '<Password>'), cookies = {"progress": "<cookie value>"})

where,

  • <Username> - Email address of the inSync administrator who generated the token or authentication information in Step 1: Obtain authentication information.
  • <Password>- API access token, generated in Step 1: Obtain authentication information.
  • <cookie value> - Progress cookie is received in the previous Events API response. Use progress cookie to get unique set of new inSync events in your subsequent Events API call.

Note: You will receive the progress cookie in an Events API response. While making the first Events API  call only provide your authentication details.

CEF Response Output format

Following is a sample output of Events API in CEF format:

"Sep 21 2017 13:41:14 cloud.druva.com CEF:0|Druva|inSync|1||Admin Audit Trail|6|suser=cloud.admin@druva.org dvchost=Admin’s Mac mini cs2Label=ClientVersion cs2=5.9.5r54841 deviceFacility=6 cs3Label=ClientOS cs3=Mac OS X duid=1 deviceExternalId=80 outcome=Admin Event cs1Label=EventDetails cs1=Device:cloud.admin@druva.org initiated backup for a device Admin’s Mac mini deviceTranslatedAddress=192.168.0.0 cn1Label=ProfileID cn1=1 cs5Label=ProfileName cs5=Default duser=Ernie",

CEF response output consists of header attributes and extension attributes.

cef_log_value.png

Header attributes

CEF response consists of the following attributes in the Header part:

Attribute Name Description
Timestamp

The date and time when the event was generated.

Format: MMM DD YYYY HH:MM:SS

Hostname Fully Qualified Domain Name (FQDN)of the originator that sent the
CEF message. The domain name of inSync Cloud or inSync GovCloud.
CEF Version The version is zero.

Value: 0

Device Vendor The name of the API vendor.

Value: Druva

Device Product The name of the API vendor's product.

Value: inSync

Event API Version The current version of inSync Events API.
Event Class ID The identifier for the event.
Name The exported inSync event type.

For the list of events, see Supported inSync events.

Severity The severity level of the event as defined in inSync.
Extension Attributes Extension attributes in a key-value pair. For the list of all the extension attributes received in the response, see Extension Attribute Field Mapping for CEF Format.

Extension Attribute Field Mapping for CEF Format

The following table lists the mapping of attributes in CEF format with JSON format.

Attribute Name in JSON format Attribute Name in CEF format Description
EventDetails cs1/cs1Label

Additional details about the event occurred.

Example, if it is a backup event, details such as the number of files backed up,  files missed, time for backup, and so on.

EventState outcome

The state of the inSync event.

For example, event triggered by an administrator. To view list of different states, see Supported inSync events.

Initiator suser

The initiator of the event.

For example, manual backup triggered by a user named Ernie Carter.

In case of a system event, the initiator is the name of the system.

ErrorLogFullTrace msg Error details
IPAddress deviceTranslatedAddress

The IP address of the device on which the event occurred.

In case of an admin event, IP address of the device on which the administrator performed the inSync activity is displayed.

ProfileID cn1/cn1Label inSync assigned identifier of the inSync profile associated with the user, for whom the event occurred.
Profile Name cs5/cs5Label The name of the inSync profile associated with the user, for whom the event occurred.
inSyncUserID duid inSync assigned identifier of the user associated with the event.
inSyncUserName duser The name of the inSync user associated with the event.
inSyncDataSourceID deviceExternalId inSync assigned identifier of the user device on which the event occurred.
inSyncDataSourceName dvchost The data source name on which the event occurred.
ClientVersion cs2/cs2Label The inSync Client version on the user device.
ClientOS cs3/cs3Label The OS on which the inSync Client is installed.
Facility deviceFacility The facility number as defined in inSync Management Console Events API settings. The default value is 23.

Syslog Response Output format

Following is a sample output of Events API in Syslog format:

"<54>1 2017-09-21T13:41:14Z cloud.druva.com Druva inSync - -  Initiator=cloud.admin@druva.org inSyncDataSourceName=Admin’s Mac mini ClientVersion=5.9.5r54841 EventType=Admin Audit Trail ClientOS=Mac OS X inSyncUserID=1 inSyncDataSourceID=80 EventState=Admin Event EventDetails=Device:cloud.admin@druva.org initiated backup for a device Admin’s Mac mini IP=192.168.0.0 ProfileID=1 ProfileName=Default inSyncUserName=Ernie",

Syslog response output consists of header attributes and extension attributes.

syslog_response_value.png

Header attributes

Syslog response consists of the following attributes in the Header part:

Attribute Name Description
PRIVAL

The Priority value (PRIVAL), and represents both the Facility and Severity.

PRIVAL is derived using the following formula:

(Facility number x 8)+Severity

VERSION The current version of inSync Events API.
TIMESTAMP

The date and time when the event was generated.

Format: yyyy-mm-ddThh:mm:ssZ

HOSTNAME Fully Qualified Domain Name (FQDN)of the originator that sent the
syslog message. The domain name of inSync Cloud or inSync GovCloud.
APP-NAME

The name of the Events API publisher.

Value: Druva inSync

PROCID The identifier for the event.
Extension Attributes Extension attributes in a key-value pair. For the list of all the extension attributes received in the response, see Extension Attribute Field Mapping in Syslog format.

 Extension Attribute Field Mapping in Syslog format

Syslog response consists of the following attributes in the Extension part. The response in Extension is similar to that received in the JSON format.

Extension Attribute Name Description
EventType

The exported inSync event type.

For the list of events, see Supported inSync events.

EventState

The state of the inSync event.

For example, event triggered by an administrator. For the full list, see Supported inSync events.

EventID

The identifier to inter-relate multiple associated events.

Example, all events associated with a backup event like Backup initialized, Backup paused, and Backup Success.

Initiator

The initiator of the event.

For example, Manual backup triggered by a user named Ernie Carter.

In case of System event, the initiator will always be the name of the system.

EventDetails

Additional details about the event occurred.

Example, for a backup event, details such as the number of files backed up, files missed, time required for backup, and so on.

IP

The IP address of the device on which the event occurred.

In case of an admin event, IP address of the device from which the inSync administrator  performed the inSync activity is displayed.

ProfileID inSync assigned identifier of the inSync profile associated with the user, for whom the event occurred.
ProfileName The name of the inSync profile associated with the user, for whom the event occurred.
inSyncUserID inSync assigned identifier of the user associated with the event.
inSyncUserName The name of the inSync user associated with the event.
inSyncDataSource ID inSync assigned identifier of the user device  on which the event occurred.
inSyncDataSourceName The data source name on which the event occurred.
ClientVersion The inSync Client version on the user device.
ClientOS The OS on which the inSync Client is installed.
  • Was this article helpful?