Getting started

Overview¶

In this guide, we show you how to manage Endpoint Protection, Server Protection, and Device Encryption policies using the Endpoint API.

This API allows policy management for a single tenant at a time. If you are a Sophos customer, you can use your tenant API credentials to call this API. Partners can use their own API credentials to manage policies for tenants that have enabled Partner assistance. Enterprise customers can use their own API credentials to manage policies for tenants (sub-estates) that have enabled Enterprise Admin management.

Pre-requisites¶

You must have a set of API credentials (service principal) to be able to call the Endpoint API. For more information refer to the appropriate quick start guide:

• Sophos Partners: Read the Partner Getting Started guide first.
• Enterprise customers: If you use Sophos Enterprise to manage multiple tenants, read the Organization Getting Started guide first.
• Other customers: Read the Tenant Getting Started guide first.

You can make the API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

Each cUrl command in the rest of this guide assumes you will replace the following variables:

• <tenant-id>: The ID of the tenant you want to query
• <jwt>: The JWT access token returned when the IDP authenticate the service principal.
• <data-region>: The regional API host in the data geography where the tenant data is located.

To understand these terms, you must read the appropriate Getting Started guide.

Terminology¶

You use "policies" to apply protection to users, devices or servers. A policy is a set of options that Sophos Fusion applies to protected users, devices or servers. There is a policy for each product, or for a feature that’s part of a product (for example, there is a policy for the application control feature). Users, devices and servers have separate policies.

You can read more about policies in the documentation for Sophos Fusion: https://docs.sophos.com/central/Customer/help/en-us/central/Customer/concepts/AboutPolicies.html

Policies in the Sophos Fusion Admin console are grouped together by type:

Read-only Operations¶

In the following sub-sections, all the curl commands have this structure:

curl -XGET -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The <data-region> and headers are skipped in the examples below to keep them simple. All API calls return the HTTP status code 200 or 201 when successful.

Get all policies¶

Call this API to get a list of all the policies in the tenant:

GET /endpoint/v1/policies

This returns a paginated list of policy objects as below (JavaScript-style comments added for annotation).

{
    "items": [
        {
            "id": "abd0c71a-09cb-43ad-8f9d-99e65a3bf8db",  // Policy ID
            "name": "Base Policy",            // Base policies always have this name
            "type": "application-control",    // Type of policy
            "lockedByManagingAccount": false, // Whether a partner or enterprise admin
                                              // has locked this policy from changing
            "priority": 0,                    // Always 0 for a Base Policy
            "tenant": {
                "id": "ae7b6340-aab4-4a23-915a-9fec5322f9f3"
            },
            "enabled": true,   // Always `true` for a Base Policy
            "settings": {      // Object with one key per setting
                "endpoint.application-control.controlled-applications": {
                    "value": [
                    ]
                },
                "endpoint.application-control.desktop-messaging.enabled": {
                    "value": true
                },
                "endpoint.application-control.desktop-messaging.message": {
                    "value": "Blocked application!"
                },
                "endpoint.application-control.detection.on-access.enabled": {
                    "value": true
                },
                "endpoint.application-control.detection.on-access.monitor": {
                    "value": false
                },
                "endpoint.application-control.detection.on-demand.enabled": {
                    "value": true
                }
            },
            "appliesTo": {                   // Arrays are always empty for Base Policy
                "users": [],                 // as it applies to all users and endpoints
                "userGroups": []
            },
            "createdAt": "2021-01-27T07:34:30.129Z",
            "updatedAt": "2021-03-08T01:01:16.801Z"
        },
        {
            "id": "d69f4c33-2da9-4f19-94b9-d4b4df4d0b46",
            "name": "Block asset management tools",
            "type": "application-control",
            "lockedByManagingAccount": false,
            "priority": 0,
            "tenant": {
                "id": "ae7b6340-aab4-4a23-915a-9fec5322f9f3"
            },
            "enabled": true,
            "settings": {
                "endpoint.application-control.controlled-applications": {
                    "value": [
                        "DBTools Manager",      // App names
                        "Ensign"
                    ]
                },
                "endpoint.application-control.desktop-messaging.enabled": {
                    "value": false
                },
                "endpoint.application-control.desktop-messaging.message": {
                    "value": ""
                },
                "endpoint.application-control.detection.on-access.enabled": {
                    "value": true
                },
                "endpoint.application-control.detection.on-access.monitor": {
                    "value": false
                },
                "endpoint.application-control.detection.on-demand.enabled": {
                    "value": false
                }
            },
            "appliesTo": {
                "users": [
                    "327af8de-5be8-442f-9c4a-571c5e8fb541"  // Block apps only for this user
                ],
                "userGroups": []
            },
            "createdAt": "2021-01-27T07:34:30.129Z",
            "updatedAt": "2021-03-08T01:01:16.801Z"
        },

        // ... Other policy objects of other types
    ],
    "pages": {
        "current": 1,
        "size": 50,
        "maxSize": 200
    }
}

NOTE: If the settings object is missing a key, you should assume that the setting has its default value. You can find the default values in this reference.

Get a single policy¶

Call this API to fetch a single policy:

GET /endpoint/v1/policies/{policyId}

Here, policyId in the path is the UUID of a policy.

This returns a policy object that has the same structure as an individual item in the items array in the response to the bulk GET operation.

Get settings¶

If you have a policy UUID, you can get the settings for that policy.

GET /endpoint/v1/policies/{policyId}/settings

For example, the API call:

GET /endpoint/v1/policies/d69f4c33-2da9-4f19-94b9-d4b4df4d0b46/settings

This returns the (sample) response:

{
    "endpoint.application-control.controlled-applications": {
        "value": [
            "DBTools Manager",
            "Ensign"
        ]
    },
    "endpoint.application-control.desktop-messaging.enabled": {
        "value": false
    },
    "endpoint.application-control.desktop-messaging.message": {
        "value": ""
    },
    "endpoint.application-control.detection.on-access.enabled": {
        "value": true
    },
    "endpoint.application-control.detection.on-access.monitor": {
        "value": false
    },
    "endpoint.application-control.detection.on-demand.enabled": {
        "value": false
    }
}

Get a single setting¶

You can get just one setting from the settings object of a policy:

GET /endpoint/v1/policies/{policyId}/settings/{settingKey}

For example, to get the names of controlled applications, make the API call:

GET /endpoint/v1/policies/d69f4c33-2da9-4f19-94b9-d4b4df4d0b46/settings/endpoint.application-control.controlled-applications

This returns:

{
    "value": [
        "DBTools Manager",
        "Ensign"
    ]
}

Base Policy operations¶

You don't need the UUID for a Base policy. You can find the settings or a setting for a Base policy by using its type instead of its UUID. To do this use /{type}/base/ instead of /{policyId}/ in the paths above.

For example, the API call to get Device Encryption Base Policy settings:

GET /endpoint/v1/policies/981d7a24-6209-4acf-b418-2e50008a0647/settings

... becomes a lot simpler:

GET /endpoint/v1/policies/device-encryption/base/settings

To see whether the Device Encryption Base Policy turns on encryption, call:

GET /endpoint/v1/policies/device-encryption/base/settings/endpoint.device-encryption.encrypt-endpoint

This returns a single boolean setting object:

{
    "value": true   // Or `false`, if the Base Policy doesn't enable encryption
}

Get policy metadata¶

Call this API to get metadata that describes all policy types and their settings (JavaScript-style comments added for annotation).

GET /endpoint/v1/policies/settings

This returns:

{
  "version": "1.0", 
  "items": [
    {
      "type": "agent-updating",
      "items": [
        {
          "name": "endpoint.agent-updating.scheduled-updates.day",
          "description": "Set the day of the week for scheduled updates, using `0` for Sunday, `1` for Monday, and so on.",
          "type": "integer",
          "useValidOnlyInBasePolicy": false,
          "useValidOnlyInAdditionalPolicies": false,
          "readOnlyInBasePolicy": false,
          "readOnlyInAdditionalPolicies": false,
          "defaultValue": {
            "value": 3,
            "unit": "day"
          },
          "defaultUnit": "day",
          "allowedUnits": [
            "day"
          ],
          "examples": []
        }
        // Other metadata under this policy type
      ]
    },
    {
      "type": "application-control",
      "items": [
        {
          "name": "endpoint.application-control.allowed-applications",
          "description": "Allow specific applications by name when the application category is controlled.",
          "type": "arrayOfStrings",
          "useValidOnlyInBasePolicy": false,
          "useValidOnlyInAdditionalPolicies": false,
          "readOnlyInBasePolicy": false,
          "readOnlyInAdditionalPolicies": false,
          "defaultValue": {
            "value": []
          },
          "examples": []
        },
        {
          "name": "endpoint.application-control.controlled-categories",
          "description": "Controlled application categories. New applications added by Sophos to these application categories will be automatically controlled.",
          "type": "arrayOfIntegers",
          "useValidOnlyInBasePolicy": false,
          "useValidOnlyInAdditionalPolicies": false,
          "readOnlyInBasePolicy": false,
          "readOnlyInAdditionalPolicies": false,
          "defaultValue": {
            "value": []
          },
          "limit": {
            "min": 10,
            "max": 63
          },
          "examples": []
        },
        {
          "name": "endpoint.application-control.controlled-applications",
          "description": "Names of applications to control.",
          "type": "arrayOfStrings",
          "useValidOnlyInBasePolicy": false,
          "useValidOnlyInAdditionalPolicies": false,
          "readOnlyInBasePolicy": false,
          "readOnlyInAdditionalPolicies": false,
          "defaultValue": {
            "value": []
          },
          "examples": []
        }
        // Other metadata under this policy type
      ]
    }
    // Other policy types and their metadata
}

Create Operations¶

Create a new additional policy¶

To create a new policy, call:

POST /endpoint/v1/policies

Here's an example of a request to create a policy that turns on the Exploit Mitigation feature to prevent credential theft on endpoints associated with users in the a specific group. (This setting is off by default).

{
    "name": "Cred guard for Ops team",
    "type": "threat-protection",
    "appliesTo": {
        "userGroups": [
            "57b952be-0fb1-4cf6-949b-024ef7693571"    // User group ID
        ]
    },
    "settings": {
        "endpoint.threat-protection.exploit-mitigation.process-protection.credential-theft-protection.enabled": {
            "value": true
        }
    }
}

You can pass the enabled field in the request body set to false if you don't want the policy to be enforced immediately after it has been created.

You can also pass the priority field in the request body, set to a number that's relative to the priorities of policies as returned in the response of the GET /endpoint/v1/policies API call. If you don't set a priority the policy has the highest priority of all policies of that type. If there is an existing policy with the same priority, Sophos Fusion assigns the new policy its requested priority and adjusts the priorities of existing policies to resolve the clash.

Clone an existing policy¶

To clone an existing policy by ID, call:

POST /endpoint/v1/policies/{policyId}/clone

To clone a base policy, call:

POST /endpoint/v1/policies/{policyType}/base/clone

In either case, the request body should look like this:

{
    "name": "New Policy Name"
}

This returns the new policy object, with all the same settings and user/endpoint assignments as the original, but with the highest available priority. The new policy is enforced ("enabled": true) or bypassed ("enabled": false) in the same way as the original.

Update Operations¶

Update a policy¶

To update the attributes of a single policy, such as its name, priority, settings, whether it is enabled, and which users or endpoints it applies to, call:

PATCH /endpoint/v1/policies/{policyId}

The request body is similar to that passed when creating a policy. For example:

{
    "name": "New name",        // Change policy name
    "priority": 12,            // Change policy priority
    "enabled": false,          // Enable/disable the policy
    "disableAt": "2021-03-31T10:12:34.000Z",   // Disable the policy at the give time
    "appliesTo": {             // Change who the policy applies to
        "endpoints": [ "713ab1fb-2338-4922-b2fe-8e35ff9ea39f" ]
    },
    "settings": {               // Change policy settings.
        "endpoint.application-control.detection.on-access.enabled": {    // Set this key value
            "value": false
        }
    }
}

All fields are optional. You can't change the policy type. The settings object doesn't need to contain keys for all supported settings. Only the supplied settings are updated.

An alternative way is to call this API for the base policy of a given type.

PATCH /endpoint/v1/policies/{policyType}/base

Note that you can change only the settings of a base policy. Other attributes such as name, priority and whether the policy is enabled are not modifiable.

Update policy settings¶

To update the settings in a policy, call:

PATCH /endpoint/v1/policies/{policyId}/settings

To update the settings of a base policy of a given type, call:

PATCH /endpoint/v1/policies/{policyType}/base/settings

Update a single policy setting¶

There are two ways to modify a single setting. If you have the policy ID, call:

PATCH /endpoint/v1/policies/{policyId}/settings/{settingKey}

If you want to modify a setting in the base policy of a specific policy type, call:

PATCH /endpoint/v1/policies/{policyType}/base/settings/{settingKey}

The body of the request takes a single JSON object with a value field. For example:

PATCH /endpoint/v1/policies/b7bbbf5f-4599-4e4d-80a5-800be1d49f45/settings/endpoint.web-control.schedule.active-periods

With the request body:

{
    "value": [
        {
            "from": "09:00", "to": "13:00", "days": ["monday"]
        },
        {
            "from": "21:00", "to": "22:00", "days": ["saturday", "sunday"]
        }
    ]
}

This API call sets the Web Control policy with the ID b7bbbf5f-4599-4e4d-80a5-800be1d49f45 to be effective only on Saturdays, Sundays, and Mondays, during the specified time periods.

Reset policy settings¶

There are two ways you can reset a policy to its default settings. If you have the policy ID, call:

POST /endpoint/v1/policies/{policyId}/settings/reset

If you want to reset all the settings in the base policy of a specific policy type, call:

POST /endpoint/v1/policies/{policyType}/base/settings/reset

In each case, pass an empty JSON object {} as the request body. This sets all the settings in the policy to their default values.

Reset a single policy setting¶

There are two ways you can reset a single setting in a policy. If you have the policy ID, call:

POST /endpoint/v1/policies/{policyId}/settings/{settingKey}/reset

If you want to reset a setting in the base policy of a specific policy type, call:

POST /endpoint/v1/policies/{policyType}/base/settings/{settingKey}/reset

In each case, pass an empty JSON object {} as the request body. This sets the named setting to its default value.

Delete Operations¶

Delete additional policy¶

To delete a policy, call:

DELETE /endpoint/v1/policies/{policyId}

Pass the request body {}. Policies are deleted immediately and any users or endpoints assigned to the deleted policy start using use the next policy with the highest priority that they are assigned to, directly or indirectly (through a group). Base policies can't be deleted.

Setting Objects¶

Each policy type has a fixed set of supported settings. Each setting name is dot-separated for loose namespacing, with dashes for readability. Values are of type boolean (true/false), integer, string, or arrays of those types. String settings may have a format attribute, and integer settings may have a unit attribute, to hint at the meaning of the value.

Here's an example of a boolean setting object:

{
    "value": false
}

Here's an example of an array-of-integers setting object:

{
    "value": [3, 6, 4],
    "unit": "days"
}

Here's an example of a string setting object:

{
    "value": "12:30",
    "format": "time"
}

You can use the reference for policy settings, keyed by setting name, to understand what each setting does, its value type, allowed values, default value, and for some, examples of use. Additional data references pages are linked from the relevant setting documentation.

AppliesTo Objects¶

As stated above, policies apply either to users (and groups of users) or endpoints (and groups of endpoints). A policy object that applies to users has an appliesTo attribute that is an object with the fields users and userGroups, each an array with zero or more UUIDs. For example:

{
    "users": [
        "e0bbd177-8ebe-4e51-aeaa-7ab4f1baba79",
        "e9dd2848-dc70-42c9-b605-8577ce57f5c4"
    ],
    "userGroups": [
        "967e30b0-e7ad-48e5-a755-1df225c782ef"
    ]
}

User and user-group UUIDs are the same as those returned by our Directory Management API.

A policy object that applies to endpoints has its appliesTo attribute set to an object with endpoints and endpointGroups fields, each an array of UUIDs.

{
    "endpoints": [],
    "endpointGroups": [
        "6153c421-44da-4e3a-bafd-0a21c1ff4eb5"
    ]
}

Call GET /endpoint/v1/endpoint-groups (see reference) to query endpoint groups.

Not all policy types apply to both users as well as endpoints. Use this table to make sure you are applying policies correctly.

Limitations¶

All PATCH, POST, PUT, and DELETE APIs are subject to rate limiting. The allowance is based on the number of requests per tenant per minute. Once you reach your allowance, you will receive a 429 response.

Conclusion¶

After reading this guide, you should understand policy types and how policies are applied to users and endpoints. You should be able to use the Endpoint API to get policies and their settings from Sophos Fusion.