Sky ATP Open API

Sky ATP Public API

Default response content-types: application/json
Schemes: http

Summary

Tag: SubmitSample

Operation Description
POST /v1/skyatp/submit/sample

Submit sample for malware analysis.

Tag: HashLookup

Operation Description
GET /v1/skyatp/lookup/hash/{hash_string}

Lookup sample malware score by hash.

Tag: blwlOne

Operation Description
GET /v1/skyatp/{list_type}/param/{server_type}
PATCH /v1/skyatp/{list_type}/param/{server_type}
DELETE /v1/skyatp/{list_type}/param/{server_type}

Tag: blwlN

Operation Description
GET /v1/skyatp/{list_type}/file/{server_type}
PATCH /v1/skyatp/{list_type}/file/{server_type}
DELETE /v1/skyatp/{list_type}/file/{server_type}

Tag: default

Operation Description
GET /ping

Ping the API to determine if it is alive.

Security

Bearer

name: Authorization
in: header

Paths

Ping the API to determine if it is alive.

GET /ping

Uses default content-types: application/json

200 OK

Ping succeeded.

Lookup sample malware score by hash.

GET /v1/skyatp/lookup/hash/{hash_string}

Tags: HashLookup

Lookup sample malware score by hash (sha256). Optional full scanning report may be requested.

hash_string

Sample hash. Only SHA256 is supported at this time.

path string (64 to 64 chars)
full_report

Whether to return a full scanning report. This should be set to true if user wants to retrieve a detailed sample analysis report in JSON format.

query boolean
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

200 OK

Hash lookup succeeded. Returns a result JSON object.

Example for application/json
{
"last_update": 0,
"malware_info": {
"ident": "MemScan:Trojan.Pws"
}
,
"report": null,
"scan_complete": false,
"score": -1,
"sha256": "516f3396086598142db5e242bc2c8f69f4f5058a637cd2f9bf5dcb4619869536"
}
401 Unauthorized

Invalid API key

404 Not Found

Sample not found.

422 Unprocessable Entity

Missing or invalid parameters to HTTP call.

429 Too Many Requests

Client has sent too many requests in a given amount of time. Submission quota exceeded.

500 Internal Server Error

Internal server error.

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer
Submit sample for malware analysis.

POST /v1/skyatp/submit/sample

Tags: SubmitSample

Submit sample for malware analysis. To call this method, the user must provide a file parameter containing file content to be uploaded. The user also may provide additional information related to the sample such as client/remote IP, sample URL, client host name, name of the user who downloaded the sample, etc. If the submitted sample is determined to be malicious, Sky ATP may use this additional information to track the client within the internal network and notify the user that the host is infected.

multipart/form-data

file

Sample file to submit.

formData file
full_report

Whether to return a full scanning report. This should be set to true if user wants to retrieve a detailed sample analysis report in JSON format.

query boolean
sample_url

URL where the sample was downloaded from.

formData string
remote_ip

IP address where the sample was downloaded from.

formData string
client_ip

IP address of the client that downloaded this sample.

formData string
client_hostname

Hostname of the client that downloaded this sample.

formData string
username

Username of the client that downloaded this sample.

formData string
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

application/json

200 OK

File submission succeeded. Returns a submission JSON object.

Example for application/json
{
"last_update": 1464891625,
"malware_info": {
"ident": "MemScan:Trojan.Pws"
}
,
"scan_complete": true,
"score": 10,
"sha256": "516f3396086598142db5e242bc2c8f69f4f5058a637cd2f9bf5dcb4619869536"
}
401 Unauthorized

Invalid API key.

413 Request Entity Too Large

Sample file size over max limit.

422 Unprocessable Entity

Missing or invalid parameters to HTTP call.

429 Too Many Requests

Client has sent too many requests in a given amount of time. Submission quota exceeded.

500 Internal Server Error

Internal server error.

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

DELETE /v1/skyatp/{list_type}/file/{server_type}

Tags: blwlN

Delete given server in the list or the entire list if one of the entries in the file is * or all.

multipart/form-data

list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars) #/parameters/list_type_path
server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars) #/parameters/server_type_path
file

csv file, with a single column for server.

formData file #/parameters/file_form
failOnError

Whether to partially process the file in case of parsing errors.

formData boolean true #/parameters/failOnError_form
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

202 Accepted

The request has been accepted for processing.

request_id: string

Unique identifier of this request. Used for logs on the server side.

400 Bad Request

Request parameters are invalid

401 Unauthorized

Invalid/Expired API key

403 Forbidden

Access denied for this API key

413 Request Entity Too Large

Input file size over max limit.

422 Unprocessable Entity

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429 Too Many Requests

Client has sent too many requests in a given amount of time, api quota exceeded.

500 Internal Server Error

Internal server error

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

GET /v1/skyatp/{list_type}/file/{server_type}

Tags: blwlN

Returns the blacklist/whitelist for the specific server type.

list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars) #/parameters/list_type_path
server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars) #/parameters/server_type_path
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

200 OK

Get the blacklist/whitelist.

400 Bad Request

Request parameters are invalid

401 Unauthorized

Invalid/Expired API key

403 Forbidden

Access denied for this API key

422 Unprocessable Entity

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429 Too Many Requests

Client has sent too many requests in a given amount of time, api quota exceeded.

500 Internal Server Error

Internal server error

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

PATCH /v1/skyatp/{list_type}/file/{server_type}

Tags: blwlN

Updates a list of IP/URL/FQDN from a file in a specific list.

multipart/form-data

list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars) #/parameters/list_type_path
server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars) #/parameters/server_type_path
file

csv file, with a single column for server.

formData file #/parameters/file_form
failOnError

Whether to partially process the file in case of parsing errors.

formData boolean true #/parameters/failOnError_form
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

202 Accepted

The request has been accepted for processing.

request_id: string

Unique identifier of this request. Used for logs on the server side.

400 Bad Request

Request parameters are invalid

401 Unauthorized

Invalid/Expired API key

403 Forbidden

Access denied for this API key

413 Request Entity Too Large

Input file size over max limit.

422 Unprocessable Entity

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429 Too Many Requests

Client has sent too many requests in a given amount of time, api quota exceeded.

500 Internal Server Error

Internal server error

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

DELETE /v1/skyatp/{list_type}/param/{server_type}

Tags: blwlOne

Delete given server in the feed or the entire feed. Pass server name as * or all, to delete the entire list.

multipart/form-data

list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars) #/parameters/list_type_path
server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars) #/parameters/server_type_path
server

IP/URL/FQDN depending on the server_type. IPv4 and IPv6 are both supported.

formData string (1 to 128 chars) #/parameters/server_form
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

202 Accepted

The request has been accepted for processing.

request_id: string

Unique identifier of this request. Used for logs on the server side.

400 Bad Request

Request parameters are invalid

401 Unauthorized

Invalid/Expired API key

403 Forbidden

Access denied for this API key

422 Unprocessable Entity

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429 Too Many Requests

Client has sent too many requests in a given amount of time, api quota exceeded.

500 Internal Server Error

Internal server error

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

GET /v1/skyatp/{list_type}/param/{server_type}

Tags: blwlOne

Returns the blacklist/whitelist for the specific server type.

list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars) #/parameters/list_type_path
server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars) #/parameters/server_type_path
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

200 OK

Get the blacklist/whitelist.

400 Bad Request

Request parameters are invalid

401 Unauthorized

Invalid/Expired API key

403 Forbidden

Access denied for this API key

422 Unprocessable Entity

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429 Too Many Requests

Client has sent too many requests in a given amount of time, api quota exceeded.

500 Internal Server Error

Internal server error

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

PATCH /v1/skyatp/{list_type}/param/{server_type}

Tags: blwlOne

Updates an IP/URL/FQDN in a blacklist/whitelist

multipart/form-data

list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars) #/parameters/list_type_path
server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars) #/parameters/server_type_path
server

IP/URL/FQDN depending on the server_type. IPv4 and IPv6 are both supported.

formData string (1 to 128 chars) #/parameters/server_form
Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string #/parameters/auth_header
X-Forwarded-For

This is a header that provides tracking information for API usage.

header string #/parameters/forward_header

Uses default content-types: application/json

202 Accepted

The request has been accepted for processing.

request_id: string

Unique identifier of this request. Used for logs on the server side.

400 Bad Request

Request parameters are invalid

401 Unauthorized

Invalid/Expired API key

403 Forbidden

Access denied for this API key

422 Unprocessable Entity

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429 Too Many Requests

Client has sent too many requests in a given amount of time, api quota exceeded.

500 Internal Server Error

Internal server error

503 Service Unavailable

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Bearer

Parameter definitions

server_form server

IP/URL/FQDN depending on the server_type. IPv4 and IPv6 are both supported.

formData string (1 to 128 chars)
file_form file

csv file, with a single column for server.

formData file
failOnError_form failOnError

Whether to partially process the file in case of parsing errors.

formData boolean true
list_type_path list_type

Type of list, blacklist or whitelist.

path string , x ∈ { whitelist , blacklist } (9 to 9 chars)
server_type_path server_type

Server type of the list. Could be one of ip, url or domain.

path string , x ∈ { ip , url , domain } (2 to 6 chars)
auth_header Authorization

Bearer token of the form, Bearer token, token is application token generated from Customer Portal.

header string
forward_header X-Forwarded-For

This is a header that provides tracking information for API usage.

header string

Response definitions

400

Request parameters are invalid

401

Invalid/Expired API key

403

Access denied for this API key

422

Unprocessable Entity. Input is syntactically correct but semantically incorrect.

429

Client has sent too many requests in a given amount of time, api quota exceeded.

500

Internal server error

503

Service is temporarily not available. The Retry-After response header will indicate how long the service is expected to be unavailable to the requesting client.

Schema definitions

AuthenticatedUser: object

Internal structure describing an authorized OpenAPI user.

TenantID: string

Sky ATP Tenant ID.

TokenID: string

Sky ATP OpenAPI tokenID.

BlwlResult: object

Describes the result of a whitelist/blacklist result.

request_id: string

Unique identifier of this request. Used for logs on the server side.

data: object

Response from Customer Portal.

servers: string[]
string

Server as a string

count: integer

count of the servers being returned.

CustomerPortalError: object

Internal structure describing an error returned by Sky ATP Portal

Error: string

Short Error Description

ErrorDesc: string

Detailed Error Description

Success: boolean

Boolean whether request succeeded

ErrorCode: integer

HTTP Response code

DetailedScanReport: object

Detailed sample scanning report.

behaviors: object[]

List of malicious behavior types.

Error: object

err_id: string

Text representation of error code.

message: string

Short error description.

details: string

Long error description. Must not be used for error handling purposes.

MaliciousBehavior: object

Describes a particular behavior noticed during scanning.

behavior: string

List of malicious behavior types.

MalwareInfo: object

Classification of the malware sample.

mw_type: string (up to 256 chars)

Malware type.

platform: string (up to 256 chars)

Platform this sample is built for.

group: string (up to 256 chars)

Group this malware sample belongs to.

family: string (up to 256 chars)

Malware family.

cmplr: string (up to 256 chars)

Compiler used.

lang: string (up to 256 chars)

Malware locale.

ident: string (up to 256 chars)

Malware identity.

ScanResult: object

sha256: string (64 to 64 chars)

Sample sha256.

score: integer (int64)

Sample malware score in [0..10] range. If the sample processing has not completed, -1 will be returned.

threat_level: string , x ∈ { high , medium , low , clean }

Textual representation of the score.

category: string

File category.

size: integer (int64)

Sample file size.

malware_info: MalwareInfo
scan_complete: boolean

Whether sample processing is complete or not.

last_update: integer (int64)

Timestamp of last successful update in sample processing pipeline.

scan_report: DetailedScanReport