Getting started with Cloud Optix REST API

Cloud Optix provides a REST API based request-response system you can use to communicate with the platform. The Cloud Optix API interface can be used for the following functions:

Authenticating requests

Every API calls requires authentication. Use the API key to authenticate with Cloud Optix.

API key: Generate the API key from the Sophos Cloud Optix console. You must keep your API key safe.

Generating the API key from the Cloud Optix console

To generate an API key, do the following:

1. Go to<Settings>on the menu.
2. Click <Integrations>.
3. Go to <Sophos Cloud Optix API> option.
4. If you see an API key in the option box, you already have an API key. If you regenerate the key, the older key will becomes invalid. Any script or tools using the older key will not work.
5. If you are generating the key for the first time, or regenerating the key, please set the validity period of the key. Choose from 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. You must specify the API key in the HTTP header in the following format:

Cloud Optix APIs available

GET APIs for Alert

Purpose: Get an alert 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:

Success Response:

Failures:

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

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

Response Json Data:

"root":{
5 items
"critical":
string"int"
"high":
string"int"
"medium":
string"int"
"low":
string"int"
"total":
string"int"
}

Getting Alerts

URL: GET api/v1/alerts

Note: This API is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

Success Response:

Failures:

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

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

Response Json Data:

"root":{
6 items
"data":[
...
]
1 item
"currentPage":
string"int"
"hasNext":
string"boolean"
"hasPrevious":
string"boolean"
"totalPages":
string"int"
"size":
string"int"
}

APIs for Image Scanning

Purpose: These APIs can be used to submit docker images for scanning and to get vulnerability details. You can integrate APIs in your build pipeline to scan docker images before deployment.

Create scan task

URL: POST api/v1/image-scanning/submit-for-scan

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

Other Query Params:

Success Response:

A successful response provides taskId. The taskId can be used to make further requests, to query for the status of the scan task/results. Response will have "duplicate = true" if task for the same repo & branch is already submitted and is in processing state. Response will return "quotaFull = true" if the task contains more images to scan than the available quota. For example value will be true if task contains 6 images to scan and quota left is 5.

Response Json Data:

"root":{
3 items
"taskId":
string"string"
"duplicate":
string"boolean"
"quotaFull":
string"boolean"
}

Failures:

Create scan task by image name

URL: POST api/v1/image-scanning/submit-for-scan/by-image-name

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

Success Response:

A successful response provides taskId. The taskId can be used to make further requests, to query for the status of the scan task/results. Response will have "duplicate = true" if task for the same repo & images is already submitted and is in processing state. Response will return "quotaFull = true" if the task contains more images to scan than the available quota. For example value will be true if task contains 6 images to scan and quota left is 5.

Response Json Data:

"root":{
3 items
"taskId":
string"string"
"duplicate":
string"boolean"
"quotaFull":
string"boolean"
}

Failures:

Getting the Status of the Scan

URL:GET api/v1/image-scanning/get-scan-result

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Other Query Params:

Success Response:

A successful response provides scanResult containing all vulnerability details, taskId, status ( "submitted, complete or failed"), createdAt (UTC timestamp), completedAt if task is finished, branch name submitted in task, filesScanned count of final images scanned.

Response Json Data:

 
"root":{
7 items
"taskId":
string"string"
"status":
string"string"
"createdAt":
string"time(UTC)"
"completedAt":
string"time(UTC)"
"branch":
string"string"
"filesScanned":
string"integer"
"scanResult":[
...
]
1 item
}

Param description:

Failures:

Get vulnerability details of a scanned image

URL:GET api/v1/image-scanning/container-scan-result

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Other Query Params:

Success Response:

A successful response provides scanResult containing all vulnerability details, if the image is analyzed. It will fail if not. Check Scan Result API for status

Response Json Data:

"root":{
5 items
"success":
string"boolean"
"status":
string"String"
"message":
string"String"
"code":
string"String"
"data":{
...
}
6 items
}

Param description:

Failures:

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:

Other Query Params:

Success Response:

A successful response provides 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:

"root":{
2 items
"scan_id":
string"string"
"summary":{
...
}
4 items
}

Failures:

Getting the Status of the Scan

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

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Other Query Params:

Success Response:

Response Json Data:

"root":{
3 items
"processing_ongoing":
string"boolean"
"success":
string"boolean"
"error":
string"string"
}

Failures:

Note: Once the Scan Status API returns success as true and process_ongoingas false, you can 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:

Other Query Params:

Success Response:

Response Json Data:

"root":{
1 item
"alerts":[
...
]
1 item
}

Failures:

Getting the Detailed Report of the Scan (v2)

Provides enhanced details for affected resources, description, and remediation over V1 of the API.

URL: GET api/v2/iac/scan/detailed-report

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Other Query Params:

Success Response:

Response Json Data:

"root":{
1 item
"alerts":[
...
]
1 item
}

Failures:

GET APIs for OutGoing Traffic

Purpose: 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:

Query Params:

Success Response:

Failures:

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

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

Response Json Data:

"root":{
6 items
"data":[
...
]
1 item
"currentPage":
string"int"
"hasNext":
string"boolean"
"hasPrevious":
string"boolean"
"totalPages":
string"int"
"size":
string"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:

Query Params:

Success Response:

Failures:

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

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

Response Json Data:

"root":{
6 items
"data":[
...
]
1 item
"currentPage":
string"int"
"hasNext":
string"boolean"
"hasPrevious":
string"boolean"
"totalPages":
string"int"
"size":
string"int"
}

Outbound Traffic Alerts

Purpose: Cloud Optix can alert on outbound traffic to a list of destination IP addresses. Use this API to provide the list.

Note: This API is not currently available to all customers.

URL: POST api/v1/outboundtraffic/ipList

Supported Media Types: Consumes: application/json

Mandatory HTTP headers:

Request JSON Payload Structure:

"root":[
1 item
0:{
...
}
2 items
]

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

Success Response:

Success Message:

Failures:

POST API for IP Whitelist

Purpose: Add whitelisted IPs.

URL: POST api/v1/whitelistIPs

Supported Media Types: Consumes: application/json

Mandatory HTTP headers:

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:

Success Message:

Response Json Data:

"root":[
1 item
0:{
...
}
5 items
]

Failures:

GET API for Hosts

Purpose: Gets details of instances/virtual machines.

Getting Hosts

URL: GET api/v1/vms

Note: This API is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

Success Response:

Failures:

Response Json Data:

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
3 items
"currentPage":
string"int"
"hasNext":
string"boolean"
"hasPrevious":
string"boolean"
"totalPages":
string"int"
"size":
string"int"
}

GET API for Accounts (Environments)

Purpose: Gets details of environments in your Cloud Optix account (e.g. AWS accounts, Azure subcriptions and GCP projects).

Getting Accounts

URL: GET api/v1/accounts

Note: This API is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

&nbsp

Success Response:

Failures:

Response Json Data:

"root":[
1 item
0:{
...
}
13 items
]

GET API for Users

Purpose: Gets details of Users on your cloud environments

Getting Users

URL: GET api/v1/users

Note: This API is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

Success Response:

Failures:

Response Json Data:

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
3 items
"currentPage":
string"int"
"hasNext":
string"boolean"
"hasPrevious":
string"boolean"
"totalPages":
string"int"
"size":
string"int"
}

GET API for Serverless

Purpose: Gets details of Serverless services such as Lambda's for AWS and Function's for Azure.

Getting Serverless

URL: GET api/v1/serverless

Note: This API is paginated.

Supported Media Types: Produces: application/json

Mandatory HTTP headers:

Query Params:

Success Response:

Failures:

Response Json Data:

For AWS:

 
"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
1 item
"currentPage":
int0
"hasNext":
booltrue
"hasPrevious":
boolfalse
"totalPages":
int56
"size":
int1
}

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
1 item
"currentPage":
int0
"hasNext":
booltrue
"hasPrevious":
boolfalse
"totalPages":
int56
"size":
int1
}

"root":{
1 item
"errorMessage":
string"String"
}

"root":{
2 items
"accountIds":[
...
]
2 items
"status":
booltrue
}

 { "accountIds": <<Array of String: valid account ids>>, "status":  <<Boolean: true to enable sync of environment name, false to disable it>> }

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
1 item
"currentPage":
int0
"hasNext":
booltrue
"hasPrevious":
boolfalse
"totalPages":
int56
"size":
int1
}

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
1 item
"currentPage":
int0
"hasNext":
booltrue
"hasPrevious":
boolfalse
"totalPages":
int56
"size":
int1
}

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
1 item
"currentPage":
int0
"hasNext":
booltrue
"hasPrevious":
boolfalse
"totalPages":
int56
"size":
int1
}

"root":{
7 items
"errorMessage":
string"String"
"data":[
...
]
1 item
"currentPage":
int0
"hasNext":
booltrue
"hasPrevious":
boolfalse
"totalPages":
int56
"size":
int1
}

"root":{
1 item
"errorMessage":
string"String"
}