WithSecure Elements API change log

anesterov

This thread is a changelog for the WithSecure Elements API.

📝 Click here to see the most recent change log and bookmark the discussion to be notified of any updates.

SergeH

Endpoint Protection API

·      New Security Events listing

 Security Events provides extensive data that WithSecure engines detected. In addition to infections it reports security events generated by application control, Dataguard, tamper protection, browsing protection...The two new endpoints below provide listing by company or partner but also filtering (e.g. by device, by engine)

·      https://connect.withsecure.com/api-reference/psb#get-/companies/-companyUuid-/security-events

·      https://connect.withsecure.com/api-reference/psb#get-/partners/-partnerUuid-/security-events

·      Infections listing are deprecated

Security Events contains infections and much more so the old infections endpoint are deprecated and should be replaced by replaced by Security Events at first opportunity

The following infections Endpoint will stop working by 29.10.2022

·      https://connect.withsecure.com/api-reference/psb#get-/companies/-companyId-/infections

·      https://connect.withsecure.com/api-reference/psb#get-/companies/-companyUuid-/computers/-computerId-/infections

·      https://connect.withsecure.com/api-reference/psb#get-/partners/-partnerId-/infections

 

SergeH

Provisioning API

·     New url to reflect our new brand

Please update the following url at first opportunity.

• Production:
  • New url: https://commercial.connect.withsecure.com
  • Deprecated url: https//boop.f-secure.com
• Staging:
  • New url: https://commercial-test.connect.withsecure.com
  • Deprecated url: https://boop-test.f-secure.com

The existing whitelist will still apply.

The deprecated url will not be supported after 06.11.2022

·     Get subscription

This new API call allows to get all the details of a subscription by querying with the key as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions/-subscription_key-

NicoL

Provisioning API

·     Register a Service Partner (SEP)

This API endpoint now return partnerUuid in the response. You may refer to API Reference in https://connect.withsecure.com/api-reference/provisioning#post-/ws/rest/provisioning/v1/seps

[Deleted User]

Endpoint Protection API

Poll for security events

This new API endpoint is specifically meant for polling for changes in Security Events. By providing boundaries using server_timestamp query parameters clients have full control over the data set they are interested in. Moreover the data is sorted in the ascending order by the timestamp parameter allowing for easy replay of historical data also simplifying the polling for new events use cases.

 Additional JavaScript code snippet is also attached to illustrate the advised approach to reading historical data and polling for the new events. 

See: https://connect.withsecure.com/api-reference/psb#get-/accounts/-accountUuid-/security-events/polling

NicoL

Provisioning API

·     Get subscriptions by company uuid

This new API call allows to get the subscription details list under the specific licensee by querying with the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-companyUuid--companyUuid--include_expired--include_expired-

·     Get subscriptions by reference number

This new API call allows to get the subscription details list under the specific licensee by querying with the buyer's internal reference number as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-buyer_assigned_account_id--buyer_assigned_account_id--include_expired--include_expired-

NicoL

Provisioning API

·     Get subscriptions by partner uuid

This new API call allows to get the subscription details list under the specific reseller by querying with the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-partnerUuid--partnerUuid--include_expired--include_expired-

·     Get subscriptions by buyer account id

This new API call allows to get the subscription details list under the specific partner by querying with the unique identifier as described in https://connect.withsecure.com/api-reference/provisioning#get-/ws/rest/provisioning/v1/subscriptions-buyer_account_id--buyer_account_id--include_expired--include_expired-

NicoL

Provisioning API

New products are now supported in Provisioning API

FCEA: WithSecure™ Elements EDR for Computers

FCEN: WithSecure™ Elements EDR for Servers

FCKC: WithSecure™ Elements Vulnerability Management

NicoL

Provisioning API

·     Terminate subscription

This new API call allows to remove the subscription of licensee by using the key as described in https://connect.withsecure.com/api-reference/provisioning#delete-/ws/rest/provisioning/v1/subscriptions/-subscription_key--force--force-

Milosz

Elements API

Elements API is a new API framework that will cover all Elements offer. For its launch it provides:

• API Credentials UI where API credentials can be managed for all Elements solution. It allows to apply a policy to renew credential after a certain time or to delete unused credentials. API credentials are now independent of users. 
• Organization endpoint allowing a partner to list all its companies
• Security Events endpoint allowing to list all security events including EDR incidents. That will replace the events endpoint in Endpoint Protection API.

Documentation:

• Getting started guide: https://connect.withsecure.com/getting-started/elements
• API reference: https://connect.withsecure.com/api-reference/elements#overview

dolatawojciech

Elements API

• Security Events endpoint now allows to fetch events also for partner organizations.

dolatawojciech

Elements API

Changes in existing endpoints:

• Organizations endpoint now has parameter 'type' which allows to fetch company or partner organizations. https://connect.withsecure.com/api-reference/elements#get-/organizations/v1/organizations

New endpoints:

• Devices endpoint allows listing all devices under organization. https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices

This first release of Devices endpoint provides information related to the devices (IP address, serial number, UPN...) to allow correlation with other data sources in a SIEM/SOAR, as well as information related to the level of protection.

We are looking for customer feedback before adding even more data. Please provide your ideas through “My feedback” when you are logged in Elements Security Center, or directly through https://ideas.withsecure.com/ideas (same credentials that you are using to access Elements Security Center), under category "Elements API".

Endpoint Protection API: Devices endpoints are deprecated

The old devices endpoints are deprecated and should be replaced by replaced by the new Elements devices endpoints that provide more information.

The following devices endpoint will stop working by 30.05.2023:

• Get all company computers report
• Get all partner computers report
• Get company computer details
• List company computers
• List partner computers

dolatawojciech

Elements API

Changes in existing endpoints:

• Devices and Security Events endpoints: parameter organizationId is now optional. If it is not present, default organization of authenticated client is used.
• Organizations endpoint: added new optional organizationId parameter, now endpoint lists organizations belonging to requested organization (including itself if type matches). If parameter is not present, default organization of authenticated client is used. https://connect.withsecure.com/api-reference/elements#get-/organizations/v1/organizations

dolatawojciech

Elements API

Changes in existing endpoints:

• Security events endpoint supports filtering by engine (e.g. EDR) or severity (critical)
• Security events endpoint supports a new engine: System events log. The type of events log sent must be configured from the EPP Profile

Endpoint Protection API

Security events endpoints are deprecated

The old security events endpoints are deprecated and should be replaced by the new Elements security events endpoints. https://connect.withsecure.com/api-reference/elements#get-/security-events/v1/security-events

The following security events endpoints will stop working by 30.06.2023:

• List security events for a company
• List security events for a partner
• Poll for security events

Infections endpoints have been removed from documentation and will stop working at any time.

Milosz

Endpoint Protection API

Companies endpoints are deprecated

Companies endpoints are deprecated. Clients should use instead Organizations endpoint from Elements API.

Support for Companies endpoint will end by 31.07.2023

dolatawojciech

Elements API

Changes in existing endpoints:

• Devices endpoint supports filtering by device serial number (https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices).

NicoL

Provisioning API

Fixed the missing product in Provisioning API Get Subscription endpoints.

The following endpoint is now showing FCEC (WithSecure™ Elements EDR and EPP for Computers) in the response:

• Get subscription by key
• Get subscriptions by buyer account id
• Get subscriptions by company uuid
• Get subscriptions by partner uuid
• Get subscriptions by reference number

Hubert_Szymanski

Elements API

Changes in existing endpoints:

• Devices endpoint: New fields were added to response with device type computer containing last software scan and install timestamps (https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices).

dolatawojciech

Elements API

Changes in existing endpoints:

• Security events endpoint: engine and severity query parameters support multiple values (https://connect.withsecure.com/api-reference/elements#get-/security-events/v1/security-events).

dolatawojciech

Elements API

Changes in existing endpoints:

• Devices endpoint: added new filter protectionStatusOverview
  (https://connect.withsecure.com/api-reference/elements#get-/devices/v1/devices)

dolatawojciech

Elements API

Changes in API Clients UI:

• Removed the organization column, current organization still can be seen in top bar.

Milosz

Elements API: Listing EDR dections and isolating computer from network

New features are released in Elements API:

1. Listing detections of EDR incident - client can correlate EDR incident
   with list of events from EDR detection engine.
2. Isolating computer from network and relasing from isolation - client can send
   command, that isolates workstation or server at risk. Other supported operation
   allows releasing safe computer from isolation.
   Support for other remote operations will be extended in the future.
3. Reading list of remote operations - client can check status of remote operation for
   particular computer.

Triggering remote operations is only allowed for clients with Read/Write permissions.
Getting Started guide contains information how to add credentials with required grant.

Milosz

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.

SergeH

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

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-

Milosz

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