Getting Started With Cloud Optix Rest API

Cloud Optix provides a REST API based request-response system to communicate with the platform. The platform’s API interface can be used for different functionalities as listed below:

Authenticating the requests

Every API calls requires authentication. The way to authenticate with Cloud Optix API server is the API key.

API key: Generate the API key from the Sophos Cloud Optix console. Keeping your API key safe is your responsibility.

Generating the API key from the Cloud Optix Web Console

The API key can be generated by following the steps as listed below:

  1. Go to <Settings> via the left navigation menu
  2. Click <Integrations>
  3. Go to <Sophos Cloud Optix API> option
  4. If you see an API key listed in the option box, you already have an API key. If you regenerate the key, the older key will become invalid and any script or tools that were using the older key will not work as desired
  5. If you are generating the key for the first time or regenerating the key, please set the validity period of the key. You may set it to 6 months, 1 year or perpetual. Click <Generate new key>
  6. Copy and save the API key

Sending an Authenticated Request

The API endpoint accepts the API key in a custom HTTP header. The API key should be specified in the HTTP header in the following format:

Authorization: ApiKey <API_KEY_VALUE>

Cloud Optix APIs available

1. Alert

These APIs can be used to get alerts count and alert details

2. IaC Integration

These APIs can be used to scan your Infrastructure-as-Code (IaC) templates

3. OutGoing Traffic

These APIs can be used to get outgoing traffic at a instance or vpc level

4. IP Whitelist

This API can be used to add whitelisted IPs and IP ranges


GET APIs for Alert

Purpose: These APIs can be used to get alerts count and alert details.

Getting Alert count

URL: GET api/v1/alerts/count

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Query Params:

Key Description
days

Integer. Optional.

Number of days for which alerts would be fetched. Cannot be less than 1 or more than 365. Value not specified means querying for 365 days

alertType

String. Optional.

Valid Values - Policy, Anomaly, GuardDuty

Value not specified means ALL

providerList

String. Optional.

Valid Values - AWS, Azure

Value not specified means ALL

policyTagList

String. Optional.

Valid Values - Avid, CIS, FFIEC, HIPAA, ISO 27001, PCI, SOC2, SOC2-TSP, FEDRAMP-LOW, FEDRAMP-MODERATE, FEDRAMP-HIGH, EBU R143

Value not specified means ALL

accountIds

String. Optional.

The Id of the accounts that you want to fetch data for

lastSeenFrom

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

lastSeenTo

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

states

String. Optional.

Valid Values -  OPEN, SUPPRESS

Value not specified means ALL

 

Success Response:

HTTP status code: 200

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400
Date in 'lastSeenTo' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400
Date in 'lastSeenFrom' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400 Alert Type not supported
400 Provider Type not supported
400 Account Ids <<ids>> not found
400 Can only set one of the filters: set 'days' or else set lastSeenFrom/lastSeenTo
400 Days cannot be less than 1 and greater than 365
400 Invalid Date format for both lastSeenFrom/lastSeenTo
400 Parameter ‘lastSeenTo’ should come after ‘lastSeenFrom’
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 

Response Json Data:

{
    "critical": "int",
    "high": "int",
    "medium": "int",
    "low": "int",
    "total": "int"
}

Getting Alerts

URL: GET api/v1/alerts

Note: This api is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Query Params:

Key Description
days

Integer. Optional.

Number of days for which alerts would be fetched. Cannot be less than 1 or more than 365. Value not specified means querying for 365 days

alertType

String. Optional.

Valid Values - Policy, Anomaly, GuardDuty

Value not specified means ALL

providerList

String. Optional.

Valid Values - AWS, Azure

Value not specified means ALL

policyTagList

String. Optional.

Valid Values - Avid, CIS, FFIEC, HIPAA, ISO 27001, PCI, SOC2, SOC2-TSP, FEDRAMP-LOW, FEDRAMP-MODERATE, FEDRAMP-HIGH, EBU R143

Value not specified means ALL

accountIds

String. Optional.

The Id of the accounts that you want to fetch data for

lastSeenFrom

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

lastSeenTo

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

states

String. Optional.

Valid Values -  OPEN, SUPPRESS

Value not specified means ALL

severity

String. Optional.

Valid Values - low, medium, high, critical

Value not specified means ALL

page

Integer. Mandatory.

Page to be retrieved.  Should start with 1.

size

Integer. Optional.

Number of records on a page.  Should not be more than 50.

Default : 20

 

Success Response:

HTTP status code: 200

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400
Date in 'lastSeenTo' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400
Date in 'lastSeenFrom' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400 Alert Type not supported
400 Provider Type not supported
400 Account Ids <<ids>> not found
400 Can only set one of the filters: set 'days' or else set lastSeenFrom/lastSeenTo
400 Days cannot be less than 1 and greater than 365
400 Invalid Date format for both lastSeenFrom/lastSeenTo
400 Parameter ‘lastSeenTo’ should come after ‘lastSeenFrom’
400 Pageable size cannot be greater than 50
400 Alert Type not supported
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 

Response Json Data:

{
    "data": [
        {
            "id": "number",
            "accountId": "string",
            "accountName": "string",
            "alertType": "string",
            "alertSummary": "string",
            "criticalLevel": "string",
            "url": "string",
            "alertId": "string",
            "policyLabel": "string",
            "alertDetails": "string",
            "firstSeen": "number",
            "lastSeen": "number",
            "score": "int",
            "state": "string",
            "lastAction": "string",
            "lastActionTime": "string",
            "jiraId": "string",
            "provider": "string",
            "ruleResult": {
                "affectedResources": [
                    {
                        "id": "number",
                        "affectedResource": "string",
                        "dataMap": "Object",
                        "remediateDate": "date",
                        "status": "string",
                        "failureReason": "string",
                        "Comment": "string",
                        "affectedResourceJSON": "object",
                        "rawAffectedResourceOutput": "object",
                        "state": "string",
                        "suppressionType": "string",
                        "firstSeen": "number",
                        "clickableResources": "number",
                        "resourceInfoList": "object"
                    }
                ],
                "severity": "string",
                "resultprefix": null,
                "displayOrder": "int",
                "controlId": "number",
                "controlIdDesc": "string"
            }
        }
    ],
    "currentPage": "int",
    "hasNext": boolean,
    "hasPrevious": boolean,
    "totalPages": "int",
    "size": "int"
}

APIs for IaC Integration

Purpose:  Scan your Infrastructure-as-Code (IaC) templates for potential misconfigurations, before deploying infrastructure to your cloud environment, or as part of your CI/CD pipeline.

Uploading IaC Templates for Scanning

URL: POST api/v1/iac/scan

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Other Query Params:

Key Description
files

MultipartFile[]. Mandatory.

The array of files to be scanned. For better results, please include helper files such as those carrying values of variables used in the templates.

repo_url

String. Optional.

The repoURL to be associated with the files. Required if you wish to save results to console.

branch

String. Optional.

The branch to be associated with the files. Required if you wish to save results to console.

committer_name

String. Optional.

The name of the person making the commits to be associated with the files. Required if you wish to save results to console.

committer_email

String. Optional.

The email of the person making the commits to be associated with the files. Required if you wish to save results to console.

async

Boolean. Optional.

By default, your IaC template files will be processed asynchronously. However, if you have a small number of files and only require summary information (count of alerts for each severity level) you can choose to process files synchronously, by changing 'async' to false.

Default: true

save_results_to_account

Boolean. Optional.

By default, scan results will not be reported in your Cloud Optix console as alerts and in compliance reports. If you only want to see the results not only in the API response, but in the console as well, change this setting to true.

Default: false

policy_name

String. Optional.

By default, your IaC template files will be scanned against all IaC policies in your Cloud Optix account. To scan files against a specific IaC policy only, provide the name of the policy

 

Success Response:

HTTP status code: 200

A successful response will provide a scan_id and a summary of the number of issues detected, by severity level. The scan_id is used to make further requests, as detailed below. The scan summary is only provided when async is set to false.

Response Json Data:

{
	"scan_id":"string",
	"summary":{
		"num_critical_alerts":integer,
		"num_high_alerts":integer,
		"num_medium_alerts":integer,
		"num_low_alerts":integer
	}
}

 

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400 Unable to retrieve user (When API key cannot be linked to a customer)
400 Proper arguments not provided (When one/more of the mandatory params is not provided properly)
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 

Getting the Status of the Scan

URL: GET api/v1/iac/scan/status

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Other Query Params:

Key Description
scan_id

String. Mandatory.

The ID of the scan that you are requesting the status for. This is provided in the response when you upload files for scanning.

 

Success Response:

HTTP status code: 200

Response Json Data:

{
	"processing_ongoing":boolean,
	"success":boolean,
	"error":"string"
}

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400 Unable to find the scan you requested
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 

Note: Once the Scan Status API returns success as true and process_ongoing as false, you can then retrieve a detailed report of the scan.

Getting the Detailed Report of the Scan

URL: GET api/v1/iac/scan/detailedReport

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Other Query Params:

Key Description
scan_id

String. Mandatory.

The ID of the scan that you are requesting the detailed report for. This is provided in the response when you upload files for scanning

 

Success Response:

HTTP status code: 200

Response Json Data:

{
	"alerts":[
		{
			"scanID":"string",
			"alertSummary":"string",
			"criticalLevel":"string (CRITICAL, HIGH, LOW or MEDIUM)",
			"alertDetails":"string",
		}
	]
}

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400 Unable to find the scan you requested
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 


GET APIs for OutGoing Traffic

Purpose: These api’s can be used to get outgoing traffic at a instance or vpc level.

Getting data at VPC level

URL: GET api/v1/outgoingtraffic/vpc

Note: This api is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Query Params:

Key Description
accountId

String. Mandatory.

The Id of the account that you want to fetch data for

vpcId

String. Mandatory.

The Id of the VPC

page

Integer. Optional if isPageable is false else Mandatory.

Page to be retrieved. Should start with 1.

size

Integer. Optional.

Number of records on a page. Should not be more than 50.

Default: 20

isPageable

Boolean. Optional.

If true, result will be paginated, else non paginated.

timeFrom

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

timeTo

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

 

Success Response:

HTTP status code: 200

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400 Page number should be greater than 0
400 Pageable size cannot be greater than 50
400 Invalid data
400 Retry using parameters timeFrom and timeTo or limited range for timeFrom and timeTo
400
Date in 'timeTo' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400
Date in 'timeFrom' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400 Parameter ‘timeTo’ should come after ‘timeFrom’
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 

Response Json Data:

{
    "data": [
        {
            "name": "string",
            "srcIpAddress": "string",
            "instanceId": "string",
            "interfaceId": "string",
            "dstIpAddress": "string",
            "dstPort": "string",
            "time": "<<epoch time>>"
        }
    ],
    "currentPage": "int",
    "hasNext": "boolean",
    "hasPrevious": "boolean",
    "totalPages": "int",
    "size": "int"
}

Getting data at instance level

URL: GET api/v1/outgoingtraffic/instance

Note: This api is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Query Params:

Key Description
instanceId

String. Mandatory.

The Id of the instance

page

Integer. Optional if isPageable is false else Mandatory.

Page to be retrieved. Should start with 1.

size

Integer. Optional.

Number of records on a page. Should not be more than 50.

Default: 20

isPageable

Boolean. Optional.

If true, result will be paginated, else non paginated.

timeFrom

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

timeTo

String. Optional.

Valid values should comply follow ISO 8601 format

[date-element] 'T' [time-element] [offset]

 where date-element = yyyy-MM-dd

 and time-element(optional) = HH:mm:ss

 and offset(optional) = [+/-]hh:mm

NOTE: If offset is not mentioned then it will consider UTC(00:00) by default

 

Success Response:

HTTP status code: 200

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400 Page number should be greater than 0
400 Pageable size cannot be greater than 50
400 Invalid data
400 Retry using parameters timeFrom and timeTo or limited range for timeFrom and timeTo
400
Date in 'timeTo' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400
Date in 'timeFrom' is not in proper format
It accepts formats described by the following syntax:
[date-element] 'T' [time-element] [offset]
 where date-element = yyyy-MM-dd
 and time-element(optional) = HH:mm:ss
 and offset(optional) = [+/-]hh:mm
400 Parameter ‘timeTo’ should come after ‘timeFrom’
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)

 

Response Json Data:

{
    "data": [
        {
            "name": "string",
            "srcIpAddress": "string",
            "instanceId": "string",
            "interfaceId": "string",
            "dstIpAddress": "string",
            "dstPort": "string",
            "time": "<<epoch time>>"
        }
    ],
    "currentPage": "int",
    "hasNext": "boolean",
    "hasPrevious": "boolean",
    "totalPages": "int",
    "size": "int"
}

POST API for IP Whitelist

Purpose: This api can be used to add whitelisted IPs.

URL: POST api/v1/whitelistIPs

Supported Media Types: Consumes: application/json

Mandatory HTTP headers:

Authorization: ApiKey <API_KEY_VALUE>

Request JSON Payload Structure:

{
  "accountIds": <<Array of String: optional valid account ids>>,
  "data": {
    "ips": [
      <<String: valid IP/IP range>>,
      <<String: valid IP/IP range>>
    ]
  }
}

Success Response:

HTTP status code: 200

Success Message:

Response Json Data:

[
    {
        "data": {
            "ips": [
                "<<string: valid IP/IP range>>",
                "<<string: valid IP/IP range>>"
            ]
        },
        "id": "number",
        "accountIds": "<<Array of string: account ids>>",
        "customerId": "int",
        "accountId": "string: account id"
    }
]

Failures:

HTTP Status Code Cause/Message
400 ApiKey not provided
400 Data object invalid
400 Account Ids <id> not found
401 Unauthorized access or ApiKey expired
404 No message available (Api resource could not be found)