Elements API Changelog

Identity response actions

New identity response actions have been released.

The new actions are enabling management of Microsoft Entra. The actions are:

endCurrentSession
resetPassword
blockUserAccess

See the details and examples of the new Elements API features from the API documentation.

Bugfix in the query devices endpoint (firewallState field)

A bugfix has been released in the query devices endpoint (GET /devices/v1/devices). Previously the response enum field firewallState contained a value "disabledMacos" while the correct and documented spelling is "disabledMacOs". With the latest release the spelling in the response has been fixed and is now "disabledMacOs" (capital O as in Os).

New Endpoint: Retrieve Latest Database Versions

We have introduced a new endpoint in the WithSecure Elements API that allows users to retrieve the latest versions of various databases. This endpoint provides up-to-date information on the current versions of databases used within the WithSecure Elements platform.

Endpoint: GET /databases/v1/latest-versions

Details:

Purpose: Check the latest versions of databases
Response: Returns a list of databases along with their latest version numbers.
Usage: Ideal for ensuring that your systems are using the most current database versions for optimal security and performance.

For more information, please refer to the API documentation.

The latest Elements API release brings new incident sources from the incidents endpoint.

There is a new query parameter <source> in the /incidents/v1/incidents endpoint.

The <source> parameter can be one or many of these (separated by comma):

endpoint - The incident contains detections raised by endpoint events
cloud - The incident contains detections raised by cloud events
customer - The incident is a support request originated from the customer
endpointExpert - The incident was raised manually by the MDR service team

If the <source> argument is not given, the incidents endpoints returns incidents from all possible sources.

Please see the api definition for more details on the incident endpoint: https://connect.withsecure.com/api-reference/elements#get-/incidents/v1/incidents

glusan

Create response actions

Elements API allows a user with EDR subscription to create a response action.

Example query like curl -X POST -H "Authorization: Bearer {token}" -H "Content-Type: application/json" https://connect.withsecure.com/response-actions/v1/response-actions -d '{"organizationId": "{organizationId}", "type": "netstat", "comment": "test", "targets": ["{deviceId}"], "parameters": {"maxFileHash": 10}}'

{
  id: "{actionId}"
}

Response contains the id of created action.

For more information about the parameters used, please use our API reference documentation.
https://connect.withsecure.com/api-reference/elements#tag--Response-actions

glusan

List created response actions.

Advance response action is a feature that allows responders to execute actions directly on attack targets when an attack is detected in order to aid with the incident investigation and containment.

Listing of response actions with filtering is now available with Elements API.

Example query like curl -X GET -H "Authorization: Bearer {token}" https://api.connect.withsecure.com/response-actions/v1/responses?organizationId={organizationId}&order=asc

{
  "items": [
    {
      "id": "18f99eba-81a0-4000-8b87-366b26bb7c01",
      "type": "string",
      "state": "created",
      "progress": {
        "devicesCount": 0,
        "pendingTasksCount": 0,
        "errorTasksCount": 0,
        "activeTasksCount": 0,
        "completedTasksCount": 0,
        "successfullyCompletedTasksCount": 0
},
      "createdTimestamp": "1970-01-01T00:00:00.000Z",
      "updatedTimestamp": "1970-01-01T00:00:00.000Z",
      "devices": [
        {
          "deviceId": "18f99eba-81a0-4000-8ac9-f6243f1f6901"
}
      ],
      "author": {
        "id": "18f99eba-81a0-4000-8906-2164b4581501",
        "source": "oneId",
        "username": "string"
},
      "comment": "string",
      "result": "succeeded"
}
  ],
  "nextAnchor": "string"
}

The response contains the list of created response actions for the organization. It contains action type, creation time, result and other parameters.

glusan

Device subscription change

Elements API allows a solution provider to move an endpoint device from one subscription to another.

Example query like curl -X PATCH -H "Authorization: Bearer {token}" -H "Content-Type: application/json" https:// connect.withsecure.com /devices/v1/devices -d '{"subscriptionKey": "E43V-DE4H-U2X8-87L2-438V", "targets": ["ec8a0100-d313-4896-b3cb-02188e060bf3",1c49df1a-02d9-4bc4-91db-5609b80ad709]}

{
  "multistatus": [
    {
      "target": "ec8a0100-d313-4896-b3cb-02188e060bf3",
      "status": 200
},
    {
      "target": "1c49df1a-02d9-4bc4-91db-5609b80ad709",
      "status": 400,
      "details": "Product transition is not allowed"
}
  ],
  "transactionId": "0000-abcdef-1234"
}

From response client can find which devices have been successfully moved to a new subscription, and which ones failed to do that and why.

Device statistics

Elements API client can read statistics of EPP devices from query endpoint. When request contains HTTP header Accept: application/vnd.withsecure.aggr+json Elements API selects all devices matching query parameters and depending on query parameters and groups items by selected property. If client requests histogram then API return statistics for last 30 days.

Device count

Elements API uses value of parameter count which represents name of property that is used to group devices by. In response API return list of items where each one represents different value of property and number of devices having such value.

Example query like curl -v -X GET -H "Accept: application/vnd.withsecure.aggr+json" "https://api.connect.withsecure.com/devices/v1/devices?count=protectionStatus" groups devices by property protectionStatus .

{

"items" : [ 
{  "count" : 1, "protectionStatus" : "isolated" } , 
{  "count" : 16, "protectionStatus" : "malwareIssue" }, 
{  "count" : 4, "protectionStatus" : "notConnected" }, 
{  "count" : 88, "protectionStatus" : "protected" },
{ "count" : 11, "protectionStatus" : "subscriptionExpired" } 
]

}

From response client can find that query found:

1 device with protection status equal isolated
16 devices with protection status equal malwareIssue
4 devices with protection status equal notConnected
88 devices with protection status equal protected
11 devices with protection status equal subscriptionExpired

Device histogram

Elements API uses value of parameter histogram which represents name of property that is used to group devices by. In such case API return statistic for each day in last 30 day. Response contains list of items sorted in descending order where each element has format

{ "count": <number of devices>, <name of property>: <value of property>, "date": <statistic date> }

Example query like curl -v -X GET -H "Accept: application/vnd.withsecure.aggr+json" "https://api.connect.withsecure.com/devices/v1/devices?histogra=protectionStatus" generates histogram for property protectionStatus .

{

"items" : [ 
{ "count" : 1, "protectionStatus" : "isolated", "date": "2024-02-14"}, 
{ "count" : 16, "protectionStatus" : "protected", "date": "2024-02-14"} ,
{ "count" : 5, "protectionStatus" : "isolated", "date": "2024-02-13"}, 
{ "count" : 12, "protectionStatus" : "protected", "date": "2024-02-13"} 
]

}

From response client can find that:

on 2024-02-14:
- there was 1 device with protection status equal isolated
- 16 devices with protection status equal protected
on 2024-02-13
- there were 5 devices with protection status equal isolated
- 12 devices with protection status equal protected

Statistics of Security Events

Elements API client can read statistics from query endpoint. When request contains HTTP header Accept: application/vnd.withsecure.aggr+json Elements API selects all events matching query parameters, groups events by selected property. In response client receives number of items in each group.

Example

curl -v -X POST -H "Accept: application/vnd.withsecure.aggr+json" -d "count=engine" -d "engineGroup=epp -d "persistenceTimestampStart=2024-01-01T00:00:00Z" "https://api.connect.withsecure.com/security-events/v1/security-events"

Example cURL reads statistics for EPP security events that have been created after 2024-01-01. Client uses parameter count=engine to group events by property engine.

{ "items" : [{ "engine" : "manualScanning", "count" : 10 }, { "engine" : "tamperProtection", "count" : 143 }, { "engine" : "firewall", "count" : 17 }, { "engine" : "deepGuard", "count" : 22 } ] }

Received response contains information that API found 10 events from manualScanning, 143 events from tamperProtection, 17 from firewall and 22 events from deepGuard

Elements API Cookbook contains example statistic request implemented in Python.

New capabilities of Elements API

Security Events Query endpoint supports new filters and response properties:

EPP security events contain device label. Label is only present in events that were created after administrator had added label to EPP device,
client can filter security events by targetId - id of EPP device or e-mail address of Office 365 user,
client can filter security events by acknowledgement status. To select only not acknowledged events client should add acknowledged=false to request parameters,
acknowledged events contains acknowledgement status:
- acknowledge date,
- name of user that acknowledged event.

Clients can use special value no-value in anchor parameter to get first page. It might be useful in various No-code or low-code services

maciej_antkiewicz

New response actions available

For the device operations endpoint support for the following new operations is added:

assign profile
scan for malware
show message
turn on feature: debug logging
collect diagnostic file

Two new fields are introduced: metadataParameters to POST response and metadata to GET response. Both serve the same purpose - to provide operation specific information. For example, collect diagnostic file returns fileId inside these objects, field which is used to identify diagnostic file.

For more information and request examples consult endpoints documentation:

https://connect.withsecure.com/api-reference/elements#post-/devices/v1/operations
https://connect.withsecure.com/api-reference/elements#get-/devices/v1/operations

Query not archived EDR incidents

Client calling Incidents endpoint can request only not archived EDR incidents by adding to query parameter archived=false. Querying only not archived incidents is highly recommended as it might have positive impact on requests speed.

Example

curl -H "Authorization: Bearer $TOKEN" https://api.connect.withsecure.com/incidents/v1/incidents?archived=false

Endpoint Protection API: List missing software updates endpoint end of life on 2nd of May 2024

The old List missing software update endpoint is deprecated and should be replaced by the Query missing software updates endpoint in the Elements API.

The Endpoint Protection API is fully deprecated. The ability to create API keys is soon going to be removed from Elements Security Center.

The following endpoints have past their end of life date and should not be used anymore

Computers endpoints: 30th of May, 2023
Security events endpoints: 30th of June, 2023
Companies endpoints: 31st of July, 2023
Invitations endpoints: 3rd of November, 2023

The following endpoints will soon be end of life, and customers should migrate as soon as possible.

Subscription endpoints: 11th of March, 2024
List missing software updates endpoint: 2nd of May,

Query missing software updates

Missing software updates query endpoint is available in Elements API. Integration client can list missing updates for particular EPP device and filter results by category and severity. It should be used as replacement for endpoint from legacy EPP API that has been deprecated.

Example

To find all critical software updates for single device with curl execute following command

curl -H "Authorization: Bearer $TOKEN" -d "deviceId=$DEVICE_ID" -d "severity=critical" https://api.connect.withsecure.com/software-updates/v1/missing-updates

Replace $TOKEN with authorization token and $DEVICE_ID with device identifier that can
be found in response from device listing.

Filter devices by name of operating system, public IP and Active Directory group

New query parameters in endpoint /devices/v1/devices allows filtering EPP devices:

activeDirectoryGroup - filter devices by name of Active Directory group
osName - filter devices by name of the operating system
publicIpAddress - filter devices by public IP address of device

Elements API: Description added to both incidents and detections endpoints

“/incidents/v1/incidents” - description of incident entered in Elements Security Center

Property “description” contains the "incident description" that user inserts in Broad Context Detections (BCD) view under "analysis" tab. This is useful information for a reporting system or a ticketing solution

“/incidents/v1/detections” - human-friendly description of detection

Property “description” contains value that is visible in detections list in Elements Security Center

Query EPP, EDR and Collaboration Protection (ECP) Security Events

New Elements Security Events query endpoint has been released and is available for new and existing integrations. New endpoint allows querying Security Events generated in Endpoint Protection (EPP), Endpoint Detection and Response (EDR) and Collaboration Protection (ECP).

Support for Collaboration Protection engines allows reading Security Events related to Microsoft Outlook, OneDrive, SharePoint and Teams from REST API. To get last 10 Collaboration Protection events with cURL run command curl -H "Authorization: Bearer <authorization token>" -d "persistenceTimestampEnd=2030-12-31T00:00:00Z&engineGroup=ecp&limit=10" https://api.connect.withsecure.com/security-events/v1/security-events. More examples can be found in endpoint documentation, Getting started guide and in Elements API Cookbook.

Q&A

Q: Why do you introduce new endpoint instead extending capabilities of existing one?

A: Existing GET /security-events/v1/security-events endpoint is a legacy from early releases and cannot be easily extended to support Collaboration Protection events. The new endpoint has a more modern design and will make it easier to add new features and capabilities in the future.

Q: Is Security Events query endpoint compatible with existing endpoint?

A: If you're interested only with events from EPP and EDR then you won't notice any significant differences. Security Events query endpoint preserves format of response that is known from existing endpoint. If you're interested with Collaboration Protection events you need to adjust your integration and prepare it for different response - for example they don't have device properties or user name.

Q: I'm only interested with Security Events from EPP and EDR. What I need to change after switching to new endpoint.

A: Response for EPP and EDR engines contains same properties that are present in response from
GET /security-events/v1/security-events. In order to get EPP and EDR events you need to make
following changes in your integration:

send query parameters in request body,
add to request HTTP header Content-type: application/x-www-form-urlencoded,
add to request HTTP header Accept: application/json,
add parameter engineGroup=epp,edr to request body in order to receive only Security Events from EDR and EPP
adjust value of parameter limit - maximal allowed value is 200

Q: What will happen with existing GET /security-events/v1/security-events endpoint.

A: Existing endpoint will stay there, we don't have plans to remove it or deprecate it. It means that you can continue using it in your integration if you're interested only with EPP and EDR events. We will keep maintaining endpoint (bug fixes) however we will stop adding new features to it. New capabilities will be added only to Security Events query endpoint.

Endpoint Protection API: Subscriptions endpoints end of life on 11th of March 2024

The old subscriptions endpoints are deprecated and should be replaced by the subscription endpoints in the Provisioning API. To use this API, you need to request Read-only Provisioning API credentials from WithSecure Support. Access to Provisioning API is only for partner (SOP) accounts.

The following Endpoint Protection API subscriptions endpoints will stop working on the 11.03.2024:

Get company subscription details
Get partner subscription details
List company subscriptions
List partner subscriptions
Remove computers from subscription (replaced by Elements API endpoints “Update device state” or “Delete device”)

Hubert_Szymanski

Elements API: incidents updates

Listing incidents: new fields have been added to incidents listing endpoint:

riskScore is numerical representation of incident's risk. It's directly linked to the riskLevel.
categories is a list with incident's categories that helps with classification of the incident like for example CREDENTIAL_THEFT etc.

Commenting incidents: new endpoint has been implemented that allows to add comment to incidents. At the moment added comments are visible in EDR portal when viewing incident's details.

NicoL

Provisioning API

· Move Company

This new API call allows to move a company to Service Partner (SEP) or Buyer Party, but the changes only allowed within the same Buyer Party of the company as described in https://connect.withsecure.com/api-reference/provisioning#post-/company/-companyUuid-

*The endpoint is only available to selected buyer

Hubert_Szymanski

Elements API: cookbook and new filter for incidents

Cookbook: To help our customers integrating with Elements API we created Elements API Cookbook. It contains recipes with descriptions of common use cases and example solutions implemented as Python procedures.
Incidents: new filters updatedTimestampStart & updatedTimestampEnd have been introduced to incidents listing endpoint. Main use case is to enhance incidents and detections polling as filtering by updatedTimestamp helps getting recent updates. Please, learn more from recipe in our new Cookbook - poll detections.
Additionally exclusiveStart flag has been added to help with avoiding duplicates while polling incidents.

Hubert_Szymanski

Elements API: new filters for devices and incidents

Incidents: new filter riskLevel has been introduced to incidents listing endpoint. It may be used to list incidents with higher risk levels.
Devices: new filter subscriptionKey has been introduced to devices listing endpoint. It allows to list only devices from specified subscription key.

Elements API: managing status of EDR incident

New endpoint for managing status of EDR incidents is available. Client can update status of incident or close it with specified resolution.

maciej_antkiewicz

Elements API:

Manage devices

New endpoints are published:
- Update device state - client can block or inactivate devices
- Remove devices - client can delete device

List devices endpoint was updated and now devices can be filtered by state. Also, state field is always returned in the response.

List incidents

New endpoint is published:

- List incidents - client can view list of the incidents in the organization

Elements API: New properties in devices list

New properties has been added to to device list endpoint:

total and free space on system drive
total and free physical memory
Vulnerability Management risk score. That values is calculated only for devices with active VM module
EDR incidents counters
computer model and BIOS version
version of malware database and timestamp of its last update
list of MAC addresses
property that indicates if user has administrator privileges

NicoL

Provisioning API

· Update Service Partner (SEP) name

This new API call allows to change an existing Service Partner(SEP) name by using the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#post-/seps/-partner_uuid-

Endpoint Protection API: Provisioning invitations endpoints end of life on 3rd of November 2023

The old invitations endpoints are deprecated and should be replaced by the new Elements devices endpoints: https://connect.withsecure.com/api-reference/elements#tag--invitations

The following Endpoint Protection API invitation endpoints will stop working on the 03.11.2023:

Create new invitation
List pending or expired invitations
Remove invitations
Renew expired invitations
Resend pending invitations

Reminder: In order to provide a better and unified set of APIs for WithSecure Elements, we are progressively deprecating the Endpoint Protection API and replacing it by Elements API. The following endpoints will reach their end of life soon as indicated earlier in this change log

Computers endpoint: 30th of May
Security events endpoint: 30th of June
Companies endpoint: 31st of July

Elements API: Managing EPP invitations

Authorized client can manage EPP invitations:

list pending or expired invitations
create new invitation - installation link with one-time password is sent to specified recipient
delete invitation - pending invitation is canceled and can't be used anymore
renew expired invitation or resend pending invitation

Legacy EPP API for managing invitations is deprecated.