Manage Sophos Endpoint Group with API

1 Overview

This article guides you to use Sophos API to manage groups of endpoints and servers

1.1 Requirements

To be able to make an API call, you need the Credential API. Instructions to get Credential API in this article LINK

This article uses the Windows CMD program to execute Curl commands, and uses the Visual Studio Code text editor to view the API call output in JSON format.

In this article, I use Prettier and Prettify JSON Extension for Visual Studio Code

1.2 General syntax for making API requests

When making an API call through Curl, we execute the statement with the following syntax:

Curl -X<method> -H “Content-type:application/json” -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” -d <Request Body> <data-region>/<path>

With the following option:

Curl: With windows machine, we change it to curl.exe

<method>:  request method ( GET, POST…. )

<tenant-id>: Tenant ID (taken from set of APIs Credential).

<jwt>: Access token (taken from set of APIs Credential).

<data-region>: Your central server address (taken from set of APIs Credential).

<path>: request path. (VD: /endpoint/v1/endpoint-groups )

<Request body>: Displayed in the article as json and needs to be converted to string to be included in the curl command. (You can use the following json to string converter website https://jsontostring.com/)

2 Instructions for implementing Call API to manage Endpoint Group

2.1 Get a list of Endpoint Groups

API: GET /endpoint/v1/endpoint-groups

The command executes as follows on CMD:

curl.exe -XGET -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” <data-region>/endpoint/v1/endpoint-groups

Open CMD and copy the above command

The results are returned as follows, we copy this text to the Visual Studio Code editor. Proceed to convert to JSON format for easy viewing.

In Visual Studio Code we create a new file in json format. File >> New File >> Select a Language

Copy the output just received above. Press Ctrl + Shift + P to convert. Select Format Document (Force)

After converting to JSON format, we can see a list of groups with information about name, id, endpoint… as shown below.

The same applies to other API calls.

Check out Groups on Sophos Central. Go to Endpoint Protection >> Computer >> Computer Group.

2.2 Create a new Endpoint Group

API: GET /endpoint/v1/endpoint-groups

Request body: Is the information about the Group that we want to create. Examples are as follows:

{

  “name”: ” Seattle computers”,                               

  “description”: ” User devices in the Seattle office”,

  “type”: “computer”,

  “endpointIds”: [

“e6a03d34-a943-45b7-8de3-deaf38864be4”,

“b7e5f3aa-a7c6-43c6-a65e-3cd52008464b”,

“f0316f62-6ce7-4008-99c5-6a1c209ab494”        //The ID of the computer you want to add to group

  ]

}

The command does the following:

curl.exe -XPOST -H “Content-type:application/json” -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” -d “{\”name\”: \”HCM computers\”,\”description\”: \”HCM office\”,\”type\”: \”computer\”,\”endpointIds\”: [\”034aa834-88bf-48ba-bcea-2864c349402b\”,\”0f416ce3-041f-4419-931d-2452a4c38566\”]}” https://api-us03.central.sophos.com/endpoint/v1/endpoint-groups

Results returned:

Check out Groups on Sophos Central. Go to Endpoint Protection >> Computer >> Computer Group.

2.3 Get Endpoint Group byID

API: GET /endpoint/v1/endpoint-groups/{groupId}

{Group ID}: here is the group ID you want to get. Group ID can be obtained in section 2.1

The command does the following:

curl.exe -XGET -H “Content-type:application/json” -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” https://api-us03.central.sophos.com/endpoint/v1/endpoint-groups/3007ed8d-5762-4880-81c6-313e8c216db2

Results returned:

2.4 Update 1 Endpoint Group

API: PATCH /endpoint/v1/endpoint-groups/{groupId}

{Group ID}: here is the group ID you want to get. Group ID can be obtained in section 2.1

Request body: The parameters of the Endpoint Group want to update.

{

  “name”: “HCM computer updated”,

  “description”: “HCM office”

}

The command does the following:

curl.exe -XPATCH -H “Content-type:application/json” -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” -d “{\”name\”: \”HCM computers updated\”}” https://api-us03.central.sophos.com/endpoint/v1/endpoint-groups/3007ed8d-5762-4880-81c6-313e8c216db2

Return result: The group name has been changed to HCM computer updated

Check out Groups on Sophos Central. Go to Endpoint Protection >> Computer >> Computer Group.

2.5 Add Endpoint to Group

API: POST /endpoint/v1/endpoint-groups/{groupId}/endpoints

{Group ID}: here is the group ID you want to get. Group ID can be obtained in section 2.1

Request body: List of endpoints you want to add

{

  “ids”: [

“8a4597a4-e5dd-4e0b-af6e-f627a4f1f699”,  //Will be added

“bf9907b2-df81-4531-9981-8c47cd24d5cc”  // Will be added

  ]

}

The command does the following:

curl.exe -XPOST -H “Content-type:application/json” -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” -d “{\”ids\”: [\”170c34f4-460a-45f6-9e1a-e6e9935f3f8c\”,\”18a23e73-97f7-4193-8e03-0e48d6cbfee8\”]}” https://api-us03.central.sophos.com/endpoint/v1/endpoint-groups/3007ed8d-5762-4880-81c6-313e8c216db2/endpoints

Return result: Group added 2 PCs

Check out Groups on Sophos Central. Access to Endpoint Protection >> Computer >> Computer Group >> Group is added.

2.6 Remove Endpoint from Group

API: DELETE /endpoint/v1/endpoint-groups/{groupId}/endpoints/{endpointId}

{Group ID}: here is the group ID you want to get. Group ID can be obtained in section 2.1

{EndpintID}: here is the Endpoint ID that you want to delete. Endpoint ID can be obtained in section 2.1

The command does the following:

curl.exe -XDELETE -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” -d “{\”ids\”: [\”170c34f4-460a-45f6-9e1a-e6e9935f3f8c\”,\”18a23e73-97f7-4193-8e03-0e48d6cbfee8\”]}” https://api-us03.central.sophos.com/endpoint/v1/endpoint-groups/3007ed8d-5762-4880-81c6-313e8c216db2/endpoints/18a23e73-97f7-4193-8e03-0e48d6cbfee8

Return result: Group deleted the PC successfully

Check out Groups on Sophos Central. Go to Endpoint Protection >> Computer >> Computer Group >> Group. We see that the endpoint has been removed from the group

2.7 Delete Endpoint Group

API: DELETE /endpoint/v1/endpoint-groups/{groupId}

{Group ID}: here is the group ID you want to get. Group ID can be obtained in section 2.1

The command does the following:

curl.exe -XDELETE -H “Authorization: Bearer <jwt>” -H “X-Tenant-ID: <tenant-id>” -d “{\”ids\”: [\”170c34f4-460a-45f6-9e1a-e6e9935f3f8c\”,\”18a23e73-97f7-4193-8e03-0e48d6cbfee8\”]}” https://api-us03.central.sophos.com/endpoint/v1/endpoint-groups/3007ed8d-5762-4880-81c6-313e8c216db2

Return result: Group deleted the PC successfully

Check out Groups on Sophos Central. Access to Endpoint Protection >> Computer >> Computer Group >> Group is added.

Be the first to comment

Leave a Reply

Your email address will not be published.


*


This site uses Akismet to reduce spam. Learn how your comment data is processed.