Skip to content

Getting started

Overview

The Cloud security APIs allow you to manage security for your cloud resources. Cloud security covers Sophos Workload Protection and Sophos Cloud Optix.

Prerequisites

You must have a set of API credentials (service principal) to be able to call the Cloud Security API. For more information, see the relevant Getting Started guide:

Making API requests

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

When using curl, a request to the Cloud Security API has the following general form:

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

The command includes the following placeholders:

  • <method>: The request method. It may be GET, DELETE, POST, or PUT.
  • <tenant-id>: The ID of the tenant you want to query.
  • <jwt>: The JWT access token returned when the IDP authenticates the service principal.
  • <data-region>: The regional API host in the data region where the tenant data is located.
  • <path>: The request path for the API operation, for example, cloud-security/v1/profiles.

For brevity, the API descriptions in this guide only specify the request method and path. For example:

GET /cloud-security/v1/profiles

To make an actual API request, you must expand this to the full form shown above.

All API requests return HTTP status code 200 or 201 when successful.

Terminology

  • Default Content: A YAML file containing all detection rules with default configuration set by SophosLabs.

Manage Linux runtime detection profiles

You can use Linux runtime detection profiles to configure Sophos Linux runtime detection. You can use these APIs to manage profiles and configure both Linux Server Protection Agent and Sophos Linux Sensor.

To create a profile, you need the version of Default Content you want to use for your profile.

**Important: Choosing a Default Content version only constrains which detection rules your can configure and is not related to the Default Content running in your agent.

Get list of Default Contents

Use this API to get a list of available Default Contents that you can configure.

GET /cloud-security/v1/profiles/default-contents

Response: A list of Default Contents with version and ID. Choose the version for Default Content you want to use when creating a profile.

{
    "items": [
        {
            "id": "2517874d-5e12-4ebb-8af0-e6192df01d33",
            "version": "5.5.1.1"
        },
        {
            "id": "c19c751d-50e1-4468-b45c-4d47378863c6",
            "version": "5.4.0.8"
        },
        {
            "id": "0f31142d-9dc7-41a0-8c1e-b24f184ef537",
            "version": "5.11.2"
        },
        {
            "id": "6cc14bc7-2d6e-4e5f-99b0-d078c3dc80f7",
            "version": "5.10.2"
        }
    ]
}

Create profile

Use this API to create a new profile or a new version of an existing profile. The profile name must be unique. Make a POST request with JSON request body. For example:

POST /cloud-security/v1/profiles
{
    "name" : "New profile",
    "contentVersion": "5.5.1.1",
    "profileDescription": "Short description to capture details for your profile",
    "settings" : {
        "lists" : [
            {
                "name" : "WebServerListeningPorts",
                "operations" : [
                    {
                        "behavior" : "add",
                        "list" : ["80", "110"]
                    }
                ]
            }
        ]
    }
}

Response : The API response contains the ID and version of the profile created. Make a note of both values, you need them to configure your Sophos Server Protection Agent.

{
    "id": "f1ed1ed6-0cb1-4c36-a6da-b851e81ac24e",
    "version": 1
}

You can now use the profile to configure runtime protection for Sophos agents:

  • Sophos Server Protection Agent: You can use Sophos Server Protection Policies API to configure your servers. You must create a policy of type "server-linux-runtime-detection", or modify an existing policy. You need the profile ID and version from the response of your Create API. You can also get these values using the List or Get APIs described below.
  • Sophos Linux Sensor: To configure Linux Sensor, you must download the YAML content of your profile and copy it to the sensor path "/etc/sophos/runtimedetections-rules.yaml". You can get the YAML content using the GET API discussed below. See for more details on how Linux sensor processes your custom configuration.

Get profile

Use this API to get full details of a profile for a specific version. You can get your profile configuration in YAML format and list of all versions present in the profile. If you don't specify a version in the GET request, the API returns details of the latest version and list of all versions. If you specify a version, the API returns details of that version, but not a list of all versions. You can get the ID required to call the GET API from the response of the Create or List API.

GET /cloud-security/v1/profiles/{Id}

Response: The response contains "diff" information you need to configure your Linux Sensor and a list of all versions.

{
    "name": "New profile",
    "profileDescription": "Short description to capture details for your profile - version 2",
    "defaultContentId": "2517874d-5e12-4ebb-8af0-e6192df01d33",
    "contentVersion": "5.5.1.1",
    "diff": "WebServerListeningPorts:\n  operations:\n  - behavior: add\n    list:\n    - 80\n    - 110\n",
    "createdAt": "2023-08-10T16:40:21.938Z",
    "versions": [
        {
            "version": 2,
            "createdAt": "2023-08-10T17:40:21.938Z"
        },
        {
            "version": 1,
            "createdAt": "2023-08-10T16:40:21.938Z"
        }
    ]
}

To see details of a specific version, use the API like this :

GET /cloud-security/v1/profiles/{Id}?version=1

List profiles (Latest version)

Use this API to get a paginated list of all your profiles.

GET /cloud-security/v1/profiles?page=1

Response: The API returns details of the latest version of each profile. For each profile, the API also returns a list of the Linux Runtime Detection policies that use the profile.

{
  "items": [
    {
      "id": "d86914c6-918b-4b64-a9e7-7d6da792k4a1",
      "name": "Main profile",
      "defaultContentId": "2517874d-5e12-4ebb-8af0-e6192dfk1d33",
      "contentVersion": "5.5.1.1",
      "createdAt": "2023-08-11T16:30:31.195Z",
      "version": 1,
      "policies": []
    },
    {
      "id": "c15fac67-b782-4e1e-b1e4-03e77fc9cb1e",
      "name": "test",
      "defaultContentId": "2517874d-5e12-4ebb-8af0-e6192df01d33",
      "contentVersion": "5.5.1.1",
      "createdAt": "2023-08-10T19:23:29.166Z",
      "version": 4,
      "policies": []
    },
    {
      "id": "5a413456-1f37-4950-8f40-59ea5640216a",
      "name": "test2",
      "defaultContentId": "2517874d-5e12-4ebb-8af0-e6192df01d33",
      "contentVersion": "5.5.1.1",
      "createdAt": "2023-08-09T19:48:08.137Z",
      "version": 5,
      "policies": [
        {
          "id": "b4faae18-eda3-4db2-b813-071ae4dkeab1",
          "name": "Test Policy",
          "version": 3
        },
        {
          "id": "0a2a848b-fc79-4c09-867c-e01c66101l4b",
          "name": "Test Policy 2",
          "version": 5
        }
      ]
    }
  ],
  "pages": {
    "total": 1,
    "items": 3,
    "maxSize": 100
  }
}

You can filter profiles by name.

GET /cloud-security/v1/profiles?page=1&searchTerm=Main

Conclusion

After reading this guide, you should be able to use the Cloud Security APIs to configure your Sophos cloud security products.