Endpoint API updates

We have made a few improvements to the Endpoint API that allow you to isolate endpoints, either one at a time or in bulk, and manage isolation exclusions. We have also added new filtering options when searching for endpoints.

Endpoint isolation¶

You can now isolate an endpoint:

PATCH /endpoint/v1/endpoints/{endpointId}/isolation

Request body:

{
  "enabled": true,
  "comment": "Reason for isolating this endpoint"
}

The response is an endpoint isolation object.

Turn on or off endpoint isolation for multiple endpoints:

POST /endpoint/v1/endpoints/isolation

Request body:

{
  "enabled": true,     // Or false if removing from isolation
  "comment": "The reason the endpoints should be isolated or not.",
  "ids": [
    "<endpoint-id>",
    "<endpoint-id>",
    ...
  ]
}

The status code is 202 (Accepted) if this operation was accepted. The response JSON has an items field which contains an isolation object per endpoint ID in the request. See the API reference for more details.

You can also GET the isolation object for any endpoint.

Manage isolation exclusions¶

To create a new isolation exclusion:

POST /endpoint/v1/settings/exclusions/isolation

Request body:

{
  "direction": "inbound", // Or "outbound" or "both"
  "comment": "Reason for excluding this traffic from isolation",
  "remoteAddresses": [
    "10.1.2.32"
  ],
  "remotePorts": [
    4233,
    4235
  ],
  "localPorts": [
    10422
  ]
}

The response is an isolation exclusion object with a unique ID.

See the API reference for how to get a single isolation exclusion by ID, update it, or delete it.

GET|PATCH|DELETE /endpoint/v1/settings/exclusions/isolation/{exclusionId}

Endpoint search improvements¶

Endpoints object returned in the response to GET /endpoint/v1/endpoints and GET /endpoint/v1/endpoints/{endpointId} now contain these additional fields:

New field	Description
`isolation`	This is the isolation state as reported by an endpoint. It contains three fields: `status`, which can have the string value `isolated` or `notIsolated`, and two other boolean fields, `adminIsolated` and `selfIsolated`, which indicate how the endpoint came to be isolated.
`cloud`	This field is set when Sophos Central becomes aware that the endpoint is a cloud instance. It has two fields: `provider`, which can be `aws` or `azure`, and `instanceId`, which is the instance ID assigned by the cloud provider.

When querying endpoints, you can now pass these query params to GET /endpoint/v1/endpoints to narrow your search:

Query param	Description
`hostnameContains`	Find endpoints where the `hostname` contains the given string.
`associatedPersonContains`	Find endpoints where the name of the person associated with the endpoint contains the given string.
`groupNameContains`	Find endpoints where the name of the group the endpoint is in contains the given string.
`ipAddresses`	Find endpoints by IP addresses.
`search`	Term to search for in the specified search fields.
`searchFields`	Comma-separated list of search fields for finding the given search term. Defaults to `hostname,groupName,associatedPersonName,ipAddresses`.
`isolationStatus`	Find endpoints by isolation status. This can have the value `isolated` or `notIsolated`.
`cloud`	Find endpoints that are cloud instances. This should be a comma-separated list of one or more terms, each of which is either the name of the provider (`aws`), or a cloud instance ID (`i-3bc4829309`), or a combination of the two (`aws:i-3bc4829309`). The first finds all endpoints that are AWS EC2 instances, the second finds an instance with the given ID across all cloud providers, and the third finds a specific AWS EC2 instance. Note: You must URL encode this query parameter value.

Passing more than one search parameter makes the search narrower.

Feedback¶

We hope you appreciate these improvements. Your feedback is valuable to us; please post and comment on the community forum.