cloudsoc management api - broadcom...2. on the cloudsoc menu bar, click your username and choose s...

CloudSOC Management API Symantec CloudSOC Tech Note

Tech Note — CloudSOC Management API

Copyright statement Copyright (c) Broadcom. All Rights Reserved.

The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries. Broadcom, the pulse logo, Connecting everything, and Symantec are among the trademarks of Broadcom. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. For more information, please visit www.broadcom.com. Broadcom reserves the right to make changes without further notice to any products or data herein to improve reliability, function, or design. Information furnished by Broadcom is believed to be accurate and reliable. However, Broadcom does not assume any liability arising out of the application or use of this information, nor the application or use of any product or circuit described herein, neither does it convey any license under its patent rights nor the rights of others.

. 2

http://www.broadcom.com/http://www.broadcom.com/


Table of Contents

Introduction

Supported authentication methods

Creating an API key

Basic authentication

Getting logs

Sample request

Supported filters

Sample responses

Sample response for Investigate

Sample response for Detect (incidents)

Sample response for Detect (ThreatScore)

Response fields

Sample queries for each app

Investigate Logs

CloudSOC history logs

Detect incidents

Detect ThreatScore

Audit incidents

Audit ThreatScore

Querying the next page of logs

Example Windows Powershell 5.1 script

Logs response codes

Usage guidelines

Logs schema

Common fields

Browser and device information

. 3


Location information

Gatelets additional fields

Securlet activity log structures

Common fields

Activities on non-S3 objects

Activities on S3 objects

Google Drive

Create a file or folder

Modify a file or folder

Upload a file or folder

Share a file or folder

Unshare a file or folder

Rename a file or folder

Trash a file or folder

Restore a file or folder from Trash

Permanently delete a file or folder

Role change

Delete user

Grant permission on an app

Revoke permission on an app

Successful login

Suspicious login

Failed login

Logout

Salesforce

Activities on Salesforce standard/custom objects

Fields common to login, logout and failed login events

. 4


Successful login

Unsuccessful login

Salesforce reports/dashboards

CloudSOC applications

Protect application

Access enforcement - gateway

File sharing - Securlet

File sharing - gateway

File transfer - gateway

ThreatScore

Detect application

Incident logs

User ThreatScore logs

Audit API

Authentication

Getting Audit datasources

Sample datasources request

Sample datasources response

Getting Audit services

Sample Audit services request

Supported Audit services filters

Sample Audit services response

Getting Audit users

Sample Audit users request

Supported Audit users filters

Sample Audit users response

Getting Audit usernames

. 5


Sample Audit usernames request

Supported Audit usernames parameters

Sample Audit usernames response

Getting Audit summary information

Sample Audit summary request

Supported Audit summary filters

Sample Audit summary response

Audit response codes

Protect APIs

Authentication

Getting Protect policies

Sample policy request

Supported policy filters

Sample policy response

Protect response codes

Protect policy schema

Policy common fields

Gatelet policy additional fields

Securlets policy additional fields

Data exposure via Securlets

Access monitoring via Securlets

ThreatScore policy additional fields

Revision history

. 6


Introduction

The CloudSOC API describes the various events that are recorded by CloudSOC applications. The API facilitates the easy integration of CloudSOC with your apps and tools.

Supported authentication methods

The CloudSOC API supports Basic Authentication using API Keys.

CloudSOC API keys inherit the access privileges of the CloudSOC user who configured them. You can use this feature to limit API keys to specific domains, SaaS services, and CloudSOC apps by creating a CloudSOC admin user specifically to enable the API key, and assigning it an access profile that limits its access. See the CloudSOC Tech Note Using CloudSOC Access Profiles for more information.

Creating an API key

To create a per-user API key:

1. Log in to CloudSoC using your administrator credentials.

2. On the CloudSOC menu bar, click your username and choose Settings.

3. On the Settings page, click the API Keys tab to bring it to the front.

4. To create a new API Access Key, enter a descriptive name for the new key and click Add New API Key.

5. In the API Keys List, click the download button for the new key.

. 7


6. Open the file in a text editor and record the following information for the key:

○ Key ID ○ Key Secret ○ Tenant

Basic authentication

The CloudSOC API supports Basic Access Authentication. Use the Key ID and Key Secret as your username and password respectively. The API keys are allocated on a per-user basis and inherit the permissions granted to that user.

Getting logs

Sample request

Note: Use the following Host URLs:

● For the US-based production cloud: api-vip.elastica.net

● For the EU-based production cloud: api.eu.elastica.net

Also note that the request header “X-Elastica-Dbname-Resolved: True” is required for successful authorization.

. 8

GET //api/admin/v1/logs/get/ HTTP/1.1

Host: api-vip.elastica.net

Authorization:

Content-Type: application/javascript

X-Elastica-Dbname-Resolved: True


Supported filters

The CloudSOC API supports the following filters that you use to narrow down the number of events returned by the request. Dates, wherever required, must follow the ISO8601 format.

. 9

Filter Nature Supported By (app - subtype)

Type and Examples

app mandatory string

One of the following: ● investigate ● detect ● audit

subtype mandatory string

Can be one of the following:

● all (for app=investigate only) ● incidents (for app=detect and

app=audit only)

● threatscore (for app=detect and app=audit only)

user optional, case sensitive

● investigate - all ● detect - incidents ● detect - ThreatScore™ ● audit - incidents ● audit

string or list (array) ● string: for 1 user ● array: for multiple users

service optional ● investigate - all ● detect - incidents

string or list (array) ● string: for 1 app ● array: for multiple apps

service=Elastica

OR

service=Elastica,Box


Supported Filters, Continued

. 10


Type and Examples

severity optional ● investigate - all ● detect - incidents ● detect - ThreatScore ● audit - incidents ● audit - ThreatScore

string or list (array) ● string: for 1 severity level ● array: for multiple severity levels

severity=informational

OR

severity=error,critical

inserted_ timestamp

optional ● investigate - all ● detect - incidents ● detect - ThreatScore ● audit - incidents ● audit - ThreatScore

string or list (array) ● string: for 1 timestamp ● array: for bounded range

For investigate, inserted timestamp

range must be less than 1 month.

inserted_timestamp=2015-01-01T00:00:

00

OR

inserted_timestamp=2015-01-01T00:00:

00,2015-02-01T00:00:00

created_ timestamp

Optional except when app= investigate

● investigate - all ● detect - incidents ● detect - threatscore ● audit - incidents ● audit - ThreatScore


For investigate, created timestamp

range must be less than 6 months.

created_timestamp:2015-01-01T00:00:0

0

OR

created_timestamp=2015-01-01T00:00:0

0,

2015-02-01T00:00:00

updated_ timestamp

optional ● detect - incidents ● detect - threatscore ● audit - incidents ● audit - ThreatScore


updated_timestamp:2015-01-01T00:00:0

0

OR

updated_timestamp=2015-01-01T00:00:0

0,

2015-02-01T00:00:00


Supported Filters, Continued

. 11


Type and Examples

search optional ● investigate - all ● detect - incidents

string

search=Login

source optional ● detect - incidents ● detect - ThreatScore

GW, API

limit optional, default: 1000 max: 1000

● investigate - all ● detect - incidents ● detect - ThreatScore

integer

limit=10

sort_inserted_timestamp

optional, default: sort on created timestamp

● investigate - all ● detect - incidents

string

sort_inserted_timestamp=asc OR

sort_inserted_timestamp=desc

Note: Logs obtained for app=detect and subtype=threat_score are always sorted by updated_timestamp. You can either provide this parameter or sort but not both. If none is provided, sort will be considered with its default value.

sort (on: created_ timestamp)

optional default: asc

● investigate - all ● detect - incidents

string

sort=asc OR sort=desc

Note: Logs obtained for app=detect and subtype=threat_score are always sorted by updated_timestamp.

threat_score optional ● detect - incidents ● detect - ThreatScore

number or list (array) ● string: for minimum threat_score (max

will be considered 100) ● array: for bounded threat_score

threat_score=10

OR threat_score=10,15 (score range between 10 and 15 both inclusive)


Sample responses

The CloudSOC API returns a list of chronologically ordered (oldest first) logs as shown in the following.

Sample response for Investigate

. 12

{

"status": "success",

"next_url":

"/api/admin/v1/logs/get/?created_timestamp=2018-11-14T00%3A00%3A00&subtype=all&app=Investigate&limit=100&next_ptr=1542271093000&from=100",

"meta": {

"from": 0,

"total": 12,

"limit": 10

},

"logs": [{

"browser": "Firefox",

"req_uri": "...",

"severity": "informational",

"facility": "Google Drive",

"user": "[email protected]",

"object_type": "Folder",

"req_size": "2387",

"user_agent": "...",

"device": "Mac OS",

"host": "50.174.78.44",

"location": "San Jose (United States)",

"referer_uri": "...",

"created_timestamp": "2020-04-16T06:10:15",

"message": "normal.",

"test_id": "Ann OMalley",

"user_name": "Fawls Poe Stivaram 0",

"inserted_timestamp": "2020-04-16T06:10:15",

"activity_type": "Create"

}, ...]

}


Sample response for Detect (incidents)

. 13

{


"next_url":

"/api/admin/v1/logs/get/?created_timestamp=2018-11-14T00%3A00%3A00&subtype=all&app=Detect&limit=100&next_ptr=1542271093000&from=100",

"meta": {

"from": 0,

"total": 3,

"limit": 1000

},

"logs": [

{

"updated_timestamp": "2017-09-06T05:41:31",

"from_detect": 1,

"service": "Slack",

"severity": "medium",

"object_type": "Channel",

"ioi_code": "ANOMALOUSLY_FREQUENT_DELETES",

"source": "API",

"threat_score": "52",


"created_timestamps": "1504525039",

"_id": "+DObAMBLAE6mAAcwAFzzAJK2",

"user_name": "Test User",

"message": "From Last Incident: Large number of deletes. 2.0 in 4.0 minute(s).

6.1 standard deviations",


"activity_type": "Delete"

},

{


"from_detect": 1,

"service": "Google Drive",


"object_type": "File",

"ioi_code": "ANOMALOUSLY_LARGE_DELETES",

"source": "API",




"_id": "DO2bAWtLAHWmAI0wADryAJ1C",

"user_name": "QA Admin net",

"message": null,



},

{


. 14


"from_detect": 1,

"service": "Box, Google Drive, Microsoft Azure, Gmail",

"activity_type": "InvalidLogin",

"severity": "high",

"object_type": "Session",


"locations": "San Jose (United States), Karachi (Pakistan)",

"devices": [

"Mac OS X",

"Android"

],

"ioi_code": "TOO_MANY_INVALID_LOGINS",

"source": "GW",

"browsers": [

"Chrome",

"Firefox"

],

"hosts": "202.141.245.38",


"created_timestamps": "1504801203, 1532950596, 1536322042",

"_id": "rPqbAKRLACymAHswADXzALri",

"user_name": "Admin QA",

"message": null,

"inserted_timestamp": "2018-09-07T12:10:14"

}

]

}


Sample response for Detect (ThreatScore)

. 15

{


"next_url":

"/api/admin/v1/logs/get/?created_timestamp=2018-11-14T00%3A00%3A00&subtype=all&app=Detect&limit=100&next_ptr=1542271093000&from=100",

"meta": {

"from": 0,

"total": 3,

"limit": 1000

},

"logs": [

{


"from_detect": 1,

"service": "Slack",


"object_type": "Channel",

"ioi_code": "ANOMALOUSLY_FREQUENT_DELETES",

"source": "API",




"_id": "+DObAMBLAE6mAAcwAFzzAJK2",

"user_name": "Test User",

"message": "From Last Incident: Large number of deletes. 2.0 in 4.0 minute(s).

6.1 standard deviations",



},

{


"from_detect": 1,

"service": "Google Drive",


"object_type": "File",

"ioi_code": "ANOMALOUSLY_LARGE_DELETES",

"source": "API",




"_id": "DO2bAWtLAHWmAI0wADryAJ1C",

"user_name": "QA Admin net",

"message": null,



},

{


. 16


"from_detect": 1,

"service": "Box, Google Drive, Microsoft Azure, Gmail",

"activity_type": "InvalidLogin",

"severity": "high",

"object_type": "Session",


"locations": "San Jose (United States), Karachi (Pakistan)",

"devices": [

"Mac OS X",

"Android"

],

"ioi_code": "TOO_MANY_INVALID_LOGINS",

"source": "GW",

"browsers": [

"Chrome",

"Firefox"

],

"hosts": "202.141.245.38",


"created_timestamps": "1504801203, 1532950596, 1536322042",

"_id": "rPqbAKRLACymAHswADXzALri",

"user_name": "Admin QA",

"message": null,

"inserted_timestamp": "2018-09-07T12:10:14"

}

]

}


Response fields

The following fields are common for all CloudSOC Logs (in alphabetic order by field name):

. 17

Field Name Type Description

activity_type string Type of the action that’s being performed on the primary object: "Allow", "Add", “Create”, “Delete”.

browser string Name of the browser, derived from user agent.

created_timestamp timestamp Time at which the activity occurred. (ISO 8601 format)

device string Name of device, derived from user agent.

host string IP address of the client device.

_id string This is the unique identifier for the log.

inserted_timestamp timestamp Time at which the activity was recorded in the CloudSOC database. (ISO 8601 format)

location string Recorded location where the activity was performed.

message string Message describing the activity.

object_type string Type of the primary object to which the activity applies. e.g. "Account", "Site", “File”, “Folder”.

service string Application Name (for example, Box, Google Drive, Elastica). All activity logs under "service=Elastica" represent an audit-trail of configuration actions performed by CloudSOC administrators. They also include sign-in and sign-out failures of all CloudSoC users. These are the logs displayed on the CloudSOC History page.

severity string Event severity, as classified by CloudSOC. May be one of the following: (for Investigate)

● informational, error, warning, critical May be one of the following: (for Detect/Audit)

● low, medium, high

threat_score (for detect)

number ThreatScore associated against user/event

updated_timestamp timestamp Time at which the activity was last updated/modified - typically present only for Detect Reports. (ISO 8601 format)


Response Fields, Continued

Optional fields may be included in logs where pertinent to convey detailed information about the operation. See the Schema section for details.

Sample queries for each app

Here are some sample curl queries for each app type. Variables are shown in bold italic. Your timestamp will be different from the one shown in this script.

Investigate Logs

curl --basic --user key_id:key_secret -H “X-Elastica-Dbname-Resolved: True” https://api-vip.elastica.net/tenant/api/admin/v1/logs/get/?app=Investigate&subtype=all&created_timestamp=2020-08-25T00:00:00,2020-08-25T23:59:59&limit=100"

--output c:\curlapioutput.txt

CloudSOC history logs

CloudSOC history logs are a subset of the Investigate logs. You obtain history logs by adding the additional filter “service=Elastica ” as shown in the following.

curl --basic --user : -H “X-Elastica-Dbname-Resolved: True” https://api-vip.elastica.net//api/admin/v1/logs/get/?app=Investigate\&subtype=all\&service=Elastica\&limit=100\&[email protected]\&created_timestamp=

2017-06-01T00:00:00

. 18


user string Email ID of the responsible user.

user_agent string String that identifies the browser, client device and the OS etc.

Note: This field is an empty string for instances where the responsible log wasn’t generated via a browser, for example activities performed by Securlets.

user_name string Responsible user’s name in format.


Detect incidents

curl --basic --user : -H “X-Elastica-Dbname-Resolved: True” https://api-vip.elastica.net//api/admin/v1/logs/get/?app=Detect\&subtype=incidents\&service=Google%40Drive\&[email protected],[email protected]

Detect ThreatScore

curl --basic --user : -H “X-Elastica-Dbname-Resolved: True” https://api-vip.elastica.net//api/admin/v1/logs/get/?app=Detect\&subtype=threatscore\&threat_score=0,50

Note: The Detect incidents and Detect ThreatScore APIs return a maximum of 10,000 logs for a given set of query parameters. In order to fetch all the logs, you must use time-sliced queries, for example by adding the updated_timestamp parameters as shown in the following: updated_timestamp=2018-03-05T00:00:00,2018-03-08T00:00:00

The Detect incidents and ThreatScore APIs return aggregated results from Detect and Audit separately.

Audit incidents

curl --basic --user : -H “ X-Elastica-Dbname-Resolved:

True ” https://api-vip.elastica.net/ /api/admin/v1/logs/get/? app=Audit\&subtyp e=incidents\&service=Google%40Drive\&[email protected], [email protected]

Audit ThreatScore

curl --basic --user : -H “ X-Elastica-Dbname-Resolved:

True ” https://api-vip.elastica.net/ /api/admin/v1/logs/get/? app=Audit\&subtyp e=threatscore\&threat_score=0,50

. 19


Querying the next page of logs

When you query for logs, the response includes a next_url element whenever the initial query does not fetch all logs. Use that next_url to query for the subsequent log entries. In earlier CloudSOC releases, you would increment from and to arguments to fetch the subsequent log entries.

The following example demonstrates the use of next_url:

Your initial request for 100 Investigate logs:

/ /api/admin/v1/logs/get/?created_timestamp=2018-11-14T00:00:00&subtype=all&app=Investigate&limit=100

The API response:

Your request for the subsequent 100 logs (copied from the next_url in the API response):

/ /api/admin/v1/logs/get/?created_timestamp=2018-11-14T00%3A00%3A00&subtype=all&app=Investigate&limit=100&next_ptr=1542271093000&fr

om=100

. 20

{


"next_url": "/api/admin/v1/logs/get/?created_timestamp=2018-11-14T00%3A00%3A00&subtype=all&app=Investigate&limit=100&next_ptr=1542271093000&fr

om=100", "meta":{

"from": 0,

"total": 324865,

"limit": 100

},

"logs":[# 100 logs lists]

}


The API response with subsequent logs and also a new next_url:

Example Windows Powershell 5.1 script

If you are using the Microsoft Windows platform to query the CloudSOC API, you can use the following basic script to query using Powershell. This script outputs the API response data into a file named APIOUTPUT.TXT.

In the following script, YOUR_KEY_ID is the key identifier from the config.json, YOUR_KEY_SECRET is the secret from the config.json file, and YOUR_TENANT is the tenant name from the config.json file. All variables are shown in bold italic. Your timestamp will be different from the one shown in this script.

# Simple script to connect to Symantec using API

try

{

Write-Host "Attempting to query CloudSOC via API..." -ForegroundColor Green

# Variables

$keyid = "YOUR_KEY_ID" $keysecret = "YOUR_KEY_SECRET" $url =

"https://api-vip.elastica.net/YOUR_TENANT/api/admin/v1/logs/get/?app=Investigate&subtype=all&created_timestamp=2020-08-25T00:00:00,2020-08-25T23:59:59&limit=100"

# Encode credentials

$encodedCredentials =

[System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("$($keyid):$($keysecret)"))

Write-Host "DEBUG: base64 Creds = $($EncodedCredentials)" -ForegroundColor Yellow

# Build REST API header with authorization token

$authHeader = @{

. 21

{


"next_url": "/api/admin/v1/logs/get/?created_timestamp=2018-11-14T00%3A00%3A00&subtype=all&app=Investigate&limit=100&next_ptr=1542365249000&fr

om=200", "meta":{

"from": 100,

"total": 324865,

"limit": 100

},

"logs":[# 100 logs lists]

}


'Content-Type' = 'application/javascript'

'Authorization' = "Basic $($EncodedCredentials)"

'X-Elastica-Dbname-Resolved' = 'True'

}

# API call

Invoke-WebRequest -uri $url -Method Get -Headers $authHeader -Outfile

C:\APIOUTPUT.TXT -Passthru Write-Host "Successful query." -Foregroundcolor Green

}

catch

{

Write-Host "Error with API call. $($_.Exception.Message)" -Foregroundcolor Red

}

Logs response codes

Based on the outcome of the request, the CloudSOC API responds with one of the following response codes:

Usage guidelines

If the total number of logs is greater than one million, or if the API is used to continuously fetch near real time logs, we recommend that you use the following implementation for efficient querying:

● Let “marker” be the current marker on inserted_timestamp

● Limit the inserted_timestamp window to [marker, marker + 5 mins] for a given API call by adding filter on inserted timestamp

. 22

Code Meaning Description

200 OK Request processed successfully, data was returned in response to this request.

400 Bad Request We encountered an error while processing the request, possible causes are:

● Malformed JSON in request body. ● Invalid parameters provided in query. ● Unsupported filters provided.

401 Unauthorized This indicates an authentication failure. Retry with a new API key. (Settings > API Keys)

405 Method not allowed This indicate this http method is not supported


● Limit the created_timestamp window to [marker - 6 months, now] by adding filter on created_timestamp

● Add the “sort_inserted_timestamp=asc” argument, along with size=1000 to the API call

● When the API call returns with a total count > 1000, exhaustively fetch remaining logs by advancing next_url as described in Querying the next page of logs

● When all the logs are fetched for the 5 min window, advance the marker by 5 mins and repeat step 2 onwards. Ensure that the marker always stays behind time.now() by 5 mins to cater to latencies.

Logs schema

This section describes the schema of the logs returned by:

● Gatelets

● Securlets

● Various CloudSOC applications such as Detect and Protect.

. 23


Common fields

All activity logs carry some common fields and these were described earlier in the document under the section Response Fields. These are listed in the following again for your convenience.

. 24


_id string This is the unique identifier for the log.

service string Application Name (for example. Box, Google Drive, Elastica). All activity logs under ‘Elastica’ represent an audit-trail of configuration actions performed by the administrators.

user string Email ID of the responsible user.

user_name string Responsible user’s name in format.

severity string Event severity, as classified by CloudSOC. One of the following: (for Investigate)

● informational ● error ● warning ● critical

One of the following: (for Detect/Audit) ● low ● medium ● high

message string Text message describing the activity.

created_timestamp timestamp Time at which the activity occurred. (ISO 8601 format)

inserted_timestamp timestamp Time at which the activity was recorded in CloudSOC database. (ISO 8601 format)

updated_timestamp timestamp Time at which the activity was last updated/modified - typically present only for Detect Reports. (ISO 8601 format)

object_type string Type of the primary object to which the activity applies. e.g. "Account", "Site", “File”, “Folder”.

activity_type string Type of the action that’s being performed on the primary object: "Allow", "Add", “Create”, “Delete”.

source string The source of the activity log. Currently set to “API” or “GW” to indicate whether the activity log was reported by a securlet or gatelet.


Browser and device information

The Gatelets always report the browser and device information (as parsed from the user-agent string). Some securlets report this information only for certain events (e.g. Salesforce Securlet for Login activities, AWS Securlet for all activities).

Location information

The Gatelets always report the location information. The location information is derived from the source IP (i.e. host) of the client device that makes a request. Some securlets do report the source IP for certain events (e.g. Salesforce and Google Drive for Login activities, Box and AWS securlets for all activities).

. 25


user-agent string User-agent string as reported by the browser or application. The browser and device info (see in the following) is determined from the user-agent string.

browser string Name of the browser, derived from user agent.

device string Name of device, derived from user agent.


host string IP address of the client device. This address is geo-coded to derive the location information (see in the following). Note that this information is not always accurate.

location string Recorded location from where the activity was performed. This is in the form “City (Country)”.

city string City of the location from where the activity was performed.

country string Country of the location from where the activity was performed.

latitude float Latitude of the location

longitude float Longitude of the location


Gatelets additional fields

The Gatelets report the following additional fields.

Securlet activity log structures

This section lists the structure of the activity logs reported by three Securlets as examples, each representing a category of applications.

● IaaS: Amazon Web Services ● File Sharing: Google Drive ● CRM: Salesforce

You can verify the activity logs by going to Investigate, selecting the Securlet in Filters, exporting the results as CSV, and comparing them with the API output.

Amazon Web Services

The AWS securlet reports activities on S3 buckets and non-S3 objects such as EC2, RDS, SNS, SQS etc.

. 26


object_name string Name of the object in question. Typically, this is the name of a file or folder that is being created, deleted, shared, renamed, moved etc. Not present in all activity logs.

shared_with string List of emails of the users with which a file or folder is being shared. Not present in all activity logs.

file_size Integer Size in bytes of a file being uploaded or downloaded. Not present in all activity logs.

req_uri string The request URI.

req_size integer Size in bytes of the request.

resp_size integer Size in bytes of the response.

referer_uri string The referer URI.


Common fields

These fields are common to activities on S3 and non-S3 objects.

Activities on non-S3 objects

. 27


object_type string Type of the object on which the activity was performed. Some examples are: Instance, Security Group, Volume, API Key, File/Folder etc

activity_type string Type of the activity that was performed. Some examples are: Create, Delete, List, Delete

region string The AWS region in which the activity was performed

event_service string The service on which the activity was performed, e.g. EC2, RDS, S3 etc

user_type string Root, AssumedRole etc

caution string Fixed string. Set to “Event is performed via assumed role and user cant be detected” when user_type is “AssumedRole”.

error_code integer Error code, if an error occurred when the activity was performed

error_string string Error string, if an error occurred when the activity was performed

Request.xxx string Various request parameters. Name of the parameter and content depend on the object_type and activity_type.

Response.xxx string Various response parameters. Name of the parameter and content depend on the object_type and activity_type.

Browser and Device

strings See the Browser and Device Information section.

Location strings See the to Location Information section.


message string “User {email} {activity_type:past tense} {object_type}” e.g. User [email protected] created security group, User [email protected] attached volumes etc


Activities on S3 objects

Google Drive

This section lists all the activities reported by the Google Drive Securlet.

Create a file or folder

. 28


message string “User {activity_type:past tense} {object_type} from/on/named bucket {Source Bucket Name} in {region} using {Operation Method}”

Source Bucket Name

string Name of the S3 bucket for which the activity is being reported

Source Bucket Owner

string Owner of the S3 bucket

file_size integer Size of the object retrieved from or uploaded to the bucket.

Operation Method string Method used to access the bucket. One of: SOAP, REST, WEB.

Field Name Type Value

message string “User created {object_type} {name}”

object_type string “File” or “Folder”

activity_type string “Create”

name string Name of the file or folder that was created

user string User who created the file or folder

file_size integer (optional) size of the file if reported by Drive API

Resource_Id String Unique identifier for the file/folder.


Modify a file or folder

Upload a file or folder

. 29


message string “User {Modified_by} modified {object_type} {name}”


activity_type string “Edit”

name string Name of the file or folder that was modified

Modified_by string Name of the user that modified the file/folder

user string Owner of the file or folder




message string “User uploaded {object_type} {name}”


activity_type string “Upload”

name string Name of the file or folder that was uploaded

user string User who uploaded the file or folder




Share a file or folder

Unshare a file or folder

. 30


message string “User shared {name}”


activity_type string “Share”

name string Name of the file or folder that was shared

Role string Role of the collaborator on the file/folder in question

shared_with string The collaborator with whom the file or folder is shared. For public and “all internal” sharing, the exact text is as follows:

- For searchable share with anyone, the text value is ‘Public’ - For with link share with anyone, the text value is 'Public (with link)' - For searchable share with people in the company, text value is ‘All

Internal’ - For with link share with people in the company, text value is ‘All

Internal (with link)' For any internal or external collaborators, the text value will be the email address of the collaborator.

user string The owner of the file or folder




message string “User unshared {name}”


activity_type string “Unshare”

name string Name of the file/folder that was unshared

shared_with string The collaborator with whom the file or folder was unshared.





Rename a file or folder

Trash a file or folder

. 31


message string “User renamed {object_type} from {name_before} to {name}”


activity_type string “Rename”

name string Current name of the file/folder that was renamed

name_before string Previous name of the file/folder that was renamed





message string “User trashed {name}”


activity_type string “Trash”

name string Name of the file/folder that was trashed

severity string “warning”





Restore a file or folder from Trash

Permanently delete a file or folder

. 32


message string “User restored {name}”


activity_type string “Restore”

name string Name of the file/folder that was restored





message string “User permanently deleted {name} from trash”


activity_type string “Trash”

name string Name of the file/folder that was permanently deleted






Role change

Delete user

Grant permission on an app

. 33


message string “User changed permission on {object_type} {name}”


activity_type string “Role”

name string Name of the file/folder on which the collaborator’s role was changed

shared_with string The collaborator with whom the file or folder is shared.

Role string Current role of the collaborator i.e. writer, reader or commenter

PreviousRole string Previous role of the collaborator i.e. writer, reader or commenter




message string “User {user} deleted”

object_type string “User”

activity_type string “Delete”



message string “User {user} granted permission to app {application}”

object_type string “Application”

activity_type string “Authorization”

application string Name of the application for which permission was granted to the user in question.

user string Email address of user for whom the permission was granted.

Has Access To string One or more data access permissions granted to the app, for example access to drive or google+ information etc

client_id string Unique client id of the application


Revoke permission on an app

Successful login

Suspicious login

. 34


message string “Permission on app {application} revoked for user {user}”

object_type string “Application”

activity_type string “Revocation”

application string Name of the application on which the permission was revoked for the user in question

user string Email address of the user for whom the permission was revoked.

Has Access To string One or more data access permissions granted to the app, for example access to drive or google+ information etc

client_id string Unique client id of the application


message string “User {user} logged in using {method}”

object_type string “Session”

activity_type string “Login”

method string Type of login: “google password”, “saml-based SSO”

user string Email address of the user that logged in

Host and location string See Location Information.


message string “Suspicious login by user {user} using {method}”



method string Type of login: “google password”, “saml-based SSO”

user string Email address of the user that logged in



Failed login

Logout

. 35


message string “User {user} login failed due to {failure_type}”


activity_type string “InvalidLogin”

failure_type string Type of the login failure. One of: ● 'invalid password', ● 'access code disallowed', ● 'missing second factor', ● 'invalid second factor', ● 'account disabled', ● 'unknown'

user string Email address of the user that attempted to login

Host and location string See Location Information section.


message string “User {user} logged out”


activity_type string “Logout”

user string Email address of the user that attempted to login



Salesforce

This section lists all the activities reported by the Salesforce Securlet.

Activities on Salesforce standard/custom objects

. 36


message string “User {activity_type:past tense} {object_type} with name {Name/Id/CaseNumber etc} {Object Name}” e.g. User created contact named ‘xyz’ User deleted case numbered 100123

object_type string Name of the Salesforce standard or custom object upon which activity has been performed. Example: Account, Lead, Opportunity etc

activity_type string Create, Delete, Update

severity string “informational”

user string Email address of the user who performed the activity.

object_url string URL of the object in question.

Object Name string Name of the Salesforce standard or custom object.


Fields common to login, logout and failed login events

Successful login

. 37


LoginTime string Time at which Login request was performed.

LoginType string The type of login, for example, Application, Remote Access 2.0

LoginUrl string URL from which the login request is coming.

Platform string Operating system on the login machine.

Application string The application used to access the organization. Example: Browser, Salesforce Developers, AppExchange

ApiType string Indicates the API type, for example Soap Enterprise, N/A.

Browser string The current browser version.

ClientVersion string Version of the API client.

ApiVersion string Displays the API version used by the client

NetworkId string The ID of the community that the user is logging in to. Available, if Salesforce Communities is enabled for your organization.


Status string Displays the status of the attempted login. Status is either success or a reason for failure. Example: Success, Invalid Password, User is Inactive, Failed: Computer activation required


message string “User {user} logged in successfully via {Application}”



user string Email address of the user that logged in.


Unsuccessful login

Salesforce reports/dashboards

CloudSOC applications

Protect application

This section describes the logs generated by the Protect application for the different policy types. All these logs are generated with severity set to that configured in the policy or CIQ profile.

Access enforcement - gateway

. 38


message string “Failed login attempt by {user}, Reason: {Status}”


activity_type string “InvalidLogin”

user string Email address of the user that made login attempt.

Message String User {activity_type:past tense} with Name/Title {Object_type}

Export Report(csv) string Export/Download URL to report data in CSV format.

Export Report(xls) string Export/Download URL to report data in XLS format.

Object_type string Report/Dashboard

Activity_type string Create, Update, Delete


message string “[ALERT] {user} attempted access to cloud apps using Platform: {platform}, Version: {platform_version} and Browser: {browser}, Version: {browser_version} violating policy: “{policy_violated}”

activity_type string “Policy Violation”

policy_violated string Name of the policy that was violated.

policy_type string “AccessEnforcement”

policy_action string “ALERT”

actions_taken string Response actions taken. One or more of: email, sms, ticketing_email, block.


File sharing - Securlet

. 39


message string “[ALERT] User shared or uploaded a document named {object_name} which violated the content policy : {policy_violated}”


policy_type string “FileSharingAPI”


object_name string Name of the document that violated the policy in question

content_vulerability string List of content vulnerabilities in the document (JSON).

Resource_Id string Unique identifier for the file/folder.


File sharing - gateway

File transfer - gateway

. 40


message string “[ALERT] {user} attempted to share content: “{object_name}” with external user(s): “{shared_with}” violating policy: “{policy_violated}”


policy_type string “FileSharingGateway”



shared_with string Email addresses of users with which the document is being shared


actions_taken string Response actions taken. One or more of: email, sms, ticketing_email, block.

scope string Name of the document that violated the policy in question


message string “[ALERT] {user} attempted to {transfer_type} content: “{object_name}” violating policy: “{policy_violated}”


policy_type string “FileTransfer”




actions_taken string Response actions taken. One or more of: email, sms, ticketing_email, block

scope string Name of the document that violated the policy in question


ThreatScore

Detect application

This section describes the logs emitted by the Detect application. There are two types of logs emitted by the Detect application, one is for the incidents and the other is for the per-user ThreatScore.

. 41


message string “[ALERT] User performed anomalous activities that violated policy: {policy_violated}


policy_type string “ThreatScore”


policy_action string One of “ALERT”, “BLOCK”

blocked_apps string “ALL” or the name of a specific SaaS service that is blocked.


Incident logs

The following fields are in incident logs in addition to the common fields documented earlier (source, service, severity, user, user_name, created_timestamp, inserted_timestamp, updated_timestamp, host).

User ThreatScore logs

These logs are emitted per user and capture the overall ThreatScore for that user. The following fields will be in the ThreatScore logs in addition to the common fields documented earlier (source, user, user_name, created_timestamp, inserted_timestamp, updated_timestamp).

Audit API

The Audit APIs consist of five endpoints for querying your shadow IT data:

. 42


threat_score integer Incident level ThreatScore from 1 to 99

browsers List Distinct list of browsers from the activity logs that resulted in this incident.

devices List Distinct list of devices from the activity logs that resulted in this incident.

host List Distinct list of hosts from the activity logs that resulted in this incident. Each host entry in turn is a JSON document that carries these fields:

ip, city, country.

alert_cleared_at timestamp Time at which the incident was cleared. (ISO 8601 format)

alert_cleared_by string email of the user who cleared the alert.

notes JSON Array An array of JSON dictionary containing notes left by user against this incident

multi_user Array of strings

An array of user emails if this incident is across users (Too many Invalid Logins across users)

multi_user_names Array of strings

An array of user names if this incident is across users (Too many Invalid Logins across users)


threat_score integer User level ThreatScore from 1 to 99

alert_ids Array of strings An array of _ids (incident ids) that contributed to the user ThreatScore


● Datasources--see Getting Audit datasources

● Services--see Getting Audit services

● Users--see Getting Audit users

● Usernames--see Getting Audit usernames

● Summary--see Getting Audit summary information

The method for querying the Audit API is the same as described in Getting logs.

Note: The Audit users API returns user_ids that you must then call against the usernames API to determine user names. You also must have rights to view the username.

Authentication

As described in Supported authentication methods.

Getting Audit datasources

Sample datasources request

Note: Use the following host URLs:




. 43

GET //audit/v2/datasources/


Authorization:

Content-Type : application/javascript



Sample datasources response

The CloudSOC datasources API returns an array of datasource objects, as shown in the following.

Getting Audit services

Sample Audit services request

. 44

{ "datasources": [

{ "id": "59e88f19e41f00eff1917aaf", "name": "ds_name1" },

{ "id": "5a53e73d6d2a12108ae30bad", "name": "ds_name2" }

]

}

GET //audit/v2/services/


Authorization:




Supported Audit services filters

The Audit services API supports the following filters that you use to narrow down the number of services returned by the request.

Sample Audit services response

. 45

Filter Nature Type Description

ds_id optional string List of datasource ids separated by comma. Empty value is default and returns data for all datasource ids

service_type optional string One of the following: ● enterprise ● consumer ● all ● prosumer (service is both enterprise

and consumer like Dropbox)

allowed optional boolean Default is true

blocked optional boolean Default is false

earliest_date required Timestamp in sec

latest_date required Timestamp in sec

next_page optional string Next page identifier

{

"headers": [ "epoch", "service_id", "location_id", "total_sessions",

"total_bytes", "total_packets", "up_bytes", "session_duration" ],

"meta_data": { "max_epoch": 1498867200,

"fields_map": {

"service_id": { "362": "Service_name1", "7299": "Service_name2" },

"location_id": { "1055": "Loc_name1", "23": "Loc_name2" }

},

"response_status": "OK",

"min_epoch": 1483228800

},

"data": [

[ 1483228800, 362, 1055, 7, 163000, null, 81500, 88 ],

[ 1485907200, 7299, 23, 49, 294625, null, 0, 1027 ]

]

}


Getting Audit users

This API returns user activity across SaaS services.

Sample Audit users request

Supported Audit users filters

The Audit users API supports the following filters that you use to narrow down the number of users returned by the request.

. 46

GET //audit/v2/users/


Authorization:





service_type optional string One of the following: ● enterprise ● consumer ● all ● prosumer (service is both enterprise and

consumer like Dropbox)

service_ids optional string A service id. The response lists the identities of all of the service users.





resolution optional 3600, 86400, 2592000

● 3600 returns hourly ● 86400 returns daily ● 2592000 (Default value) returns monthly

next_page optional string Next page identifier


Sample Audit users response

Getting Audit usernames

Sample Audit usernames request

. 47

{

"total_users": 138,

"headers": [ "user_id", "service_id", "location_id", "device_id", "sessions",

"total_bytes", "up_bytes", "down_bytes", "session_duration" ],

"meta_data": {

"max_epoch": 1498867200,

"fields_map": {

"service_id": { "3": "service_name" },

"location_id": { "1": "loc_name" },

"device_id": { "1": "dev_name" }

},


"min_epoch": 1483228800

},

"data": [

[ 2012625, 3, 1, 1, 89, 631342, 0, 631342, 2019 ],

[ 2012647, 3, 1, 1, 91, 627986, 0, 627986, 1053 ]

]

}

POST //audit/v2/usernames/

Headers:


Authorization:



POST Request Parameters:

{

"user_ids":[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],

"limit": 2

}


Supported Audit usernames parameters

The Audit usernames API supports the following parameters that you can use to specify the users whose names should be resolved.

Sample Audit usernames response

Getting Audit summary information

Sample Audit summary request

. 48


user_ids required int List of user ids separated by comma.

limit optional int Max no of users out of the given user ids that should be resolved. Default is 1000. Specifying a limit > 1000 fails.

{

"headers": [ "user_id", "username" ],

"data": [

[ 5, "Ali" ],

[ 1, "Unknown" ]

]

}

GET //audit/v2/summary/


Authorization:




Supported Audit summary filters

The Audit summary API supports the following filters that you use to narrow down volume of summary information returned by the request.

. 49



service_type optional string One of the following: ● enterprise ● consumer ● all ● prosumer (service is both enterprise

and consumer like Dropbox)





resolution optional 3600, 86400, 2592000

● 3600 returns hourly ● 86400 returns daily ● 2592000 (Default value) returns

monthly


Sample Audit summary response

. 50

{

"latest_date": "1501545599",

"top_risky_services": [

{

"sort_key_brr_class": 1,

"top_users": [ { "traffic": 1778, "user_id": 2010642, "sessions": 1 }

],

"users_count": 9,

"sort_key_brr": 38,

"service_id": 3545,

"top_destinations": [ { "traffic": 1789, "location_id": 3, "sessions":

12 } ]

}

],

"high_risk_services": 137,

"meta_data": {

"datasource_id": "",

"max_epoch": 1498867200,

"fields_map": { "service_id": { "5": "service_name" } },

"logsource_ids": null,


"min_epoch": 1483228800,

"resolution": null,

"hardware_ids": null

},

"total_services": 177, "is_valid": true, "request_type": 0,

"logsource_ids": [], "total_users": 138, "enterprise": true,

"total_destinations": 27, "med_risk_services": 36,

"top_used_services": [ ],

"consumer": true,

"company_brr": {

"buckets": [ { "bucket_id": 9, "score": 78 } ],

"value": 41

},

"earliest_date": "1470009600"

}


Audit response codes

Based on the outcome of the request, the CloudSOC Audit API may respond with one of the following response codes:

Protect APIs

Authentication

As described in Supported authentication methods.

Getting Protect policies

Sample policy request

Note: Use the following host URLs:



. 51



● Invalid parameters provided in query. ● Unsupported filters provided.


503 Maintenance Database is undergoing scheduled weekly maintenance. Check the response message for the maintenance schedule.

50x Unexpected Error An unexpected error occurred. Report the error to CloudSOC support.

GET //api/admin/v1/policies/ HTTP/1.1


Authorization:

Content-Type: application/javascript




Supported policy filters

The CloudSOC Policies API supports the following filters that you use to narrow down the number of policies returned by the request.

Sample policy response

The CloudSOC Policies API returns a list of alphabetically ordered by policy_name (case sensitive) policies. Shown in the following is a sample request for a data exposure policy.

. 52

Filter Nature Type and Examples

policy_name optional string

policy_type optional string

Can be one of the following: ● documentshareapi (Data Exposure via Securlets) ● documentshare (File Sharing via Gatelets) ● filexfer (File Transfer via Gatelets) ● accessenforcement (Access Enforcement via Gatelets) ● anomalydetect (ThreatScore policy) ● accessenforceapi (Access Monitoring via Securlets)

is_active optional bool

Can be one of the following: ● true ● false

{

"meta": {

"limit": 50,

"next": null,

"offset": 0,

"previous": null,

"total_count": 1

},

"objects": [

{

"applications": [

"Box"

],


. 53

"content_profiles": [],

"content_profiles_whitelist": [],

"created_by": "[email protected]",

"created_on": "2017-04-27T06:45:27.510000",

"exposure_match": "any",

"exposure_scope": [

"collaborators"

],

"file_size": {

"larger_than": 104857600,

"smaller_than": 0

},

"file_type": [

"__ALL_EL__"

],

"file_type_whitelist": [],

"filename_pattern": [],

"folder_scope": [],

"folder_scope_whitelist": [],

"id": "5901938737abd118bbf870f6",

"is_active": false,

"is_archived": false,

"modified_by": "[email protected]",

"modified_on": "2017-04-29T16:02:37.731000",

"policy_description": "",

"policy_name": "100mbPlus",

"policy_type": "documentshareapi",

"recipient_scope": {

"domains": [

"__ALL_EL__"

],

"groups": [

"__ALL_EL__"

],

"users": [

"__ALL_EL__"

]

},

"recipient_scope_whitelist": {

"domains": [],

"groups": [],

"users": []

},

"response": [

{

"meta_info": {

"severity_level": "high"

},

"type": "SEVERITY_LEVEL"


Protect response codes

Based on the outcome of the request, the CloudSOC Protect API may respond with one of the following response codes:

. 54

}

],

"site_urls": [],

"sub_features": [],

"sub_id": "5901938737abd118bbf870f4",

"users_scope": {

"domains": [

"__ALL_EL__"

],

"groups": [

"__ALL_EL__"

],

"org_unit": [

"__ALL_EL__"

],

"users": [

"__ALL_EL__"

]

},

"users_scope_whitelist": {

"groups": [],

"users": []

},

"violations": 0,

"vulnerability_type": []

}

]

}


200 OK Request processed successfully, data was returned in response to this request.


● Invalid parameters provided in query. ● Unsupported filters provided.


405 Method not allowed This indicate this http method is not supported


. 55


Protect policy schema

This section describes the schema of the Protect policies returned by policy types.

Policy common fields

All policy types have the common fields described in the following. Fields specific to Gateway and Securlets are defined separately.

. 56


applications list Application Name (eg. Box, Google Apps, Dropbox).

created_by string User who created the policy

created_on timestamp Time at which the activity occurred. (ISO 8601 format)

policy_description string Description of policy

filename_pattern list File names to match

id string This is the unique identifier for the policy.

is_active bool Policy status

modified_by string User who last modified the policy

modified_on timestamp Last time at which policy was modified. (ISO 8601 format)

policy_name string Policy name

policy_type string One of the following: ● documentshareapi (Data Exposure via Securlets) ● documentshare (File Sharing via Gatelets) ● filexfer (File Transfer via Gatelets) ● accessenforcement (Access Enforcement via

Gatelets) ● anomalydetect (ThreatScore policy) ● accessenforceapi (Access Monitoring via Securlets)

response list or object

List of response in case of Securlets Policy Type object for gatelets policies

sub_id string Internal id

users_scope object List of users that are included for File Owner field.

users_scope_whitelist object List of users that are excluded for File Owner/ field.


Gatelet policy additional fields

Gatelets policies have following additional fields.

. 57


account_type list

activities_scope list Activities to match. Supported only in accessenforcement

browser list Included Browser

browser_whitelist list Browser exceptions

content_profiles list List of content iq profiles included in the policy. Supported gateway policy: filexfer

content_profiles_whitelist list List of content iq profiles exceptions in the policy. Supported gateway policy: filexfer

device_management_info object Device management and ownership status

file_size object File size limits in larger_than and smaller_than in bytes Applicable on: filexfer


Applicable on: filexfer, documentshare

file_scope_types list List of File extension to match Applicable on: documentshare

file_scope_whitelist list List of File extension to exclude Applicable on: documentshare

geoip_scope list Included Location. This is in the form “City (Country)”.

geoip_whitelist list Location exceptions. This is in the form “City (Country)”.

ip_scope list IP address ranges

ip_scope_whitelist list IP address ranges exceptions

platform list Operating System information to match on policy evaluation

platform_whitelist list Operating System information exception included on policy evaluation


Gatelet policy additional fields, continued

Securlets policy additional fields

Securlets policies have the additional fields described in the following tables.

Data exposure via Securlets

. 58


recipient_scope object List of users that are included for File Shared with field. Applicable on: documentshare

recipient_scope_whitel

ist

object List of users that are excluded for File Shared with field. Applicable on: documentshare

risk_level number User’s minimum threatscore to match when evaluating policy


content_profiles list List of content iq profiles included in the policy.

content_profiles_whitelist list List of content iq profiles exceptions in the policy.

exposure_match string Can be among “any” or “all”.

exposure_scope list Can be among "company", "open", "unexposed" or "collaborators"

file_size object File size limits in larger_than and smaller_than in bytes

folder_scope list Limit the policy to this folder (Supported only for Box App)

folder_scope_whitelist list Exclude the policy for this folder (Supported only for Box App)

recipient_scope object List of users that are included for File Shared with field.

recipient_scope_whitelist object List of users that are excluded for File Shared with field.

site_urls list Limit policy to selective Office365 Sites subfeature.

sub_features list Subfeature for the application. Applicable to applications: Office 365, Salesforce and Google Apps.



Access monitoring via Securlets

ThreatScore policy additional fields

ThreatScore-based policies have the additional fields described in the following table.

Revision history

. 59


activities_scope list Activities to match.




Date Version Description

15 May 2017 1.0 Initial release created from content in Elastica Logs API with addition of Protect policy API content

31 July 2017 2.0 Add Audit API content

15 August 2017 2.1 Address access profiles effect on API keys

30 November 2017 2.2 Add Audit response codes, service_ids Audit filter, add &created_timestamp to Investigate logs sample query

21 December 2017 2.3 Add CloudSOC History sample query

16 January 2018 2.4 Clarify "service=Elastica" filter

8 March 2018 2.5 Clarify that Detect Incidents and ThreatScore queries return a maximum of 10,000 logs.

2 April 2018 2.6 Clarify description of the Audit API

22 May 2018 3.0 Add example Powershell query script

16 November 2018 3.1 Address Audit incidents and Audit ThreatScore

4 March 2019 3.2 Remove responsible_logs entry

16 April 2019 4.0 Address new next_url element for querying multiple pages of logs

30 May 2019 4.1 Removed "for other securlets contact your CloudSOC representative"

cloudsoc management api - broadcom...2. on the cloudsoc menu bar, click your username and choose s...

Documents