Elements API Changelog

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.

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

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.

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.