WithSecure Elements Endpoint Security

The WithSecure Elements Endpoint Security connector enables streamlined security automation for incident management and device monitoring within an organization's network.

WithSecure Elements Endpoint Security offers a robust platform for endpoint protection and response, safeguarding against sophisticated cyber threats. This connector enables Swimlane Turbine users to integrate seamlessly with WithSecure's capabilities, allowing for automated incident commenting, response action creation, device management, and user information retrieval. By leveraging this integration, security teams can efficiently manage incidents, respond to threats proactively, and maintain visibility over their security posture, all within the Swimlane Turbine environment.

WithSecure Elements Connector can be deployed in a security events forwarder role to pull data from WithSecure Elements and forward it to almost any SIEM using Syslog, Common Event Format (CEF) or Log Event Extended Format (LEEF).

Elements Connector is fully managed from the WithSecure Elements Security Center. Specifically, you can configure the use of the forwarding feature for the whole partner scope or limit it to a certain company.

See the Elements Connector Getting Started Guide for more details.

Prerequisites

To utilize the WithSecure Elements Endpoint Security connector with Swimlane Turbine, ensure you have the following prerequisites:

Custom authentication with the following parameters:

URL: The endpoint URL for the WithSecure API.

Client ID: Your unique identifier for WithSecure API access.

Client Secret: A secret key associated with your Client ID to authenticate API requests.

Capabilities

The WithSecure Elements Endpoint Security connector provides the following capabilities:

Add Comment to Incidents

Create New Response Actions

Delete Devices

Get Current User Information

List Created Response Actions

List Detection for Incident in Organization Scope

List Device Operations

List Incidents in Organization Scope

List Organizations

Query Devices

Query EPP, EDR and Collaboration Security Events

Read List of Security Events

Trigger New Remote Operation on Devices

Update Devices

Update Status of Incidents

Asset Setup

Goto Management-> Organization Settings -> API Clients and create an new API Client.

Copy th Client ID, Client Secret. Use it for Asset setup.

Tasks Setup

Query devices

The Query devices Endpoint can be used for following Usecases :

List Devices

Get Statistics about devices

Get Histogram with device statistics for the last 30 days

First use case is supported when Accept header is set to application/json. Second use case requires Accept header equal to application/vnd.withsecure.aggr+json and count parameter to be set. Third use case requires Accept header equal to application/vnd.withsecure.aggr+json and histogram parameter to be set.

With application/json Accept header endpoint returns list of devices - for given organization retrieves devices matching all filters that are used in query. When query contains "deviceId" parameter then other used filters are ignored.

With application/vnd.withsecure.aggr+json Accept header endpoint returns aggregations. Aggregations provide useful statistical overview for the broader picture of organization's assets. Devices are first filtered according to the provided query parameters and then grouped and counted. Use count query parameter to select the property by which values devices will be counted. Histogram query parameter works exactly the same as count, with only difference that histogram will return aggregations data for the last 30 days. count and histogram parameters can't be used together in a single query. Filters supported with count and histogram parameters: organizationId, type, name, online, label, clientVersion, protectionStatusOverview.

Trigger New Remote Operation on Devices

Triggering has two stages:

Operation is created in the internal backend

Operation is triggered on the remote host

Successful response only means that the operation was created in the internal backend (first stage). Client can query operations for the device to check status from the remote host (second stage). Depending on an operation type, additional arguments might be required - they should be sent in the body parameters map-like object. Operation specific information in the response may be returned in the metadataParameters map-like object. Check the list of supported operations here.

Update Devices

Endpoint may be used to:

Change device state

Change device subscription

Can find more details about above scenarios here.

Query EPP, EDR and Collaboration Protection Security Events

This Endpoint supports following response formats:

items page (default) - endpoint return Security Events matching filter parameters as page of items where each item represents Security Event object. Client iterate over search results using page anchor and it can decide about page size and items ordering.

aggregation - endpoint groups and counts Security Events matching filter parameters by property selected by the client. To select this mode client must add HTTP header Accept: application/vnd.withsecure.aggr+json to the request. Additionally it has to add parameter count={property name} the request.

Parameters usage and Examples can be found here

Read list of security events

This endpoint is kept in maintenance mode which means it will receive only bugfixes and any new feature won't be added in the future.

Create new response action

Check the supported action Types and Parameters here before choosing this connector action.

Notes

WithSecure Elements Endpoint Security API Reference Documentation

Configurations

WithSecure EDR OAuth2.0 Authentication

Authentication using Client ID and Client Secret.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
verify_ssl	Verify SSL certificate.	boolean	Optional
token_url		string	Optional
client_id	The client ID.	string	Required
client_secret	The client secret.	string	Required
http_proxy	A proxy to route requests through.	string	Optional

Actions

Add Comment to Incidents

Adds a specified comment to selected incidents in WithSecure Elements Endpoint Security using target identifiers.

Endpoint

URL: /incidents/v1/comments

Method: POST

Input

Argument Name	Type	Required	Description
targets	array	Optional	List of incident IDs to comment. Min Items:- 1 Max Items:- 10.
comment	string	Optional	Comment to add to the target incidents.

Input Example

{"json_body":{"targets":["2c902c73-e2a6-40fd-9532-257ee102e1c1"],"comment":"TICKET-1234"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.incidentId	string	Unique identifier
items.comment	string	Output field: items.comment

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"items":[{},{}]}}

Create New Response Action

Initiates a response action on specified targets within WithSecure Elements Endpoint Security using organizationId, type, and targets.

Endpoint

URL: /response-actions/v1/response-actions

Method: POST

Input

Argument Name	Type	Required	Description
organizationId	string	Optional	ID of organization to which target devices belong.
type	string	Optional	Type of action.
targets	array	Optional	List of targets (device identifiers) on which action is created Min Items:- 1 Max Items:- 10.
comment	string	Optional	Additional comment for action.
parameters.maxFileHash	number	Optional	Maximum file size to hash, in MB. Prevents excessive delays when hashing large files (required in netstat).
parameters.threadId	number	Optional	Thread Id (required in killThread).
parameters.match	string	Optional	Strategy used to match processes (required in killProcess).
parameters.processMemoryDump	boolean	Optional	Run memory dump on process before killing it. Required in killProcess. Memory dump can be run only if processName or processId strategy is used.
parameters.memoryDumpFlag	string	Optional	Flag that will be used when dumping the process memory. Required in killProcess. full - memory dump includes all accessible memory of process, pmem - only information necessary to capture process' stack traces.
parameters.processMatchValues	array	Optional	List of values that are used to match process to kill (required in killProcess). Depending on selected strategy it might be list of identifiers, names or regular expressions Min Items:- 1 Max Items:- 6.
parameters.captureMemory	boolean	Optional	Take capture of system's memory Required in fullMemoryDumpwhen Linux devices are selected as targets.
parameters.collectProfile	boolean	Optional	Collect files required to build a kernel profile. Required in fullMemoryDump when Linux devices are selected as targets.
parameters.winpmemVersion	string	Optional	Version of winpmem to use Required in fullMemoryDump when Windows devices are selected as targets.

Input Example

{"json_body":{"organizationId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad","type":"killThread","targets":["ec8a0100-d313-4896-b3cb-02188e060bf3","01898f1e-d32d-40fe-b3c5-9f039c1eac04"],"comment":"string","parameters":{"maxFileHash":10,"threadId":23435,"match":"processName","processMemoryDump":false,"memoryDumpFlag":"full","processMatchValues":"killProcess","captureMemory":true,"collectProfile":true,"winpmemVersion":"v1_6"}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	string	Unique identifier

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 09 Sep 2024 10:11:29 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-d425d30e3a4a4a79","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"OK","json_body":{"id":"string"}}

Delete Devices

Removes specified devices from WithSecure Elements Endpoint Security, freeing up subscription seats and hiding them from the device list.

Endpoint

URL: /devices/v1/devices

Method: DELETE

Input

Argument Name	Type	Required	Description
parameters.deviceId	array	Required	List of Device ID's to be deleted. Up to 20 items.

Input Example

{"parameters":{"deviceId":["string"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
devices	array	Output field: devices

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 09 Sep 2024 07:12:50 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-cac6b1b18e344010","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"OK","json_body":{"devices":["ec8a0100-d313-4896-b3cb-02188e060bf3","01898f1e-d32d-40fe-b3c5-9f039c1eac04"]}}

Get Current User Information

Retrieve details about the currently authenticated user in WithSecure Elements Endpoint Security.

Endpoint

URL: /whoami/v1/whoami

Method: GET

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
clientId	string	Unique identifier
organizationId	string	Unique identifier

Output Example

{"status_code":200,"response_headers":{"Date":"Wed, 11 Sep 2024 09:51:32 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-ba65dbf08940468b","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"","json_body":{"clientId":"fusion_df13a6b8f1314e549b539930","organizationId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad"}}

List Created Response Actions

Retrieve a list of response actions created for RDR sensors in WithSecure Elements Endpoint Security, requiring an organizationId.

Endpoint

URL: /response-actions/v1/responses

Method: GET

Input

Argument Name	Type	Required	Description
parameters.organizationId	string	Required	UUID of an organization.
parameters.order	string	Optional	Sorting order.
parameters.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
parameters.type	string	Optional	Filter by response action type.
parameters.actionId	string	Optional	Filter by response action ID.
parameters.state	string	Optional	Filter by response action state.
parameters.comment	string	Optional	Filter by comment. Matches any part of the comment.
parameters.author	string	Optional	Filter by author username.
parameters.result	string	Optional	Filter by response action result.
parameters.deviceId	string	Optional	UUID of a device.
parameters.limit	number	Optional	The size of the single batch. Value defines upper bound for number of items, that are sent in single response. However it doesn't guarantee, that response will contain exact number of items if next page exist. Client that reads all items matching query parameters should depend only on nextAnchor property, which contain link to next result. Client can stop iteration when nextAnchor is missing in response.

Input Example

{"parameters":{"organizationId":"ec8a0100-d313-4896-b3cb-02188e060bf3","order":"desc","anchor":"no-value","type":"","actionId":"","state":"","comment":"","author":"","result":"succeeded","deviceId":"","limit":10}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.id	string	Unique identifier
items.type	string	Type of the resource
items.state	string	Output field: items.state
items.progress	object	Output field: items.progress
items.progress.devicesCount	number	Count value
items.progress.pendingTasksCount	number	Count value
items.progress.errorTasksCount	number	Error message if any
items.progress.activeTasksCount	number	Count value
items.progress.completedTasksCount	number	Count value
items.progress.successfullyCompletedTasksCount	number	Whether the operation was successful
items.createdTimestamp	string	Output field: items.createdTimestamp
items.updatedTimestamp	string	Output field: items.updatedTimestamp
items.devices	array	Output field: items.devices
items.devices.deviceId	string	Unique identifier
items.author	object	Output field: items.author
items.author.id	string	Unique identifier
items.author.source	string	Output field: items.author.source
items.author.username	string	Name of the resource
items.comment	string	Output field: items.comment
items.result	string	Result of the operation
nextAnchor	string	Output field: nextAnchor

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 09 Sep 2024 10:59:03 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-8ea252f7eaa348b7","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"","json_body":{"items":[{}],"nextAnchor":"string"}}

List Detections for Incident in Organization Scope

Retrieve a list of detections for a specified incident within an organization's scope, ordered by time in descending order.

Endpoint

URL: /incidents/v1/detections

Method: GET

Input

Argument Name	Type	Required	Description
parameters.organizationId	string	Optional	UUID of an organization. If organizationID is missing, default organization of authenticated client is used.
parameters.incidentId	string	Required	ID of an incident. Client can find that value in details of EDR Security Event. Incident ID must match UUID format.
parameters.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
parameters.createdTimestampStart	string	Optional	Lower, inclusive bound for createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
parameters.createdTimestampEnd	string	Optional	Upper, exclusive bound for createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
parameters.limit	number	Optional	Maximal number of items in response. Min -> 1, Max -> 100.

Input Example

{"parameters":{"organizationId":"ec8a0100-d313-4896-b3cb-02188e060bf3","incidentId":"ec8a0100-d313-4896-b3cb-02188e060bf3","anchor":"no-value","createdTimestampStart":"2023-03-22T13:34:51.097Z","createdTimestampEnd":"2023-03-22T13:34:51.097Z","limit":"20"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.detectionId	string	Unique identifier
items.incidentId	string	Unique identifier
items.deviceId	string	Unique identifier
items.name	string	Name of the resource
items.detectionClass	string	Output field: items.detectionClass
items.severity	string	Output field: items.severity
items.riskLevel	string	Output field: items.riskLevel
items.exePath	string	Output field: items.exePath
items.exeName	string	Name of the resource
items.exeHash	string	Output field: items.exeHash
items.cmdl	string	Output field: items.cmdl
items.pid	number	Unique identifier
items.createdTimestamp	string	Output field: items.createdTimestamp
items.initialReceivedTimestamp	string	Output field: items.initialReceivedTimestamp
items.username	string	Name of the resource
items.privileges	string	Output field: items.privileges
items.activityContext	array	Output field: items.activityContext
items.activityContext.type	string	Type of the resource
items.activityContext.description	string	Output field: items.activityContext.description
items.activityContext.detectionAvgCount	number	Count value
items.activityContext.detectionMaxCount	number	Count value
items.activityContext.detectionAvgSensors	number	Output field: items.activityContext.detectionAvgSensors

Output Example

{"status_code":200,"reason":"OK","json_body":{"items":[{}],"nextAnchor":"next-page-ref"}}

List Device Operations

Retrieves a list of operations triggered on a specified device within WithSecure Elements Endpoint Security; returns empty for inactive devices.

Endpoint

URL: /devices/v1/operations

Method: GET

Input

Argument Name	Type	Required	Description
parameters.deviceId	string	Required	UUID of a device.

Input Example

{"parameters":{"deviceId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad"}}

Output

Parameter	Type	Description
items	array	Output field: items
items.id	string	Unique identifier
items.status	string	Status value
items.operationName	string	Name of the resource
items.startedTimestamp	string	Output field: items.startedTimestamp
items.lastUpdatedTimestamp	string	Output field: items.lastUpdatedTimestamp
items.expirationTimestamp	string	Output field: items.expirationTimestamp
items.metadata	object	Response data
items.metadata.profileId	string	Response data

Output Example

{"items":[{"id":"7243413413490181","status":"pending","operationName":"isolateFromNetwork","startedTimestamp":"2023-04-01T15:08:17Z","lastUpdatedTimestamp":"2023-04-01T15:08:17Z","expirationTimestamp":"2023-04-15T15:08:17Z","metadata":{}},{"id":"7243413413490193","status":"pending","operationName":"assignProfile","startedTimestamp":"2023-04-01T15:08:17Z","lastUpdatedTimestamp":"2023-04-01T15:08:17Z","expirationTimestamp":"2023-04-15T15:08:17Z","metadata":{}}]}

List Incidents in Organization Scope

Retrieve a list of incidents within a specified organization and time frame using WithSecure Elements Endpoint Security.

Endpoint

URL: /incidents/v1/incidents

Method: GET

Input

Argument Name	Type	Required	Description
parameters.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
parameters.organizationId	string	Optional	UUID of an organization. If organizationID is missing, default organization of authenticated client is used.
parameters.incidentId	string	Optional	UUID of the incident.
parameters.createdTimestampStart	string	Optional	Lower, inclusive bound for createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
parameters.createdTimestampEnd	string	Optional	Upper, exclusive bound for createdTimestamp in the returned list. Cannot be used with updatedTimestamp filters.
parameters.updatedTimestampStart	string	Optional	Lower, inclusive bound for updatedTimestamp in the returned list. Cannot be used with createdTimestamp filters.
parameters.updatedTimestampEnd	string	Optional	Upper, exclusive bound for updatedTimestamp in the returned list. Cannot be used with createdTimestamp filters.
parameters.exclusiveStart	boolean	Optional	If equals "true", then createdTimestampStart and updatedTimestampStart are used as exclusive lower bound. Otherwise, createdTimestampStart and updatedTimestampStart are inclusive.
parameters.status	string	Optional	Status of the incidents to return. To filter by multiple statuses add this parameter repeatedly.
parameters.resolution	string	Optional	Resolution of the incident to return. To filter by multiple resolutions add this parameter repeatedly.
parameters.riskLevel	string	Optional	Filters by risk level. To filter by multiple risk levels add this parameter repeatedly.
parameters.archived	boolean	Optional	Specify whether archived incidents should be send in response. It is advised to query only not archived incidents as it might have positive impact on query performance. It is strongly advised to add archived=false.
parameters.limit	number	Optional	Maximal number of items in response. Min 1 to Max 50.
parameters.order	string	Optional	Specifies sorting order.

Input Example

{"parameters":{"anchor":"no-value","organizationId":"ec8a0100-d313-4896-b3cb-02188e060bf3","incidentId":"2c902c73-e2a6-40fd-9532-257ee102e1c1","createdTimestampStart":"","createdTimestampEnd":"","updatedTimestampStart":"","updatedTimestampEnd":"","exclusiveStart":false,"status":"new","resolution":"unconfirmed","riskLevel":"info","archived":false,"limit":20,"order":"desc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.organizationId	string	Unique identifier
items.severity	string	Output field: items.severity
items.riskLevel	string	Output field: items.riskLevel
items.riskScore	number	Score value
items.incidentPublicId	string	Unique identifier
items.createdTimestamp	string	Output field: items.createdTimestamp
items.name	string	Name of the resource
items.incidentId	string	Unique identifier
items.initialReceivedTimestamp	string	Output field: items.initialReceivedTimestamp
items.resolution	string	Output field: items.resolution
items.updatedTimestamp	string	Output field: items.updatedTimestamp
items.status	string	Status value
items.categories	array	Output field: items.categories
nextAnchor	string	Output field: nextAnchor

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 09 Sep 2024 10:35:40 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-4baa6e30943a485f","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"","json_body":{"items":[{},{}],"nextAnchor":"next-page-ref"}}

List Organizations

Retrieve a list of organizations associated with the specified WithSecure Elements Endpoint Security organization, including the organization itself.

Endpoint

URL: /organizations/v1/organizations

Method: GET

Input

Argument Name	Type	Required	Description
parameters.organizationId	string	Optional	UUID of an organization. If organizationID is missing, default organization of authenticated client is used.
parameters.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
parameters.type	string	Optional	Filter by organization type. Matches all organizations of this type.
parameters.limit	number	Optional	The size of the single batch. Value defines upper bound for number of items, that are sent in single response. However it doesn't guarantee, that response will contain exact number of items if next page exist. Client that reads all items matching query parameters should depend only on nextAnchor property, which contain link to next result. Client can stop iteration when nextAnchor is missing in response.

Input Example

{"parameters":{"organizationId":"ec8a0100-d313-4896-b3cb-02188e060bf3","anchor":"no-value","type":"company","limit":"200"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.name	string	Name of the resource
items.id	string	Unique identifier
items.type	string	Type of the resource

Output Example

{"status_code":200,"response_headers":{"Date":"Wed, 04 Sep 2024 11:10:18 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-dccdc640d48c4c10","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"","json_body":{"items":[{}]}}

Query Devices

Executes a query to retrieve information about the organization's devices within WithSecure Elements Endpoint Security.

Endpoint

URL: /devices/v1/devices

Method: GET

Input

Argument Name	Type	Required	Description
parameters.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
parameters.organizationId	string	Optional	UUID of an organization. If organizationID is missing, default organization of authenticated client is used.
parameters.deviceId	string	Optional	UUID of a device.
parameters.type	string	Optional	Filter by device type. Matches all devices of this type. If type is missing, all types of devices are included in response.
parameters.state	string	Optional	Filter by device state. Matches all devices of this state. If state is missing, only active devices are included in response.
parameters.name	string	Optional	Filter devices by device name (exact match).
parameters.serialNumber	string	Optional	Filter devices by device serial number (exact match).
parameters.online	boolean	Optional	Filter devices by online state.
parameters.label	string	Optional	Filter by single label. Matches all devices that contains at least this label.
parameters.clientVersion	string	Optional	Filter devices by client version (exact match).
parameters.protectionStatusOverview	string	Optional	Filter devices by protection status overview.
parameters.patchOverallState	string	Optional	Filter devices by protection status overview.
parameters.publicIpAddress	string	Optional	Public IP address of the device.
parameters.organizationName	string	Optional	Name of organization (company or partner).
parameters.osName	string	Optional	Name of the operating system that is installed on the device.
parameters.activeDirectoryGroup	string	Optional	Name of the Active Directory Group.
parameters.subscriptionKey	string	Optional	Filter by subscription key that device registered with. Only devices in given subscription key are returned. Required format is XXXX-XXXX-XXXX-XXXX-XXXX where X is either a digit or an uppercase letter.
parameters.count	string	Optional	Name of the property to use in aggregation. When count parameter is provided and Accept header is set to application/vnd.withsecure.aggr+json then response contains aggregation data. Devices matching query parameters are grouped and counted by selected property values. count and histogram parameters can't be used together in a single query.
parameters.histogram	string	Optional	Name of the property to use in histogram type aggregation. When histogram parameter is provided and Accept header is set to application/vnd.withsecure.aggr+json then response contains aggregation data in the histogram form - aggregation data is returned for every date from last 30 days. Devices matching query parameters are grouped and counted by selected property values. count and histogram parameters can't be used together in a single query.
parameters.limit	number	Optional	The size of the single batch. Value defines upper bound for number of items, that are sent in single response. However it doesn't guarantee, that response will contain exact number of items if next page exist. Client that reads all items matching query parameters should depend only on nextAnchor property, which contain link to next result. Client can stop iteration when nextAnchor is missing in response.
headers	object	Optional	HTTP headers for the request
headers.Accept	string	Optional	HTTP headers for the request

Input Example

{"parameters":{"anchor":"no-value","organizationId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad","deviceId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad","type":"computer","state":"active","name":"","serialNumber":"","online":false,"label":"","clientVersion":"","protectionStatusOverview":"isolated","patchOverallState":"missingCriticalUpdates","publicIpAddress":"","organizationName":"","osName":"","activeDirectoryGroup":"","subscriptionKey":"","count":"protectionStatus","histogram":"protectionStatus","limit":20},"headers":{"Accept":"application/json"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.file_name	string	Name of the resource
items.file	string	Output field: items.file

Output Example

{"status_code":200,"response_headers":{"Date":"Wed, 11 Sep 2024 08:43:53 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-62bdff98fa4c42f1","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"","json_body":{"items":[]}}

Query EPP, EDR and Collaboration Security Events

Executes a search query against EPP, EDR, and Collaboration Protection Security Events in WithSecure Elements Endpoint Security, returning results in JSON. Includes events from child companies for partners.

Endpoint

URL: /security-events/v1/security-events

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Required	HTTP headers for the request
headers.Content-Type	string	Required	HTTP header that defines format of request body.
headers.Accept	string	Required	HTP header defines expected format of response body. Client should use header application/vnd.withsecure.aggr+json to receive aggregated results - security events grouped and counted by selected property.
data_body	object	Optional	Response data
data_body.organizationId	string	Optional	ID of an organization. If organizationID is missing, default organization of authenticated client is used.
data_body.persistenceTimestampStart	string	Optional	Lower bound for persistence timestamp in the returned security events. Minimum allowed value is 2022-08-01T00:00:01Z.
data_body.persistenceTimestampEnd	string	Optional	Upper, exclusive bound for persistence timestamp in the returned security events.
data_body.engine	array	Optional	Response data
data_body.engineGroup	array	Optional	Engine that triggered event.
data_body.severity	array	Optional	Event's severity.
data_body.targetId	string	Optional	ID of event's target - either ID of device or e-mail address. When parameter is present response contains all events related to EPP device or Office 365 entity.
data_body.acknowledged	boolean	Optional	Filter security events by acknowledgement status. If parameter is missing then response contains all events.
data_body.count	string	Optional	Name of property to use in aggregation. All Security Events matching filter parameters are grouped and counted by selected property. This parameter is required when client sends request with HTTP header Accept= application/vnd.withsecure.aggr+json.
data_body.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
data_body.order	string	Optional	Sorting order.
data_body.exclusiveStart	boolean	Optional	If equals true, then persistenceTimestampStart is used as exclusive lower bound. Otherwise, persistenceTimestampStart is inclusive.
data_body.limit	number	Optional	The size of the single batch. Min 1 to Max 200. Value defines upper bound for number of items, that are sent in single response. However it doesn't guarantee, that response will contain exact number of items if next page exist. Client that reads all items matching query parameters should depend only on nextAnchor property, which contain link to next result. Client can stop iteration when nextAnchor is missing in response.

Input Example

{"headers":{"Content-Type":"application/x-www-form-urlencoded","Accept":"application/json"},"data_body":{"organizationId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad","persistenceTimestampStart":"2022-08-01T00:00:01Z","persistenceTimestampEnd":"2022-08-01T00:00:01Z","engine":["engine1","engine2"],"engineGroup":["ecp","edr"],"severity":["critical","warning"],"targetId":"string","acknowledged":true,"count":"engine","anchor":"no-value","order":"desc","exclusiveStart":true,"limit":50}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
items	array	Output field: items
items.id	string	Unique identifier
items.action	string	Output field: items.action
items.engine	string	Output field: items.engine
items.severity	string	Output field: items.severity
items.serverTimestamp	string	Output field: items.serverTimestamp
items.persistenceTimestamp	string	Output field: items.persistenceTimestamp
items.eventTransactionId	string	Unique identifier
items.clientTimestamp	string	Output field: items.clientTimestamp
items.acknowledged	boolean	Output field: items.acknowledged
items.organization	object	Output field: items.organization
items.organization.id	string	Unique identifier
items.organization.name	string	Name of the resource
items.target	object	Output field: items.target
items.target.name	string	Name of the resource
items.target.id	string	Unique identifier
items.device	object	Output field: items.device
items.device.id	string	Unique identifier
items.device.name	string	Name of the resource
items.userName	string	Name of the resource
items.details	object	Output field: items.details
items.details.profileName	string	Name of the resource
items.details.path	string	Output field: items.details.path

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 09 Sep 2024 10:44:48 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-c460567a9f914407","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"OK","json_body":{"items":[{}],"nextAnchor":"link-to-next-page"}}

Read List of Security Events

Retrieve a list of security events within a specified time frame for a given organization, including hierarchical data if requested with a partner organizationId.

Endpoint

URL: /security-events/v1/security-events

Method: GET

Input

Argument Name	Type	Required	Description
parameters.organizationId	string	Optional	UUID of an organization. If organizationID is missing, default organization of authenticated client is used.
parameters.engine	array	Optional	Filter by engines that triggered event.
parameters.persistenceTimestampStart	string	Optional	Lower bound for persistence timestamp in the returned security events. Minimum allowed value is 2022-08-01T00:00:01Z.
parameters.persistenceTimestampEnd	string	Optional	Upper, exclusive bound for persistence timestamp in the returned security events.
parameters.serverTimestampStart	string	Optional	Lower bound for server timestamp in the returned security events.
parameters.serverTimestampEnd	string	Optional	Upper, exclusive bound for server timestamp in the returned security events.
parameters.severity	string	Optional	Filter by event's severities.
parameters.anchor	string	Optional	Anchor pointing to the page that should be retrieved. If the parameter is missing or equal to default value then endpoint returns first page.
parameters.order	string	Optional	Sorting order.
parameters.exclusiveStart	boolean	Optional	If equals "true", then persistenceTimestampStart and serverTimestampStart are used as exclusive lower bound. Otherwise, persistenceTimestampStart and serverTimestampStart are inclusive.
parameters.limit	number	Optional	The size of the single batch. Min 1 to Max 200. Value defines upper bound for number of items, that are sent in single response. However it doesn't guarantee, that response will contain exact number of items if next page exist. Client that reads all items matching query parameters should depend only on nextAnchor property, which contain link to next result. Client can stop iteration when nextAnchor is missing in response.

Input Example

{"parameters":{"organizationId":"5a1b6078-3c68-4870-9d2b-4f1fff3485ad","engine":["{engine1}","{engine2}"],"persistenceTimestampStart":"","persistenceTimestampEnd":"","serverTimestampStart":"","serverTimestampEnd":"","severity":"desc","anchor":"no-value","order":"critical","exclusiveStart":false,"limit":200}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
items	array	Output field: items
items.id	string	Unique identifier
items.serverTimestamp	string	Output field: items.serverTimestamp
items.clientTimestamp	string	Output field: items.clientTimestamp
items.persistenceTimestamp	string	Output field: items.persistenceTimestamp
items.engine	string	Output field: items.engine
items.severity	string	Output field: items.severity
items.action	string	Output field: items.action
items.organization	object	Output field: items.organization
items.organization.id	string	Unique identifier
items.organization.name	string	Name of the resource
items.device	object	Output field: items.device
items.device.id	string	Unique identifier
items.device.name	string	Name of the resource
items.device.winsAddress	string	Output field: items.device.winsAddress
items.eventTransactionId	string	Unique identifier
items.userName	string	Name of the resource
nextAnchor	string	Output field: nextAnchor

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 09 Sep 2024 10:44:48 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-c460567a9f914407","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"","json_body":{"items":[{}],"nextAnchor":"string"}}

Trigger New Remote Operation on Devices

Initiates a specified operation on active devices within the client's organization using their UUIDs provided in the request body.

Endpoint

URL: /devices/v1/operations

Method: POST

Input

Argument Name	Type	Required	Description
operation	string	Optional	Type of an operation to execute.
parameters.message	string	Optional	For isolateFromNetwork and showMessage operations. constraint-> max 512 characters.
parameters.consentMessage	string	Optional	For collectDiagnosticFile operation. constraint -> max 512 characters.
parameters.profileId	number	Optional	For assignProfile operation.
parameters.feature	string	Optional	For turnOnFeature operation.
parameters.turnOnTimeout	number	Optional	For turnOnFeature operation. Must be between 5 and 1440. Debug logging also turns off automatically with the device restart.
targets	array	Optional	List of targets (device identifiers) on which operation will be execute. Min Items= 1 and Max Items =5.

Input Example

{"json_body":{"operation":"isolateFromNetwork","parameters":{"message":"Your device will be isolated","consentMessage":"","profileId":123,"feature":"debugLogging","turnOnTimeout":5},"metadataParameters":[{"fileId":"string"}],"targets":["ec8a0100-d313-4896-b3cb-02188e060bf3","01898f1e-d32d-40fe-b3c5-9f039c1eac04","1226e0a9-653a-4682-b4ad-6a2fd54218b9","181fd624-1db0-49b8-b1b9-b88d6336bd75","21ccd888-01cc-459d-9341-2001508a83fc"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
multistatus	array	Status value
multistatus.target	string	Status value
multistatus.status	number	Status value
multistatus.operationId	number	Unique identifier
transactionId	string	Unique identifier

Output Example

{"status_code":207,"response_headers":{"Date":"Mon, 09 Sep 2024 07:12:50 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx","X-Transaction":"0000-cac6b1b18e344010","Vary":"Origin, Access-Control-Request-Method, Access-Control-Request-Headers","Strict-Transport-Security":"max-age=31536000 ; includeSubDomains"},"reason":"OK","json_body":{"multistatus":[{},{},{}],"transactionId":"0000-abcdef-1234"}}

Update Devices

Modify the state or subscription of specified devices in WithSecure Elements Endpoint Security. Requires a 'targets' JSON body.

Endpoint

URL: /devices/v1/devices

Method: PATCH

Input

Argument Name	Type	Required	Description
state	string	Optional	Device state to be changed to.
targets	array	Optional	list of targets (device identifiers) on which state will be changed. Min Items:- 1 Max Items:- 5.
subscriptionKey	string	Optional	Key of the subscription to which the devices will be moved.

Input Example

{"json_body":{"state":"blocked","targets":["ec8a0100-d313-4896-b3cb-02188e060bf3"],"subscriptionKey":"E43V-DE4H-U2X8-87L2-438V"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
multistatus	array	Status value
multistatus.target	string	Status value
multistatus.status	number	Status value
transactionId	string	Unique identifier

Output Example

Update Status of Incidents

Updates the status of specified incidents in WithSecure Elements Endpoint Security using target identifiers and a new status value.

Endpoint

URL: /incidents/v1/incidents

Method: POST

Input

Argument Name	Type	Required	Description
targets	array	Optional	List of incident IDs to update. Min Items:- 1 Max Items:- 1.
status	string	Optional	Status of the incident.
resolution	string	Optional	Resolution of incident. That property is required when status of incident is 'closed'.

Input Example

{"json_body":{"targets":["2c902c73-e2a6-40fd-9532-257ee102e1c1"],"status":"monitoring","resolution":"confirmed"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
multistatus	array	Status value
multistatus.target	string	Status value
multistatus.status	number	Status value
transactionId	string	Unique identifier

Output Example

{"status_code":200,"reason":"OK","json_body":{"multistatus":[{}],"transactionId":"0000-d1467e4907a54c87"}}

Response Headers

Header	Description	Example
Connection	HTTP response header: Connection	keep-alive
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Mon, 09 Sep 2024 07:12:50 GMT
Server	Information about the software used by the origin server	nginx
Strict-Transport-Security	HTTP response header: Strict-Transport-Security	max-age=31536000 ; includeSubDomains
Transfer-Encoding	HTTP response header: Transfer-Encoding	chunked
Vary	HTTP response header: Vary	Origin, Access-Control-Request-Method, Access-Control-Request-Headers
X-Transaction	HTTP response header: X-Transaction	0000-d425d30e3a4a4a79