Integrate Events API with a SIEM tool
Elite Plus Elite Enterprise 
Business This version of Events APIs will be deprecated soon. We recommend inSync administrators to use the enhanced version of Events API for exporting inSync events. For more information, see Events APIs to export inSync events.
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
- Enable the option to export events from the inSync Management Console. For more information, see Enable export of events in inSync.
- Generate a token to access Events API. For more information, see Use Events API to export events from inSync.
- Access Events API using the script and receive a response in the desired format.
- Save the response to a local drive.
- 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.
- 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
- Log on to the inSync Management Console as an inSync Cloud administrator.
- On the inSync Management Console menu bar, click
> Settings. The Settings page appears. - Click the inSync APIs tab. The Access token for inSync APIs page appears.
- Click Copy Token. The token is copied to your clipboard.
The Copy Token button is available only when the authentication token is valid. - If the token has expired, then click Create New Token and run the following steps:
- In the Expire on field, specify the expiry date of the authentication token.
- Click Done.
- 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
- Request URL:
- To obtain response in the CEF format: https://insyncapi-cloud.druva.com/api/events/v1?format=CEF
- To obtain response in the Syslog format: https://insyncapi-cloud.druva.com/api/events/v1?format=Syslog
- Request_Headers: Authorization = <LOGIN CREDENTIALS>
Following is a sample query to access the Events API in CEF format:
requests.get('https://insyncapi-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.
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.
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. |