# Sophos

SureCloud connects to Sophos Central to retrieve endpoint inventory, protection status, threat detection alerts, and policy assignment data. This allows SureCloud to verify that Sophos endpoint agents are deployed and active across your estate, that endpoints are assigned to protection policies, and that threat detections are being captured — providing continuous evidence for endpoint security controls.

## Authentication and setup

Sophos Central authenticates API requests using OAuth 2.0 with client credentials. SureCloud uses a dedicated API credential generated in Sophos Central.

{% stepper %}
{% step %}
**Create an API credential in Sophos Central**

Log in to Sophos Central at [central.sophos.com](https://central.sophos.com/) with a Super Admin account. Navigate to **Global Settings → API Credentials** and click **Add Credential**. Name it `SureCloud CCM` and select the **Service Principal ReadOnly** role. Click **Add** and copy the **Client ID** and **Client Secret** — the secret is only shown once.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Sophos → Connect**. Enter the **Client ID** and **Client Secret**. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the Client Secret securely — it is not shown again after creation. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Sophos Central → Global Settings → API Credentials** and update it in **SureCloud → Integrations → Sophos → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                  | Use Case                                                                                     |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| `GET /whoami/v1`                          | Verify credentials and retrieve tenant ID for subsequent API calls                           |
| `GET /endpoint/v1/endpoints`              | Enumerate all endpoints including OS, agent version, and health status                       |
| `GET /endpoint/v1/endpoints/{endpointId}` | Retrieve individual endpoint detail including policy assignment and tamper protection status |
| `GET /endpoint/v1/policies`               | List endpoint protection policies and their settings                                         |
| `GET /siem/v1/alerts`                     | Retrieve threat detection alerts and events                                                  |
| `GET /endpoint/v1/threats`                | Retrieve detected threats per endpoint                                                       |

## Pagination

`GET /endpoint/v1/endpoints` uses cursor-based pagination. SureCloud uses the `nextKey` from each response as the `pageFromKey` parameter in the next request, continuing until no `nextKey` is returned.

```json
GET /endpoint/v1/endpoints?pageSize=500&pageFromKey=<value_from_previous_response>
```

`GET /siem/v1/alerts` uses a `cursor` parameter similarly.

## Required permissions

SureCloud requires a Sophos Central API credential with the **Service Principal ReadOnly** role. This provides read-only access to:

* Endpoint inventory and health status
* Policy assignments
* Threat detections and alerts

No administrative, policy-change, or endpoint-management permissions are required.

## Polling frequency

| Data Type                                | Interval       |
| ---------------------------------------- | -------------- |
| Endpoint inventory and protection status | Every 24 hours |
| Policy assignments                       | Every 24 hours |
| Threat detection alerts                  | Every 4 hours  |

## Troubleshooting

<details>

<summary>Connection test returns "invalid_client" or 401</summary>

The Client ID or Client Secret is incorrect, or the credential has been deleted. Navigate to **Sophos Central → Global Settings → API Credentials**, confirm the credential is active, and regenerate the Client Secret if necessary. Update both values in **SureCloud → Integrations → Sophos → Edit Connection**.

</details>

<details>

<summary>Endpoint count in SureCloud is lower than expected</summary>

Sophos Central may manage endpoints across multiple sub-estates (tenants) in a partner or enterprise setup. SureCloud collects endpoints from the tenant associated with the API credential. If your organisation uses a multi-tenant Sophos setup, contact SureCloud Support to configure collection across all sub-estates.

</details>

<details>

<summary>Threat alerts are not appearing despite detections in Sophos Central</summary>

The `GET /siem/v1/alerts` endpoint uses a cursor-based lookback. If no threats have been detected within the lookback window, the response will be empty — which is itself a valid evidence state. If threats visible in Sophos Central are not appearing in SureCloud, confirm the API credential has access to SIEM data and trigger a manual refresh.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/sophos.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.