cloudsoc management api - broadcom...2. on the cloudsoc menu bar, click your username and choose s...
TRANSCRIPT
-
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/
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
Supported Filters, Continued
. 10
Filter Nature Supported By (app - subtype)
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
string or list (array) ● string: for 1 timestamp ● array: for bounded range
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
string or list (array) ● string: for 1 timestamp ● array: for bounded range
updated_timestamp:2015-01-01T00:00:0
0
OR
updated_timestamp=2015-01-01T00:00:0
0,
2015-02-01T00:00:00
-
Tech Note — CloudSOC Management API
Supported Filters, Continued
. 11
Filter Nature Supported By (app - subtype)
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)
-
Tech Note — CloudSOC Management API
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"
}, ...]
}
-
Tech Note — CloudSOC Management API
Sample response for Detect (incidents)
. 13
{
"status": "success",
"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",
"user": "[email protected]",
"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",
"inserted_timestamp": "2018-04-03T06:28:33",
"activity_type": "Delete"
},
{
"updated_timestamp": "2017-09-18T13:36:30",
"from_detect": 1,
"service": "Google Drive",
"severity": "medium",
"object_type": "File",
"ioi_code": "ANOMALOUSLY_LARGE_DELETES",
"source": "API",
"threat_score": "60",
"user": "[email protected]",
"created_timestamps": "1505735753",
"_id": "DO2bAWtLAHWmAI0wADryAJ1C",
"user_name": "QA Admin net",
"message": null,
"inserted_timestamp": "2018-04-03T06:28:33",
"activity_type": "Delete"
},
{
-
Tech Note — CloudSOC Management API
. 14
"updated_timestamp": "2018-09-07T12:07:22",
"from_detect": 1,
"service": "Box, Google Drive, Microsoft Azure, Gmail",
"activity_type": "InvalidLogin",
"severity": "high",
"object_type": "Session",
"threat_score": "94",
"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",
"user": "[email protected]",
"created_timestamps": "1504801203, 1532950596, 1536322042",
"_id": "rPqbAKRLACymAHswADXzALri",
"user_name": "Admin QA",
"message": null,
"inserted_timestamp": "2018-09-07T12:10:14"
}
]
}
-
Tech Note — CloudSOC Management API
Sample response for Detect (ThreatScore)
. 15
{
"status": "success",
"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",
"user": "[email protected]",
"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",
"inserted_timestamp": "2018-04-03T06:28:33",
"activity_type": "Delete"
},
{
"updated_timestamp": "2017-09-18T13:36:30",
"from_detect": 1,
"service": "Google Drive",
"severity": "medium",
"object_type": "File",
"ioi_code": "ANOMALOUSLY_LARGE_DELETES",
"source": "API",
"threat_score": "60",
"user": "[email protected]",
"created_timestamps": "1505735753",
"_id": "DO2bAWtLAHWmAI0wADryAJ1C",
"user_name": "QA Admin net",
"message": null,
"inserted_timestamp": "2018-04-03T06:28:33",
"activity_type": "Delete"
},
{
-
Tech Note — CloudSOC Management API
. 16
"updated_timestamp": "2018-09-07T12:07:22",
"from_detect": 1,
"service": "Box, Google Drive, Microsoft Azure, Gmail",
"activity_type": "InvalidLogin",
"severity": "high",
"object_type": "Session",
"threat_score": "94",
"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",
"user": "[email protected]",
"created_timestamps": "1504801203, 1532950596, 1536322042",
"_id": "rPqbAKRLACymAHswADXzALri",
"user_name": "Admin QA",
"message": null,
"inserted_timestamp": "2018-09-07T12:10:14"
}
]
}
-
Tech Note — CloudSOC Management API
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)
-
Tech Note — CloudSOC Management API
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
Field Name Type Description
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.
-
Tech Note — CloudSOC Management API
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
-
Tech Note — CloudSOC Management API
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
{
"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&fr
om=100", "meta":{
"from": 0,
"total": 324865,
"limit": 100
},
"logs":[# 100 logs lists]
}
-
Tech Note — CloudSOC Management API
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
{
"status": "success",
"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]
}
-
Tech Note — CloudSOC Management API
'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
-
Tech Note — CloudSOC Management API
● 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
-
Tech Note — CloudSOC Management API
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
Field Name Type Description
_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.
-
Tech Note — CloudSOC Management API
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
Field Name Type Description
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.
Field Name Type Description
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
-
Tech Note — CloudSOC Management API
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
Field Name Type Description
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.
-
Tech Note — CloudSOC Management API
Common fields
These fields are common to activities on S3 and non-S3 objects.
Activities on non-S3 objects
. 27
Field Name Type Description
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.
Field Name Type Description
message string “User {email} {activity_type:past tense} {object_type}” e.g. User [email protected] created security group, User [email protected] attached volumes etc
-
Tech Note — CloudSOC Management API
Activities on S3 objects
Google Drive
This section lists all the activities reported by the Google Drive Securlet.
Create a file or folder
. 28
Field Name Type Description
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.
-
Tech Note — CloudSOC Management API
Modify a file or folder
Upload a file or folder
. 29
Field Name Type Value
message string “User {Modified_by} modified {object_type} {name}”
object_type string “File” or “Folder”
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
file_size integer (optional) size of the file if reported by Drive API
Resource_Id String Unique identifier for the file/folder.
Field Name Type Value
message string “User uploaded {object_type} {name}”
object_type string “File” or “Folder”
activity_type string “Upload”
name string Name of the file or folder that was uploaded
user string User who uploaded 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.
-
Tech Note — CloudSOC Management API
Share a file or folder
Unshare a file or folder
. 30
Field Name Type Value
message string “User shared {name}”
object_type string “File” or “Folder”
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
file_size integer (optional) size of the file if reported by Drive API
Resource_Id String Unique identifier for the file/folder.
Field Name Type Value
message string “User unshared {name}”
object_type string “File” or “Folder”
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.
user string Owner of 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.
-
Tech Note — CloudSOC Management API
Rename a file or folder
Trash a file or folder
. 31
Field Name Type Value
message string “User renamed {object_type} from {name_before} to {name}”
object_type string “File” or “Folder”
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
user string Owner of 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.
Field Name Type Value
message string “User trashed {name}”
object_type string “File” or “Folder”
activity_type string “Trash”
name string Name of the file/folder that was trashed
severity string “warning”
user string Owner of 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.
-
Tech Note — CloudSOC Management API
Restore a file or folder from Trash
Permanently delete a file or folder
. 32
Field Name Type Value
message string “User restored {name}”
object_type string “File” or “Folder”
activity_type string “Restore”
name string Name of the file/folder that was restored
user string Owner of 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.
Field Name Type Value
message string “User permanently deleted {name} from trash”
object_type string “File” or “Folder”
activity_type string “Trash”
name string Name of the file/folder that was permanently deleted
severity string “warning”
user string Owner of 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.
-
Tech Note — CloudSOC Management API
Role change
Delete user
Grant permission on an app
. 33
Field Name Type Value
message string “User changed permission on {object_type} {name}”
object_type string “File” or “Folder”
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
file_size integer (optional) size of the file if reported by Drive API
Resource_Id String Unique identifier for the file/folder.
Field Name Type Value
message string “User {user} deleted”
object_type string “User”
activity_type string “Delete”
severity string “warning”
Field Name Type Value
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
-
Tech Note — CloudSOC Management API
Revoke permission on an app
Successful login
Suspicious login
. 34
Field Name Type Value
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
Field Name Type Value
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.
Field Name Type Value
message string “Suspicious login by user {user} 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.
-
Tech Note — CloudSOC Management API
Failed login
Logout
. 35
Field Name Type Value
message string “User {user} login failed due to {failure_type}”
object_type string “Session”
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.
Field Name Type Value
message string “User {user} logged out”
object_type string “Session”
activity_type string “Logout”
user string Email address of the user that attempted to login
Host and location string See Location Information.
-
Tech Note — CloudSOC Management API
Salesforce
This section lists all the activities reported by the Salesforce Securlet.
Activities on Salesforce standard/custom objects
. 36
Field Name Type Value
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.
-
Tech Note — CloudSOC Management API
Fields common to login, logout and failed login events
Successful login
. 37
Field Name Type Value
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.
Host and location string See Location Information.
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
Field Name Type Value
message string “User {user} logged in successfully via {Application}”
object_type string “Session”
activity_type string “Login”
user string Email address of the user that logged in.
-
Tech Note — CloudSOC Management API
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
Field Name Type Value
message string “Failed login attempt by {user}, Reason: {Status}”
object_type string “Session”
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
Field Name Type Value
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.
-
Tech Note — CloudSOC Management API
File sharing - Securlet
. 39
Field Name Type Value
message string “[ALERT] User shared or uploaded a document named {object_name} which violated the content policy : {policy_violated}”
activity_type string “Policy Violation”
policy_type string “FileSharingAPI”
policy_violated string Name of the policy that was violated.
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.
-
Tech Note — CloudSOC Management API
File sharing - gateway
File transfer - gateway
. 40
Field Name Type Value
message string “[ALERT] {user} attempted to share content: “{object_name}” with external user(s): “{shared_with}” violating policy: “{policy_violated}”
activity_type string “Policy Violation”
policy_type string “FileSharingGateway”
policy_violated string Name of the policy that was violated.
object_name string Name of the document that violated the policy in question
shared_with string Email addresses of users with which the document is being shared
policy_action string “ALERT”
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
Field Name Type Value
message string “[ALERT] {user} attempted to {transfer_type} content: “{object_name}” violating policy: “{policy_violated}”
activity_type string “Policy Violation”
policy_type string “FileTransfer”
policy_violated string Name of the policy that was violated.
object_name string Name of the document that violated the policy in question
policy_action string “ALERT”
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
-
Tech Note — CloudSOC Management API
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
Field Name Type Value
message string “[ALERT] User performed anomalous activities that violated policy: {policy_violated}
activity_type string “Policy Violation”
policy_type string “ThreatScore”
policy_violated string Name of the policy that was violated.
policy_action string One of “ALERT”, “BLOCK”
blocked_apps string “ALL” or the name of a specific SaaS service that is blocked.
-
Tech Note — CloudSOC Management API
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
Field Name Type Value
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)
Field Name Type Value
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
-
Tech Note — CloudSOC Management API
● 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:
● 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.
. 43
GET //audit/v2/datasources/
Host: api-vip.elastica.net
Authorization:
Content-Type : application/javascript
X-Elastica-Dbname-Resolved: True
-
Tech Note — CloudSOC Management API
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/
Host: api-vip.elastica.net
Authorization:
Content-Type : application/javascript
X-Elastica-Dbname-Resolved: True
-
Tech Note — CloudSOC Management API
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 ]
]
}
-
Tech Note — CloudSOC Management API
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/
Host: api-vip.elastica.net
Authorization:
Content-Type : application/javascript
X-Elastica-Dbname-Resolved: True
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)
service_ids optional string A service id. The response lists the identities of all of the service users.
allowed optional boolean Default is true
blocked optional boolean Default is false
earliest_date required Timestamp in sec
latest_date required Timestamp in sec
resolution optional 3600, 86400, 2592000
● 3600 returns hourly ● 86400 returns daily ● 2592000 (Default value) returns monthly
next_page optional string Next page identifier
-
Tech Note — CloudSOC Management API
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" }
},
"response_status": "OK",
"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:
Host: api-vip.elastica.net
Authorization:
Content-Type : application/javascript
X-Elastica-Dbname-Resolved: True
POST Request Parameters:
{
"user_ids":[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
"limit": 2
}
-
Tech Note — CloudSOC Management API
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
Filter Nature Type Description
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/
Host: api-vip.elastica.net
Authorization:
Content-Type : application/javascript
X-Elastica-Dbname-Resolved: True
-
Tech Note — CloudSOC Management API
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
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
resolution optional 3600, 86400, 2592000
● 3600 returns hourly ● 86400 returns daily ● 2592000 (Default value) returns
monthly
-
Tech Note — CloudSOC Management API
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,
"response_status": "OK",
"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"
}
-
Tech Note — CloudSOC Management API
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:
● For the US-based production cloud: api-vip.elastica.net
● For the EU-based production cloud: api.eu.elastica.net
. 51
Code Meaning Description
400 Bad Request We encountered an error while processing the request, possible causes are:
● Invalid parameters provided in query. ● Unsupported filters provided.
401 Unauthorized This indicates an authentication failure. Retry with a new API key. (Settings > API Keys)
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
Host: api-vip.elastica.net
Authorization:
Content-Type: application/javascript
X-Elastica-Dbname-Resolved: True
-
Tech Note — CloudSOC Management API
Also note that the request header “X-Elastica-Dbname-Resolved: True” is required for successful authorization.
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"
],
-
Tech Note — CloudSOC Management API
. 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"
-
Tech Note — CloudSOC Management API
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": []
}
]
}
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:
● 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
-
Tech Note — CloudSOC Management API
. 55
-
Tech Note — CloudSOC Management API
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
Field Name Type Description
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.
-
Tech Note — CloudSOC Management API
Gatelet policy additional fields
Gatelets policies have following additional fields.
. 57
Field Name Type Description
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
filename_pattern list File names to match
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
-
Tech Note — CloudSOC Management API
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
Field Name Type Description
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
Field Name Type Description
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.
filename_pattern list File names to match
-
Tech Note — CloudSOC Management API
Access monitoring via Securlets
ThreatScore policy additional fields
ThreatScore-based policies have the additional fields described in the following table.
Revision history
. 59
Field Name Type Description
activities_scope list Activities to match.
risk_level number User’s minimum threatscore to match when evaluating policy
Field Name Type Description
risk_level number User’s minimum threatscore to match when evaluating policy
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"