symantec-logo-top
Symantec™ Advanced Threat Protection

ATP API version 2

1. Introduction

1.1. About ATP APIs

Symantec Advanced Threat Protection (ATP) RESTful APIs allow for direct API access to the ATP appliance over SSL. All integrating applications must use OAuth 2.0 created tokens. ATP APIs use standard HTTP features and standard HTTP status codes to indicate errors. The REST APIs return JSON-formatted data.

1.2. Version information

ATP API version 2.

This version of the ATP API supports Symantec Advanced Threat Protection 3.2.x and later.

Important: With the release of Symantec Advanced Threat Protection 3.1, ATP implemented API version 2.0. API version 1.0 is now deprecated. Version 1 will be deprecated May 2019.

1.3. Important information

An API call might return a field named command_id or command_uid. These fields are the same and represent the command identifier.

1.4. URI scheme

All APIs exposed by the ATP appliance carry authentication tokens and other privileged data. To ensure the confidentiality of the data, the REST APIs exposed by ATP are only available on https://.

The base URI is as follows:

Note

The relative path prefix /v2/ indicates the use of version 2 of the API.

1.5. Enums

Enums become JSON strings and new JSON fields are ignored by pre-existing client applications. Unless otherwise stated, enums and integer enums may have values added in the future.

1.6. Time values

The following are tips to help you understand the meaning and usage of the following terms:

time

In the event JSON result, this represents the ISO 8601 date/time¹ that the event was created from the original source.

log_time

In the event JSON result, this represents the ISO 8601 date/time¹ that the event was recorded in ATP Manager.

updated

In the incident JSON result, this represents the ISO 8601 date/time¹ that the incident was last updated. This is useful for detecting any changes to the incident over time (for example, a new event being added to the incident or the closing of the incident within ATP Manager).

first_seen

In the association and entities JSON result, this represents the ISO 8601 date/time¹ of the first contributing event’s time.

last_seen

In the association and entities JSON result, this represents the ISO 8601 date/time¹ of the last contributing event’s time.

¹ Date formats are typically ISO 8601.

For events, remember that there can be propagation delays between the path of the event originator (endpoint, ATP network scanner, and ATP Manager). For instance, an endpoint may be outside the corporate network for 2 days on travel before it can access its Symantec Endpoint Protection Manager. During this period, the endpoint may be generating events with a time value. Once connected to the Symantec Endpoint Protection Manager, those older events propagate to Symantec Endpoint Protection Manager then to ATP Manager. The time value remains unchanged at the time the event was created, say 1 or 2 days ago. However, the log_time is recorded as now.

The event query APIs use filters based on log_time within the "query" clause and start_time/end_time parameters. The "query" clause uses a query language so that the client can query for any log_time (recording time) range. The events (creation) time range is restricted by the start_time/end_time JSON parameters.

The incident query APIs use filters based on “updated” time within the "query" clause and start_time/end_time parameters. The "query" clause uses a query language so that the client can query for any updated time range. The incidents (creation) time range is restricted by the start_time/end_time JSON parameters.

2. Paths

2.1. Get Appliance Info

GET /atpapi/v2/appliances

2.1.1. Description

This API can be used by partner services to access ATP server information.

The following appliance information is returned by this API:

  • ATP appliance ID / machine ID

  • ATP appliance name

  • ATP software version

  • Current time on the appliance in UTC time zone

  • Appliance role

This API currently returns only the management server details.

Authorization Requirement

API access requires privilege: atp_view_appliance_details. For details see link Generating an OAuth client

2.1.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

2.1.3. Responses

HTTP Code Description Schema

200

OK.

AppliancesResponse

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

ApiError

2.1.4. Produces

  • application/json

2.1.5. Tags

  • Appliances Resource

2.2. Get Associations between domains and files

POST /atpapi/v2/associations/entities/domains-files

2.2.1. Description

Allows the Public API client to search the ATP database for associations between domains and files.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Associations next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.2.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what associations to retrieve from the database.

AssociationsQueryRequest

2.2.3. Responses

HTTP Code Description Schema

200

OK.

DomainFileAssociationsResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.2.4. Produces

  • application/json

2.2.5. Tags

  • Associations Resource

2.3. Get Associations between endpoints and domains

POST /atpapi/v2/associations/entities/endpoints-domains

2.3.1. Description

Allows the Public API client to search the ATP database for associations between endpoints and domains.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Associations next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.3.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what associations to retrieve from the database.

AssociationsQueryRequest

2.3.3. Responses

HTTP Code Description Schema

200

OK.

EndpointDomainAssociationsResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.3.4. Produces

  • application/json

2.3.5. Tags

  • Associations Resource

2.4. Get Associations between endpoints and files

POST /atpapi/v2/associations/entities/endpoints-files

2.4.1. Description

Allows the Public API client to search the ATP database for associations between endpoints and files.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Associations next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.4.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what associations to retrieve from the database.

AssociationsQueryRequest

2.4.3. Responses

HTTP Code Description Schema

200

OK.

EndpointFileAssociationsResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.4.4. Produces

  • application/json

2.4.5. Tags

  • Associations Resource

2.5. Release Associations next field

DELETE /atpapi/v2/associations/entities/next/{next}

2.5.1. Description

Allows the Public API client to delete the next field used for associations cursoring.

The server caches result sets to ensure clients get stable results across multiple API calls as the client iterates through the results, updating the next pointer with each call. In order to ensure the server resources are released, it is strongly recommended that the client DELETE the next pointer returned in the last result set response. Without this, the server resources will be released after the specified keep_alive_secs value provided on the last query expires.

Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.5.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

next
required

The field used for associations cursoring.

string

2.5.3. Responses

HTTP Code Description Schema

204

Success. No content.

No Content

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

ApiError

2.5.4. Tags

  • Associations Resource

2.6. Issue a Command Action

POST /atpapi/v2/commands

2.6.1. Description

This API is used to issue a command action.

You can issue command actions to endpoints that are managed by Symantec Endpoint Protection. This API requires an endpoint identifiable target be specified. You can obtain the endpoint information using the Get Endpoint Entities API, Get Events API, or Get Incidents APIs.

Note
You must have a SEPM Controller configured in ATP Manager to issue command actions to endpoints.

The following command actions are supported

Isolate endpoint

When you isolate an endpoint, you cut off the connections that the endpoint has to internal networks and external networks. Isolating an endpoint keeps that computer from infecting any other computers. ATP supports isolating endpoints on Symantec Endpoint Protection 12.1 RU6 MP3 and later.

Authorization Requirement

API access requires privilege: atp_manage_remediate_cmds. For details see link Generating an OAuth client

Rejoin endpoint

When you rejoin an endpoint, you re-establish that endpoint’s connections to internal networks and external networks. You can only rejoin endpoints that are isolated. ATP supports rejoining endpoints on Symantec Endpoint Protection 12.1 RU6 MP3 and later.

Authorization Requirement

API access requires privilege: atp_manage_remediate_cmds. For details see link Generating an OAuth client

Get file

When you initiate a get file command for a given sha2 from a specified target endpoint, the file is fetched from the target endpoint and stored into the ATP appliance filestore.

Authorization Requirement

API access requires privilege: atp_endpoint_copy_file. For details see link Generating an OAuth client

Delete file

When you delete a file, you delete all instances of that file on the specified endpoint. ATP supports deleting files on Symantec Endpoint Protection 12.1 RU6 MP3 and later.

Authorization Requirement

API access requires privilege: atp_manage_remediate_cmds. For details see link Generating an OAuth client

If you integrate ATP and Symantec Endpoint Protection, and enable the endpoint data recorder feature, you can search your endpoints' data recorder for the artifact. ATP supports endpoint data recorder searches on Symantec Endpoint Protection 14.1 RU1 and later.

Note
ATP limits the maximum number of results from the recorded data to the following (maximums are not configurable): - Maximum events per search: 500,000 records. - Maximum number of events per endpoint: 100 records.
Authorization Requirement

API access requires privilege: atp_manage_endpoint_search. For details see link Generating an OAuth client

If you integrate ATP and Symantec Endpoint Protection, you can search your endpoints' hard drive for EOCs (such as files, processes, registry keys, and services). ATP supports limited EOC search (except File name searches and use of wildcards in search expressions) on Symantec Endpoint Protection 12.1 RU5 and later. ATP supports full EOC search on Symantec Endpoint Protection is 12.1 RU6. If you integrate ATP and Symantec Endpoint Protection, and enable the endpoint data recorder feature, you can search endpoints for EOCs in near real-time. ATP supports near real-time full EOC search on Symantec Endpoint Protection 14.1 RU1 and later.

Note
ATP limits the maximum number of results from the EOC search to the following (maximums are not configurable): - Maximum events per search: 500,000 records. - Maximum number of events per endpoint: 100 records.
Authorization Requirement

API access requires privilege: atp_manage_endpoint_search. For details see link Generating an OAuth client

Cancel command

When you cancel a command that is already in progress, you cancel the command execution on all the endpoints where it is still in progress. Only one command can be cancelled at a time, and ATP supports command cancellation on Symantec Endpoint Protection 12.1 RU6 MP5 and later.

Authorization Requirement

API access requires privilege:

Command Privileges

Cancel command on Delete file

atp_manage_remediate_cmds

Cancel command on Endpoint data recorder search

atp_manage_endpoint_search

Cancel command on EOC search

atp_manage_endpoint_search

For details see link Generating an OAuth client

2.6.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body defines the action and targets for the command request contained within the CommandBody.

CommandBody

2.6.3. Responses

HTTP Code Description Schema

200

OK.

Request for issuing a command action is accepted, and it will be further processed.

This does not mean that the command action has been successfully triggered. This means that the syntax of the request was correct, and the API has proceeded to the next step, which is to issue the command action and generate a command_id.

There could be individual failures, which will be captured in command status. In case of 200 OK, the API will return a command_id in the response body.

CommandActionResponse

400

Bad request - malformed request.

API returns 400 BAD request when either the payload or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to perform the requested action.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to perform the requested action. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to perform the requested action.

ApiError

409

Conflict - the command target states are still being initialized.

API returns 409 Conflict when a cancel_command action is issued on an initializing command.

In this case, the response contains Retry-After header that indicates the minimum seconds the client is asked to wait before re-trying the cancellation request. Documented in the response headers sections.
Headers :
Retry-After (integer (int32)) : Minimum time in seconds to wait before re-trying the cancellation request.

ApiError

413

Request entity too large - the list of targets is too long.

API returns 413 HTTP status code when the list of targets exceeds a specific acceptable threshold.

In this case, the response contains an X-header that has the permitted number of targets in a single request. Documented in the response headers sections.
Headers :
X-TARGET-LIST-LIMIT (integer (int32)) : Maximum number of targets permitted in a single request.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

In those cases where the requests are temporarily disallowed, the response contains Retry-After header that indicates the minimum seconds the client is asked to wait before re-trying the request. Documented in the response headers sections.
Headers :
Retry-After (integer (int32)) : Minimum time in seconds to wait before re-trying the request.

ApiError

2.6.4. Produces

  • application/json

2.6.5. Tags

  • Commands Resource

2.7. Query Command Status

POST /atpapi/v2/commands/{command_id}

2.7.1. Description

This API is used to query command status.

If you make a request using the limit parameter, there may be more status objects than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the status objects for the same request (i.e., show the next result set). The next value will continue to be returned in response to subsequent requests until the final results for that request have been retrieved.

Authorization Requirement

API access requires privilege:

Command Privileges

Isolate endpoint

atp_view_remediate_cmds

Rejoin endpoint

atp_view_remediate_cmds

Delete file

atp_view_remediate_cmds

Get file

atp_view_copy_file_cmds

Endpoint data recorder search

atp_view_endpoint_search

EOC search

atp_view_endpoint_search

For details see link Generating an OAuth client

2.7.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

command_id
required

Command ID to query.

string

Body

body
required

The body defines the cursoring options for the command status response.

CommandStatusQueryRequestBody

2.7.3. Responses

HTTP Code Description Schema

200

OK.

CommandStatusResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access this API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access this API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access this API.

ApiError

500

Internal server error.

ApiError

2.7.4. Produces

  • application/json

2.7.5. Tags

  • Commands Resource

2.8. Query Command Results

POST /atpapi/v2/commands/{command_id}/results

2.8.1. Description

This API is used to query command results of an EOC search or an Endpoint data recorder search command.

This API accepts query request over a specified time range and returns result records that match the search condition specified in the query request. For EOC search or Endpoint data recorder search commands, the result record is an endpoint event.

You must specify the time range using the start_time parameter and the end_time parameter (the maximum time range is 7 days). The time in the result schema is typically the result record creation time. This API supports search query in Lucene query syntax (such as boolean operators, ranges, regular expressions) to narrow the records to be retrieved.

If you make a request using the limit parameter, there may be more matching records than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching records for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
Unless the command has been completed, review the Achieving stable results for events and incidents section to get details on some of ATP’s event processing characteristics. Skipping this section could lead to unreliable result sets in client queries.
Authorization Requirement

API access requires privilege: atp_view_endpoint_search. For details see link Generating an OAuth client

2.8.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

command_id
required

Command ID of an existing Endpoint data recorder search or EOC search command.

string

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what result records to retrieve from the command results.

CommandResultQueryRequestBody

2.8.3. Responses

HTTP Code Description Schema

200

OK.

CommandResultResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access this API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access this API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access this API.

ApiError

500

Internal server error.

ApiError

2.8.4. Produces

  • application/json

2.8.5. Tags

  • Commands Resource

2.9. Get Entities

POST /atpapi/v2/entities

2.9.1. Description

Allows the Public API client to search the ATP database for entities (such as file, domain, and endpoint).

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.9.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what entities to retrieve from the database.

EntityQueryRequest

2.9.3. Responses

HTTP Code Description Schema

200

OK.

EntityQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.9.4. Produces

  • application/json

2.9.5. Tags

  • Entities Resource

2.10. Get Domain Entities

POST /atpapi/v2/entities/domains

2.10.1. Description

Allows the Public API client to search the ATP database for list of domain entities.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.10.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what domain entities to retrieve from the database.

EntityQueryRequest

2.10.3. Responses

HTTP Code Description Schema

200

OK.

DomainEntityQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.10.4. Produces

  • application/json

2.10.5. Tags

  • Entities Resource

2.11. Get Domain Instances

POST /atpapi/v2/entities/domains/instances

2.11.1. Description

Allows the Public API client to search the ATP database for list of domain instances.

Note
Unlike domain entities, domain instances provide insight into all variants of the domain IP address, the URL path or other known information seen by ATP. There could be more than one URL associated with a domain name. In addition, a domain could be hosted on different IP addresses. This represents the domain names, urls, ip addresses, and other known information seen across all SEP endpoints.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.11.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what domain instances to retrieve from the database.

EntityQueryRequest

2.11.3. Responses

HTTP Code Description Schema

200

OK.

DomainInstanceQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.11.4. Produces

  • application/json

2.11.5. Tags

  • Entities Resource

2.12. Get Domain Instances for specific domain name

POST /atpapi/v2/entities/domains/{data_source_url_domain}/instances

2.12.1. Description

Allows the Public API client to query the varying host URLs, IP addresses, and other known information seen for this specific domain name.

Note
Unlike domain entities, domain instances provide insight into all variants of the domain IP address, the URL path or other known information seen by ATP. There could be more than one URL associated with a domain name. In addition, a domain could be hosted on different IP addresses. This represents the domain names, urls, ip addresses, and other known information seen across all SEP endpoints.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.12.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

data_source_url_domain
required

Unique domain identifier.

string

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what domain instances to retrieve from the database.

EntityQueryRequest

2.12.3. Responses

HTTP Code Description Schema

200

OK.

DomainInstanceQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when - the specified next could not be found in the server cache. It could have been either expired or deleted. - the specified data_source_url_domain could not be found.

ApiError

500

Internal server error.

ApiError

2.12.4. Produces

  • application/json

2.12.5. Tags

  • Entities Resource

2.13. Get Endpoint Entities

POST /atpapi/v2/entities/endpoints

2.13.1. Description

Allows the Public API client to search the ATP database for list of endpoint entities.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.13.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what endpoint entities to retrieve from the database.

EntityQueryRequest

2.13.3. Responses

HTTP Code Description Schema

200

OK.

EndpointEntityQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.13.4. Produces

  • application/json

2.13.5. Tags

  • Entities Resource

2.14. Get Endpoint Instances

POST /atpapi/v2/entities/endpoints/instances

2.14.1. Description

Allows the Public API client to search the ATP database for list of endpoint instances.

Note
Unlike endpoint entities, endpoint instances provide insight into all variants of the host name, the IP address, or other known information seen by ATP. As and when an endpoint gets assigned a new IP address, it results in a new IP address being associated with the device id. Similarly, when host name or other known information changes, a new endpoint instance gets created. This represents the host names, device ids, ip addresses, and other known information seen across all SEP endpoints.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.14.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what endpoint instances to retrieve from the database.

EntityQueryRequest

2.14.3. Responses

HTTP Code Description Schema

200

OK.

EndpointInstanceQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.14.4. Produces

  • application/json

2.14.5. Tags

  • Entities Resource

2.15. Get Endpoint Instances for specific device id

POST /atpapi/v2/entities/endpoints/{device_uid}/instances

2.15.1. Description

Allows the Public API client to query the varying host names, IP addresses, and other known information seen for this specific device ID.

Note
Unlike endpoint entities, endpoint instances provide insight into all variants of the host name, the IP address, or other known information seen by ATP. As and when an endpoint gets assigned a new IP address, it results in a new IP address being associated with the device id. Similarly, when host name or other known information changes, a new endpoint instance gets created. This represents the host names, device ids, ip addresses, and other known information seen across all SEP endpoints.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.15.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

device_uid
required

Unique endpoint identifier.

string

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what endpoint instances to retrieve from the database.

EntityQueryRequest

2.15.3. Responses

HTTP Code Description Schema

200

OK.

EndpointInstanceQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when - the specified next could not be found in the server cache. It could have been either expired or deleted. - the specified device_uid could not be found.

ApiError

500

Internal server error.

ApiError

2.15.4. Produces

  • application/json

2.15.5. Tags

  • Entities Resource

2.16. Get File Entities

POST /atpapi/v2/entities/files

2.16.1. Description

Allows the Public API client to search the ATP database for list of file entities.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.16.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what file entities to retrieve from the database.

EntityQueryRequest

2.16.3. Responses

HTTP Code Description Schema

200

OK.

FileEntityQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.16.4. Produces

  • application/json

2.16.5. Tags

  • Entities Resource

2.17. Get File Instances

POST /atpapi/v2/entities/files/instances

2.17.1. Description

Allows the Public API client to search the ATP database for list of file instances.

Note
Unlike file entities, file instances provide insight into all variants of a file name or the file path seen by ATP. There could be more than one file name associated with a hash. In addition, a single file name could be in different paths. This represents the file names, sha2s, and paths seen across all SEP endpoints.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.17.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what file instances to retrieve from the database.

EntityQueryRequest

2.17.3. Responses

HTTP Code Description Schema

200

OK.

FileInstanceQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified next could not be found in the server cache. It could have been either expired or deleted.

ApiError

500

Internal server error.

ApiError

2.17.4. Produces

  • application/json

2.17.5. Tags

  • Entities Resource

2.18. Get File Entity for specific SHA2

GET /atpapi/v2/entities/files/{sha2}

2.18.1. Description

Allows the Public API client to query specific file entity by SHA2.

Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.18.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

sha2
required

Unique file identifier.

string

2.18.3. Responses

HTTP Code Description Schema

200

OK.

FileEntity

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified sha2 could not be found.

ApiError

500

Internal server error.

ApiError

2.18.4. Produces

  • application/json

2.18.5. Tags

  • Entities Resource

2.19. Get File Instances for specific SHA2

POST /atpapi/v2/entities/files/{sha2}/instances

2.19.1. Description

Allows the Public API client to query the varying file names and paths seen for this specific file SHA2.

Note
Unlike file entities, file instances provide insight into all variants of a file name or the file path seen by ATP. There could be more than one file name associated with a hash. In addition, a single file name could be in different paths. This represents the file names, sha2s, and paths seen across all SEP endpoints.

The limit parameter allows you to configure the maximum number of objects to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

You must use keep_alive_secs parameter to correctly set the keep alive timeout of the next between subsequent search requests. As keeping alive a next consumes server resources, it should be explicitly released as soon as the latest next is not being used anymore using the Release Entities next field API.

Note
The results that are returned from a search request reflect the state of the database at the time that the initial search request was made, like a snapshot in time. Subsequent changes to database resources (add, update, or delete) will only affect later search requests.
Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.19.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

sha2
required

Unique file identifier.

string

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what file instances to retrieve from the database.

EntityQueryRequest

2.19.3. Responses

HTTP Code Description Schema

200

OK.

FileInstanceQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when - the specified next could not be found in the server cache. It could have been either expired or deleted. - the specified sha2 could not be found.

ApiError

500

Internal server error.

ApiError

2.19.4. Produces

  • application/json

2.19.5. Tags

  • Entities Resource

2.20. Release Entities next field

DELETE /atpapi/v2/entities/next/{next}

2.20.1. Description

Allows the Public API client to delete the next field used for entities cursoring. The server caches result sets to ensure clients get stable results across multiple API calls as the client iterates through the results, updating the next pointer with each call. In order to ensure the server resources are released, it is strongly recommended that the client DELETE the next pointer returned in the last result set response. Without this, the server resources will be released after the specified keep_alive_secs value provided on the last query expires.

Authorization Requirement

API access requires privilege: atp_view_entities. For details see link Generating an OAuth client

2.20.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

next
required

The field used for entities cursoring.

string

2.20.3. Responses

HTTP Code Description Schema

204

Success. No content.

No Content

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

ApiError

2.20.4. Tags

  • Entities Resource

2.21. Get Events

POST /atpapi/v2/events

2.21.1. Description

This API is used to get events from ATP.

This API accepts search requests over a specified time range and returns events that match the search condition. You must specify the time range using the start_time parameter and the end_time parameter (the maximum time range is 7 days). The time in the result schema is typically the event creation time. This API supports search query in Lucene query syntax (such as boolean operators, ranges, regular expressions) to narrow the events to be retrieved.

If you make a request using the limit parameter, there may be more matching events than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching events for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
Review the Achieving stable results for events and incidents section to get details on some of ATP’s event processing characteristics. Skipping this section could lead to unreliable result sets in client queries.
Authorization Requirement

API access requires privilege: atp_view_events. For details see link Generating an OAuth client

2.21.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what events to retrieve from the event store.

EventQueryRequest

2.21.3. Responses

HTTP Code Description Schema

200

OK.

EventQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

ApiError

2.21.4. Produces

  • application/json

2.21.5. Tags

  • Events Resource

2.22. Get Incident Related Events

POST /atpapi/v2/incidentevents

2.22.1. Description

This API is used to get from ATP events that are related to incidents.

This API accepts search requests over a specified time range and returns the related events for incidents that match the search condition. You must specify the time range using the start_time parameter and the end_time parameter (the maximum time range is 30 days). This API supports search query in Lucene query syntax (such as boolean operators, ranges, regular expressions) to narrow the incidents to be retrieved.

If you make a request using the limit parameter, there may be more matching events than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching events for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
If your ATP appliance is updated from a release before 2.2, then the related events query may not return correct results if you specify a log_time or start_time that contains a date prior to or on the migration date. This is because in ATP 2.2, the method for indexing events in the database changed. For efficient searching of events, ATP indexes events daily. The data indexing takes effect when ATP creates new indices the date after migration. We recommend calling this API with a start_time greater than the ATP migration date.
Note
Review the Achieving stable results for events and incidents section to get details on some of ATP’s event processing characteristics. Skipping this section could lead to unreliable result sets in client queries.
Authorization Requirement

API access requires privilege: atp_view_incidents. For details see link Generating an OAuth client

2.22.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define the search request. A search request is a set of instructions that describes the incident related events to retrieve from the incident store.

EventQueryRequest

2.22.3. Responses

HTTP Code Description Schema

200

OK.

EventQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error

ApiError

2.22.4. Produces

  • application/json

2.22.5. Tags

  • Incident Events Resource

2.23. Get Incidents

POST /atpapi/v2/incidents

2.23.1. Description

This API is used to get incidents from ATP.

This API accepts search requests over a specified time range and returns incidents that match the search condition. You must specify the time range using the start_time parameter and the end_time parameter (the maximum time range is 30 days). This API supports search conditions (such as logical operators and special characters) to narrow the incidents to be retrieved.

Note
The updated field in the result schema is the time that the incident was last updated.

If you make a request using the limit parameter, there may be more matching incidents than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching incidents for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
Review the Achieving stable results for events and incidents section to get details on some of ATP’s event processing characteristics. Skipping this section could lead to unreliable result sets in client queries.
Authorization Requirement

API access requires privilege: atp_view_incidents. For details see link Generating an OAuth client

2.23.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define the search request. A search request is a set of instructions that describes what incidents to retrieve from the incident store.

IncidentQueryRequest

2.23.3. Responses

HTTP Code Description Schema

200

OK.

IncidentQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

ApiError

2.23.4. Produces

  • application/json

2.23.5. Tags

  • Incidents Resource

2.24. Patch Incidents (Close Incidents, Update Resolution or Add Comments)

PATCH /atpapi/v2/incidents

2.24.1. Description

This API is used to close, update resolution or add comments to incidents in bulk. API follows the RFC 6902 for resource modifications. The property that can be specified is changing the state property setting to 4 (i.e., close), updating resolution of an already closed incident or adding comments to the incident.

Note
The Patch command execution stops at the first occurrence of an error. All of the previous commands before the Patch command execution stops are successful. All commands after the execution stops are not processed.
Authorization Requirement

API access requires privilege: atp_manage_incidents. For details see link Generating an OAuth client

2.24.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body defines patch parameters for close incident, update resolution or add comments contained within the array of PatchIncidentBody.

To close an incident, the patch body must contain replace operation, path as /{uuid}/state and value as 4.

To update the resolution of an already closed incident, the patch body must contain replace operation, path as /{uuid}/resolution and value must be a supported incident resolution value. To set the resolution of an open incident, the patch body must contain an array of at least two replace operations, first element path as /{uuid}/state and value as 4, and second element path as /{uuid}/resolution and value must be a supported incident resolution value.

To add comments, the patch body must contain add operation, /{uuid}/comments/ as path and user defined string as value.

< PatchIncidentBody > array

2.24.3. Responses

HTTP Code Description Schema

204

Success. No content.

No Content

400

Bad request.

In this case, the response body contains the first invalid patch command body.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

In this case, the response body contains the first incident uuid that could not be found.

ApiError

413

Request entity too large - the list of patch operations is too long.

API returns 413 HTTP status code when the list of patch operations exceeds a specific acceptable threshold.

In this case, the response contains an X-header that has the permitted number of patch operations in a single request. Documented in the response headers sections.
Headers :
X-PATCH-LIST-LIMIT (integer (int32)) : Maximum number of patch operations permitted in a single request.

ApiError

500

Internal server error.

ApiError

2.24.4. Produces

  • application/json

2.24.5. Tags

  • Incidents Resource

2.25. Get Incident Comments

POST /atpapi/v2/incidents/{uuid}/comments

2.25.1. Description

This API is used to get the incident comments.

Authorization Requirement

API access requires privilege: atp_view_incidents. For details see link Generating an OAuth client

2.25.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

uuid
required

The GUID assigned for the incident.

string

Body

body
required

The body consists of a single JSON object to define the search request. A search request is a set of instructions that describes the incident comments to retrieve from the incident store.

IncidentCommentQueryRequest

2.25.3. Responses

HTTP Code Description Schema

200

OK.

IncidentCommentQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when the specified uuid could not be found.

ApiError

500

Internal server error.

ApiError

2.25.4. Produces

  • application/json

2.25.5. Tags

  • Incidents Resource

2.26. Create Blacklist Policies

POST /atpapi/v2/policies/blacklist

2.26.1. Description

This API is used to create blacklist policies.

Blacklist policies can be created for blocking or monitoring external communications. These can be of type ip, domain, url, md5 or sha256.

On success, it returns a list of blacklist policy identifiers which can be used in patch or delete APIs.

Note
Blacklist policy creation operation is atomic, so either all or none are created.
Authorization Requirement

API access requires privilege: atp_manage_policies. For details see link Generating an OAuth client

2.26.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single json object that defines the blacklist policies to be created.

BlacklistPolicyCreationRequestBody

2.26.3. Responses

HTTP Code Description Schema

200

Ok.

Blacklist policies have been successfully created and their corresponding identifiers have been returned to user.

For rate limiting purpose, the response also contains X-MAX-POLICY-LIMIT and X-REMAINING-POLICY-LIMIT headers that indicate the system wide maximum and remaining policy limit respectively. Documented in the response headers sections.
Headers :
X-MAX-POLICY-LIMIT (integer (int32)) : Maximum number of policies (includes both blacklists and whitelists) that can be created on this platform.
X-REMAINING-POLICY-LIMIT (integer (int32)) : The remaining number of policies (includes both blacklists and whitelists) that can be created without causing the system to exceed the above defined maximum policy limit.

BlacklistPolicyCreationResponse

400

Bad request - malformed request.

API returns 400 Bad request when either the payload or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

409

Resource already exists.

API returns 409 Resource already exists when blacklist policy for same target value already exists.

In this case, the response body contains the first conflicting target_value in message field.

ApiError

413

Request entity too large - policy creation list is too long.

API returns 413 Request entity too large when the number of policies to be created exceeds a specific acceptable threshold.

In this case, the response contains an X-POLICY-LIST-LIMIT that has the permitted number of policies, which can be created in a single request. Documented in the response headers sections.
Headers :
X-POLICY-LIST-LIMIT (integer (int32)) : Maximum number of policy creation permitted in a single request.

ApiError

429

Too many requests.

API returns 429 Too many requests when the number of policies to be created causes the system to exceed a platform specific maximum policy limit.

In this case, the response contains X-MAX-POLICY-LIMIT and X-REMAINING-POLICY-LIMIT headers that indicate the system wide maximum and remaining policy limit respectively. Documented in the response headers sections.
Headers :
X-MAX-POLICY-LIMIT (integer (int32)) : Maximum number of policies (includes both blacklists and whitelists) that can be created on this platform.
X-REMAINING-POLICY-LIMIT (integer (int32)) : The remaining number of policies (includes both blacklists and whitelists) that can be created without causing the system to exceed the above defined maximum policy limit.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.26.4. Produces

  • application/json

2.26.5. Tags

  • Blacklist Policies Resource

2.27. Get Blacklist Policies

GET /atpapi/v2/policies/blacklist

2.27.1. Description

This API is used to get blacklist policies from ATP.

Search query can be used to get specific blacklist policies. It can be searched by specifying either target_types (ip, domain, url, md5, or sha256) or a blacklist policy identifier (id). If no search parameter specified in URL then all blacklist policies will be served.

Currently only single target_type & target_value of same type is supported.

The limit parameter allows you to configure the maximum number of blacklist policies to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
The results that are returned from a search request reflect the latest state of the database at the time. Subsequent changes to database resources (add, update or delete) will be immediately available during result set cursoring of the same search request.
Authorization Requirement

API access requires privilege: atp_view_policies. For details see link Generating an OAuth client

2.27.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Query

domain
optional

Returns list of domain type blacklist policies matching to the specified pattern value. If no value is specified then all domain type blacklist policies will be returned.

Example: "www.abc.com"

string

Query

id
optional

Returns specific blacklist policy for the specified identifier. If no value is specified then all blacklist policies will be returned.

Example ="10"

string

Query

ip
optional

Returns list of ip type blacklist policies matching to the specified pattern value. If no value is specified then all ip type blacklist policies will be returned.

Following example for full match

Example : "1.1.1.1"

Following example for partial match

Example : "1.1"

string

Query

limit
optional

Specifies the maximum number of blacklist policies to return. If no limit is specified, then the limit value is set to the default limit.

Minimum = 10 Maximum = 1000 Default = 100 Example: 100

integer (int32)

Query

md5
optional

Returns specific md5 type blacklist policy for the specified md5 value. If no value is specified then all md5 type blacklist policies will be returned.

Example:"a457c5c52bcbe376ac0bd6a4fad6054f"

string

Query

next
optional

It is used for cursoring to get next set of blacklist policies. The value of next must be treated as an opaque value.

Use this value (data and type) in the next query.

Example: "ZW50aXRpZXM7MTUxNjk2NDQyMDE2MDswOkRYRj="

string

Query

sha256
optional

Returns specific sha256 type blacklist policy for the specified sha256 value. If no value is specified then all sha256 type blacklist policies will be returned.

Example: "7b455653bad6e0877dd0cffc4d4e"

string

Query

url
optional

Returns list of url type blacklist policies matching to the specified pattern value. If no value is specified then all url type blacklist policies will be returned.

Note: url string must be specified in encoded format.

Following example for full match

Example: "abc.com/book"

Following example for encoded url

Example: "abc.com/book/My%20book"

string

2.27.3. Responses

HTTP Code Description Schema

200

Ok.

Blacklist policies have been successfully fetched and returned.

BlackListPolicyResponse

400

Bad request - malformed request.

API returns 400 Bad request when either the query parameters or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

429

Too Many Requests.

API returns 429 Too many requests when there are too many blacklist policy GET requests.

In this case, the response contains Retry-After header that indicates the minimum seconds the client is asked to wait before re-trying the blacklist policy get request. Documented in the response headers sections.
Headers :
Retry-After (integer (int32)) : Minimum time in seconds to wait before re-trying the blacklist policy get request.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.27.4. Produces

  • application/json

2.27.5. Tags

  • Blacklist Policies Resource

2.28. Delete Blacklist Policy

DELETE /atpapi/v2/policies/blacklist/{id}

2.28.1. Description

This API is used to delete a blacklist policy.

Authorization Requirement

API access requires privilege: atp_manage_policies. For details see link Generating an OAuth client

2.28.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

id
required

The blacklist policy identifier.

string

2.28.3. Responses

HTTP Code Description Schema

204

Success. No content.

No Content

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.28.4. Tags

  • Blacklist Policies Resource

2.29. Patch Blacklist Policy (Update Comment)

PATCH /atpapi/v2/policies/blacklist/{id}

2.29.1. Description

This API is used to update comment to a blacklist policy.

API follows the RFC 6902 for resource modifications. The property that can be specified is updating the comment field of the blacklist policy.

Note
If blacklist type or value needs to be updated then user needs to delete the old and create a new blacklist policy.
Authorization Requirement

API access requires privilege: atp_manage_policies. For details see link Generating an OAuth client

2.29.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

id
required

The blacklist policy identifier.

string

Body

body
optional

The body consists of a single JSON object that defines patch parameters to update a blacklist policy comment.

BlacklistPolicyPatchBody

2.29.3. Responses

HTTP Code Description Schema

204

Success. No content.

Comment for blacklist policy has been updated successfully.

No Content

400

Bad request - malformed request.

API returns 400 Bad request when either the payload or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

API returns 404 Not found when the blacklist policy to be updated, does not exist.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.29.4. Produces

  • application/json

2.29.5. Tags

  • Blacklist Policies Resource

2.30. Create Whitelist Policies

POST /atpapi/v2/policies/whitelist

2.30.1. Description

This API is used to create whitelist policies.

Whitelist policies can be created for files or external computers which are considered to be safe. ATP considers these items trustworthy and takes no action when endpoints access them. You create whitelist policies based on a target_type: ip, domain, url, or sha256.

When you successfully create a new whitelist policy, the API returns a whitelist policy identifier (id).

Note
Whitelist policy creation operation is atomic, so either all or none are created.
Authorization Requirement

API access requires privilege: atp_manage_policies. For details see link Generating an OAuth client

2.30.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single json object that defines the whitelist policies to be created.

WhiteListPolicyCreationRequestBody

2.30.3. Responses

HTTP Code Description Schema

200

Ok.

Whitelist policies have been successfully created and their corresponding identifiers have been returned to user.

For rate limiting purpose, the response also contains X-MAX-POLICY-LIMIT and X-REMAINING-POLICY-LIMIT headers that indicate the system wide maximum and remaining policy limit respectively. Documented in the response headers sections.
Headers :
X-MAX-POLICY-LIMIT (integer (int32)) : Maximum number of policies (includes both blacklists and whitelists) that can be created on this platform.
X-REMAINING-POLICY-LIMIT (integer (int32)) : The remaining number of policies (includes both blacklists and whitelists) that can be created without causing the system to exceed the above defined maximum policy limit.

WhiteListPolicyCreationResponse

400

Bad request - malformed request.

API returns 400 Bad request when either the payload or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

409

Resource already exists.

API returns 409 Resource already exists when whitelist policy for same target value already exists.

In this case, the response body contains the first conflicting target_value in message field.

ApiError

413

Request entity too large - policy creation list is too long.

API returns 413 Request entity too large when the number of policies to be created exceeds a specific acceptable threshold.

In this case, the response contains an X-POLICY-LIST-LIMIT header that has the permitted number of policies, which can be created in a single request. Documented in the response headers sections.
Headers :
X-POLICY-LIST-LIMIT (integer (int32)) : Maximum number of policy creation permitted in a single request.

ApiError

429

Too Many Requests.

API returns 429 Too many requests when the number of policies to be created causes the system to exceed a platform specific maximum policy limit.

In this case, the response contains X-MAX-POLICY-LIMIT and X-REMAINING-POLICY-LIMIT headers that indicate the system wide maximum and remaining policy limit respectively. Documented in the response headers sections.
Headers :
X-MAX-POLICY-LIMIT (integer (int32)) : Maximum number of policies (includes both blacklists and whitelists) that can be created on this platform.
X-REMAINING-POLICY-LIMIT (integer (int32)) : The remaining number of policies (includes both blacklists and whitelists) that can be created without causing the system to exceed the above defined maximum policy limit.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.30.4. Produces

  • application/json

2.30.5. Tags

  • Whitelist Policies Resource

2.31. Get Whitelist Policies

GET /atpapi/v2/policies/whitelist

2.31.1. Description

This API is used to get whitelist policies from ATP.

You can use a search query to get specific whitelist policies. You can search by specifying either a target_type: (such as ip, domain, url, or sha256) or a whitelist policy identifier (id).

If no search parameter is specified in URL, then all whitelist policies will be served.

Currently, only single target_type and target_value of same type is supported.

The limit parameter allows you to configure the maximum number of whitelist policies to be returned in response to the search request. The response of each search request always includes a next value. The next value can be used in a subsequent request to retrieve the next group of matching results for the same search request (i.e., show the next result set). The result array will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
The results that are returned from a search request reflect the latest state of the database at the time. Subsequent changes to database resources (add, update, or delete) will be immediately available during result set cursoring of the same search request.
Authorization Requirement

API access requires privilege: atp_view_policies. For details see link Generating an OAuth client

2.31.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Query

domain
optional

Returns list of domain type whitelist policies matching to the specified pattern value. If no value is specified, then all domain type whitelist policies will be returned.

Example : "skyscan.com"

string

Query

id
optional

Returns specific whitelist policy for the specified identifier. If no value is specified, then all whitelist policies will be returned.

Example : "10"

string

Query

ip
optional

Returns list of ip type whitelist policies matching to the specified pattern value. If no value is specified, then all ip type whitelist policies will be returned.

Following example for full match: Example : "1.1.1.1"

Following example for partial match: Example : "1.1"

string

Query

limit
optional

Specifies the maximum number of whitelist policies to return. If no limit is specified, then the limit value is set to the default limit.

Minimum = 10 Maximum = 1000 Default = 100 Example : 100

integer (int32)

Query

next
optional

It is used for cursoring to get the next set of whitelist policies. The value of next must be treated as an opaque value.

Use this value (data and type) in the next query.

Example : "ZW50aXRpZXM7MTUxNjk2NDQyMDE2MD swOkRYRj="

string

Query

sha256
optional

Returns specific sha256 type whitelist policy for the specified sha256 value. If no value is specified, then all sha256 type whitelist policies will be returned.

Example : "4cbaa39e03c088b7e44d31722f099fb8030753 bad30ba09edcb27490f7802cd9"

string

Query

url
optional

Returns list of url type whitelist policies matching to the specified pattern value. If no value is specified, then all url type whitelist policies will be returned.

Note: url string must be specified in encoded URL format.

Following example for full match: Example : "http://www.abc.com/book"

Following example for encoded url: Example : "http://www.abc.com/book/My%20book"

string

2.31.3. Responses

HTTP Code Description Schema

200

Ok.

Whitelist policies have been successfully fetched and returned.

WhiteListPolicyResponse

400

Bad request - malformed request.

API returns 400 Bad request when either the query parameters or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

429

Too Many Requests.

API returns 429 Too many requests when there are too many whitelist policy GET requests.

In this case, the response contains Retry-After header that indicates the minimum seconds the client is asked to wait before re-trying the whitelist policy get request. Documented in the response headers sections.
Headers :
Retry-After (integer (int32)) : Minimum time in seconds to wait before re-trying the whitelist policy get request.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.31.4. Produces

  • application/json

2.31.5. Tags

  • Whitelist Policies Resource

2.32. Delete Whitelist Policy

DELETE /atpapi/v2/policies/whitelist/{id}

2.32.1. Description

This API is used to delete a whitelist policy.

Authorization Requirement

API access requires privilege: atp_manage_policies. For details see link Generating an OAuth client

2.32.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

id
required

The whitelist policy identifier.

string

2.32.3. Responses

HTTP Code Description Schema

204

Success. No content.

No Content

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.32.4. Tags

  • Whitelist Policies Resource

2.33. Patch Whitelist Policy (Update Comment)

PATCH /atpapi/v2/policies/whitelist/{id}

2.33.1. Description

This API is used to update a comment to a whitelist policy.

API follows the RFC 6902 for resource modifications. The property that can be specified is updating the comment field of the white policy.

Note
This API can only be used to modify whitelist policy comments. If you need to change the target_type or its value, you must delete the existing whitelist policy and create a new one.
Authorization Requirement

API access requires privilege: atp_manage_policies. For details see link Generating an OAuth client

2.33.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

id
required

The whitelist policy identifier.

string

Body

body
optional

The body consists of a single JSON object that defines patch parameters to update a whitelist policy comment.

WhiteListPolicyPatchBody

2.33.3. Responses

HTTP Code Description Schema

204

Success. No content.

Comment for whitelist policy has been updated successfully.

No Content

400

Bad request - malformed request.

API returns 400 Bad request when either the payload or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

API returns 404 Not found when the whitelist policy to be updated does not exist.

ApiError

500

Internal server error.

API returns 500 Internal server error when it could not process the request.

ApiError

2.33.4. Produces

  • application/json

2.33.5. Tags

  • Whitelist Policies Resource

2.34. Issue Sandbox Command

POST /atpapi/v2/sandbox/commands

2.34.1. Description

This API provides the ability for a file to be detonated in a sandbox. It will return an assessment of the file’s behaviors and likely level of maliciousness.

The resulting sandbox service called depends on ATP Manager’s configuration. This could either be the Cynic or Content Analysis service. See ATP Manager’s configuration.

In order to perform an analysis, Cynic and Content Analysis require that the file in question be in ATP Manager’s file store. In some cases, the Cynic cloud service can perform a hash-based query where Cynic has already recently analyzed the requested file. Failure to have the file in ATP Manager’s file store causes the command status to return an error_code 9007 = File Not Found In FileStore (Use get_endpoint_file Command To Copy File Into FileStore). When this occurs, use the Get file command to retrieve the file from the desired endpoint and reissue this command.

If a given file has already been fully analyzed and the result is still available in the server cache, this API will return 204 No Content. See Get Sandbox Verdict of specific SHA2 to retrieve the previously cached verdict. See Get Sandbox Events of specific SHA2, Get Sandbox Activities of specific SHA2 and Get Sandbox Patterns of specific SHA2 to retrieve the previously cached full analysis report.

In some cases, the Sandbox service may decide against the need of a full analysis and just rely on intelligence like contextual metadata and prevalence information to provide an assessment. As intelligence can evolve over time, this API allows a resubmission of the same file. See Get File Entity for specific SHA2 to retrieve the previously cached verdict.

Authorization Requirement

API access requires privilege: atp_manage_sandbox. For details see link Generating an OAuth client

2.34.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body defines the action and targets for the command request contained within the SandboxCommandBody.

SandboxCommandBody

2.34.3. Responses

HTTP Code Description Schema

200

OK.

API returns 200 OK when a new sandbox command registers successfully with ATP services and the response body contains command_id.

SandboxCommandResponseBody

204

Success. No content.

API returns 204 No Content when a given file has already been fully analyzed and the result is still available in the server cache.

ApiError

400

Bad request - malformed request.

API returns 400 BAD request when either the payload or the headers are malformed.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

413

Request entity too large - the list of targets is too long.

API returns 413 HTTP status code when the list of targets exceeds a specific acceptable threshold.

In this case, the response contains an X-header that has the permitted number of targets in a single request. Documented in the response headers sections.
Headers :
X-TARGET-LIST-LIMIT (integer (int32)) : Maximum number of targets permitted in a single request.

ApiError

2.34.4. Produces

  • application/json

2.34.5. Tags

  • Sandbox Resource

2.35. Query Sandbox Command Status

GET /atpapi/v2/sandbox/commands/{command_id}

2.35.1. Description

This API is used to query the sandbox command status.

Authorization Requirement

API access requires privilege: atp_view_sandbox. For details see link Generating an OAuth client

2.35.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

command_id
required

Command ID to query.

string

2.35.3. Responses

HTTP Code Description Schema

200

OK.

SandboxCommandStatusResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

ApiError

500

Internal server error.

ApiError

2.35.4. Produces

  • application/json

2.35.5. Tags

  • Sandbox Resource

2.36. Get Sandbox Activities of specific SHA2

GET /atpapi/v2/sandbox/results/{sha2}/activities

2.36.1. Description

This API is used to get the previously cached sandbox activities from the specified SHA2’s full analysis report.

If you make a request using the limit parameter, there may be more matching sandbox activities than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching sandbox activities for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Authorization Requirement

API access requires privilege: atp_view_sandbox. For details see link Generating an OAuth client

2.36.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

sha2
required

Unique file identifier.

string

Query

limit
optional

Specifies the maximum number of sandbox activities to return. If any sandbox activities are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Minimum = 10 Maximum = 50 Default = 30

Example : 10

integer (int32)

Query

next
optional

Used for sandbox activities cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Example : "c2FuZGJveF9hY3Rpdml0aWVzOzEw"

string

2.36.3. Responses

HTTP Code Description Schema

200

OK.

SandboxActivitiesQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when sandbox results for the specified sha2 could not be found in the cache. Either the specified sha2 has not been fully analyzed yet or the result has been purged from the cache. When this occurs, use Issue Sandbox Command to issue a sandbox analysis.

ApiError

500

Internal server error.

ApiError

2.36.4. Produces

  • application/json

2.36.5. Tags

  • Sandbox Resource

2.37. Get Sandbox Events of specific SHA2

GET /atpapi/v2/sandbox/results/{sha2}/events

2.37.1. Description

This API is used to get the previously cached sandbox events from the specified SHA2’s full analysis report.

If you make a request using the limit parameter, there may be more matching sandbox events than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching sandbox events for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Authorization Requirement

API access requires privilege: atp_view_sandbox. For details see link Generating an OAuth client

2.37.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

sha2
required

Unique file identifier.

string

Query

limit
optional

Specifies the maximum number of sandbox events to return. If any sandbox events are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Minimum = 10 Maximum = 30 Default = 20

Example : 10

integer (int32)

Query

next
optional

Used for sandbox events cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Example : "c2FuZGJveF9ldmVudHM7MTA="

string

2.37.3. Responses

HTTP Code Description Schema

200

OK.

SandboxEventsQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when sandbox results for the specified sha2 could not be found in the server cache. Either the specified sha2 has not been fully analyzed yet or the result has been purged from the cache. When this occurs, use Issue Sandbox Command to issue a sandbox analysis.

ApiError

500

Internal server error.

ApiError

2.37.4. Produces

  • application/json

2.37.5. Tags

  • Sandbox Resource

2.38. Get Sandbox Patterns of specific SHA2

GET /atpapi/v2/sandbox/results/{sha2}/patterns

2.38.1. Description

This API is used to get the previously cached sandbox patterns from the specified SHA2’s full analysis report.

Currently, only the Content Analysis platform reports patterns. These patterns define why Content Analysis deemed the file to be good or bad.

If you make a request using the limit parameter, there may be more matching sandbox patterns than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching sandbox patterns for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Authorization Requirement

API access requires privilege: atp_view_sandbox. For details see link Generating an OAuth client

2.38.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

sha2
required

Unique file identifier.

string

Query

limit
optional

Specifies the maximum number of sandbox patterns to return. If any sandbox patterns are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Minimum = 10 Maximum = 100 Default = 50

Example : 10

integer (int32)

Query

next
optional

Used for sandbox patterns cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Example : "c2FuZGJveF9wYXR0ZXJuczsxMA=="

string

2.38.3. Responses

HTTP Code Description Schema

200

OK.

SandboxPatternsQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when sandbox results for the specified sha2 could not be found in the server cache. Either the specified sha2 has not been fully analyzed yet or the result has been purged from the cache. When this occurs, use Issue Sandbox Command to issue a sandbox analysis.

ApiError

500

Internal server error.

ApiError

2.38.4. Produces

  • application/json

2.38.5. Tags

  • Sandbox Resource

2.39. Get Sandbox Verdict of specific SHA2

GET /atpapi/v2/sandbox/results/{sha2}/verdict

2.39.1. Description

This API is used to get the previously cached sandbox verdict information from the specified SHA2’s full analysis report.

Authorization Requirement

API access requires privilege: atp_view_sandbox. For details see link Generating an OAuth client

2.39.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Path

sha2
required

Unique file identifier.

string

2.39.3. Responses

HTTP Code Description Schema

200

OK.

SandboxVerdict

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

404

Not found.

The API returns 404 Not found when sandbox results for the specified sha2 could not be found in the server cache. Either the specified sha2 has not been fully analyzed yet or the result has been purged from the cache. When this occurs, use Issue Sandbox Command to issue a sandbox analysis.

ApiError

500

Internal server error.

ApiError

2.39.4. Produces

  • application/json

2.39.5. Tags

  • Sandbox Resource

2.40. Get System Activities

POST /atpapi/v2/systemactivities

2.40.1. Description

This API is used to get system activities from ATP.

This API accepts search requests over a specified time range and returns system activities that match the search condition. You must specify the time range using the start_time parameter and the end_time parameter (the maximum time range is 7 days). The time in the result schema is typically the system activities creation time. This API supports search query in Lucene query syntax (such as boolean operators, ranges, regular expressions) to narrow the system activities to be retrieved.

If you make a request using the limit parameter, there may be more matching system activities than can be returned for that response. In this scenario, the response for that request will include a next value. The next value can be used in a subsequent request to retrieve the next group of the matching system activities for the same search request (i.e., show the next result set). The next value will continue to be returned in subsequent search requests until the final results for that search have been retrieved.

Note
Review the Achieving stable results for events and incidents section to get details on some of ATP’s event processing characteristics. Skipping this section could lead to unreliable result sets in client queries.
Authorization Requirement

API access requires privilege: atp_view_events. For details see link Generating an OAuth client

2.40.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

This header provides the OAuth2 access token. The token is obtained by calling /oauth2/tokens APIs. See OAuth Grant Usage Example section for example usage.

string

""

Body

body
required

The body consists of a single JSON object to define search request. A search request is a set of instructions that describes what system activities to retrieve from the event store.

SystemActivitiesQueryRequest

2.40.3. Responses

HTTP Code Description Schema

200

OK.

SystemActivitiesQueryResponse

400

Bad request.

ApiError

401

Unauthorized.

API returns 401 Unauthorized when valid authentication credentials are not provided.

ApiError

403

Forbidden.

API returns 403 Forbidden when the client does not have sufficient privileges to access the API.

In this case, the response contains X-MISSING-PRIVILEGE header that indicates the privilege required to access the API. Documented in the response headers sections.
Headers :
X-MISSING-PRIVILEGE (string) : The privilege required to access the API.

ApiError

500

Internal server error.

ApiError

2.40.4. Produces

  • application/json

2.40.5. Tags

  • System Activities Resource

2.41. OAuth 2.0 Token Grant

POST /oauth2/tokens

2.41.1. Description

This resource is used to generate an OAuth 2 access token.

To generate an access token with the client_credentials grant type, you must first create an OAuth2 client in the ATP Manager. Then get the client_id and client_secret from the registered OAuth2 client.

When using an issued token, your code must expect that after the returned expires_in time occurs, you will receive an HTTP 401 error response. Your code will use the same client_id and client_secret again to issue a new access_token for subsequent API calls. You may decide to pre-renew an access_token before the expires_in time occurs. However, you may still receive a HTTP 401 expired response from any API call (this depends on your service).

When you access an API with a token that does not have the required privilege, your code must expect that you will receive an HTTP 403 error response. If you still need to access the API then you must delete the exiting OAuth2 client in ATP Manager and then create and use a new OAuth2 client with the required privilege set.

Note
Contact Support if you detect a discrepancy between this API’s MUSTs and RFC-6749/RFC-6750.

2.41.2. Parameters

Type Name Description Schema Default

Header

Authorization
required

The Authorization header must be "Basic" scheme.

Steps to get an Authorization header in Basic scheme: - Obtain the client_id and client_secret from the user. - Construct the user-pass by concatenating the client_id, a single colon (:) character, and the client_secret. - Encode the user-pass into an octet sequence. - Obtain the basic-credentials by encoding the octet sequence using Base64 into a sequence of US-ASCII characters.

Refer to https://tools.ietf.org/html/rfc7617 for more details.

string

""

Query

grant_type
required

Currently supported: "client_credentials"

string

2.41.3. Responses

HTTP Code Description Schema

200

OK.

TokensResponse

400

Bad request.

ApiError

401

Unauthorized

ApiError

500

Internal server error.

ApiError

2.41.4. Consumes

  • application/x-www-form-urlencoded

2.41.5. Produces

  • application/json

2.41.6. Tags

  • OAuth 2.0 Token Resource

Unresolved directive in index.adoc - include::/generated/atp_api_resources.adoc[]

3. Definitions

3.1. ATPService

Details of the ATP service.

Name Description Schema

action
optional

Action taken on a service (such as started, stopped, terminated, etc.).

Applicable events : 1000
Example : "stop"

string

pid
optional

PID of the service for which an action was taken.

Applicable events : 1000
Example : 31337

integer (int32)

service
optional

Name of service on which an action (such as started, stopped, terminated, etc.) was triggered.

Applicable events : 1000
Example : "microservice_host"

string

3.2. ActivityVerboseDetails

Activity Verbose Details object.

Type : object

3.3. ApiError

ATP Api Error object.

Name Description Schema

code
optional

A number that indicates the reason for the error. It may be the same as the status code, or it may be a more specific code that is specific to the problem domain.
Example : 101

integer (int32)

developer_message
optional

A string that contains technical information. Intended for application developers.
Example : "Object not found in collection users with query {\"_id\" : \"abc\"}"

string

error
optional

Only provided for errors during the …/oauth2/ related calls as per the OAuth 2.0 specifications. Matches message.
Example : "invalid request parameter"

string

error_message
optional

Only provided for errors during the …/oauth2/ related calls as per the OAuth 2.0 specifications. Matches developer_message.
Example : "Object not found in collection users with query {\"_id\" : \"abc\"}"

string

message
optional

A string that contains an error message giving a concise reason for the error. Intended for application end users.
Example : "Time format does not follow ISO 8601 date stamp standard."

string

status
required

Standard HTTP status code.

HTTP status codes
Example : 400

integer (int32)

3.4. Appliance

Appliance details object.

Name Description Schema

appliance_id
required
read-only

ATP appliance/machine ID.
Example : "4219625C-8EBF-D8C9-146D-3CBD5D173BF"

string

appliance_name
required

ATP appliance name.
Example : "ATP"

string

appliance_time
required

Current timestamp at the appliance in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).
Example : "2016-06-30T17:56:22Z"

string

role
required

Indicates the appliance’s role. If the item appears in the array, the feature is enabled on the appliance. Possible values are:

management = Runs as a management platform network scanner = Runs as a network scanner endpoint = Runs as an endpoint control point unassigned = Admin has not yet assigned a role to this appliance

Example : ["endpoint", "network scanner", "management"]

< string > array

software_version
required

Current software version of the appliance.
Example : "2.2.0-212"

string

3.5. AppliancesResponse

Response object containing the list of appliance objects.

Name Description Schema

appliance_list
required

List of ATP appliances.

< Appliance > array

3.6. AssociationsQueryRequest

Request body to query associations of entities.

Name Description Schema

keep_alive_secs
optional

This value determines the length of time in seconds that the query results will be cached on the server. Each API HTTP request resets the cache countdown to the specified value.

See example for proper usage of this value.

Minimum = 30 sec Maximum = 300 sec Default = 60 sec
Example : 60

integer (int32)

limit
optional

Specifies the maximum number of associations to return. If any associations are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 100
Example : 100

integer (int32)

next
optional

Used for associations cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "ZXhhbXBsZSBhc3NvY2lhdGlvbnMgbmV4dCBzdHJpbmcg"

string

query
optional

Specifies a search query as Lucene query string.

The search query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. - A Single Term is a single word such as "test" or "hello" - A Phrase is a group of words surrounded by double quotes such as "hello dolly"

When creating a search query string, consider the following: - You can search any field by specifying the field name followed by a colon ":" and then the term you are looking for - Escape special characters that are part of the query syntax. To escape a special character use the \ before the character. The current list of special characters are + - && || ! ( ) { } [ ] ^ " ~ * ? \ : - Date value should follow ISO 8601 date stamp standard format (yyyy-MM-dd’T’HH:mm:ss.SSSXXX) - Supported Boolean operators for complex query are: AND OR + - NOT Note: Boolean operators must be ALL CAPS - Multiple terms can be combined together with Boolean operators to form a more complex query in the query clause - Use parentheses to group clauses to form sub-queries - By default, matches all records - The maximum length of the query string is 10240 characters
Example : "first_seen:[2017-01-01T00:00:00.000Z TO 2017-01-08T00:00:00.000Z]"

string

verb
required

Request verb. Currently, only query verb is supported.
Example : "query"

string

3.7. Attack

Attack object.

Name Description Schema

tactic_ids
optional

The MITRE tactic ID(s) for the attack. Tactic ID values are: 1 = Initial Access 2 = Execution 3 = Persistence 4 = Privilege Escalation 5 = Defense Evasion 6 = Credential Access

7 = Discovery 8 = Lateral Movement 9 = Collection 10 = Exfiltration 11 = Command and Control

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

< integer (int32) > array

technique_name
optional

The MITRE technique name for the attack.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

string

technique_uid
optional

The MITRE technique ID for the attack.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

string

3.8. Av

Av object.

Name Description Schema

date_detected
optional

Threat file detection date in ISO 8601 format.

Applicable events : 4102

string

date_quarantined
optional

Threat file quarantined date in ISO 8601 format.

Applicable events : 4102

string

threat_categories
optional

Comma-separated list of integers indicating relevant threat categories. Possible list values are: 0 = CATEGORY_MALWARE 1 = CATEGORY_NON_VIRAL_MALICIOUS 2 = CATEGORY_RESERVED_MALICIOUS 3 = CATEGORY_HEURISTIC 4 = CATEGORY_SECURITY_RISK_ON 5 = CATEGORY_HACKTOOLS 6 = CATEGORY_SPYWARE 7 = CATEGORY_TRACKWARE 8 = CATEGORY_DIALERS 9 = CATEGORY_REMOTE_ACCESS 10 = CATEGORY_ADWARE 11 = CATEGORY_JOKE 12 = CATEGORY_SECURITY_RISK_OFF 13 = CATEGORY_SECURITY_ASSESMENT_TOOL 14 = CATEGORY_MISLEADING_APPLICATION 15 = CATEGORY_POTENTIALLY_UNWANTED_APPLICATION 16 = CATEGORY_EXPERIMENTAL_HEURISTIC 17 = CATEGORY_PARENTAL_CONTROL 18 = CATEGORY_REPUTATION_DETECTION

Applicable events : 4102
Example : "1, 3"

string

3.9. BASH

BASH object.

The BASH object provides the required data for the SONAR feature.

Name Description Schema

recommended_action
optional

Recommended actions by BASH. Possible values are: 0 = Unknown 1 = Remediate 2 = Block

Applicable events : 4100

string

signature_version
optional

BASH signature version.

Applicable events : 4100
Example : "20110422.001"

string

virus_id
optional

The virus identifier for the detection.

Applicable events : 4100

string

virus_name
optional

The virus name associated with the detection.

Applicable events : 4100

string

3.10. BlackListPolicy

Blacklist policy object model.

Name Description Schema

comment
optional

Specifies the comment for this blacklist policy. If not specified, then defaults to empty string.
Example : "Seeing Command and Control traffic from this IP."

string

id
required
read-only

The unique ID of this blacklist policy. This id can be used in patch or delete request.

Note: This ID is ignored if it is present in the create request.

string

target_type
required

Specifies the type of this blacklist policy.
Example : "ip"

enum ("ip", "domain", "url", "md5", "sha256")

target_value
required

Specifies the value of this blacklist policy.
Example : "1.1.1.1"

string

3.11. BlackListPolicyResponse

Response containing the list of blacklist policies.

Name Description Schema

next
required

The token used for blacklist policies cursoring.

For details, refer to ResultSet request examples.

string

result
required

List of blacklist policies.

< BlackListPolicy > array

3.12. BlacklistPolicyCreationRequestBody

This defines the list of all of the blacklist policies to be created.

Name Description Schema

policies
required

It contains the list of blacklist policies to be created.

< BlackListPolicy > array

verb
required

Request verb.

Currently, create verb is supported for blacklist policy creation.
Example : "create"

string

3.13. BlacklistPolicyCreationResponse

Blacklist Policy Creation Response object containing a list of blacklist policy identifiers.

Name Description Schema

ids
required

List of blacklist policy identifiers successfully created. These are returned in the same order as the policies defined in BlacklistPolicyCreationRequestBody.

< string > array

3.14. BlacklistPolicyPatchBody

Patch parameters for updating comment to the blacklist policy.

Name Description Schema

op
required

Specifies the operation to take on the specified policy.

enum ("replace")

path
required

String containing a JSON-pointer value that references a location within the policy document where the operation is performed.

For replace operation the path must be /comment.

enum ("/comment")

value
required

The value field is specific to the type of operation being patched.

For replace operation, the value must be a string. - The maximum length of comment is 512 characters.

string

3.15. CancelCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("cancel_command")

end_time
optional
read-only

Should not be sent as part of cancel_command command body.

string

query
optional
read-only

Should not be sent as part of cancel_command command body.

string

start_time
optional
read-only

Should not be sent as part of cancel_command command body.

string

targets
required

List of command IDs to cancel.

< string > array

3.16. CommandActionResponse

Response of a command action.

Name Description Schema

command_id
required

Command ID.

string

error_code
optional

This represents the status of the command action. Possible values: -1 = Error 0 = Command {action} successfully requested 1 = Command cancel_command not supported for target command type 2 = Command cancel_command failed because the target command is already in terminal state (i.e., completed, error, or cancelled) 3 = Command cancel_command is already in progress for the target command

integer (int32)

message
optional

Message explaining error code. Possible values: Error (-1) Command {action} successfully requested (0) Command cancel_command not supported for target command type (1) Command cancel_command failed because the target command is already in terminal state (2) Command cancel_command is already in progress for the target command (3)

string

3.17. CommandBody

Command body object for /atpapi/v2/commands.

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("isolate_endpoint", "rejoin_endpoint", "delete_endpoint_file", "get_endpoint_file", "recorder_search", "eoc_search", "cancel_command")

end_time
optional

Required when action: recorder_search.

Specifies the end of the search query time frame.

When specifying end_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - Query operation on end_time is exclusive. Example: end_time < 2017-01-08T00:00:00.000Z - The end time must be greater than the start time - The default is the current server time
Example : "2017-01-08T00:00:00.000Z"

string

query
optional

Required when action is: recorder_search or when action is: eoc_search.

Specifies the search query expression.

When specifying query, consider the following: - The expression should be written in the following format: Token: "Value" - The expression should be constructed from supported tokens, operators, wildcards, and from How to write successful endpoint search expressions - The maximum length of search query expression is 10240 characters
Example : "Search query examples"

string

start_time
optional

Required when action: recorder_search.

Specifies the beginning of the search query time frame.

When specifying start_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - The query operation on start_time is inclusive. Example: start_time >= '2017-01-01T00:00:00.000Z' - The start time must be less than the end time - The default is end_time minus 7 days
Example : "2017-01-01T00:00:00.000Z"

string

targets
required

The targets field is specific to the type of command.

For isolate_endpoint or rejoin_endpoint, the field is an array of strings each representing a device ID of the target computer.

For delete_endpoint_file or get_endpoint_file, the field is an array of FileEndpointPair that contains the SHA256 value of the target file and the corresponding device ID of the target computer.

For recorder_search or eoc_search, the field is an array of SearchScope.

For cancel_command, the field is an array of strings each representing a command ID.

object

3.18. CommandResultQueryRequestBody

Request body for command result query.

Name Description Schema

end_time
optional

Specifies the end of the search time frame.

When specifying end_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - Query operation on end_time is exclusive. Example: end_time < 2017-01-08T00:00:00.000Z - The end time must be greater than the start time - The default depends on the type of action - For recorder_search, the default is command end_time provided while issuing the command - For eoc_search, the default is 7 days later than command issue time
Example : "2017-01-08T00:00:00.000Z"

string

limit
optional

Specifies the maximum number of events to return. If any events are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 100
Example : 100

integer (int32)

max_slice
optional

Specifies the total number of slices being fetched. To enable sliced query request, set 2 <= max_slice < 20.

Default = 0 Minimum = 2 Maximum = 20
Example : 10

integer (int32)

next
optional

Used for events cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "ZXhhbXBsZSBuZXh0IHN0cmluZw=="

string

query
optional

Specifies a search query as Lucene query string.

The search query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. - A Single Term is a single word such as "test" or "hello" - A Phrase is a group of words surrounded by double quotes such as "hello dolly"

When creating a search query string, consider the following: - You can search any field by specifying the field name followed by a colon ":" and then the term you are looking for - Escape special characters that are part of the query syntax. To escape a special character use the \ before the character. The current list of special characters are + - && || ! ( ) { } [ ] ^ " ~ * ? \ : - Date value should follow ISO 8601 date stamp standard format (yyyy-MM-dd’T’HH:mm:ss.SSSXXX) - Supported Boolean operators for complex query are: AND OR + - NOT Note: Boolean operators must be ALL CAPS - Multiple terms can be combined together with Boolean operators to form a more complex query in the query clause - Use parentheses to group clauses to form sub-queries - Defaults to all events for the start_time and end_time specified in the query - The maximum length of the query string is 10240 characters
Example : "log_time:[2017-01-01T00:00:00.000Z TO 2017-01-08T00:00:00.000Z]"

string

slice_field
optional

Specify a field for slicing. The field must be one of log_time, time, or empty "".

Default = ""
Example : "log_time"

string

slice_id
optional

The ID of the slice being requested. 0 <= slice_id < max_slice.

Default = 0 Minimum = 0 Maximum = max_slice-1
Example : 9

integer (int32)

start_time
optional

Specifies the beginning of the search time frame.

When specifying start_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - The query operation on start_time is inclusive. Example: start_time >= '2017-01-01T00:00:00.000Z' - The start time must be less than the end time - The default depends on the type of action - For recorder_search, the default is command start_time provided while issuing the command - For eoc_search, the default is command issue time
Example : "2017-01-01T00:00:00.000Z"

string

verb
required

Request verb. Currently, only query verb is supported.
Example : "query"

string

3.19. CommandResultResponse

Command Result Response object containing the list of events.

Name Description Schema

next
optional

The token used for cursoring.

For details, refer to ResultSet request examples.

string

result
optional

Array of events.

When consuming events, consider the following: - For recorder_search, the applicable events are 8000 to 8009 - For eoc_search, the applicable events are 8080 to 8089

< Event > array

total
optional

The total number of events in the overall query.

integer (int32)

3.20. CommandStatus

Status of specific target.

Name Description Schema

error_code
required

This represents error codes for a specific target. Possible values: -1 = Error 0 = Success 1 = In progress 3 = Cancelled 4 = Cancel requested 201 = Endpoint is not isolated yet 301 = File was not found on endpoint 5001 = Endpoint’s managing SEPM is unknown 5002 = Failed to connect to SEPM (Check SEPM controller settings in ATP Manager for cause) 5003 = Failed to locate endpoint on SEPM 5004 = SEPM controller configuration for endpoint is missing 5005 = Endpoint has been isolated already 5006 = There is no Quarantine Firewall Policy configured at corresponding SEPM group 5007 = This command is not supported for the version of SEP/SEPM that you currently running 6000 = Search completed on the endpoint with results found 6001 = Search completed on the endpoint with no results found 6002 = Search completed on the endpoint with results but only partial results are uploaded due to ATP data limits 6100 = The endpoint failed to initialize search module 6101 = The endpoint was performing LiveUpdate updates 6102 = The endpoint was being shutdown 6103 = The endpoint failed to upload complete search results to ATP 6104 = The endpoint ran out of memory while executing search 6105 = The endpoint doesn’t recognize one of the search arguments 6106 = The endpoint doesn’t recognize one of the search path 6107 = The endpoint search module was not ready 6108 = The endpoint encountered a revision level in a security object that it does not recognize 6109 = The endpoint failed to execute the search 6110 = The endpoint encountered an unexpected error while executing search 6111 = The Lucene query expression is not supported by the endpoint 6112 = The endpoint rejected the search command 6113 = Endpoint data recorder is not configured on the endpoint 6114 = The endpoint is not yet enrolled with ATP for endpoint data recording feature (either endpoint doesn’t support the feature or it is disabled from ATP Manager) 6115 = Failed to provision the command for the endpoint 6116 = Failed to notify the endpoint 7000 = Cannot download file from SEPM 7001 = CSIDL path substitution for file failed 7002 = File not found at the specified path on Endpoint 7003 = File found at the specified path on Endpoint but there’s a hash mismatch 7004 = File type not supported 7005 = File too large in size 7006 = File upload from Endpoint to SEPM failed 7007 = File access denied

integer (int32)

message
required

Message explaining error code. Possible values: Error (-1) Success (0) In progress (1) Cancelled (3) Cancel requested (4) Endpoint is not isolated yet (201) File was not found on endpoint (301) Endpoint’s managing SEPM is unknown (5001) Failed to connect to SEPM (5002) Failed to locate endpoint on SEPM (5003) SEPM controller configuration for endpoint is missing (5004) Endpoint has been isolated already (5005) There is no Quarantine Firewall Policy configured at corresponding SEPM group (5006) This command is not supported for the version of SEP/SEPM that you currently running (5007) Search completed on the endpoint with results found (6000) Search completed on the endpoint with no results found (6001) Search completed on the endpoint with results but only partial results are uploaded due to ATP data limits (6002) The endpoint failed to initialize search module (6100) The endpoint was performing LiveUpdate updates (6101) The endpoint was being shutdown (6102) The endpoint failed to upload complete search results to ATP (6103) The endpoint ran out of memory while executing search (6104) The endpoint doesn’t recognize one of the search arguments (6105) The endpoint doesn’t recognize one of the search path (6106) The endpoint search module was not ready (6107) The endpoint encountered a revision level in a security object that it does not recognize (6108) The endpoint failed to execute the search (6109) The endpoint encountered an unexpected error while executing search (6110) The Lucene query expression is not supported by the endpoint (6111) The endpoint rejected the search command (6112) Endpoint data recorder is not configured on the endpoint (6113) The endpoint is not yet enrolled with ATP for endpoint data recording feature (6114) Failed to provision the command for the endpoint (6115) Failed to notify the endpoint (6116) Cannot download file from SEPM (7000) CSIDL path substitution for file failed (7001) File not found at the specified path on Endpoint (7002) File found at the specified path on Endpoint but there’s a hash mismatch (7003) File type not supported (7004) File too large in size (7005) File upload from Endpoint to SEPM failed (7006) File access denied (7007)

string

state
required

This represents the command status for specific target. Possible values: 0 = Completed 1 = In progress 2 = Error 3 = Cancelled 4 = Cancel requested

integer (int32)

target
required

The target field is specific to the command action.

For isolate_endpoint or rejoin_endpoint, the field is a string representing the device ID of the target computer.

For recorder_search or eoc_search, the field is a string representing the device ID of the target computer. If you need to match the device_uid to the original target criteria provided when issuing the command, either lookup the device_uids and issue the command to those ids or match the device_uids returned here with the original target criteria using other available APIs.

For delete_endpoint_file or get_endpoint_file, the field is a FileEndpointPair that contains the SHA256 value of the file to delete and the corresponding device ID of the target computer.

object

3.21. CommandStatusQueryRequestBody

Request body for command status query.

Name Description Schema

limit
optional

Specifies the maximum number of CommandStatus objects to return. If any command statuses are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 100
Example : 100

integer (int32)

next
optional

Used for command status cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "ZXhhbXBsZSBuZXh0IHN0cmluZw=="

string

verb
required

Request verb. Currently, only query verb is supported.
Example : "query"

string

3.22. CommandStatusResponse

Status of each target specified in the command.

Name Description Schema

next
required

The token used for cursoring.

For details, refer to ResultSet request examples.

string

state
required

Command state

enum ("completed", "initializing", "in_progress", "error", "cancel_requested", "cancelled")

status
optional

List representing status of each target.

< CommandStatus > array

total
required

The total number of status elements present in this query.

integer

3.23. Data

Details of the system activities.

Name Description Schema

atp_service
optional

ATPService sub-type.

Applicable events : 1000

ATPService

search_config
optional

SearchConfig sub-type.

Applicable events : 1

SearchConfig

sepm_server
optional

SEPMServer sub-type.

Applicable events : 1000

SEPMServer

3.24. DeleteFileCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("delete_endpoint_file")

end_time
optional
read-only

Should not be sent as part of delete_endpoint_file command body.

string

query
optional
read-only

Should not be sent as part of delete_endpoint_file command body.

string

start_time
optional
read-only

Should not be sent as part of delete_endpoint_file command body.

string

targets
required

List of pair of SHA256 value of the file to delete and the corresponding device ID.

< FileEndpointPair > array

3.25. Directory

Directory details of the event.

Name Description Schema

name
optional

The name of directory.

Applicable events : 8004, 8084

string

normalized_path
optional

The CSIDL normalized path name; Windows Only

Applicable events : 8004, 8084
Example : "CSIDL_SYSTEM\\svchost.exe"

string

path
optional

The full path to the object.

Applicable events : 8004, 8084
Example : "c:\\windows\\system32\\svchost.exe"

string

3.26. DnsTarget

Polymorphism : Composition

Name Description Schema

domain_name
required

The domain name for which a DNS query was made.
Example : "www.shample.ru"

string

type
required

The requested DNS record type.
Example : "A"

string

3.27. DomainEntity

Object of ATP domain entities. A domain entity object is uniquely identified by the data_source_url_domain field.

Note
Except first_seen and data_source_url_domain, all other values gets replaced with the last values seen.
Name Description Schema

data_source_url
optional

Last URL accessed on this domain.
Example : "http://www.skyscan.com/shample/shample.exe"

string

data_source_url_domain
required

The name of the domain.
Example : "skyscan.com"

string

disposition
optional

Domain disposition: 0 = healthy/good 1 = unknown 2 = suspicious 3 = bad

integer (int32)

domain_threat_data
optional

DomainThreatData sub type.

DomainThreatData

external_ip
optional

The IP address of the device/machine that accepted the connection.
Example : "85.158.136.166"

string

first_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this entity.
Example : "2018-01-30T04:13:10.669Z"

string

last_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this entity.
Example : "2018-01-30T04:13:10.669Z"

string

location
optional

Location sub type.

Location

registration
optional

Registration sub type.

Registration

type
required

The domain entity type.

Currently only external_domain_latest is supported.

enum ("external_domain_latest")

3.28. DomainEntityQueryResponse

Response object containing the list of domain entity objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of domain entity objects.

< DomainEntity > array

total
required

Count of domain entity objects matching the query.

integer (int32)

3.29. DomainFileAssociation

Object that represents an association between a domain entity and a file entity. A domain is uniquely identified by data_source_url_domain and a file is uniquely identified by sha2.

Name Description Schema

data_source_url
optional

The URL that was accessed.
Example : "http://www.westfallave.com/insight/cloudcar.exe"

string

data_source_url_domain
required

Domain name of the accessed URL.
Example : "westfallave.com"

string

device_ip
optional

The IPv6 or IPv4 address of the endpoint when this association was last updated.
Example : "10.212.24.159"

string

device_name
optional

The host name or, if unavailable, the IP address of the endpoint when this association was last updated.
Example : "170915-000020"

string

device_uid
optional

Unique ID of the endpoint that downloaded the file from the URL.
Example : "04cfc04b-5c7a-4aa8-b95b-79be23f768f4"

string

first_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this association.
Example : "2018-01-30T04:13:10.669Z"

string

last_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this association.
Example : "2018-01-30T04:13:10.669Z"

string

name
optional

The file name of the downloaded file. This attribute doesn’t include the path of the file.
Example : "cloudcar[2].exe"

string

sha2
required

The SHA256 checksum of the file (hex string) that was downloaded from the URL.
Example : "3559378c933cdd434af2083f7535460843d2462033de74ec7c70dbe5f70124f5"

string

signature_company_name
optional

The signer company name of the downloaded file.
Example : "Microsoft Windows"

string

3.30. DomainFileAssociationsResponse

Response object containing the list of domain file association objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/associations/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of domain file association objects.

< DomainFileAssociation > array

total
required

Count of domain file association objects matching the query.

integer (int32)

3.31. DomainInstance

Object of ATP domain instances.

Name Description Schema

data_source_url
optional

Last URL accessed on this domain.
Example : "http://www.skyscan.com/shample/shample.exe"

string

data_source_url_domain
required

The name of the domain.
Example : "skyscan.com"

string

disposition
optional

Domain disposition: 0 = healthy/good 1 = unknown 2 = suspicious 3 = bad

integer (int32)

external_ip
optional

The IP address (IPv4 or IPv6) of the device/machine that accepted the connection.
Example : "85.158.136.166"

string

first_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this instance.
Example : "2018-01-30T04:13:10.669Z"

string

last_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this instance.
Example : "2018-01-30T04:13:10.669Z"

string

3.32. DomainInstanceQueryResponse

Response object containing the list of domain instances.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of domain instances.

< DomainInstance > array

total
required

Count of domain instances matching the query.

integer (int32)

3.33. DomainThreatData

Behavior details for the domain (source: DeepSight).

Name Description Schema

behavior
optional

The domain’s behavior as observed by DeepSight. Behaviors include: - Attacks - CnC (Command and Control) - Fraud - Malware - Phishing

string

confidence
optional

Symantec’s confidence on whether the listing is correct or not. Values range from 1 - 5, with 5 being the highest confidence in listing.

integer (int32)

hostility
optional

The hostility score is calculated based on the frequency of activity. Values range from 1 - 5, with 5 being the most malicious.

integer (int32)

ips_domain_hosted
optional

Array of IPs and the details associated with this domain (source: DeepSight).

< IpInfo > array

reputation_band
optional

The domain’s reputation score. Values range from 1 - 10, with 10 being the worst reputation.

integer (int32)

urls
optional

Array of URLs involved in the behavior.

< string > array

3.34. EndpointDomainAssociation

Object that represents an association between an endpoint entity and a domain entity. An endpoint is uniquely identified by device_uid and a domain is uniquely identified by data_source_url_domain.

Name Description Schema

data_source_url
optional

The URL that was accessed.
Example : "http://www.westfallave.com/insight/cloudcar.exe"

string

data_source_url_domain
required

Domain name of the accessed URL.
Example : "westfallave.com"

string

device_ip
optional

The IPv6 or IPv4 address of the endpoint when this association was last updated.
Example : "10.212.24.159"

string

device_name
optional

The host name or, if unavailable, the IP address of the endpoint when this association was last updated.
Example : "170915-000020"

string

device_uid
required

Unique ID of the endpoint that accessed this URL.
Example : "04cfc04b-5c7a-4aa8-b95b-79be23f768f4"

string

first_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this association.
Example : "2018-01-30T04:13:10.669Z"

string

last_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this association.
Example : "2018-01-30T04:13:10.669Z"

string

3.35. EndpointDomainAssociationsResponse

Response object containing the list of endpoint domain association objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/associations/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of endpoint domain association objects.

< EndpointDomainAssociation > array

total
required

Count of endpoint domain association objects matching the query.

integer (int32)

3.36. EndpointEntity

Object of ATP endpoint entities. An endpoint entity object is uniquely identified by the device_uid field.

Note
Except first_seen and device_uid, all other values gets replaced with the last values seen.
Name Description Schema

agent_version
optional

The version of Symantec Endpoint Protection that this endpoint is running.
Example : "14.0.3542.1000"

string

atp_endpoint_action_idx
optional

Current status of an ATP-initiated action on this endpoint. Possible values are: 0 = unknown 1 = isolate 2 = rejoin 3 = isolate in progress 4 = rejoin in progress 5 = isolate failed 6 = rejoin failed

integer (int32)

device_ip
optional

The IP address of the endpoint. IPv4 or IPv6 format.
Example : "192.168.0.250"

string

device_name
optional

The host name or, if unavailable, the IP address of the endpoint.
Example : "WIN-CRNK1KQJBC0"

string

device_uid
required

Unique ID of the endpoint.
Example : "12b1d2ce-dddb-4bcc-990e-28f44cf8ddcb"

string

disposition_endpoint
optional

Endpoint disposition: 0 = healthy/good 1 = unknown 2 = suspicious 3 = bad
Example : 0

integer (int32)

domain_or_workgroup
optional

Domain or workgroup name depending on the configuration.
Example : "WORKGROUP"

string

enrollment_status
optional

The status of an endpoint in the enrollment process with ATP.

enum ("unknown", "init_pending", "in_progress", "authentication_pending", "enrolled", "not_applicable", "unenrolled")

first_seen
required

The date and time (in ISO 8601 format) that specifies the creation time of this entity.
Example : "2018-01-30T04:13:10.669Z"

string

ip_addresses
optional

Array of all the IP addresses (IPv4 or IPv6) associated with the endpoint. Example : ["192.168.0.250"]

< string > array

last_seen
required

The date and time (in ISO 8601 format) that specifies last updated time of this entity.
Example : "2018-01-30T04:13:10.669Z"

string

mac_addresses
optional

Array of all the MAC addresses associated with the endpoint. Example : ["00-0C-29-4D-E3-FC"]

< string > array

managed_sepm_ip
optional

IP Address (IPv4 or IPv6) of SEPM.
Example : "192.168.0.250"

string

managed_sepm_version
optional

Version of SEPM.
Example : "14.0.3542.1000"

string

operating_system
optional

OperatingSystem subtype.

OperatingSystem

sep_group_summary
optional

SepGroupSummary subtype.

SepGroupSummary

type
required

The endpoint entity type.

Currently only endpoint_latest is supported.

enum ("endpoint_latest")

user_name
optional

The name of the user that originated or caused the event.
Example : "Administrator"

string

3.37. EndpointEntityQueryResponse

Response object containing the list of endpoint entity objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of endpoint entity objects.

< EndpointEntity > array

total
required

Count of endpoint entity objects matching the query.

integer (int32)

3.38. EndpointFileAssociation

Object that represents an association between an endpoint entity and a file entity. An endpoint is uniquely identified by device_uid and a file is uniquely identified by sha2.

Name Description Schema

device_ip
optional

The IPv6 or IPv4 address of the endpoint when this association was last updated.
Example : "10.212.24.159"

string

device_name
optional

The host name or, if unavailable, the IP address of the endpoint when this association was last updated.
Example : "170915-000020"

string

device_uid
required

Unique ID of the endpoint that has this file.
Example : "04cfc04b-5c7a-4aa8-b95b-79be23f768f4"

string

first_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this association.
Example : "2018-02-04T09:00:00.577Z"

string

folder
optional

The folder where the file resides. This attribute doesn’t include the name of the file.
Example : "c:\\windows\\system32"

string

last_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this association.
Example : "2018-02-04T09:00:01.778Z"

string

name
optional

The name of the file. This attribute doesn’t include the path of the file.
Example : "sc.exe"

string

sha2
required

The SHA256 checksum of the file (hex string).
Example : "eaab690ebd8ddf9ae452de1bc03b73c8154264dbd7a292334733b47a668ebf31"

string

3.39. EndpointFileAssociationsResponse

Response object containing the list of endpoint file association objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/associations/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of endpoint file association objects.

< EndpointFileAssociation > array

total
required

Count of endpoint file association objects matching the query.

integer (int32)

3.40. EndpointInstance

Object of ATP endpoint instances.

Name Description Schema

device_ip
optional

The IP address of the endpoint. IPv4 or IPv6 format.
Example : "192.168.0.250"

string

device_name
optional

The host name or, if unavailable, the IP address of the endpoint.
Example : "WIN-CRNK1KQJBC0"

string

device_uid
required

Unique ID of the endpoint.
Example : "12b1d2ce-dddb-4bcc-990e-28f44cf8ddcb"

string

domain_or_workgroup
optional

Domain or workgroup name depending on the configuration.
Example : "WORKGROUP"

string

ip_addresses
optional

Array of all the IP addresses (IPv4 or IPv6) associated with the endpoint. Example : ["192.168.0.250"]

< string > array

time
optional

The timestamp (in ISO 8601 format) that specifies the creation or last update time of this instance. This is the creation time when there were no updates. Otherwise, it is the time of the last update.
Example : "2018-01-15T14:05:57.127Z"

string

user_name
optional

The name of the user that originated or caused the event.
Example : "Administrator"

string

3.41. EndpointInstanceQueryResponse

Response object containing the list of endpoint instances.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of endpoint instances.

< EndpointInstance > array

total
required

Count of endpoint instances matching the query.

integer (int32)

3.42. EnrichedData

Enriched data of the endpoint data recorded events.

Name Description Schema

category_id
optional

The possible values of supported category_id.

0 = All Events 1 = Suspicious N-Gram 2 = Process Launch 3 = Process Termination 100 = Suspicious Protocol-Port Usage By System Processes 102 = Suspicious PowerShell commands

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

integer (int32)

category_name
optional

The IntelliFilter rules fall into the following categories:

System File Launched Or Loaded From Unexpected Location = 8001, 8002 Suspicious PowerShell Script Executed = 8001 Suspicious N-gram = 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009 Process Termination = 8001 Process Launch = 8001 Load Point Modification = 8005, 8006 File with Double Exe Extension (.jpg.exe) = 8003 Attempt to Change to Windows Event Logs or Registry Settings = 8005, 8006 Suspicious Protocol-Port Usage By System Processes = 8007 All events = 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

string

rule_name
optional

The name of the IntelliFilter rule that observes all of the endpoint data recorded events on the client.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

string

suspicion_score
optional

Score that determines the suspiciousness of the action captured in the event. 1. Very Low : 1-25 (Informational) 2. Low : 26-50 (Suspicious) 3. Moderate : 51-75 (Suspicious) 4. Severe : 76-87 (Malicious) 5. Very Severe : 88-100 (Malicious)

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

integer (int32)

3.43. EntityQueryRequest

Entity Query object.

Name Description Schema

keep_alive_secs
optional

This value determines the length of time in seconds that the query results will be cached on the server. Each API HTTP request resets the cache countdown to the specified value.

See example for proper usage of this value.

Minimum = 30 sec Maximum = 300 sec Default = 60 sec
Example : 60

integer (int32)

limit
optional

Specifies the maximum number of entities to return. If any entities are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 100
Example : 100

integer (int32)

next
optional

Used for entities cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "ZXhhbXBsZSBlbnRpdGllcyBuZXh0IHN0cmluZyA="

string

query
optional

Specifies a search query as Lucene query string.

The search query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. - A Single Term is a single word such as "test" or "hello" - A Phrase is a group of words surrounded by double quotes such as "hello dolly"

When creating a search query string, consider the following: - You can search any field by specifying the field name followed by a colon ":" and then the term you are looking for - Escape special characters that are part of the query syntax. To escape a special character use the \ before the character. The current list of special characters are + - && || ! ( ) { } [ ] ^ " ~ * ? \ : - Date value should follow ISO 8601 date stamp standard format (yyyy-MM-dd’T’HH:mm:ss.SSSXXX) - Supported Boolean operators for complex query are: AND OR + - NOT Note: Boolean operators must be ALL CAPS - Multiple terms can be combined together with Boolean operators to form a more complex query in the query clause - Use parentheses to group clauses to form sub-queries - By default, matches all records - The maximum length of the query string is 10240 characters
Example : "mac_addresses:00-0C-29-4D-E3-FC"

string

verb
required

Request verb. Currently, only query verb is supported.
Example : "query"

string

3.44. EntityQueryResponse

Response object containing the list of entity objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

Custom List having entity objects of types EndpointEntity, FileEntity, DomainEntity.

< object > array

total
required

Count of entity objects matching the query.

integer (int32)

3.45. EocSearchCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("eoc_search")

end_time
optional
read-only

Should not be sent as part of eoc_search command body.

string

query
required

A Lucene query expression of supported EOC tokens, operators.

string

start_time
optional
read-only

Should not be sent as part of eoc_search command body.

string

targets
required

A combination of sepm_groups, ipv4_addresses, hostnames and device_uids.

< SearchScope > array

3.46. Event

Object of ATP Events.

An Event object is uniquely identified by the type_id field. The optional fields are relevant only if a type_id is in the list of "Applicable events".

Name Description Schema

action_id
optional

Action taken with respect to the underlying cause of the event. Possible values are: 0 = BLOCK 1 = MONITOR

Applicable events : 4112, 4113, 4115, 4116, 4117, 4118, 4353

integer (int32)

actual_action
optional

This is the string version of the action taken on the risk (in actual_action_idx).

Applicable events : 4123

string

actual_action_idx
optional

This is the ID of action taken on the risk. Possible values are: -1 = Action invalid 0 = Not applicable 1 = Quarantined 2 = Renamed 3 = Deleted 4 = Left alone 5 = Cleaned 6 = Cleaned or macros deleted 7 = Saved 9 = Restored 10 = Renamed back 11 = Undone 12 = Bad 13 = Backed up 14 = Pending repair 15 = Partially repaired 16 = Process termination pending restart 17 = Excluded 18 = Restart processing 19 = Cleaned by deletion 20 = Access denied 21 = Process terminated 22 = No repair available 23 = All actions failed 24 = Threat blocked - Power Eraser recommended for repair 25 = No repair available - Power Eraser recommended for repair 26 = Left alone by Admin 98 = Suspicious 99 = Remediation in progress 100 = Intrusion Prevention block 101 = Network Threat Protection violation 102 = Allowed by user 110 = Detected using commercial application list 111 = Forced detection using file name 1000 = Forced detection using file hash 200 = Attachment stripped 500 = Not applicable

Applicable events : 4123

integer (int32)

agent_version
optional

The version of the client software.

Applicable events : 4123
Example : "12.1.6306.6100"

string

app_name
optional

The full path of the application involved. It may be empty if an unknown application is involved or if no application is involved. For example, the ping of death denial-of-service attack doesn’t have an AppName because it attacks the operating system itself.

Applicable events : 4124

string

atp_node_role
optional

The role of the ATP appliance that generated the event. Possible values are: 0 = Pre-Bootstrap 1 = Network Scanner 2 = Management 3 = Standalone Network 4 = Standalone Endpoint 5 = All in One

Applicable events : 1, 1000
Example : 5

integer (int32)

attacks
optional

Attack properties according to the MITRE Attack system.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

< Attack > array

av
optional

Av sub-type.

Applicable events : 4102

Av

bash
optional

BASH sub-type. The BASH fields provides the required data for the SONAR feature.

Applicable events : 4100

BASH

categories
optional

A list of categories an intrusion event may belong to. The list includes, but is not limited to, the following:

Adware, Attack, Audit, Auto-rooter, Backdoor, Bot, Buffer Overflow, Covert Channel, DDOS, Deception, Diagnostic, Dialer, DOS, Failed Access, Flood, Hack Tool, Hoax, Instant Messaging, Keylogger, Malcode, Mass-mailer, Non-malicious, Nuisance, Other Security Risk, Peer to Peer, Potentially Unwanted Application (PUA), Probe, Protocol Anomaly, Reconnaissance, Rootkit, Scanner, Security Risk, Spyware, Suspicious Event, Trackware, Trojan, Virus, Weak Authentication, Worm

Applicable events : 4098, 4113, 4124

< string > array

count
optional

Event aggregation count.

Applicable events : 4098, 4099, 4100, 4102, 4112, 4113, 4123, 4124, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

integer (int32)

country
optional

Originating country of the attack. Possible values are in the form of two-letter country codes defined in ISO 3166-1. Applicable events : 4125
Example : "US"

string

data
optional

Data sub-type.

Applicable events : 1, 1000

Data

data_direction
optional

The direction of the data source. Possible values are: 0 = Unknown. Traffic direction could not be determined. 1 = Inbound. Traffic flow from WAN to LAN. 2 = Outbound. Traffic flow from LAN to WAN. 4 = Pass-through. Network traffic passed through like a proxy.

Applicable events : 4096, 4098, 4100, 8007

integer (int32)

data_source_ip
optional

The source IP address that the file came from (either IPv4 or IPv6).

Applicable events : 4096, 4099

string

data_source_url
optional

The URL that the traffic came from.

Applicable events : 4096, 4098, 4099, 4100, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4125, 4353
Example : "www.eicar.org/download/eicar_com.zip"

string

data_source_url_domain
optional

The domain from which the file was downloaded. The domain is extracted from the URL for the query performance.

Applicable events : 4096, 4098, 4099, 4100, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353
Example : "symantec.com"

string

data_source_url_referer
optional

The referer URL used in the download.

Applicable events : 4096, 4098, 4099, 4112, 4113, 4115, 4116, 4117, 4118, 4353
Example : "http://www.symantec.com/"

string

deepsight_domain
optional

The domain reported and listed in Deepsight reputation.

Applicable events : 4096, 4098, 4100, 4112, 4113, 4115, 4116, 4117, 4118, 4124, 4125, 4353

string

detection_method
optional

The detection technology used to detect the conviction. Possible values are: - Signatures - Skeptic Heuristics - Skeptic Signatures - Link Following - Cynic Applicable events : 4125

string

device_cap
optional

Name or caption of ATP appliance that generated the event.

Applicable events : 1, 1000
Example : "ATP-3.1.0-664"

string

device_domain
optional

The domain where device resides. Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090
Example : "internal.somecompany.com"

string

device_end_time
optional

The end time of an event (in format yyyy-MM-dd’T’HH:mm:ss.SSSZ). This is used with the aggregation count field.

Applicable events : 4123, 4124, 8007

string

device_ip
optional

The IPv6 or IPv4 address of the device that originated the event.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

string

device_name
optional

The device name (i.e., the name of the endpoint or appliance associated with an event).

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

string

device_os_name
optional

The operating system running on the device_type that originated the event. The possible values include, but are not limited to, the following:

Windows, Mac OSX, IOS, Android

Applicable events : 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090
Example : "Windows, Mac OSX, iOS, Android"

string

device_os_ver
optional

The version of the operating system that is running on the device_type that originated the event. The possible values include, but are not limited to, the following:

For device_os_name = "Windows": 7, 8.0, 8.1 For device_os_name = "Mac OSX": 10.4, 10.7

Applicable events : 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353
Example : "7, 10.4, 10.7"

string

device_time
optional

The timestamp (in ISO 8601 format) that specifies the time at which the event occurred.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

string

device_type
optional

The type of the device that originated the event.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353
Example : "unknown, server, desktop, laptop, tablet, mobile, virtual, browser"

string

device_uid
optional

Unique ID of the device that originated the event.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090
Example : "7c056576-860b-4eb9-b49c-3c349edb733f"

string

direction
optional

Indication direction of the email. Possible values are: O = Outbound I = Inbound

Applicable events : 4125

enum ("O", "I")

directory
optional

Directory sub-type.

Applicable events : 8004, 8084

Directory

domain_name
optional

The domain name of the client computer.

Applicable events : 4123, 4124

string

dynacat
optional

The subcategory for the risk threat. Possible values: 0 = Viral 1 = Non-Viral malicious 2 = Malicious 3 = Heuristic 4 = Security Risk 5 = Hack Tool 6 = Spyware 7 = Trackware 8 = Dialer 9 = Remote Access 10 = Adware 11 = Jokeware 12 = Client compliancy 13 = Generic Load Point 14 = Application Heuristic 15 = Cookie 16 = Experimental Heuristic 17 = Parental Control 18 = Insight Network Threat Applicable events : 4123

integer (int32)

email_action
optional

The action executed on the email. Possible values are: - blocked - delivered - released

Applicable events : 4125

enum ("blocked", "delivered", "released")

email_received_date
optional

The time when the mail transfer agent received the email. The format is: yyyy-MM-dd’T’HH:mm:ss.SSSZ

Applicable events : 4125
Example : "2015-11-04T06:47:00"

string

email_subject
optional

Email subject.

Applicable events : 4125

string

enriched_data
optional

Enriched_Data sub-type.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

EnrichedData

event_actor
optional

Process sub-type.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

Process

event_desc
optional

A description of the event. Usually, the first line of the description is treated as summary.

Applicable events : 4124

string

event_id
optional

The event ID as reported by Symantec Endpoint Protection security log. Possible values for corresponding events are:

Compliance events: 209 = Host integrity failed 210 = Host integrity passed 221 = Host integrity failed but it was reported as PASS 237 = Host integrity custom log entry

Firewall and Intrusion Prevention System events: 207 = Active response 211 = Active response disengaged 219 = Active response canceled 205 = Executable file changed 216 = Executable file change detected 217 = Executable file change accepted 218 = Executable file change denied 220 = Application hijacking 201 = Invalid traffic by rule 202 = Port scan 203 = Denial-of-service attack 204 = Trojan horse 206 = Intrusion detected 208 = MAC spoofing 249 = Browser protection

Application and Device control: 238 = Device control disabled device 239 = Buffer overflow event 240 = Software protection has thrown an exception

Host Intrusion Prevention Events: 250 = Memory exploit mitigation blocked event 251 = Memory exploit mitigation allowed event

Applicable events : 4124

integer (int32)

event_uuid
optional

The unique ID of the originating event for this related event.

Note: Use this as uuid along with device_time as start_time to query for the originating event.

Applicable events : All events associated with an incident

string

external_ip
optional

The IP address of the device/machine that accepted the connection.

Applicable events : 4096, 4098, 4099, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8007

string

external_port
optional

The port number identified as the target port in traffic sent to the target device.

Applicable events : 4098, 4112, 4113, 4115, 4116, 4117, 4118, 4353

integer (int32)

feature_name
optional

The name of the feature that originated the event.

Applicable events : 1, 1000
Example : "Search"

string

file
optional

File sub-type.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4115, 4116, 4117, 4118, 4123, 4125, 4353, 8002, 8003, 8082, 8083

File

hid_level
optional

The cumulative risk rating of the threat as defined by the Foresight policy. Possible values: 0 = Not Set 100 = Bad 200 = Somewhat Bad 300 = Neutral 400 = Somewhat Untrusted 500 = Untrusted

Applicable events : 4123

integer (int32)

host_name
optional

The host name of the client computer.

Applicable events : 4123, 4124

string

id
optional

The event identifier. 1 = Exists 2 = Partial

Applicable events : 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

integer (int32)

incident
optional

The unique ID of the incident that is related to this event.

Applicable events : All events associated with an incident

string

infected
optional

Indicates whether the client computer is infected.

Applicable events : 4098
Default : false

boolean

internal_hostname
optional

The host name of the internal device/machine for the connection.

Applicable events : 4112, 4113, 4115, 4116, 4117, 4118, 4353

string

internal_ip
optional

The IP address of the internal device/machine for the connection.

Applicable events : 4098, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4353, 8007

string

internal_port
optional

The port number identified as the source port in traffic sent to the target device.

Applicable events : 4098, 4112, 4113, 4115, 4116, 4117, 4118, 4353

integer (int32)

intrusion
optional

Intrusion sub-type.

Applicable events : 4098

Intrusion

intrusion_url
optional

The URL from where a malicious script was loaded.

Applicable events : 4124
Example : "www.eicar.org/download/eicar.com.txt"

string

is_targeted
optional

Flag indicating if the attack was targeted. Applicable events : 4125
Default : false

boolean

kernel
optional

Kernel sub-type.

Applicable events : 8009, 8089

Kernel

link_following
optional

LinkFollowing sub-type.

Applicable events : 4125

LinkFollowing

local_host_mac
optional

The MAC address of the local computer.

Applicable events : 4123, 4124

string

log_name
optional

The index of the event.

Note: This is for informational purpose and cannot be used as a filter. Use time as start_time to query for events.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090
Example : "epmp_events-2015-11-05"

string

log_time
optional

The time the event was logged.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090
Example : "2018-04-23T08:50:37.785Z"

string

message
optional

Human-readable (possibly multi-line) event message or description of the event.

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353

string

message_id
optional

The unique ID of the email message.

Applicable events : 4125
Example : "FE7B8CBD-0741-40DB-BF6E-4D3C633B2A93"

string

network_protocol
optional

Network protocol as reported by SEP. Possible values are: 1 = Other 2 = TCP 3 = UDP 4 = ICMP

Applicable events : 4124

integer (int32)

network_scanner_type
optional

The type of network scanner that detected the event. Possible values are: 0 = ATP-N Scanner (default) 1 = WSS .cloud Scanner

Applicable events : 4112, 4113, 4115, 4116, 4117, 4118, 4353

integer (int32)

no_of_viruses
optional

The number of events for the aggregated event record. This number can be due to client-side aggregation, server-side compression, or both.

Applicable events : 4123

integer (int32)

operation
optional

The OS operation that initiated the event; listed below are the operations:

For type_id 8000 - Session : 1: LOGON 2: LOGOFF For type_id 8001 - Process : 1: LAUNCH 2: TERMINATE 3: OPEN 4: INJECTION For type_id 8002 - Module : 1: LOAD 2: UNLOAD For type_id 8003 - File and type_id 8004 - Directory : 1: CREATE 2: DELETE 3: OPEN 4: RENAME 5: MODIFY 6: SET_ATTRIBUTES 7: SET_SECURITY 8: GET_ATTRIBUTES 9: GET_SECURITY 10: ENCRYPT 11: DECRYPT For type_id 8005 - Reg Key : 1: CREATE_KEY 2: DELETE_KEY 3: OPEN_KEY 4: RENAME_KEY 5: SET_KEY_SECURITY_DESCRIPTOR 6: RESTORE_KEY For type_id 8006 - Reg Value : 1: GET_VALUE 2: SET_VALUE 3: DELETE_VALUE For type_id 8007 - Network : 1: CONNECT 2: DISCONNECT For type_id 8009 - Kernel : 1: CREATE 2: READ 3: DELETE

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

integer (int32)

orig_message_header_id
optional

The message header ID.

Applicable events : 4125
Example : "208158"

string

parent_file_sha2
optional

The SHA256 of the parent file.

Applicable events : 4096

string

process
optional

Process sub-type.

Applicable events : 8001, 8081

Process

product_name
optional

The name of the product that originated the event.

Applicable events : 1, 1000
Example : "Advanced Threat Protection"

string

product_ver
optional

The version of the product that originated the event.

Applicable events : 1, 1000
Example : "3.1.0-664"

string

reason
optional

This field is overloaded and has following possible interpretations (depending on the corresponding type_id).

For type_id 4118, it specifies the Blacklist hash function that was used to identify the file. This field has following possible values: 0 = BY_FILE_BLACKLIST_SHA2 1 = BY_FILE_BLACKLIST_MD5

For type_id 4112, it specifies the Blacklist criteria that identify the traffic. This field has following possible values: 0 = BY_SOURCE_IP 1 = BY_DEST_IP 2 = BY_DEST_URL

Applicable events : 4118, 4112

integer (int32)

receivers
optional

Email receivers sub-type.

Applicable events : 4125

< Receivers > array

reg_key
optional

Reg_Key sub-type.

Applicable events : 8005, 8085

RegKey

reg_value
optional

Reg_Value sub-type.

Applicable events : 8006, 8086

RegValue

remediation
optional

Description how to fix the issue, if applicable.

Applicable events : 1000
Example : "Enter valid connection settings for SEPM server [SEPM_DB→192.168.0.10:8081] for Symantec Endpoint Protection Correlation to work properly."

string

remote_host_mac
optional

The MAC address of the remote computer.

Applicable events : 4124

string

request_source
optional

Indicate where the hash or file request comes from. Possible values are: - user_submit - auto_response - file_inspection

Applicable events : 4117

enum ("user_submit", "auto_response", "file_inspection")

sandbox
optional

Sandbox sub-type.

Note: The Sandbox object will be sent for convictions generated by both Cynic as well as the Content Analysis Appliance for backward compatibility. Refer to the sandbox_service attribute in the event details for information on the sandboxing service that generated the event.

Applicable events : 4117

Sandbox

sandbox_service
optional

The sandboxing service used for suspicious file analysis. Possible values are: - cynic - content_analysis

Applicable events : 4117

enum ("cynic", "content_analysis")

scan
optional

Scan sub-type.

Applicable events : 4100

Scan

scan_type
optional

This is the scan type that originated the event. This field is a string with following possible values: - Scheduled Scan - Manual Scan - Real Time Scan - Integrity Shield - Definition downloader - System - Startup Scan - DefWatch - Manual Quarantine - Reboot Processing - Heuristic Scan - Power Eraser - SymELAM - EvidenceOfCompromise Scan

Applicable events : 4123

string

scanner_name
optional

The name of the ATP scanner that generated this event.

Applicable events : 4112, 4113, 4115, 4116, 4117, 4118, 4353

string

sender
optional

Email sender sub-type.

Applicable events : 4125

Sender

sep_installed
optional

Indicates whether SEP was installed when the event was generated.

Applicable events : 4096, 4098, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353
Default : false

boolean

service
optional

Service sub-type.

Applicable events : 8090

Service

session
optional

Session sub-type.

Applicable events : 8000, 8080

Session

severity
optional

The seriousness of the event. 0 indicates most serious.

For the 4124 event, possible values are as followings:

0 - 3 = Critical 4 - 7 = Major 8 - 11 = Minor 12 - 15 = Info

For the 4125 event, the following mapping is used for displaying the user-friendly description in ATP Manager UI:

0 = Critical 1 = High 2 = Medium 3 = Low Applicable events : 4124, 4125

integer (int32)

severity_id
optional

Event severity that specifies the importance of the event. Possible values are: 1 = info (default) 2 = warning 3 = minor 4 = major 5 = critical 6 = fatal

Applicable events : 1, 1000, 4096, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

integer (int32)

signature_id
optional

The NDC signature ID. To view details, go to the following URL: https://www.symantec.com/security_response/attacksignatures/detail.jsp?asid=<signature_id>; where <signature_id> is the signature_id field value.

For example, if signature_id = 28274, then the URL would be: https://www.symantec.com/security_response/attacksignatures/detail.jsp?asid=28274

Applicable events : 4098, 4113, 4124
Example : "28274"

string

signature_name
optional

The name of the signature.

Applicable events : 4098, 4113, 4124

string

source
optional

This field is overloaded and has following possible interpretations (depending on the corresponding type_id).

For type_id 4112 and 4118, identifies the entity that defined the information that ATP uses to determine whether traffic is suspicious. This field is a string with following possible values: - Symantec - Customer Supplied - Automatic - Unknown

Applicable events : 4112, 4118

string

source_ip
optional

The remote IP address (IPv4 or IPv6).

Applicable events : 4098, 8007

string

source_port
optional

The remote port numbers.

Applicable events : 4098, 8007

< integer (int32) > array

status_detail
optional

String representing the type of failure that may have occurred. The list includes, but is not limited to, the following:

service_failure service_unavailable network_error certificate_error sw_update_error internal_error authentication_error connection_error

Applicable events : 1000
Example : "connection_error"

string

status_exception
optional

Low level exception message if available.

Applicable events : 1000

string

status_id
optional

The overall success or failure of the action reported by the event. Possible values are: 0 = Unknown 1 = Success 2 = Failure

Applicable events : 1, 1000
Example : 1

integer (int32)

status_stack_trace
optional

Exception stack trace if available.

Applicable events : 1000

string

target_ip
optional

The local (victim) IP address (IPv4 or IPv6).

Applicable events : 4098, 8007

string

target_port
optional

The local (victim) port numbers.

Applicable events : 4098, 8007

< integer (int32) > array

targeted_attack_type
optional

The type of targeted attack detected. Possible values are: - New malware - Advanced malware technology - Different malware technologies with common characteristics Applicable events : 4125

string

threat
optional

Threat sub-type.

Applicable events : 4102, 4123, 4125, 4353

Threat

timezone
optional

The timezone offset in minutes. For UTC this will always be 0.

Applicable events : 1, 1000
Example : 0

integer (int32)

traffic_direction
optional

The direction of the network traffic. Possible values are: 0: Unknown 1: Inbound 2: Outbound

Applicable events : 4124

integer (int32)

type_id
required

The unique identifier for an event. The following events are supported: 1 = Application Activity 1000 = System Health 4096 = Reputation Request 4098 = Intrusion Prevention 4099 = Suspicious File 4100 = SONAR 4102 = Antivirus (endpoint detection) 4112 = Blacklist (IP/URL/Domain) 4113 = Vantage 4115 = Insight 4116 = Mobile Insight 4117 = Sandbox 4118 = Blacklist (file) 4123 = Endpoint File Detection 4124 = Endpoint (IP/URL/Domain) Detection 4125 = Email 4353 = Antivirus | Network Detection 8000 = Session events report when a user attempts a logon or logoff, successful or otherwise 8001 = Process events report when a process launches, terminates, or open another process, successful or otherwise 8002 = Module event report when a process loads or unloads a module 8003 = File events report operations on file system objects 8004 = Directory events report operations on directories 8005 = Registry events reports actions on Windows registry keys 8006 = Registry events reports actions on Windows registry values 8007 = Network events report attempted network connections - successful or otherwise 8009 = Kernel events report when an actor process creates, reads, or deletes a kernel object 8080 = EOC Session Query Result events report information about existing user sessions 8081 = EOC Process Query Result events report information about running processes 8082 = EOC Module Query Result events report information about loaded modules 8083 = EOC File Query Result events report information about files that are present on the system 8084 = EOC Directory Query Result events report information about directories that are present on the system 8085 = EOC Registry Key Query Result events report information about Windows registry keys 8086 = EOC Registry Value Query Result events report information about Windows registry values 8089 = EOC Kernel Query Result events report information about kernel resources 8090 = EOC Service Query Result events report information about running services

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090
Example : 4096

integer (int32)

user_name
optional

The user name or ID that originated or caused the event.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

string

user_uid
optional

Unique ID of the user that originated the event or the user on whose behalf the event occurred.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353

string

uuid
optional

The unique ID for this event. UUID uniquely identifies an event with a single event type (type_id).

Applicable events : 1, 1000, 4096, 4098, 4099, 4100, 4102, 4112, 4113, 4115, 4116, 4117, 4118, 4123, 4124, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081, 8082, 8083, 8084, 8085, 8086, 8089, 8090

string

virus_def
optional

The virus definition version number.

Applicable events : 4123
Example : "2015-08-17 rev. 001"

string

virus_name
optional

Name of the virus.

Applicable events : 4123

string

vlan_id
optional

Indicates the VLAN ID (between 0 and 4095) on which the endpoint is deployed. If the value is 0 or missing, the endpoint is deployed in a non-VLAN setup.

Applicable events : 4112, 4113, 4115, 4116, 4117, 4118, 4353

integer (int32)

3.47. EventQueryRequest

Event Query object.

Name Description Schema

end_time
optional

Specifies the end of the search time frame.

When specifying end_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - Query operation on end_time is exclusive. Example: end_time < 2017-01-08T00:00:00.000Z - The end time must be greater than the start time - The default is the current server time
Example : "2017-01-08T00:00:00.000Z"

string

limit
optional

Specifies the maximum number of events to return. If any events are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 5000 Default = 100
Example : 100

integer (int32)

max_slice
optional

Specifies the total number of slices being fetched. To enable sliced query request, set 2 <= max_slice < 20.

Default = 0 Minimum = 2 Maximum = 20
Example : 10

integer (int32)

next
optional

Used for events cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "ZXhhbXBsZSBuZXh0IHN0cmluZw=="

string

query
optional

Specifies a search query as Lucene query string.

The search query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. - A Single Term is a single word such as "test" or "hello" - A Phrase is a group of words surrounded by double quotes such as "hello dolly"

When creating a search query string, consider the following: - You can search any field by specifying the field name followed by a colon ":" and then the term you are looking for - Escape special characters that are part of the query syntax. To escape a special character use the \ before the character. The current list of special characters are + - && || ! ( ) { } [ ] ^ " ~ * ? \ : - Date value should follow ISO 8601 date stamp standard format (yyyy-MM-dd’T’HH:mm:ss.SSSXXX) - Supported Boolean operators for complex query are: AND OR + - NOT Note: Boolean operators must be ALL CAPS - Multiple terms can be combined together with Boolean operators to form a more complex query in the query clause - Use parentheses to group clauses to form sub-queries - Defaults to all events for the start_time and end_time specified in the query - The maximum length of the query string is 10240 characters
Example : "log_time:[2017-01-01T00:00:00.000Z TO 2017-01-08T00:00:00.000Z]"

string

slice_field
optional

Specify a field for slicing. The field must be one of log_time, time, or empty "".

Default = ""
Example : "log_time"

string

slice_id
optional

The ID of the slice being requested. 0 <= slice_id < max_slice.

Default = 0 Minimum = 0 Maximum = max_slice-1
Example : 9

integer (int32)

start_time
optional

Specifies the beginning of the search time frame.

When specifying start_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - The query operation on start_time is inclusive. Example: start_time >= '2017-01-01T00:00:00.000Z' - The start time must be less than the end time - The default is end_time minus 7 days
Example : "2017-01-01T00:00:00.000Z"

string

verb
required

Request verb. Currently, only query verb is supported.
Example : "query"

string

3.48. EventQueryResponse

Response object containing the list of events.

Name Description Schema

next
optional

The token used for cursoring.

For details, refer to ResultSet request examples.

string

result
required

Array of events.

< Event > array

total
optional

The total number of events in the overall query.

integer (int32)

3.49. ExternalCommunicationDetails

Polymorphism : Composition

Name Description Schema

request_type
required

Specifies the type of the request.

enum ("dns", "tcp", "udp", "url")

target
required

The target field is specific to the type of the request.

For type dns, the field is an instance of DnsTarget.

For type tcp or udp, the field is an instance of IPTarget.

For type url, the field is an instance of UrlTarget.

Target

3.50. File

File object.

Name Description Schema

accessed
optional

Threat file last accessed date in ISO 8601 format.

Applicable events : 4102

string

attributes
optional

Additional information about the file.

The attributes are represented as a bitmap. A set bit at a given position corresponds to an attribute being applicable:

0x01 - the file is portal 0x02 - the file was created by an installer 0x04 - the file was embedded

Note: Remaining bits are unused. The data type is an integer for events 4096 and 4099; null for event 4100.

Applicable events : 4096, 4099, 4100
Example : "0x4"

integer (int32)

company_name
optional

The company name.

Applicable events : 4123

string

created
optional

Threat file creation date in ISO 8601 format.

Applicable events : 4102

string

desc
optional

The file type, such as text, exe, etc.

Applicable events : 4096, 4099, 4100
Example : "exe"

string

file_age
optional

A code between 1 and 4 representing the file’s global age defined by the time the file was first reported to Mr. Clean. Possible values are: 1 = Years ago 2 = Months ago 3 = Weeks ago 4 = Days ago

Applicable CEvents : 4096, 4115, 4116, 4117, 4118, 4353

integer (int32)

folder
optional

The folder where the file resides.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4123

string

md5
optional

The MD5 checksum of the file.

Applicable events : 4096, 4098, 4099, 4102, 4115, 4116, 4117, 4118, 4123, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081, 8082, 8083, 8090

string

mime_type
optional

The MIME type of the file associated with the event.

Applicable events : 4115, 4116, 4117, 4118, 4353

string

modified
optional

Threat file modified date in ISO 8601 format.

Applicable events : 4102, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081

string

name
optional

The name of the file.

Applicable events : 4096, 4098, 4099, 4100, 4102, 4115, 4116, 4117, 4118, 4123, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081, 8082, 8083, 8090

string

normalized_path
optional

The CSIDL normalized path name; Windows Only

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081, 8082, 8083, 8090
Example : "CSIDL_SYSTEM\\svchost.exe"

string

path
optional

The full path to the object.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081, 8082, 8083, 8090
Example : "c:\\windows\\system32\\svchost.exe"

string

prevalence_band
optional

A code between 1 and 8 representing the file’s prevalence. Possible values are: 1 = Fewer than 5 users 2 = Fewer than 50 users 3 = Fewer than 100 users 4 = Hundreds of users 5 = Thousands of users 6 = Tens of thousands of users 7 = Hundreds of thousands of users 8 = Millions of users

Applicable events : 4096, 4115, 4116, 4117, 4118, 4353

integer (int32)

reputation_band
optional

A code between 1 and 6 representing the file’s reputation band. Possible values are: 1 = Symantec-trusted 2 = Good 3 = Trending Good 4 = Unproven 5 = Poor 6 = Untrusted

Applicable events : 4096, 4115, 4116, 4117, 4118, 4353

integer (int32)

sha2
optional

The SHA256 checksum of the file (hex string).

Applicable events : 4096, 4099, 4100, 4102, 4115, 4116, 4117, 4118, 4123, 4125, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081, 8082, 8083, 8090

string

signature_company_name
optional

The name of the company on the certificate.

Applicable events : 4096, 4099, 4115, 4116, 4117, 4118, 4353, 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081, 8082, 8083, 8090

string

signature_issuer
optional

The issuer of the signature.

Applicable events : 4096, 4099

string

signature_serial_number
optional

The signature serial number.

Applicable events : 4096, 4099

string

size
optional

The size of the file in bytes. Type is 64-bit long.

Applicable events : 4096, 4099, 4100, 4102, 4115, 4116, 4117, 4118, 4125, 4353

integer (int64)

targeted_attack
optional

Indicates whether this is a targeted attack.

Applicable events : 4115, 4116, 4117, 4118, 4353
Default : false

boolean

version
optional

Application file version.

Applicable events : 4098, 4102

string

3.51. FileEndpointPair

Represents Endpoint/ file pair.

Name Description Schema

device_uid
required

This represents device ID.

string

hash
required

The SHA256 checksum of the file (hex string).

string

3.52. FileEntity

Object of ATP file entities. A file entity object is uniquely identified by the sha2 field.

Note
Except first_seen and sha2, all other values gets replaced with the last values seen.
Name Description Schema

file_health
optional

Bucketing category: 1 = Good 2 = Unknown 3 = Suspicious 4 = Bad 6 = Leaning good

integer (int32)

first_seen
optional

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this entity.
Example : "2018-01-17T13:44:48.936Z"

string

global_first_seen
optional

The first date and time (in ISO 8601 format) that Insight saw this entity worldwide.
Example : "2018-01-17T13:44:48.936Z"

string

is_targeted
optional

A flag that indicates whether this file is a part of targeted attack launched against an organization.
Default : false

boolean

last_seen
optional

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this entity.
Example : "2018-01-17T13:44:48.936Z"

string

md5
optional

The MD5 checksum of the file.
Example : "5CDEA99C91025755ECBE30EEC0AA525A"

string

mime_type
optional

Indicates the true file type, which may not necessarily match the file extension. This information is determined by inspecting the file contents – not by the file extension. See RFC6838 specification for more details on MIME types:

https://tools.ietf.org/html/rfc6838

string

name
optional

The name of the file. This attribute doesn’t include the path of the file.
Example : "vjdrxiz6tvjw4xutcxlpzxh62t1.exe"

string

prevalence_band
optional

The number of times a file reputation request has been made on this file worldwide.
Example : 78

integer (int32)

reputation_band
optional

The reputation score of the file between -127 to 127. Reputation text computed based on confidence and disposition. Symantec trusted = reputation_band > 75 Good = reputation_band > 25 Trending good = reputation_band >= 8 Unproven = reputation_band >= -5 Poor = reputation_band >= -20
Example : 56

integer (int32)

sandbox_verdict
optional

Represents the verdict given by Symantec’s Sandbox analysis service. Possible values are: malware clean file_type_unrecognized

string

sha2
required

The SHA256 checksum of the file (hex string).
Example : "B20BF4FD7BB125CD7440668EB7220EE64EA1DB4410662F86FC56133E3DF4C634"

string

signature_company_name
optional

The company name on the certificate that signed the file.
Example : "VMWare Inc."

string

signature_issuer
optional

The issuer of the object signature.
Example : "COMODO Code Signing CA 2"

string

size
optional

The size of the file in bytes. Type is 64-bit long.
Example : 69472

integer (int64)

threat_name
optional

Name of the threat if the file is determined to be a malware.
Example : "BloodHound.SymVT.FP.H"

string

type
required

The file entity type.

Currently only file_latest is supported.

enum ("file_latest")

3.53. FileEntityQueryResponse

Response object containing the list of file entity objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of file entity objects.

< FileEntity > array

total
required

Count of file entity objects matching the query.

integer (int32)

3.54. FileInstance

Object of ATP file instances.

Name Description Schema

first_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the creation of this instance.
Example : "2018-01-30T04:13:10.669Z"

string

folder
optional

The folder where the file resides. This attribute doesn’t include the name of the file.
Example : "c:\\users\\public\\pictures"

string

last_seen
required

The timestamp (in ISO 8601 format) that specifies the creation time of the event that resulted into the update of this instance.
Example : "2018-01-30T04:13:10.669Z"

string

name
optional

The name of the file. This attribute doesn’t include the path of the file.
Example : "virus.exe"

string

sha2
optional

The SHA256 checksum of the file (hex string).
Example : "65635F3617640DB032BD8E85D82204C875C2772801AD8B2F271FC6B9EA77D6B0"

string

3.55. FileInstanceQueryResponse

Response object containing the list of file instance objects.

Name Description Schema

next
required

The token used for cursoring.

Note: Remember to DELETE the returned {next} value via DELETE /atpapi/v2/entities/next/{next} to ensure the server resources are released.

For details, refer to ResultSet request examples.

string

result
optional

List of File instance objects.

< FileInstance > array

total
required

Count of objects matching the query.

integer (int32)

3.56. GeoIP

Geo IP object.

Name Description Schema

country
required

Country code in ISO 3166-1 format.
Example : "IN"

string

region
optional

Region code in ISO 3166-2 or FIPS 10-4 format. Examples : "IN-KA", "IN19"

string

3.57. GetFileCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("get_endpoint_file")

end_time
optional
read-only

Should not be sent as part of get_endpoint_file command body.

string

query
optional
read-only

Should not be sent as part of get_endpoint_file command body.

string

start_time
optional
read-only

Should not be sent as part of get_endpoint_file command body.

string

targets
required

List of pair of SHA256 value of the file to get and the corresponding device ID.

< FileEndpointPair > array

3.58. IPTarget

Polymorphism : Composition

Name Description Schema

asn
optional

The autonomous system number as assigned by Internet Assigned Numbers Authority.
Example : "18924"

string

geoip
optional

The Geo location details of this IP.

GeoIP

ip
required

The IP address (IPv4 or IPv6) of the device/machine that accepted the connection.
Example : "131.253.61.100"

string

is_server
optional

Indicates whether the executed process acts as a server on this IP, port pair.
Default : false

boolean

port
required

The port number identified as the target port in traffic sent to the target device.
Example : 443

integer (int32)

3.59. Incident

Object of ATP Incidents.

Name Description Schema

atp_incident_id
required

A unique identifier for this incident.

integer (int32)

device_time
required

The timestamp (in ISO 8601 format) that specifies the time at which the event occurred.

string

first_event_seen
required

The creation time (in ISO 8601 format) when the first event associated with the incident was created. Matches the first event’s time field. This is likely before the incident’s creation time field given incidents are created after their first event is seen.

string

last_event_seen
required

The creation time (in ISO 8601 format) when the last event associated with the incident was created. Matches the last event’s time field.

string

log_name
required

The index of the incident.

Note: This is for informational purpose and cannot be used as a filter. Use time as start_time to query for incidents.
Example : "epmp_incident-2018-03-01"

string

priority_level
required

Priority level of the incident. Possible values are: 1 = LOW 2 = MED 3 = HIGH

integer (int32)

recommended_action
required

Recommended action for this incident. Possible actions could be isolating an endpoint, deleting file from endpoint, blacklist URL, or domain, etc.

string

resolution
optional

The resolution of the closed incident. Possible values are: 0 = INSUFFICIENT_DATA. The incident does not have sufficient information to make a determination. 1 = SECURITY_RISK. The incident indicates a true security threat. 2 = FALSE_POSITIVE. The incident has been incorrectly reported as a security threat. 3 = MANAGED_EXTERNALLY. The incident was exported to an external application and will be triaged there. 4 = NOT_SET. The incident resolution was not set. 5 = BENIGN. The incident detected the activity as expected but is not a security threat. 6 = TEST. The incident was generated due to internal security testing.

integer (int32)

state
required

The current state of the incident. Possible values are: 1 = OPEN 2 = WAITING 3 = IN_WORK 4 = CLOSED

integer (int32)

summary
required

Summary information about the incident.

string

time
required

The creation time (in ISO 8601 format) of the incident.

string

updated
required

The time (in ISO 8601 format) of last modification.

string

uuid
required

The GUID assigned for this incident.
Example : "483e3fde-4556-4800-81b1-e8da5ee394b6"

string

3.60. IncidentComment

Object of ATP Incident comments.

Name Description Schema

comment
required

The comment of incident.

string

time
required

The timestamp (in ISO 8601 format) that specifies the time at which the comment was added to incident.

string

user_id
required

The user id who registered the comment.
Example : 100000

integer (int32)

3.61. IncidentCommentQueryRequest

Incident Comment Query object.

Name Description Schema

end_time
optional

Specifies the end of the search time frame.

When specifying end_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - Query operation on end_time is exclusive. Example: end_time < 2017-01-08T00:00:00.000Z - The end time must be greater than the start time - The default is the current server time
Example : "2017-01-08T00:00:00.000Z"

string

limit
optional

Specifies the maximum number of incident comments to return. If any incident comments are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 20
Example : 20

integer (int32)

next
optional

Used for incident comments cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "RXhhbXBsZSBpbmNpZGVudCBjb21tZW50cyBuZXh0"

string

start_time
optional

Specifies the beginning of the search time frame.

When specifying start_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - The query operation on start_time is inclusive. Example: start_time >= '2017-01-01T00:00:00.000Z' - The start time must be less than the end time - The default is end_time minus 30 days
Example : "2017-01-01T00:00:00.000Z"

string

verb
optional

Request verb. Currently, only the query verb is supported.
Example : "query"

string

3.62. IncidentCommentQueryResponse

Response object containing the list of comments.

Name Description Schema

next
optional

The token used for cursoring.

For details, refer to ResultSet request examples.

string

result
required

Array of comments.

< IncidentComment > array

total
optional

Count of IncidentComment objects matching the query.

integer (int32)

3.63. IncidentQueryRequest

Incident Query object.

Name Description Schema

end_time
optional

Specifies the end of the search time frame.

When specifying end_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - Query operation on end_time is exclusive. Example: end_time < 2017-01-08T00:00:00.000Z - The end time must be greater than the start time - The default is the current server time
Example : "2017-01-08T00:00:00.000Z"

string

limit
optional

Specifies the maximum number of incidents to return. If any incidents are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 20
Example : 20

integer (int32)

next
optional

Used for incidents cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "RXhhbXBsZSBpbmNpZGVudCBxdWVyeSBuZXh0"

string

query
optional

Specifies a search query as Lucene query string.

The search query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. - A Single Term is a single word such as "test" or "hello" - A Phrase is a group of words surrounded by double quotes such as "hello dolly"

When creating a search query string, consider the following: - You can search any field by specifying the field name followed by a colon ":" and then the term you are looking for - Escape special characters that are part of the query syntax. To escape a special character use the \ before the character. The current list of special characters are + - && || ! ( ) { } [ ] ^ " ~ * ? \ : - Date value should follow ISO 8601 date stamp standard format (yyyy-MM-dd’T’HH:mm:ss.SSSXXX) - Supported Boolean operators for complex query are: AND OR + - NOT Note: Boolean operators must be ALL CAPS - Multiple terms can be combined together with Boolean operators to form a more complex query in the query clause - Use parentheses to group clauses to form sub-queries - Defaults to all incidents for the start_time and end_time specified in the query. If no start_time and end_time are specified, returns all incidents for the last 30 days - The maximum length of the query string is 10240 characters
Example : "updated:[2017-01-01T00:00:00.000Z TO 2017-01-08T00:00:00.000Z]"

string

start_time
optional

Specifies the beginning of the search time frame.

When specifying start_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - The query operation on start_time is inclusive. Example: start_time >= '2017-01-01T00:00:00.000Z' - The start time must be less than the end time - The default is end_time minus 30 days
Example : "2017-01-01T00:00:00.000Z"

string

verb
optional

Request verb. Currently, only the query verb is supported.
Example : "query"

string

3.64. IncidentQueryResponse

Response object containing the list of incidents.

Name Description Schema

next
optional

The token used for cursoring.

For details, refer to ResultSet request examples.

string

result
required

Array of incidents.

< Incident > array

total
optional

The total number of incidents in the overall query.

integer (int32)

3.65. Intrusion

Intrusion attributes.

Name Description Schema

attacker_local_remote
optional

Direction of the attack. Possible values are: 0 = unknown 1 = local 2 = remote

Applicable events : 4098

string

date_detected
optional

Time (in ISO 8601 format) when Symantec Endpoint Protection detected an intrusion event.

Applicable events : 4098

string

detail_id
optional

Signature sub-identifier.

Applicable events : 4098

string

protocol_id
optional

Layer 4 protocol number (e.g., TCP=6, UDP = 17). Go to the following URL for a complete list: http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml#protocol-numbers-1

Applicable events : 4098

string

signature_properties
optional

Signature properties (bitmap) as specified in the meta-data. It is a 64-bit number represented as a string.

A set bit at a given position corresponds to a property being applicable: 0x01 - Signature is disk-less. This threat does not touch the disk. Also known as fileless.

0x02 - Attacker destination. This means the attacker is the destination of the packet being used to finalize the attack detection. For example, we detected a shell opening and greeting the remote server, the packet is outbound TO the attacker.

0x04 - Blocks traffic.

0x08 - Generates any heuristic notifications. This signature’s events, regardless of blocking status, are consumed by other on-system components for one or more heuristics.

0x10 - Generates IPS ping submission. This signature’s events are sent to Symantec ping gateway.

0x20 - Reserved. Ignore if set.

0x40 - Results in display of a safe landing page. Signature, if detected in browser, will result in the browser page being redirected to a safe Symantec site describing the detection.

0x80 - This signature results in the app terminating.

0x100 - System requires manual remediation. Indicates possible ongoing infection on the host.

0x200 - LOG flag. When detection occurs, suggestion is for product to log the detection.

0x400 - ALLOW flag. When detection occurs, default action is to ALLOW the related network traffic. Product is able to override.

0x800 - Category audit signature. Audit signatures detect events which are not malicious, but which may be banned by corporate policy. For example, chat client traffic.

0x1000 - Reserved. Ignore if set.

0x2000 - Reserved. Ignore if set.

0x4000 - Reserved. Ignore if set.

0x8000 - Reboot required to enable signature. If flag set on detection event, the reboot already occurred and detection occurred.

0x10000 - Reserved. Ignore if set.

Applicable events : 4098

string

3.66. IpInfo

IP information associated with this domain (source: DeepSight).

Name Description Schema

address
optional

The IPv4 address that exhibited the malicious behavior.
Example : "173.199.134.47"

string

city
optional

The city in which the IP address is located.
Example : "Chicago"

string

country
optional

The country in which the IP address is located.
Example : "United States"

string

ip_version
optional

A static value of 4.
Example : "4"

string

organization
optional

The organization name that owns the IP address.
Example : "cogswell enterprises inc."

string

state
optional

The state in which the IP is located.
Example : "Illinois"

string

3.67. IsolateCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("isolate_endpoint")

end_time
optional
read-only

Should not be sent as part of isolate_endpoint command body.

string

query
optional
read-only

Should not be sent as part of isolate_endpoint command body.

string

start_time
optional
read-only

Should not be sent as part of isolate_endpoint command body.

string

targets
required

List of device IDs to isolate.

< string > array

3.68. Kernel

The target of the kernel object.

Name Description Schema

name
optional

The name of the kernel resource.

Applicable events : 8009, 8089

string

3.69. LinkFollowing

The origin URL link found in the email and list of redirect URLs.

Name Description Schema

origin_url
optional

The origin URL link found in the email.

Applicable events : 4125

string

redirect_urls
optional

List of redirect URLs related to the origin URL.

Applicable events : 4125

< RedirectUrls > array

3.70. Location

Domain location information.

Name Description Schema

country
optional

Geolocation of last seen IP.
Example : "United States"

string

3.71. OperatingSystem

Operating system details.

Name Description Schema

is_64_bit
optional

Whether the endpoint running a 64-bit operating system.
Default : false

boolean

osfullname
optional

The endpoint’s operating system.
Example : "Windows Server 2012 Standard Edition"

string

3.72. PatchIncidentBody

Patch parameters for the close incident, update resolution of closed incident or add comments to incident.

Name Description Schema

op
required

Specifies the operation to take on specified incident. - For close incident, the operation must be replace. - For update resolution of closed incident, the operation must be replace. - For add comments, the operation must be add.

enum ("replace", "add")

path
required

String containing a JSON-pointer value that references a location within the incident document where the operation is performed. - For close incident, the path must be /{uuid}/state. - For update resolution of closed incident, the path must be /{uuid}/resolution. - For add comments, the path must be /{uuid}/comments. - The uuid is the GUID assigned for the incident.

enum ("/{uuid}/state", "/{uuid}/resolution", "/{uuid}/comments")

value
required

New value for the field being patched. - The maximum length of comment is 512 characters. - For close incident, the value must be 4. The type is integer. - For update resolution of closed incident, the value must be a supported incident resolution value. See resolution field in the incident definition for supported values. The type is integer. - For add comments, the value should contain user defined comment. The type is string.

object

3.73. Process

The process performed an operation/action on a target object.

Name Description Schema

cmd_line
optional

The command line that was used to launch the process.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081

string

file
optional

File sub-type.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081

File

pid
optional

The process unique identifier as reported by the operating system.

Applicable events : 1, 1000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081

integer (int32)

signature_level_id
optional

A numeric representation of the signature level, as defined by STAR. Possible values are: 0 = UNKNOWN 10 = UNSIGNED 20 = SIGNED_BUT_UNTRUSTED 30 = SIGNED 40 = CLASS3_SIGNED 50 = SYMC_SIGNED 60 = MICROSOFT_SIGNED 70 = MICROSOFT_OS_COMPONENT Applicable events : 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009

integer (int32)

user
optional

User sub-type.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8081

User

3.74. Receivers

Receivers object.

Name Description Schema

delivered
optional

Indicate whether the email was delivered to the enterprise mail server.

Applicable events : 4125
Default : false

boolean

email_address
optional

Receiver’s email address.

Applicable events : 4125

string

internal
optional

Indicate whether the email is internal to the enterprise.

Applicable events : 4125
Default : false

boolean

released_from_quarantine
optional

Indicate whether this user released this email from the quarantine storage.

Applicable events : 4125
Default : false

boolean

3.75. RecorderSearchCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("recorder_search")

end_time
optional

The end of the search query time frame.

string

query
required

A Lucene query expression of supported recorder tokens, operators.

string

start_time
optional

The beginning of the search query time frame.

string

targets
required

A combination of sepm_groups, ipv4_addresses, hostnames and device_uids.

< SearchScope > array

3.76. RedirectUrls

List of redirect URLs.

Name Description Schema

redirect_url
optional

The redirect URL.

Applicable events : 4125

string

url_type
optional

The type of the redirect URL. Possible values are: - javascript - html - meta Applicable events : 4125

string

3.77. RegKey

The target of the registry operation.

Name Description Schema

path
optional

The full path to registry key.

Applicable events : 8005, 8085

string

3.78. RegValue

The target of the registry operation.

Name Description Schema

data
optional

The data of the registry value types : REG_BINARY, REG_DWORD, REG_EXPAND_SZ, REG_LINK, REG_NONE, REG_QWORD, REG_SZ, REG_DWORD_BIG_ENDIAN, REG_RESOURCE_LIST, REG_FULL_RESOURCE_DESCRIPTOR, REG_RESOURCE_REQUIREMENTS_LIST

Applicable events : 8006

string

name
optional

The name of the registry value.

Applicable events : 8006, 8086

string

path
optional

The full path to registry key where the value is located.

Applicable events : 8006, 8086

string

3.79. Registration

Domain registration information.

Name Description Schema

city
optional

The city of the organization that registered the domain.
Example : "Bethesda"

string

country
optional

The country of the organization that registered the domain.
Example : "United States"

string

create_date
optional

The date the domain was originally registered. ISO 8601 compliant date format for an undefined time zone.
Example : "2007-04-25"

string

expiry_date
optional

The expiry date of the domain. ISO 8601 compliant date format for an undefined time zone.
Example : "2015-06-25"

string

organization
optional

The organization that registered the domain.
Example : "Exent Technologies Inc"

string

person
optional

Name of the organization who registered the domain.
Example : "David Freund"

string

state
optional

The state of the organization that registered the domain.
Example : "Md"

string

update_date
optional

The date the domain registration was last updated. ISO 8601 compliant date format for an undefined time zone.
Example : "2013-06-25"

string

3.80. RejoinCommandBody

Polymorphism : Inheritance
Discriminator : action

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("rejoin_endpoint")

end_time
optional
read-only

Should not be sent as part of rejoin_endpoint command body.

string

query
optional
read-only

Should not be sent as part of rejoin_endpoint command body.

string

start_time
optional
read-only

Should not be sent as part of rejoin_endpoint command body.

string

targets
required

List of device IDs to rejoin.

< string > array

3.81. SEPMServer

Details of SEPM server (for example, server name, database type, database name, etc.).

Name Description Schema

db_ip_address
optional

IP address of the SEPM database.

Applicable events : 1000
Example : "192.168.0.10"

string

db_name
optional

Configured SEPM database name.

Applicable events : 1000
Example : "sem5"

string

db_port
optional

Database port of SEPM database.

Applicable events : 1000
Example : 8081

integer (int32)

db_type
optional

Type of database: MSSQL or Sybase.

Applicable events : 1000
Example : "SYBASE"

string

enabled
optional

Indicates whether ATP is enabled to log on and gather logs from this database.

Applicable events : 1000
Default : false
Example : true

boolean

sepm_name
optional

User-provided name for SEPM database server.

Applicable events : 1000
Example : "SEPM_DB"

string

status
optional

Status of SEPM database configuration with ATP.

Applicable events : 1000
Example : "healthy"

string

user_name
optional

User name of the SEPM database.

Applicable events : 1000
Example : "ATP_QUERY_USER"

string

3.82. Sandbox

Sandbox object.

Name Description Schema

sandbox_task_id
optional

The task ID that Sandbox returns on submitted files.

Applicable events : 4117

string

targeted_data
optional

Targeted data sub-type.

Applicable events : 4117

TargetedData

verdict
optional

Sandbox verdict. Possible values are: - malware - clean - file_type_unrecognized

Applicable events : 4117

enum ("malware", "clean", "file_type_unrecognized")

verdict_type
optional

The type of verdict: - full_analysis - intelligence

Applicable events : 4117

enum ("full_analysis", "intelligence")

3.83. SandboxActivitiesQueryResponse

Response object containing the list of sandbox activities.

Name Description Schema

next
required

The token used for sandbox activities cursoring.

For details, refer to ResultSet request examples.

string

result
optional

List of sandbox activities.

< SandboxActivity > array

total
required

The total number of sandbox activities in the overall query.

integer (int32)

3.84. SandboxActivity

This represents the summary of an exhibited sandbox system change.

Name Description Schema

activity_type
required

Specifies the type of system change.

enum ("process_thread_events", "named_object_events", "file_system_events", "network_events", "windows_registry_events", "static_events")

summary
optional

A summary of the system change.

string

verbose_details
optional

The verbose_details field is specific to the type of system change.

For network_events, the field is an instance of ExternalCommunicationDetails.

ActivityVerboseDetails

3.85. SandboxCommandBody

This represents request body for sandbox command.

Name Description Schema

action
required

Specifies the type of action to take on the specified target(s).

enum ("analyze")

targets
required

The targets field is specific to the type of command.

For analyze, the field is an array of strings each representing a SHA256 of the target file.

< string > array

3.86. SandboxCommandResponseBody

This represents response body for sandbox command.

Name Description Schema

command_id
optional

Command ID

string

3.87. SandboxCommandStatus

Status of specific target.

Name Description Schema

error_code
required

This represents error code for specific target. Possible values: -1 = Error 1 = In progress 9000 = File Is Clean 9001 = File Is Malware 9003 = File Size Over Limit (File Size Should Not Exceed 10MB For Sandbox Submission) 9005 = Query To Sandbox Failed (Check Network Connectivity) 9006 = File Type Not Supported (Check With Symantec Support For Sandbox Supported File List) 9007 = File Not Found In FileStore (Use get_endpoint_file Command To Copy File Into FileStore)

integer (int32)

message
required

Message explaining error code. Possible values: Error (-1) In progress (1) File Is Clean (9000) File Is Malware (9001) File Size Over Limit (9003) Query To Sandbox Failed (9005) File Type Not Supported (9006) File Not Found In FileStore (9007)

string

state
required

This represents command status for specific target. Possible values: 0 = Completed 1 = In progress 2 = Error

integer (int32)

target
required

The target field represents SHA256 of a file.

string

3.88. SandboxCommandStatusResponse

Status of each target specified in the command.

Name Description Schema

status
required

List representing status of each target.

< SandboxCommandStatus > array

3.89. SandboxEvent

This represents an exhibited sandbox behavior.

Name Description Schema

details
optional

The value that an event modified, added or deleted; e.g. for a registry write event this would contain the value written, for a process create event this is the exe that was run etc.

string

pid
optional

A identifier of the process that generated this event; e.g. a PID.

integer (int32)

severity
optional

An assesment of the impact or malicious nature of this event. Values range from 0 - 5, with 0 being no impact and 5 being most severe.

integer (int32)

target
optional

The target of the event; e.g. a registry key or filename.

string

type
required

A high level description of the event. Examples : "FILE:WRITE", "REGISTRY:CREATE", "OBJ_CreateProcess", "REG_CreateKey"

string

verbose_details
optional

Verbose details of this event; e.g. this may include the time the event took place, the command line of an OBJ_CreateProcess, the registry key name for REG_CreateKey etc.

< SandboxEventVerboseDetail > array

3.90. SandboxEventVerboseDetail

The verbose detail of a sandbox behavior.

Name Description Schema

name
required

The verbose deatil indentifier. e.g. A registry key.
Example : "key"

string

value
required

The value of the indentifier. e.g. A path of a registry key.
Example : "HKLM\\system\\currentcontrolset\\services\\tcpip\\parameters"

string

3.91. SandboxEventsQueryResponse

Response object containing the list of sandbox events.

Name Description Schema

next
required

The token used for sandbox events cursoring.

For details, refer to ResultSet request examples.

string

result
optional

List of sandbox events.

< SandboxEvent > array

total
required

The total number of sandbox events in the overall query.

integer (int32)

3.92. SandboxPattern

This represents a sandbox observed pattern.

Name Description Schema

name
required

The name of the pattern performed by the sample.

string

risk_score
required

The risk posed by this pattern on a scale of 1 (benign) to 10 (malicious). ATP considers a 7 or greater as malicious.

integer (int32)

3.93. SandboxPatternsQueryResponse

Response object containing the list of sandbox patterns.

Name Description Schema

next
required

The token used for sandbox patterns cursoring.

For details, refer to ResultSet request examples.

string

result
optional

List of sandbox patterns.

< SandboxPattern > array

total
required

The total number of sandbox patterns in the overall query.

integer (int32)

3.94. SandboxVerdict

This represents sandbox verdict of a file.

Name Description Schema

confidence
optional

The confidence level about the verdict.

integer (int32)

is_targeted
optional

Indicates whether this is a targeted attack.
Default : false

boolean

sandbox_service
optional

The sandboxing service used for suspicious file analysis. Possible values are: - cynic - content_analysis

enum ("cynic", "content_analysis")

sandbox_task_id
optional

The task ID that Sandbox returns on submitted files.

string

verdict
required

Sandbox verdict. Possible values are: - malware - clean - file_type_unrecognized

enum ("malware", "clean", "file_type_unrecognized")

verdict_type
optional

The type of verdict. Possible values are: - full_analysis - intelligence

enum ("full_analysis", "intelligence")

3.95. Scan

Scan object.

Name Description Schema

signatures_version
optional

DefSet signature version.

Applicable events : 4098, 4100
Example : "20110422.001"

string

3.96. SearchConfig

Search configuration (i.e., command ID and command type for endpoint search).

Name Description Schema

atp_command_id
optional

Command ID to uniquely identify the search.

Applicable events : 1
Example : "f283b7dc9255493daed443e13e726903-2018-05-16"

string

cmd_type
optional

Type of search command. Possible values are:

eoc_search edr_search fdr_search fdr_full_dump fdr_process_dump.

Applicable events : 1
Example : "fdr_process_dump"

string

3.97. SearchScope

Represents the union set of all matching endpoints based on matching the endpoint’s matching sepm_groups, ipv4_addresses, hostnames and device_uids.

Note
The combined array size of sepm_groups, ipv4_addresses, hostnames and device_uids is limited to 100.
Name Description Schema

device_uids
optional

A list of strings each representing an device ID.

< string > array

hostnames
optional

A list of strings each representing a managed endpoint’s host name.

< string > array

ipv4_addresses
optional

A list of strings each representing a managed endpoint’s IPv4 address.

< string > array

sepm_groups
optional

A list of strings each representing a managed SEPM group name.

When you specify a Symantec Endpoint Protection Manager group, all endpoints belonging to this group along with all endpoints belonging to the subgroups are searched.

< string > array

3.98. Sender

Sender object.

Name Description Schema

email_address
optional

Sender’s email address.

Applicable events : 4125

string

internal
optional

Indicate whether the sender is within the enterprise or not.

Applicable events : 4125
Default : false

boolean

sender_ip
optional

Human-readable sender IP address.

Applicable events : 4125

string

3.99. SepDomain

Symantec Endpoint Protection Manager Group’s Domain Summary.

Name Description Schema

name
optional

The Symantec Endpoint Protection Manager domain name to which this endpoint belongs.
Example : "Default"

string

3.100. SepGroupSummary

Symantec Endpoint Protection Manager Group Summary.

Name Description Schema

name
optional

The Symantec Endpoint Protection Manager group to which this endpoint belongs.
Example : "My Company\\ATPPrivateInsightGroup"

string

sep_domain_summary
optional

SepDomainSummary subtype.

SepDomain

3.101. Service

Service details of the event.

Name Description Schema

file
optional

File sub-type.

Applicable events : 8090

File

loaded_module_name
optional

The name of the loaded module.

Applicable events : 8090

string

name
optional

The unique name of the service.

Applicable events : 8090

string

reg_path
optional

The registry path of the service.

Applicable events : 8090

string

start_id
optional

The start type of the service. Possible values are: 0 = Unknown (The service startup is unknown) 1 = Auto (The service started automatically by the service control manager during system startup) 2 = Boot (The device driver service started by the system loader) 3 = Demand (The service started by the service control manager when a process calls the StartService function) 4 = System (The device driver service started by the IoInitSystem function) 5 = Disabled (The service is disabled)

Applicable events : 8090

integer (int32)

3.102. Session

Session details of the event.

Name Description Schema

id
optional

The id of session.

Applicable events : 8000, 8080

integer (int32)

user
optional

User sub-type.

Applicable events : 8000, 8080

User

3.103. SystemActivitiesQueryRequest

System activities query object.

Name Description Schema

end_time
optional

Specifies the end of the search time frame.

When specifying end_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - Query operation on end_time is exclusive. Example: end_time < 2017-01-08T00:00:00.000Z - The end time must be greater than the start time - The default is the current server time
Example : "2017-01-08T00:00:00.000Z"

string

limit
optional

Specifies the maximum number of system activities to return. If any system activities are found, they are returned in a single JSON array. If no limit is specified, then the limit value is set to the default limit.

Maximum = 1000 Default = 100
Example : 100

integer (int32)

next
optional

Used for system activities cursoring. The value of the next field must be treated as an opaque value. Use this value (data and type) in the next query.

Default = empty string
Example : "ZXhhbXBsZSBuZXh0IHN0cmluZw=="

string

query
optional

Specifies a search query as Lucene query string.

The search query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. - A Single Term is a single word such as "test" or "hello" - A Phrase is a group of words surrounded by double quotes such as "hello dolly"

When creating a search query string, consider the following: - You can search any field by specifying the field name followed by a colon ":" and then the term you are looking for - Escape special characters that are part of the query syntax. To escape a special character use the \ before the character. The current list of special characters are + - && || ! ( ) { } [ ] ^ " ~ * ? \ : - Date value should follow ISO 8601 date stamp standard format (yyyy-MM-dd’T’HH:mm:ss.SSSXXX) - Supported Boolean operators for complex query are: AND OR + - NOT Note: Boolean operators must be ALL CAPS - Multiple terms can be combined together with Boolean operators to form a more complex query in the query clause - Use parentheses to group clauses to form sub-queries - Defaults to all system activities for the start_time and end_time specified in the query - The maximum length of the query string is 10240 characters
Example : "log_time:[2017-01-01T00:00:00.000Z TO 2017-01-08T00:00:00.000Z]"

string

start_time
optional

Specifies the beginning of the search time frame.

When specifying start_time, consider the following: - The value should follow ISO 8601 date stamp standard format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX - The query operation on start_time is inclusive. Example: start_time >= '2017-01-01T00:00:00.000Z' - The start time must be less than the end time - The default is end_time minus 7 days
Example : "2017-01-01T00:00:00.000Z"

string

verb
required

Request verb. Currently, only query verb is supported.
Example : "query"

string

3.104. SystemActivitiesQueryResponse

Response object containing the list of system activities.

Name Description Schema

next
optional

The token used for cursoring.

For details, refer to ResultSet request examples.

string

result
required

Array of Events.

< Event > array

total
optional

The total number of events in the overall query.

integer (int32)

3.105. Target

Target object.

Type : object

3.106. TargetedData

targeted_data object.

Name Description Schema

is_targeted
optional

Indicates whether this is a targeted attack.

Applicable events : 4117
Default : false

boolean

3.107. Threat

Threat object.

Name Description Schema

category
optional

Malware category as detected by scanner. Possible values are: - Worm - Virus - Backdoor - InfoStealer - Downloader - Trojan - Hacktool - Phish - Uncategorized Applicable events : 4125

string

category_id
optional

The virus category ID reported by the scanning engine. Possible values are:

0 = CATEGORY_MALWARE 1 = CATEGORY_NON_VIRAL_MALICIOUS 2 = CATEGORY_RESERVED_MALICIOUS 3 = CATEGORY_HEURISTIC 4 = CATEGORY_SECURITY_RISK_ON 5 = CATEGORY_HACKTOOLS 6 = CATEGORY_SPYWARE 7 = CATEGORY_TRACKWARE 8 = CATEGORY_DIALERS 9 = CATEGORY_REMOTE_ACCESS 10 = CATEGORY_ADWARE 11 = CATEGORY_JOKE 12 = CATEGORY_SECURITY_RISK_OFF 13 = CATEGORY_SECURITY_ASSESMENT_TOOL 14 = CATEGORY_MISLEADING_APPLICATION 15 = CATEGORY_POTENTIALLY_UNWANTED_APPLICATION 16 = CATEGORY_EXPERIMENTAL_HEURISTIC 17 = CATEGORY_PARENTAL_CONTROL 18 = CATEGORY_REPUTATION_DETECTION

Applicable events : 4353

integer (int32)

detection_engine
optional

The detection engine category reported by the scanning engine. Possible values are:

* Antivirus * Heuristic * Unknown

Applicable events : 4102

string

id
optional

The virus ID as reported by the scanning engine.

Applicable events : 4102, 4353

integer (int64)

name
optional

The virus name as reported by the scanning engine.

Applicable events : 4102, 4123, 4125, 4353

string

quarantine_id
optional

Internal reference used by the Virus Release process.

Applicable events : 4125
Example : "250511_1475614197"

string

risk
optional

Malware risk-level identified by Symantec’s AV Engine. Possible vales are:

1 = Low 3 = Medium 5 = High

Applicable events : 4353

integer (int32)

3.108. TokenObject

Token object.

Name Description Schema

access_token
optional

Returned access token.

string

expires_in
optional

Time (in seconds) in which the token will expire. Typically, this response is returned as 1 hour (60 seconds), but make sure your code uses the expires_in time rather than the assumed 1 hour time period.

string

refresh_token
optional

Returned refresh token. Currently not supported.

string

scope
optional

Granted scope for access token.

string

token_type
optional

Token type. Currently, the token type that is returned is always "Bearer".

string

3.109. TokensResponse

Response object containing the access token.

Name Description Schema

token
required

OAuth grant token.

TokenObject

3.110. UrlTarget

Polymorphism : Composition

Name Description Schema

url
required

The URL accessed during the execution.
Example : "http://crl.microsoft.com/pki/crl/products/tspca.crl"

string

3.111. User

User Object

Name Description Schema

domain
optional

The user domain.

Applicable events : 8000, 8080

string

name
optional

The name of the user that originated or caused the event or the user on whose behalf the event occured.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081

string

sid
optional

The user security identifier.

Applicable events : 8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8009, 8080, 8081

string

3.112. WhiteListPolicy

Whitelist policy object model

Name Description Schema

comment
optional

Specifies the comment for this whitelist policy. If not specified then defaults to empty string.
Example : "No monitoring required for Control traffic from this IP."

string

id
required
read-only

The unique ID of this whitelist policy. This id can be used in patch or delete request.

Note: This is ignored if present in create request

string

target_type
required

Specifies type of this whitelist policy.
Example : "ip"

enum ("ip", "domain", "url", "sha256")

target_value
required

Specifies value of this whitelist policy.
Example : "1.1.1.1"

string

3.113. WhiteListPolicyCreationRequestBody

This defines list of all whitelist policies to be created.

Name Description Schema

policies
required

It contains the list of whitelist policies to be created.

< WhiteListPolicy > array

verb
required

Request verb.

Currently, create verb is supported for whitelist policy creation.
Example : "create"

string

3.114. WhiteListPolicyCreationResponse

Whitelist Policy Creation Response object containing a list of whitelist policy identifiers.

Name Description Schema

ids
required

List of whitelist policy identifiers successfully created. These are returned in same order as policies defined in WhiteListPolicyCreationRequestBody.

< string > array

3.115. WhiteListPolicyPatchBody

Patch parameters for updating comment to the whitelist policy

Name Description Schema

op
required

Specifies the operation to take on specified policy.

enum ("replace")

path
required

String containing a JSON-pointer value that references a location within the policy document where the operation is performed.

For replace operation the path must be /comment.

enum ("/comment")

value
required

The value field is specific to the type of operation being patched.

For replace operation the value must be string. - The maximum length of comment is 512 characters.

string

3.116. WhiteListPolicyResponse

Response containing the list of whitelist policies

Name Description Schema

next
required

The token used for whitelist policies cursoring.

For details, refer to ResultSet request examples.

string

result
required

List of whitelist policies.

< WhiteListPolicy > array

4. Codes and IDs

4.1. Event type IDs

ID number

Event

1

Application Activity

1000

System Health

4096

Reputation Request

4098

Intrusion Prevention

4099

Suspicious File

4100

SONAR

4102

Antivirus (endpoint detection)

4112

Blacklist (IP/URL/domain)

4113

Vantage

4115

Insight

4116

Mobile Insight

4117

Cynic

4118

Blacklist (file)

4123

Endpoint File Detection

4124

Endpoint (IP/URL/domain) Detection

4125

Email

4353

Antivirus / Network Detection

8000

Session

8001

Process

8002

Module

8003

File

8004

Directory

8005

Registry Key

8006

Registry Value

8007

Network

8009

Kernel

8080

EOC Session

8081

EOC Process

8082

EOC Module

8083

EOC File

8084

EOC Directory

8085

EOC Registry Key

8086

EOC Registry Value

8089

EOC Kernel

8090

EOC Service

4.2. ATP search fields and descriptions

Click on the following link to learn more about the available ATP search fields and their descriptions:

4.3. HTTP status codes

Value

Status

Reason

Description

200

OK

Ok

Server found the requested resource. (Idempotent)

201

CREATED [POST/PUT/PATCH]

Created

Server successfully created a resource.

204

NO CONTENT

No content

Server successfully completed the specified operation on the specified resource.

400

BAD_REQUEST

Bad Request

Client provided bad data to the server. The server did nothing with it. (Idempotent)

401

UNAUTHORIZED

Unauthorized

Request rejected because it lacks valid authentication credentials for the target resource.

403

FORBIDDEN

Forbidden

Request rejected because it lacks sufficient privileges to access the target resource.

404

NOT_FOUND

Not Found

Client referenced a nonexistent resource or collection. The server did nothing. (Idempotent)

408

REQUEST_TIMEOUT

Request Timeout

Request timed-out. The request that the client sent took longer than the server was prepared to wait.

409

CONFLICT

Conflict

Request rejected because it resulted in a resource state conflict.

413

REQUEST_ENTITY_TOO_LARGE

Request Entity Too Large

Request rejected because it is too large to be processed for the target resource.

429

TOO_MANY_REQUESTS

Too Many Requests

Request rejected because too many requests were sent for the target resource in a given amount of time ("rate limiting").

500

INTERNAL_SERVER_ERROR

Internal Server Error

Server encountered an error. The client has no knowledge if the request was successful.

503

SERVICE_UNAVAILABLE

Service Unavailable

When the ATP appliance comes back online after an upgrade to version 3.1, migration of non-operational data begins in background. While the migration is in progress, some event and incident data is unavailable. During this time, public APIs are unavailable (the details of which are documented in Symantec™ Advanced Threat Protection 3.1 Migration Guide). Upon receiving this response, retry after an interval of 5-10 minutes.

Where to get support

504

GATEWAY_TIMEOUT

Gateway Timeout

Server timed-out. The ATP server did not receive a timely response from the back-end services. The client has no knowledge if the request was successful.

4.4. JSON error codes

Code

Reason

Originating Component

100

Invalid request

OAuth

101

Already exists

OAuth

102

Not authorized

OAuth

103

Expired

OAuth

104

Revoked

OAuth

105

Malformed Token

OAuth

106

Invalid Token

OAuth

300

unsupported_response_type

OAuth

301

invalid_grant

OAuth

302

invalid_request

OAuth

303

invalid_token

OAuth

304

insufficient_scope

OAuth

305

unauthorized_client

OAuth

306

access_denied

OAuth

307

invalid_scope

OAuth

308

server_error

OAuth

309

temporarily_unavailable

OAuth

310

invalid_redirect_uri

OAuth

311

invalid_client_metadata

OAuth

312

invalid_software_statement

OAuth

313

unapproved_software_statement

OAuth

314

unknown_client

OAuth

315

invalid_client

OAuth

10000

invalid parameter¹

For example, invalid query field name or value.

ATP

10001

http error

For example, unexpected HTTP 4xx errors.

ATP

10002

resource not found

ATP

¹ For example, invalid query field name or value.

5. Examples

5.1. Appliance API example

GET /atpapi/v2/appliances

Sample HTTP Request

GET /atpapi/v2/appliances HTTP/1.1
Host: 192.168.1.15
Authorization: Bearer <OAUTH TOKEN>
Content-Type:application/json

Curl Command Request

curl -X GET -H 'Authorization: Bearer "eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk90ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA"' -k https://192.168.1.15/atpapi/v2/appliances

Sample Response Body

{
   "appliance_list":[
      {
         "appliance_id":"564D884D-CCF5-D3DE-4F66-ADA4A1DAE8C2",
         "appliance_name":"ATP",
         "appliance_time":"2018-02-18T09:24:40.982Z",
         "role":[
            "endpoint",
            "network scanner",
            "management"
         ],
         "software_version":"3.1.0-375"
      }
   ]
}

5.2. Events query API example

POST /atpapi/v2/events

Warning

Unless specifically mentioned, the following examples can potentially return unstable results. Refer Stable Results section for how to make these calls return stable results.

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJOX2gzbzhXaFNGQ01raDFJbWZhZ2JRIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSndGZVJEWThRQk9EM2dMZVhNM2dHUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmgzdWdpc2c1MDJmYjA3M2Y4dGhvbHRiOWIzXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uaDN1Z2lzZzUwMmZiMDczZjh0aG9sdGI5YjNcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODAwMTQzOCwiaWF0IjoxNTE3OTk3ODM4LCJqdGkiOiI1amExQzFlMFFjQ3BneTNOMEZLQXhBIn0.OmBRr4NH83U5ifGKHTm1FY1542_m-46u2e82mochGpd8sSsrhgw45MU10x5jfUM1B4vdXK1zpHg2rsI2vjNm7r3qHO-XfE4adpGpKf-zTqJ20eNq1fmu48AEOdppJG3Z--gTgzuAsdhsAbsRhDCTwfzyg1FD7ci5FKF_AXzI1WOVGaFonpwrnLfED1r94TdQa9Hof1IH291sGo5Ag-irWVgM9ZNcfnabOS8SP1tgiJP3tUlLLiAGnE2yDcgm_QRGYOucg-eG4nQGj1_SJDNwVKY-OjAUTLHcH8eoKl1TLBjXrGXa1oKYThq6MEls9F9Ubf_uwGmTdRQXT5GQ8YeuIw" "https://192.168.1.15/atpapi/v2/events"

Sample Request Body

{
   "verb":"query",
   "limit":"1"
}

Sample Response Body

{
    "next": "MSwyMDE4LTAyLTA3VDEwOjEyOjIyLjYyNFo=",
    "result": [
        {
            "data_direction": 1,
            "data_source_ip": "10.7.69.6",
            "data_source_url": "http://10.7.69.6/ATP_Test_Data/INSIGHT/obsolete/Unknown/DI_BadMin.sys",
            "data_source_url_domain": "10.7.69.6",
            "device_ip": "192.168.0.10",
            "device_name": "w7ent-sp1x64-v1",
            "device_time": "2018-02-07T04:04:15.945Z",
            "device_uid": "692ce485-2703-4d2a-adda-5d30b7d2aef3",
            "external_ip": "10.7.69.6",
            "file": {
                "file_age": 1,
                "folder": "CSIDL_PROFILE\\downloads",
                "md5": "28305c3687b0a5adf37134dd0f59afe6",
                "name": "DI_BadMin.sys",
                "prevalence_band": 6,
                "reputation_band": 4,
                "sha2": "b422a4a226c4c16ff50e2813917a5e49c782f024196f8d2e21c98ffd1425e850",
                "signature_company_name": "Microsoft Windows",
                "signature_issuer": "Microsoft Windows Verification PCA",
                "signature_serial_number": "6101C6C1000000000007",
                "size": 49764
            },
            "log_name": "epmp_events-rrs-2018-02-07",
            "log_time": "2018-02-07T04:04:18.325Z",
            "parent_file_sha2": "BE0B500D92C2A93E2EF1770AA3A15E09ED9DBBA124FD674A778215BD58ADD2AD",
            "sep_installed": true,
            "type_id": 4096,
            "user_name": "SaturnServiceUser",
            "uuid": "f6a2bb90-0bbb-11e8-fc5c-000000004a37"
        }
    ],
    "total": 4245
}

Sample Requests

Example 1. Return all events for the last 7 days

{
   "verb":"query"
}

Example 2. Return all events between 2016-06-08T15:39:55.616Z and now

{
   "verb":"query",
   "query":"log_time:[2016-06-08T15:39:55.616Z TO *]"
}

Example 3. Return events with typeId 4096 or 4098 or 4123 for the last 7 days

{
   "verb":"query",
   "query":"type_id:(4096 OR 4098 OR 4123)"
}

Example 4. Return events with type_id 4096 or 4098 or 4123 between 2016-06-08T15:39:55.616Z and now and time range between 2016-06-08T15:39:55.616Z and 2016-06-11T15:39:55.616Z

{
   "verb":"query",
   "query":"log_time:[2016-06-08T15:39:55.616Z TO *] AND (type_id:(4096 OR 4098 OR 4123))",
   "start_time":"2016-06-08T15:39:55.616Z",
   "end_time":"2016-06-11T15:39:55.616Z"
}

Example 5. Same as #4 but limited to logtime < 6/7/2016

{
   "verb":"query",
   "query":"log_time:{2016-06-06T15:39:55.616Z TO 2016-06-07T00:00:00.000Z} AND  (type_id:4096 OR 4098 OR 4123))",
   "start_time":"2016-06-06T15:39:55.616Z",
   "end_time":"2016-06-07T00:00:00.000Z"
}

Example 6. Same as #5 but limited to logtime >= 6/6/2016… and 2016-{future}Z time.

{
   "verb":"query",
   "query":"log_time:[2016-06-06T15:39:55.616Z TO 2016--{future}Z} AND ( type_id:(4096 OR 4098 OR 4123))",
   "start_time":"2016-06-06T15:39:55.616Z",
   "end_time":"2016-06-11T15:39:55.616Z"
}

Example 7. Return events with type_id 4096 or 4098 or 4123 or type_id range from 8000 to 8009 between 2016-06-08T15:39:55.616Z and now and time range between 2016-06-08T15:39:55.616Z and 2016-06-11T15:39:55.616Z

{
   "verb":"query",
   "query":"log_time:[2016-06-08T15:39:55.616Z TO *] AND (type_id:(4096 OR 4098 OR 4123 OR [8000 TO 8009]))",
   "start_time":"2016-06-08T15:39:55.616Z",
   "end_time":"2016-06-11T15:39:55.616Z"
}

Example 8. Return events with type_id 4096 or 4098 or 4123 or 8000 or type_id range from 8002 to 8009 or (type_id 8001 and enriched_data.category_id:102) between 2016-06-08T15:39:55.616Z and now and time range between 2016-06-08T15:39:55.616Z and 2016-06-11T15:39:55.616Z

{
   "verb":"query",
   "query":"log_time:[2016-06-08T15:39:55.616Z TO *] AND (type_id:(4096 OR 4098 OR 4123 OR 8000 OR [8002 TO 8009])) OR (type_id: 8001 AND enriched_data.category_id:102)",
   "start_time":"2016-06-08T15:39:55.616Z",
   "end_time":"2016-06-11T15:39:55.616Z"
}

5.2.1. Complex request examples

This example demonstrates the events query requests for more complex use cases.

Event query request for time range longer than 7 days

Event query API limits the time range parameters (start_time and end_time) to a maximum range of 7 days.

To retrieve event data for a period longer than 7 days, send multiple requests. These requests must be composed in such a way that the time range (start_time to end_time) for each request covers a non-overlapping span.

For example, if you want to retrieve events for a time range between 2016-01-01T00:00:00.000Z to 2016-02-01T00:00:00.000Z, you would compose five separate requests with non-overlapping time.

Time range parameters start_time and end_time are inclusive and exclusive, respectively (i.e., start_time < = event time < end_time). This lets you use end_time of an event data request as the start_time for the next event data request to obtain continuous, non-overlapping event data.

Note that multiple requests sent in a tight loop can potentially overload the ATP appliance. This can be mitigated by adding time delays between multiple calls.

Example 9. Return all events with type_id 4096 recorded between 2016-01-30T00:00:00.000Z and now and with creation time range between 2016-01-01T00:00:00.000Z and 2016-02-01T00:00:00.000Z

{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-01T00:00:00.000Z",
   "end_time":"2016-01-08T00:00:00.000Z"
}
{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-08T00:00:00.000Z",
   "end_time":"2016-01-15T00:00:00.000Z"
}
{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-15T00:00:00.000Z",
   "end_time":"2016-01-22T00:00:00.000Z"
}
{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-22T00:00:00.000Z",
   "end_time":"2016-01-29T00:00:00.000Z"
}
{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-29T00:00:00.000Z",
   "end_time":"2016-02-01T00:00:00.000Z"
}

Event query request for time range longer than 7 days with cursoring

You may use cursoring for each of the requests in the last example to limit the number of events returned in each response. For example, if you want a maximum of 100 events returned in each response, you can use limit and next to iterate over the results for each of the requests. The following example assumes that there were 250 events with type_id= 4096 between 2016-01-01T00:00:00.000Z and 2016-01-08T00:00:00.000Z. This would require a total of three requests.

Example 10. Return all events with type_id 4096 recorded between 2016-01-30T00:00:00.000Z and now and with creation time range between 2016-01-01T00:00:00.000Z and 2016-01-08T00:00:00.000Z with a maximum limit of 100 events

{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-01T00:00:00.000Z",
   "end_time":"2016-01-08T00:00:00.000Z",
   "limit":100
}
{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-01T00:00:00.000Z",
   "end_time":"2016-01-08T00:00:00.000Z",
   "next":"MSwyMDE2LTA2LTIwVDIwOjQ2OjE2LjgyN1o="
}
{
   "verb":"query",
   "query":"log_time:[2016-01-30T00:00:00.000Z TO *] AND type_id:4096",
   "start_time":"2016-01-01T00:00:00.000Z",
   "end_time":"2016-01-08T00:00:00.000Z",
   "next":"2LTIwVMSwyMDE2LTADIwOjQ2OjE2LjgyN1o="
}

In the above examples, all of the queries could potentially return data. This is because the log_time represents the time that the event was recorded by ATP Manager. The start_time and end_time represent filters on the event “time” field. The “time” field is the time the event was created. Using an example, say a SEP endpoint had a malware detection yesterday but was unable to talk to its SEPM server at that time. Today it finally forwarded the event to SEPM and then onto ATP Manager. In this example, the event has a time (creation time) field set to yesterday and the log_time (recording time) set to today.

The reason any of the above queries might have new data for a log_time >= '2016-01-30T00:00:00.000Z' is because newly recorded (log_time) events can come with old creation time (“time” field) values.

Click the following link for more details about cursoring.

5.2.2. Slice Request example

Event query request example:

POST /atpapi/v2/events
Host: localhost
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{"verb" : "query",
 "query" : "log_time: [ 2016-06-06T15:39:55.616Z TO 2016-06-06T16:39:55.616Z ] AND ( type_id : (4096 OR 4098 OR 4123)) ",
 "start_time" : "2016-06-06T15:39:55.616Z",
 "end_time" : "2016-06-11T15:39:55.616Z",
 "max_slice" : 10.
 "slice_id" : 1,
 "size" : 4000,
 "next" : "DnF1ZXJ5VGhlbkZldGNoBgAAAAAABAAAAAftnBZUb0doSDlVNlFwMmtyYXpqQ1FaU19BAAABBBBBBBBBBBBBDDDDDDDDDDFSFCJDBHSJAJ"}

Event query response example:

{"result" : [{"type_id" : 8001,......"uuid" : "887bca30-2439-11e8-d8c5-00000000078b", "log_name" : "epmp_events-fdr-2018-03-10", "operation" : "LAUNCH"}],
"total" : 14,
"next" : "DnF1ZXJ5VGhlbkZldGNoBgAAAAAABAAAAAftnBZUb0doSDlVNlFwMmtyYXpqQ1FaU19BAAAAAAVG9Hag5VTZRcDJrcmF6akRWlNfQQAAAAAAB-"}

5.3. Incidents API example

5.3.1. Incidents query API example

POST /atpapi/v2/incidents

Warning

Unless specifically mentioned, the following examples can potentially return unstable results. Refer Stable Results section for how to make them return stable results.

Sample Requests

Example 11. Return all incidents for the last 30 days

{
   "verb":"query"
}

Example 12. Return only ten incidents created/updated between 2016-06-08T15:39:55.616Z and now

{
   "verb":"query",
   "query":"updated:[2016-06-08T15:39:55.616Z TO *]",
   "limit":10
}

Example 13. Return incidents between 2016-06-08T15:39:55.616Z and now and time range between 2016-06-08T15:39:55.616Z and 2016-06-11T15:39:55.616Z

{
   "verb":"query",
   "query":"updated:[2016-06-08T15:39:55.616Z TO *]",
   "start_time":"2016-06-08T15:39:55.616Z",
   "end_time":"2016-06-11T15:39:55.616Z"
}

Example 14. Same as #11 but limited to updated < 6/7/2016

{
   "verb":"query",
   "query":"updated:{2016-06-06T15:39:55.616Z TO 2016-06-07T00:00:00.000Z}",
   "start_time":"2016-06-06T15:39:55.616Z",
   "end_time":"2016-06-07T00:00:00.000Z"
}

Sample HTTP Request

POST /atpapi/v2/incidents HTTP/1.1
Host: 10.3.106.17
Accept: application/json
Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ
Content-Type: application/json

Sample Request Body

{
    "verb" : "query",
    "query" : "updated:[2018-03-12T00:00:00.000Z TO 2018-03-15T23:59:59.999Z]"
}

Sample Response Body

{
   "next":null,
   "result":[
      {
         "atp_incident_id":100001,
         "device_time":"2018-03-13T03:06:25.063Z",
         "first_event_seen":"2018-03-13T03:06:24.800Z",
         "last_event_seen":"2018-03-13T03:06:24.800Z",
         "log_name":"epmp_incident-2018-03-13",
         "priority_level":3,
         "recommended_action":"You can isolate the endpoint(s), remove the file(s) and/or clean the system(s).",
         "state":1,
         "summary":"Sandbox detection: shample[1].exe",
         "time":"2018-03-13T03:06:25.063Z",
         "updated":"2018-03-13T03:06:25.063Z",
         "uuid":"83dfab70-266b-11e8-f6fc-000000000002"
      },
      {
         "atp_incident_id":100000,
         "device_time":"2018-03-12T19:51:01.530Z",
         "first_event_seen":"2018-03-12T19:47:23.746Z",
         "last_event_seen":"2018-03-12T19:49:36.699Z",
         "log_name":"epmp_incident-2018-03-12",
         "priority_level":3,
         "recommended_action":"Investigate the downloaded content and download sites. Isolate and remediate affected endpoints and delete/clean infected files if they have not been blocked already by Symantec Endpoint Protection. Investigate further activity at the endpoint by downloading a full dump of the endpoint's recorded data.",
         "state":1,
         "summary":"Suspicious PowerShell detected: content downloaded from a remote location and executed",
         "time":"2018-03-12T19:51:01.530Z",
         "updated":"2018-03-12T20:09:01.693Z",
         "uuid":"b108dfa0-262e-11e8-eeae-000000000001"
      }
   ],
   "total":2
}

5.3.2. Patch Incidents API example

PATCH /atpapi/v2/incidents

Close incidents example

Sample HTTP Request

PATCH /atpapi/v2/incidents HTTP/1.1
Host: 10.3.106.17
Accept: application/json
Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ
Content-Type: application/json

Sample Request Body

[
   {
      "op":"replace",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/state",
      "value":4
   }
]

Sample Request Body

[
   {
      "op":"replace",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/resolution",
      "value":2
   }
]

Sample Request Body

[
   {
      "op":"replace",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/state",
      "value":4
   },
   {
      "op":"replace",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/resolution",
      "value":1
   }
]

Sample Request Body (Multiple Incidents)

[
   {
      "op":"replace",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/state",
      "value":4
   },
   {
      "op":"replace",
      "path":"/372e7ac0-f9d6-11e7-df30-000000000067/state",
      "value":4
   }
   {
      "op":"replace",
      "path":"/372e7ac0-f9d6-11e7-df30-000000000067/resolution",
      "value":2
   }
]

Sample Response

204 No content.
Add comments example

Sample HTTP Request

PATCH /atpapi/v2/incidents HTTP/1.1
Host: 10.3.106.17
Accept: application/json
Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ
Content-Type: application/json

Sample Request Body

[
   {
      "op":"add",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/comments",
      "value":"API test"
   }
]

Sample Request Body (Multiple Incidents)

[
   {
      "op":"add",
      "path":"/60ce3400-fa9f-11e7-eedb-00000000007d/comments",
      "value":"API testing"
   },
   {
      "op":"add",
      "path":"/372e7ac0-f9d6-11e7-df30-000000000067/comments",
      "value":"Public API testing"
   }
]

Sample Response

204 No content.

5.3.3. Incident comments query API example

POST /atpapi/v2/incidents/{uuid}/comments

Sample Requests

Example 15. Return all incident comments for the last 30 days

{
   "verb":"query"
}

Example 16. Return incident comments between 2016-06-08T15:39:55.616Z and 2016-06-11T15:39:55.616Z

{
   "verb":"query",
   "start_time":"2016-06-08T15:39:55.616Z",
   "end_time":"2016-06-11T15:39:55.616Z"
}

Sample HTTP Request

POST /atpapi/v2/incidents/b108dfa0-262e-11e8-eeae-000000000001/comments HTTP/1.1
Host: 10.3.106.17
Accept: application/json
Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ
Content-Type: application/json

Sample Request Body

{
   "verb":"query"
}

Sample Response Body

{
   "next":null,
   "result":[
      {
         "comment":"Pending Investigation",
         "time":"2018-03-15T09:24:24.491Z",
         "user_id":2
      }
   ],
   "total":1
}

POST /atpapi/v2/incidentevents

Warning

Unless specifically mentioned, the following examples can potentially return unstable results. Refer Stable Results section for how to make these calls return stable results.

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJOX2gzbzhXaFNGQ01raDFJbWZhZ2JRIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSndGZVJEWThRQk9EM2dMZVhNM2dHUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmgzdWdpc2c1MDJmYjA3M2Y4dGhvbHRiOWIzXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uaDN1Z2lzZzUwMmZiMDczZjh0aG9sdGI5YjNcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODAwMTQzOCwiaWF0IjoxNTE3OTk3ODM4LCJqdGkiOiI1amExQzFlMFFjQ3BneTNOMEZLQXhBIn0.OmBRr4NH83U5ifGKHTm1FY1542_m-46u2e82mochGpd8sSsrhgw45MU10x5jfUM1B4vdXK1zpHg2rsI2vjNm7r3qHO-XfE4adpGpKf-zTqJ20eNq1fmu48AEOdppJG3Z--gTgzuAsdhsAbsRhDCTwfzyg1FD7ci5FKF_AXzI1WOVGaFonpwrnLfED1r94TdQa9Hof1IH291sGo5Ag-irWVgM9ZNcfnabOS8SP1tgiJP3tUlLLiAGnE2yDcgm_QRGYOucg-eG4nQGj1_SJDNwVKY-OjAUTLHcH8eoKl1TLBjXrGXa1oKYThq6MEls9F9Ubf_uwGmTdRQXT5GQ8YeuIw" "https://192.168.1.15/atpapi/v2/incidentevents"

Sample Request Body

{
   "verb":"query",
   "limit":"1"
}

Sample Response Body

{
    "next": "MSwyMDE4LTAyLTA3VDEwOjEzOjM3LjU0N1o=",
    "result": [
        {
            "count": 1,
            "data_source_url": "http://www.test.com",
            "data_source_url_domain": "www.test.com",
            "data_source_url_referer": "http://www.firstpage.com",
            "device_name": "10.127.168.20",
            "device_time": "2018-01-25T17:50:46.155Z",
            "device_uid": "b937f5a2-1a4c-408b-ab3d-19854a1db918",
            "direction": 4,
            "external_ip": "12.34.56.78",
            "external_port": 5605,
            "incident": "56776010-0767-11e8-dba9-000000000013",
            "internal_ip": "192.168.1.1",
            "internal_port": 1234,
            "log_name": "epmp_incident-2018-02-01",
            "log_time": "2018-01-26T17:50:46.515Z",
            "reason": 2,
            "resolution": 1,
            "scanner_name": "atp-symc.1",
            "severity_id": 1,
            "source": "Customer Supplied",
            "type_id": 4112,
            "uuid": "6ff65b40-02c1-11e8-d998-000000001ea6"
        }
    ],
    "total": 1443
}

Sample Requests

Example 17. Return all incident-related events for the last 30 days

{
   "verb":"query"
}

Example 18. Return all incident-related events between 2016-06-08T15:39:55.616Z and now

{
   "verb":"query",
   "query":"log_time:[2016-06-08T15:39:55.616Z TO *]"
}

Example 19. Return incident related events with typeId 4096 or 4098 or 4123 for the last 30 days

{
   "verb":"query",
   "query":"type_id:(4096 OR 4098 OR 4123)"
}

Example 20. Return incident related events with type_id 4096 or 4098 or 4123 between 2016-06-08T15:39:55.616Z and now and time range between 2016-06-08T15:39:55.616Z and 2016-06-31T15:39:55.616Z

{
   "verb":"query",
   "query":"log_time:[2016-06-08T15:39:55.616Z TO *] AND (type_id:(4096 OR 4098 OR 4123))",
   "start_time":"2016-06-08T15:39:55.616Z",
   "end_time":"2016-06-31T15:39:55.616Z"
}

Example 21. Same as #18 but limited to logtime < 6/7/2016

{
   "verb":"query",
   "query":"log_time :{2016-06-06T15:39:55.616Z TO 2016-06-07T00:00:00.000Z} AND  (type_id:(4096 OR 4098 OR 4123))",
   "start_time":"2016-06-06T15:39:55.616Z",
   "end_time":"2016-06-07T00:00:00.000Z"
}

5.5. Commands API example

5.5.1. Issue command action API example

POST /atpapi/v2/commands

Isolate endpoint example

Sample Curl Request to issue an isolate_endpoint action

curl -XPOST -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJVWkZZQUhyNFFUZTA5aVBqMVN4THdBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvNkR6Q3F2NVdTUWlqakpQbHdsTmhRd1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5oanZvaTVpdWMwcTBwZHAzaWViZ3VuZDlqMFwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmhqdm9pNWl1YzBxMHBkcDNpZWJndW5kOWowXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjczMzI3NzAsImlhdCI6MTQ2NzMyOTE3MCwianRpIjoiVlNHUVBQYTBRZGVGa091WllVMkdmZyJ9.ClfqMnDv-13ckgxaFRRbA1_1KXODvmcP5EO9pfszpRAMEtxhGtOqkHlBA83yEQVlcmMMPvfHEYY-PkkzZIFAgHQZdgXtsNCxf-nlsZ6coQR1KaNWEduF4s2F6ecDFDw5NwJIOHqXbcqNuYoj-r-RApNohdVEPnSANVK8M6WEB5SNzhzK0LKdk3MAVeKXRkNTNiAqeuu7GVvCPW8f_6Tq4qiJ5fpa9xR8chwKKaP-xEp3gIKCsvmMLI64tOHEpzq539P22Q2mEi9jaVdlrfDVPs3wc5uC6UfFEfWS_TgFDQ5kNHt3Zh9MCAQKlqZxCHPl-T6BEhAf0C0nf9mVArhBhg" -H "Content-Type: application/json" -k 'https://10.0.43.171/atpapi/v2/commands' -d '{"action":"isolate_endpoint", "targets":["cb46d251-151d-4583-a8fb-ebff7c42cfd8"]}'

Sample Request Body

{
   "action":"isolate_endpoint",
   "targets":[
      "cb46d251-151d-4583-a8fb-ebff7c42cfd8"
   ]
}

Sample Response Body

{
    "command_id": "55d51d343824463c896a4cf1a1d00585-2018-02-20",
    "error_code": 0,
    "message": "Command isolate_endpoint successfully requested"
}
Rejoin endpoint example

Sample Curl Request to issue a rejoin_endpoint action

curl -XPOST -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJVWkZZQUhyNFFUZTA5aVBqMVN4THdBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvNkR6Q3F2NVdTUWlqakpQbHdsTmhRd1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5oanZvaTVpdWMwcTBwZHAzaWViZ3VuZDlqMFwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmhqdm9pNWl1YzBxMHBkcDNpZWJndW5kOWowXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjczMzI3NzAsImlhdCI6MTQ2NzMyOTE3MCwianRpIjoiVlNHUVBQYTBRZGVGa091WllVMkdmZyJ9.ClfqMnDv-13ckgxaFRRbA1_1KXODvmcP5EO9pfszpRAMEtxhGtOqkHlBA83yEQVlcmMMPvfHEYY-PkkzZIFAgHQZdgXtsNCxf-nlsZ6coQR1KaNWEduF4s2F6ecDFDw5NwJIOHqXbcqNuYoj-r-RApNohdVEPnSANVK8M6WEB5SNzhzK0LKdk3MAVeKXRkNTNiAqeuu7GVvCPW8f_6Tq4qiJ5fpa9xR8chwKKaP-xEp3gIKCsvmMLI64tOHEpzq539P22Q2mEi9jaVdlrfDVPs3wc5uC6UfFEfWS_TgFDQ5kNHt3Zh9MCAQKlqZxCHPl-T6BEhAf0C0nf9mVArhBhg" -H "Content-Type: application/json" -k 'https://10.212.24.158/atpapi/v2/commands' -d '{"action":"rejoin_endpoint", "targets":["cb46d251-151d-4583-a8fb-ebff7c42cfd8"]}'

Sample Request Body

{
   "action":"rejoin_endpoint",
   "targets":[
      "cb46d251-151d-4583-a8fb-ebff7c42cfd8"
   ]
}

Sample Response Body

{
    "command_id": "cadc68b84f594064afdff42f2c46fe3f-2018-02-20",
    "error_code": 0,
    "message": "Command rejoin_endpoint successfully requested"
}
Get file example

Sample Curl Request to issue a get_endpoint_file action

curl -XPOST "https://10.212.24.240/atpapi/v2/commands" -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJYeXRLbS03QlJWcXNpVGhQR3VuNvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5yODNmdHFkZzM2MTFtaTI1ZHZyc3E5bmp1aFwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnI4M2Z0cWRnMzYxMW1pMjVkdnJzcTluanVoXCJ9IiwidmVyIjoxLCJpc3MiOiJpgAYAClVCvGLDGEA0QQz6uaoXpBcbZwWr8_G8452pytenSbNeqK4anaox4Yf1SLLT5LI4wjiNOtgVNQTwp98uVfWvw5cFLADeKLh9frhls9q_Qa_-
JioJli_9Y60A7hAJFxjYH7cSnTUyy8EyziVVOXc2o-fKDWuUYs_WyGKcJkoLlFwdf03ypcfJp9td5xtUB0lwJhd8kSfaYnGsTl5OMcF9j7haoMIsyGK5ya4wdtLWTsbN3f3L8NRp_UcIwsVecQkC_ZlidaIKfXgLRN7Aog" -H "Content-Type: application/json" -d '{"action":"get_endpoint_file", "targets":[{"hash":"86263727095009b136c832b851b3d9b329352d60a1ecc251d4a309d44a407c3b","device_uid":"52cabbae-86cf-4612-a980-4c7a838d90d1"}]}'

Sample Request Body

{
   "action":"get_endpoint_file",
   "targets":[
      {
        "hash" : "86263727095009b136c832b851b3d9b329352d60a1ecc251d4a309d44a407c3b",
        "device_uid" : "52cabbae-86cf-4612-a980-4c7a838d90d1"
      }
   ]
}

Sample Response Body

{
    "command_id": "1ebc5d45c4814816b8d9c6596cdc252b-2018-02-21",
    "error_code": 0,
    "message": "Command get_endpoint_file successfully requested."
}
Delete file example

Sample Curl Request to issue a delete_file action

curl -XPOST -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJVWkZZQUhyNFFUZTA5aVBqMVN4THdBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvNkR6Q3F2NVdTUWlqakpQbHdsTmhRd1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5oanZvaTVpdWMwcTBwZHAzaWViZ3VuZDlqMFwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmhqdm9pNWl1YzBxMHBkcDNpZWJndW5kOWowXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjczMzI3NzAsImlhdCI6MTQ2NzMyOTE3MCwianRpIjoiVlNHUVBQYTBRZGVGa091WllVMkdmZyJ9.ClfqMnDv-13ckgxaFRRbA1_1KXODvmcP5EO9pfszpRAMEtxhGtOqkHlBA83yEQVlcmMMPvfHEYY-PkkzZIFAgHQZdgXtsNCxf-nlsZ6coQR1KaNWEduF4s2F6ecDFDw5NwJIOHqXbcqNuYoj-r-RApNohdVEPnSANVK8M6WEB5SNzhzK0LKdk3MAVeKXRkNTNiAqeuu7GVvCPW8f_6Tq4qiJ5fpa9xR8chwKKaP-xEp3gIKCsvmMLI64tOHEpzq539P22Q2mEi9jaVdlrfDVPs3wc5uC6UfFEfWS_TgFDQ5kNHt3Zh9MCAQKlqZxCHPl-T6BEhAf0C0nf9mVArhBhg" -H "Content-Type: application/json" -k 'https://10.212.24.158/atpapi/v2/commands' -d '{"action":"delete_endpoint_file", "targets":[{"hash":"8692251329fef60490be1c26281710b7e88250fd82b3f679f87d6785db854ed5","device_uid":"cb46d251-151d-4583-a8fb-ebff7c42cfd8"}]}'

Sample Request Body

{
   "action":"delete_endpoint_file",
   "targets":[
      {
         "hash":"8692251329fef60490be1c26281710b7e88250fd82b3f679f87d6785db854ed5",
         "device_uid":"cb46d251-151d-4583-a8fb-ebff7c42cfd8"
      }
   ]
}

Sample Response Body

{
    "command_id": "f1958f013f8240c29233c0d34b4dcf09-2018-02-20",
    "error_code": 0,
    "message": "Command delete_endpoint_file successfully requested"
}
Recorder search example

Sample Curl Request to issue a recorder_search action

curl -XPOST "https://10.212.24.158/atpapi/v2/commands" -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJYeXRLbS03QlJWcXNpVGhQR3VuakJ3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvQ2U5dlVZY2NTV1dSOU42eDdVR0E3QVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuY9lcG1wX2lfYWxkb21haW4iLCJleHAiOjE1MTYyMjA5NTYsImlhdCI6MTUxNjIxNzM1NiwianRpIjoiTVp0YmdSNTBRXzJxWjZUQ0Q4TWFIUSJ9.OudYzo3zSHztLGQMlCEdr1jDKURgLLrnEWJgeBFpFPqHweY3rPGMvaJ7oQFzdIRvgAYAClVCvGLDGEA0QQz6uaoXpBcbZwWr8_G8452pytenSbNeqK4anaox4Yf1SLLT5LI4wjiNOtgVNQTwp98uVfWvw5cFLADeKLh9frhls9q_Qa_-JioJli_9Y60A7hAJFxjYH7cSnTUyy8EyziVVOXc2o-fKDWuUYs_WyGKcJkoLlFwdf03ypcfJp9td5xtUB0lwJhd8kSfaYnGsTl5OMcF9j7haoMIsyGK5ya4wdtLWTsbN3f3L8NRp_UcIwsVecQkC_ZlidaIKfXgLRN7Aog" -H "Content-Type: application/json" -d '{"action":"recorder_search", "targets":[{"device_uids":["a4110728-6fac-4aa4-98a4-db2bd1be20d8"],"hostnames":["170915-000042"], "sepm_groups":["My Company\\10K"], "ipv4_addresses":["10.212.24.159"]}], "start_time":"2018-01-01T00:00:00.000Z", "end_time":"2018-01-10T00:00:00.000Z", "query": "file.path:\"c:\\\\windows\\\\svchost.exe\""}'

Sample Request Body

{
   "action":"recorder_search",
   "targets":[
      {
         "device_uids":[
            "a4110728-6fac-4aa4-98a4-db2bd1be20d8"
         ],
         "hostnames":[
            "170915-000042"
         ],
         "sepm_groups":[
            "My Company\\10K"
         ],
         "ipv4_addresses":[
            "10.212.24.159"
         ]
      }
   ],
   "start_time":"2018-01-01T00:00:00.000Z",
   "end_time":"2018-01-10T00:00:00.000Z",
   "query":"file.path:\"c:\\\\windows\\\\svchost.exe\""
}
Note

The search is initiated on all matching endpoints based on those endpoint’s matching sepm_groups, ipv4_addresses, hostnames, and device_uids.

Sample Response Body

{
    "command_id": "822c2032b4184e58a55cdd85e68a6cf6-2018-02-20",
    "error_code": 0,
    "message": "Command recorder_search successfully requested"
}
EOC search example

Sample Curl Request to issue an eoc_search action

curl -XPOST "https://10.212.24.158/atpapi/v2/commands" -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJYeXRLbS03QlJWcXNpVGhQR3VuakJ3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvQ2U5dlVZY2NTV1dSOU42eDdVR0E3QVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuY9lcG1wX2lfYWxkb21haW4iLCJleHAiOjE1MTYyMjA5NTYsImlhdCI6MTUxNjIxNzM1NiwianRpIjoiTVp0YmdSNTBRXzJxWjZUQ0Q4TWFIUSJ9.OudYzo3zSHztLGQMlCEdr1jDKURgLLrnEWJgeBFpFPqHweY3rPGMvaJ7oQFzdIRvgAYAClVCvGLDGEA0QQz6uaoXpBcbZwWr8_G8452pytenSbNeqK4anaox4Yf1SLLT5LI4wjiNOtgVNQTwp98uVfWvw5cFLADeKLh9frhls9q_Qa_-JioJli_9Y60A7hAJFxjYH7cSnTUyy8EyziVVOXc2o-fKDWuUYs_WyGKcJkoLlFwdf03ypcfJp9td5xtUB0lwJhd8kSfaYnGsTl5OMcF9j7haoMIsyGK5ya4wdtLWTsbN3f3L8NRp_UcIwsVecQkC_ZlidaIKfXgLRN7Aog" -H "Content-Type: application/json" -d '{"action":"eoc_search", "targets":[{"device_uids":["a4110728-6fac-4aa4-98a4-db2bd1be20d8"],"hostnames":["170915-000042"], "sepm_groups":["My Company\\10K"], "ipv4_addresses":["10.212.24.159"]}], "query": "file.path:\"c:\\\\windows\\\\dllhost.exe\""}'

Sample Request Body

{
   "action":"eoc_search",
   "targets":[
      {
         "device_uids":[
            "a4110728-6fac-4aa4-98a4-db2bd1be20d8"
         ],
         "hostnames":[
            "170915-000042"
         ],
         "sepm_groups":[
            "My Company\\10K"
         ],
         "ipv4_addresses":[
            "10.212.24.159"
         ]
      }
   ],
   "query":"file.path:\"c:\\\\windows\\\\dllhost.exe\""
}
Note

The search is initiated on all matching endpoints based on those endpoint’s matching sepm_groups, ipv4_addresses, hostnames, and device_uids.

Sample Response Body

{
    "command_id": "de9a10b993ec4980a774a268f55ed1c0-2018-02-20",
    "error_code": 0,
    "message": "Command eoc_search successfully requested"
}
Cancel command example

Sample Curl Request to issue a cancel_command action

curl -XPOST "https://10.212.24.158/atpapi/v2/commands" -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJYeXRLbS03QlJWcXNpVGhQR3VuNvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5yODNmdHFkZzM2MTFtaTI1ZHZyc3E5bmp1aFwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnI4M2Z0cWRnMzYxMW1pMjVkdnJzcTluanVoXCJ9IiwidmVyIjoxLCJpc3MiOiJpgAYAClVCvGLDGEA0QQz6uaoXpBcbZwWr8_G8452pytenSbNeqK4anaox4Yf1SLLT5LI4wjiNOtgVNQTwp98uVfWvw5cFLADeKLh9frhls9q_Qa_-JioJli_9Y60A7hAJFxjYH7cSnTUyy8EyziVVOXc2o-fKDWuUYs_WyGKcJkoLlFwdf03ypcfJp9td5xtUB0lwJhd8kSfaYnGsTl5OMcF9j7haoMIsyGK5ya4wdtLWTsbN3f3L8NRp_UcIwsVecQkC_ZlidaIKfXgLRN7Aog" -H "Content-Type: application/json" -d '{"action":"cancel_command", "targets":["b82e0bcd3b4f4433940f2bd1eddf02fc-2018-01-17"]}'

Sample Request Body

{
   "action":"cancel_command",
   "targets":[
      "b82e0bcd3b4f4433940f2bd1eddf02fc-2018-01-17"
   ]
}

Sample Response Body

{
    "command_id": "b82e0bcd3b4f4433940f2bd1eddf02fc-2018-01-17",
    "error_code": 0,
    "message": "Command cancel_command successfully requested."
}

5.5.2. Command status query API example

POST /atpapi/v2/commands/{command_id}

Sample Requests

Example 22. Return all target status objects for the specified command_id

{
  "verb":"query"
}

Sample HTTP Request

POST /atpapi/v2/commands/2522791ee5b246039cdfc2f96896fe00-2018-03-15 HTTP/1.1
Host: 10.3.106.17
Accept: application/json
Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ
Content-Type: application/json

Sample Request Body

{
    "verb" : "query",
    "limit" : 1
}

Sample Response

{
    "next": "MSwyLGNvbXBsZXRlZCwyNTIyNw==",
    "state": "completed",
    "status": [
        {
            "error_code": 6002,
            "message": "Search completed on the endpoint with results but only partial results are uploaded due to ATP data limits",
            "state": 0,
            "target": "b092267d-0f84-4e9c-931d-b30ea46dc32e"
        }
    ],
    "total": 2
}

5.5.3. Command results query API example

POST /atpapi/v2/commands/{command_id}/results

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJOX2gzbzhXaFNGQ01raDFJbWZhZ2JRIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSndGZVJEWThRQk9EM2dMZVhNM2dHUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmgzdWdpc2c1MDJmYjA3M2Y4dGhvbHRiOWIzXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uaDN1Z2lzZzUwMmZiMDczZjh0aG9sdGI5YjNcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODAwMTQzOCwiaWF0IjoxNTE3OTk3ODM4LCJqdGkiOiI1amExQzFlMFFjQ3BneTNOMEZLQXhBIn0.OmBRr4NH83U5ifGKHTm1FY1542_m-46u2e82mochGpd8sSsrhgw45MU10x5jfUM1B4vdXK1zpHg2rsI2vjNm7r3qHO-XfE4adpGpKf-zTqJ20eNq1fmu48AEOdppJG3Z--gTgzuAsdhsAbsRhDCTwfzyg1FD7ci5FKF_AXzI1WOVGaFonpwrnLfED1r94TdQa9Hof1IH291sGo5Ag-irWVgM9ZNcfnabOS8SP1tgiJP3tUlLLiAGnE2yDcgm_QRGYOucg-eG4nQGj1_SJDNwVKY-OjAUTLHcH8eoKl1TLBjXrGXa1oKYThq6MEls9F9Ubf_uwGmTdRQXT5GQ8YeuIw" "https://10.212.24.158/atpapi/v2/commands/3fcf0817550a43de8a3fec612e3cf98d-2018-03-14/results"

Sample Request Body

{
    "next": "TVN3eU1ERTRMVEF6TFRJMlZESXdPakUyT2pBM0xqZzRNbG89LDNmY2Yw",
    "result": [
        {
            "device_domain": "workgroup",
            "device_ip": "10.212.24.160",
            "device_name": "170915-000042",
            "device_os_name": "Microsoft Windows 7 Ultimate",
            "device_time": "2018-03-12T11:03:00.203Z",
            "device_uid": "c2937757-3968-4eb2-a1f3-4f7efbfdaafd",
            "event_actor": {
                "cmd_line": "C:\\Windows\\system32\\vssvc.exe",
                "file": {
                    "md5": "b60ba0bc31b0cb414593e169f6f21cc2",
                    "modified": "2010-11-21T03:23:55.360Z",
                    "name": "vssvc.exe",
                    "normalized_path": "CSIDL_SYSTEM\\vssvc.exe",
                    "path": "c:\\windows\\system32\\vssvc.exe",
                    "sha2": "47b801e623254cf0202b3591cb5c019cabfb52f123c7d47e29d19b32f1f2b915",
                    "signature_company_name": "Microsoft Windows"
                },
                "pid": 5168,
                "user": {
                    "name": "SYSTEM",
                    "sid": "S-1-5-18"
                }
            },
            "file": {
                "attributes": 32,
                "folder": "c:\\windows\\system32",
                "name": "rpcrt4.dll",
                "normalized_path": "CSIDL_SYSTEM\\rpcrt4.dll",
                "path": "c:\\windows\\system32\\rpcrt4.dll"
            },
            "log_name": "atp_cmd_results-search-fdr-3fcf0817550a43de8a3fec612e3cf98d-2018-03-14",
            "log_time": "2018-03-14T10:36:06.378Z",
            "operation": 6,
            "severity_id": 1,
            "type_id": 8003,
            "user_name": "SYSTEM",
            "uuid": "ed7e03b0-25e4-11e8-d1f9-00000018941a"
        }
    ],
    "total": 200
}

Sample Requests

Example 23. Return all command results for the command_id

{
  "verb":"query"
}

Example 24. Return all command results returned from device_ip 10.212.24.159

{
  "verb":"query",
  "query":"device_ip:10.212.24.159"
}

Example 25. Return command results with type_id 8001 or 8002 or 8003

{
  "verb":"query",
  "query":"type_id:(8001 OR 8002 OR 8003)"
}

5.6. Entities API example

  • Search expressions should be written in the format: Token: the term that you want to search for

  • Values that are the string data type must be enclosed in quotes.

  • The date value should follow ISO 8601 date stamp standard format (i.e., yyyy-MM-dd’T’HH:mm:ss.SSSXXX).

  • Escape special characters that are part of the query syntax. Special characters are as follows: " - && || ! ( ) { } [ ] ^ " ~ * ? : "

  • Boolean operators must be ALL CAPS. Supported Boolean operators are: AND, OR, +, -, NOT

  • You can specify ranges for the date, numeric, or string fields. Inclusive ranges are specified with square brackets [min TO max] and exclusive ranges with curly brackets {min TO max}.

  • You can combine curly and square brackets in ranges. For example, to get a count of numbers from 1 up to, but not including 5, the search expression would be: count:[1..5}

5.6.1. All entities query API example

POST /atpapi/v2/entities

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTExMjY3NTM1MTswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQW1LeHdXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "file_health": 4,
            "first_seen": "2018-03-12T19:25:41.708Z",
            "is_targeted": false,
            "last_seen": "2018-03-14T10:21:09.297Z",
            "md5": "30b02b4d8e5c95aa25b864d9be46e54e",
            "name": "shample[1].exe",
            "prevalence_band": 0,
            "sandbox_verdict": "malware",
            "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9",
            "size": 33824,
            "type": "file_latest"
        }
    ],
    "total": 2
}

Sample Requests

Example 26. Returns entities with device_name “SEP-Only”

{
    "verb":"query",
    "query":"device_name:SEP-Only"
}

Example 27. Returns entities with ip_addresses “192.168.0.40”

{
   "verb":"query",
   "query":"ip_addresses:192.168.0.40"
}

Example 28. Returns entities with ip_addresses between “192.168.0.40” and “192.168.0.45”

{
   "verb":"query",
   "query":"ip_addresses:[192.168.0.40 TO 192.168.0.45]"
}

Example 29. Returns entities with mac_addresses “00-50-56-A4-10-29”

{
   "verb":"query",
   "query":"mac_addresses:00-50-56-A4-10-29"
}

Example 30. Returns entities with mac_addresses between “00-50-56-A4-10-29” and all

{
   "verb":"query",
   "query":"mac_addresses:[00-50-56-A4-10-29 TO *]"
}

Example 31. Returns entities with operating_system.osfullname "Windows 7 Enterprise Edition"

{
   "verb":"query",
   "query":"operating_system.osfullname:\"Windows 7 Enterprise Edition\""
}

5.6.2. Domain entities query API example

POST /atpapi/v2/entities/domains

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities/domains"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTExMjgyMjg0MzswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQW1LNU1XVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "data_source_url": "http://www.westfallave.com/insight/cloudcar.exe",
            "data_source_url_domain": "westfallave.com",
            "disposition": 1,
            "external_ip": "78.129.245.143",
            "first_seen": "2018-03-12T19:25:15.095Z",
            "last_seen": "2018-03-14T18:34:07.000Z",
            "type": "external_domain_latest"
        }
    ],
    "total": 3
}

Sample Requests

Example 32. Returns domain entity with data_source_url : http://www.westfallave.com/insight/cloudcar.exe

{
   "verb":"query",
   "query":"data_source_url:\"http://www.westfallave.com/insight/cloudcar.exe\""
}

Example 33. Returns domain entity with external_ip : 95.131.109.32

{
   "verb":"query",
   "query":"external_ip:95.131.109.32"
}

Example 34. Returns domain entity with data_source_url_domain : westfallave.com

{
   "verb":"query",
   "query":"data_source_url_domain:westfallave.com"
}

Example 35. Returns domain entity with dispostion : 2 (suspicious)

{
   "verb":"query",
   "query":"disposition:2"
}

5.6.3. Domain instances query API example

POST /atpapi/v2/entities/domains/instances

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities/domains/instances"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTEzOTA4OTk1MzswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXFYTzhXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "data_source_url": "http://www.westfallave.com/insight/cloudcar.exe",
            "data_source_url_domain": "westfallave.com",
            "disposition": 1,
            "external_ip": "78.129.245.143",
            "first_seen": "2018-03-12T19:25:15.095Z",
            "last_seen": "2018-03-12T19:31:07.526Z"
        }
    ],
    "total": 6
}

Sample Requests

Example 36. Returns domain instances with external_ip : 95.131.109.32

{
   "verb":"query",
   "query":"external_ip:95.131.109.32"
}

5.6.4. Domain instances by domain name query API example

POST /atpapi/v2/entities/domains/{data_source_url_domain}/instances

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODk1NDIyMiwiaWF0IjoxNTE4OTUwNjIyLCJqdGkiOiJEMHB0Mk5tNlNLLUdzQzBLQnZscUVRIn0.ZmgTCf7kMNHqVooCmcni7VU-xNXrn9Qy8rzkjXnEFxGwJVW7_ay4vFg7TG9_opGkod-Ajnu57MAuEaPBLU5yWKpHafZEPR1edBo8WU2n3OVKeT0rK2yRBruB6bti1v8fFe0tDryCAfMfEKj83QyYJR-MXv2ZJ-X4bSSc_hNp8kr1y2R9Sd0d3yVInI6QXgmu1yoRv0pSMnDMa6xsCoE4BAbGsjSFlPCWDlFQcO4gG0yKafjuOc03jysaf4MigYpGLyxcwjRsLc4GNWko2tOWTqjAW-VV1TfmJ6ib_Qbl-AwvRaL_vYUrVqZDVzlF8pkLsJ2fl7rqAK2Dqu2-wwpfvg" -d '{ "verb":"query" }' "https://192.168.1.15/atpapi/v2/entities/domains/westfallave.com/instances"

Sample Request Body

{
    "verb":"query"
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTEzOTI1OTMwNzswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXFjdlFXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "data_source_url": "http://www.westfallave.com/insight/cloudcar.exe",
            "data_source_url_domain": "westfallave.com",
            "disposition": 1,
            "external_ip": "78.129.245.143",
            "first_seen": "2018-03-12T19:25:15.095Z",
            "last_seen": "2018-03-12T19:31:07.526Z"
        },
        {
            "data_source_url_domain": "westfallave.com",
            "disposition": 1,
            "first_seen": "2018-03-13T18:34:07.000Z",
            "last_seen": "2018-03-15T18:34:07.000Z"
        }
    ],
    "total": 2
}

5.6.5. Endpoint entities query API example

POST /atpapi/v2/entities/endpoints

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities/endpoints"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTE0MDIyNjYxNjswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXE2RmdXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "agent_version": "14.0.3542.1000",
            "device_ip": "10.212.24.159",
            "device_name": "170915-000020",
            "device_uid": "b092267d-0f84-4e9c-931d-b30ea46dc32e",
            "disposition_endpoint": 0,
            "domain_or_workgroup": "WORKGROUP",
            "first_seen": "2018-03-12T18:49:57.085Z",
            "ip_addresses": [
                "10.212.24.159"
            ],
            "last_seen": "2018-03-15T18:30:21.257Z",
            "mac_addresses": [
                "00-0C-29-E8-26-ED"
            ],
            "managed_sepm_ip": "10.212.24.160",
            "managed_sepm_version": "14.0.3542.1000",
            "operating_system": {
                "is_64_bit": true,
                "osfullname": "Windows 7 Ultimate Edition"
            },
            "sep_group_summary": {
                "name": "My Company\\AtpGroup",
                "sep_domain_summary": {
                    "name": "Default"
                }
            },
            "type": "endpoint_latest",
            "user_name": "Administrator"
        }
    ],
    "total": 50003
}

Sample Requests

Example 37. Returns endpoint entities with device_name “SEP-Only”

{
    "verb":"query",
    "query":"device_name:SEP-Only"
}

Example 38. Returns endpoint entities with disposition_endpoint :2 (suspicious)

{
   "verb":"query",
   "query":"disposition_endpoint:2"
}

Example 39. Returns endpoint entities with device_uid : 37dab41d-877b-4fe2-9e86-053940e6b6e3

{
   "verb":"query",
   "query":"device_uid:37dab41d-877b-4fe2-9e86-053940e6b6e3"
}

5.6.6. Endpoint instances query API example

POST /atpapi/v2/entities/endpoints/instances

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities/endpoints/instances"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTE0MDQ3NTUzOTswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXE2S2tXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "device_ip": "10.212.24.159",
            "device_name": "170915-000020",
            "device_uid": "b092267d-0f84-4e9c-931d-b30ea46dc32e",
            "domain_or_workgroup": "WORKGROUP",
            "ip_addresses": [
                "10.212.24.159"
            ],
            "time": "2018-03-12T18:49:57.085Z"
        }
    ],
    "total": 50003
}

Sample Requests

Example 40. Returns endpoint instance with time >= 2018-02-15T01:07:45.254Z

{
   "verb":"query",
   "query":"time:[2018-02-15T01:07:45.254Z TO *]"
}

Example 41. Returns endpoint instances with hostname : W7ENT-SP1x64-v1

{
   "verb":"query",
   "query":"device_name:W7ENT-SP1x64-v1"
}

Example 42. Returns endpoint instances by time with or without hostname : W7ENT-SP1x64-v1

{
   "verb":"query",
   "query":"time:\"2018-02-15T01:07:45.254Z\" OR device_name:W7ENT-SP1x64-v1"
}

5.6.7. Endpoint instances by device_uid query API example

POST /atpapi/v2/entities/endpoints/{device_uid}/instances

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query", "limit":1}' "https://192.168.1.15/atpapi/v2/entities/endpoints/b092267d-0f84-4e9c-931d-b30ea46dc32e/instances"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTE0MDcwMDE0ODswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXE2UFVXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "device_ip": "10.212.24.159",
            "device_name": "170915-000020",
            "device_uid": "b092267d-0f84-4e9c-931d-b30ea46dc32e",
            "domain_or_workgroup": "WORKGROUP",
            "ip_addresses": [
                "10.212.24.159"
            ],
            "time": "2018-03-12T18:49:57.085Z"
        }
    ],
    "total": 2
}

5.6.8. File entities query API example

POST /atpapi/v2/entities/files

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities/files"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTE0MDkxMzI1MjswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXE2VU1XVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "file_health": 4,
            "first_seen": "2018-03-12T19:25:41.708Z",
            "is_targeted": false,
            "last_seen": "2018-03-14T10:21:09.297Z",
            "md5": "30b02b4d8e5c95aa25b864d9be46e54e",
            "name": "shample[1].exe",
            "prevalence_band": 0,
            "sandbox_verdict": "malware",
            "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9",
            "size": 33824,
            "type": "file_latest"
        }
    ],
    "total": 2
}

Sample Requests

Example 43. Returns file entities by file_health with 3 (Suspicious)

{
   "verb":"query",
   "query":"file_health:3"
}

Example 44. Returns file entities by sha2 with 49C5442985037E7E4C35A8840596A8347164A4FB42D2B19F69B833E9139B4366

{
   "verb":"query",
   "query":"sha2:49C5442985037E7E4C35A8840596A8347164A4FB42D2B19F69B833E9139B4366"
}

Example 45. Returns file entities by name with virus.exe

{
   "verb":"query",
   "query":"name:virus.exe"
}

5.6.9. File entity by SHA2 query API example

GET /atpapi/v2/entities/files/{sha2}

Curl Command Request

curl -XGET -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" "https://192.168.1.15/atpapi/v2/entities/files/bb711de8d59c4ad52858f7c39a77ce5439b92f78779fdf85bd445fb9c359c642"

Sample Response Body

{
   "file_health":4,
   "first_seen":"2018-03-12T19:25:41.708Z",
   "is_targeted":false,
   "last_seen":"2018-03-14T10:21:09.297Z",
   "md5":"30b02b4d8e5c95aa25b864d9be46e54e",
   "name":"shample[1].exe",
   "prevalence_band":0,
   "sandbox_verdict":"malware",
   "sha2":"4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9",
   "size":33824,
   "type":"file_latest"
}

5.6.10. File instances query API example

POST /atpapi/v2/entities/files/instances

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query","limit":1}' "https://192.168.1.15/atpapi/v2/entities/files/instances"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTE0MTAzNzI0MDswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXE2VVlXVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "first_seen": "2018-03-12T19:25:41.708Z",
            "folder": "csidl_profile\\appdata\\local\\microsoft\\windows\\temporary internet files\\content.ie5\\8k59dimc",
            "last_seen": "2018-03-12T19:25:41.708Z",
            "name": "shample[1].exe",
            "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9"
        }
    ],
    "total": 4
}

Sample Requests

Example 46. Returns file instances by name with virus.exe

{
   "verb":"query",
   "query":"name:virus.exe"
}

5.6.11. File instances by SHA2 query API example

POST /atpapi/v2/entities/files/{sha2}/instances

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query"}' "https://192.168.1.15/atpapi/v2/entities/files/4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9/instances"

Sample Request Body

{
    "verb":"query"
}

Sample Response Body

{
    "next": "ZW50aXRpZXM7MTUyMTE0MTEyMDUzOTswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQXE2VW9XVEZkTE9WRnRlV0ZSVUVjelVreEdhVmRJV0hSdFFRPT0=",
    "result": [
        {
            "first_seen": "2018-03-12T19:25:41.708Z",
            "folder": "csidl_profile\\appdata\\local\\microsoft\\windows\\temporary internet files\\content.ie5\\8k59dimc",
            "last_seen": "2018-03-12T19:25:41.708Z",
            "name": "shample[1].exe",
            "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9"
        },
        {
            "first_seen": "2018-03-13T03:06:24.800Z",
            "last_seen": "2018-03-13T03:06:24.800Z",
            "name": "shample[1].exe",
            "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9"
        }
    ],
    "total": 2
}

5.6.12. Release entities next field API example

DELETE /atpapi/v2/entities/next/{next}

Curl Command Request

curl -X DELETE -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODk2MTg3NiwiaWF0IjoxNTE4OTU4Mjc2LCJqdGkiOiJtRG05SUhpNlNiMkhDR0dkSWI3TF9nIn0.T0d0XFtHXm0YG3mF-X6LMuckPbnVUYSjAuOHZBx9yFchpstGtIvRZD785Ht6wWhiC4YVMqy7Y2Dului2_o3L5OGBVmVbgKqiKpqKsr8D0PD40AyMlzyOyELae955zAMeb5aZ6Kg7hd-IJ76elm2uWnDDfslfGQyZndSs3GrhzpnGbtAPnqqJJZ7mdpXaBugAQBplBcWfLfHpzFAIAP_w0_M37YfIdHC6xg_MpTqBQBoJcmGGfVRPqM7RZL-0B1NrW8-ZAztMdESte0Pp8mNKeaLk5VRZX-8yj8QFe-4SLBzGBJ6ifA8-f4lXS1C3UcdQi3J-nEW6FJjVKFaaeJuteA" 'https://192.168.1.15/atpapi/v2/entities/next/ZW50aXRpZXM7MTUxODk1ODY3NTQ3ODswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQUlTek1XUmpWVFJtaExWRGxVUjIxWlNYWlFNbGRsTFZwc1FRPT0='

Sample Response

204 No content.

5.7. Associations API examples

5.7.1. Domains files associations query API example

POST /atpapi/v2/associations/entities/domains-files

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query", "limit":1}' "https://192.168.1.15/atpapi/v2/associations/entities/domains-files"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "YXNzb2NpYXRpb25zOzE1MjExNDIwMjI1NzI7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUFxNmlzV1RGZExPVkZ0ZVdGUlVFY3pVa3hHYVZkSVdIUnRRUT09",
    "result": [
        {
            "data_source_url": "http://www.westfallave.com/insight/cloudcar.exe",
            "data_source_url_domain": "westfallave.com",
            "device_ip": "10.212.24.160",
            "device_name": "170915-000042",
            "device_uid": "c2937757-3968-4eb2-a1f3-4f7efbfdaafd",
            "first_seen": "2018-03-12T19:25:15.095Z",
            "last_seen": "2018-03-12T19:25:15.095Z",
            "name": "cloudcar[1].exe",
            "sha2": "3559378c933cdd434af2083f7535460843d2462033de74ec7c70dbe5f70124f5"
        }
    ],
    "total": 6
}

Sample Requests

Example 47. Returns domain file association by data_source_url_domain with westfallave.com

{
   "verb":"query",
   "query":"data_source_url_domain:westfallave.com"
}

Example 48. Returns domain file association by sha2 with 55668B98E05299B410E3ABAC01DD283059CC0E02FEC7F1DC1C6869DAD245A89A

{
   "verb":"query",
   "query":"sha2:55668B98E05299B410E3ABAC01DD283059CC0E02FEC7F1DC1C6869DAD245A89A"
}

5.7.2. Endpoints domains associations query API example

POST /atpapi/v2/associations/entities/endpoints-domains

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query", "limit":1}' "https://192.168.1.15/atpapi/v2/associations/entities/endpoints-domains"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "YXNzb2NpYXRpb25zOzE1MjExNDIwOTI5MzY7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUFxNm5ZV1RGZExPVkZ0ZVdGUlVFY3pVa3hHYVZkSVdIUnRRUT09",
    "result": [
        {
            "data_source_url": "http://www.westfallave.com/insight/cloudcar.exe",
            "data_source_url_domain": "westfallave.com",
            "device_ip": "10.212.24.160",
            "device_name": "170915-000042",
            "device_uid": "c2937757-3968-4eb2-a1f3-4f7efbfdaafd",
            "first_seen": "2018-03-12T19:25:15.095Z",
            "last_seen": "2018-03-12T19:25:15.095Z"
        }
    ],
    "total": 6
}

Sample Requests

Example 49. Returns endpoint domain association by device_uid with b937a5a2-1a4c-408b-ab3d-29854a1db018

{
   "verb":"query",
   "query":"device_uid:b937a5a2-1a4c-408b-ab3d-29854a1db018"
}

Example 50. Returns endpoint domain association by data_source_url_domain with westfallave.com

{
   "verb":"query",
   "query":"data_source_url_domain:westfallave.com"
}

5.7.3. Endpoints files associations query API example

POST /atpapi/v2/associations/entities/endpoints-files

Curl Command Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query", "limit":1}' "https://192.168.1.15/atpapi/v2/associations/entities/endpoints-files"

Sample Request Body

{
    "verb":"query",
    "limit":1
}

Sample Response Body

{
    "next": "YXNzb2NpYXRpb25zOzE1MjExNDIxODI5MDc7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUFxNm5jV1RGZExPVkZ0ZVdGUlVFY3pVa3hHYVZkSVdIUnRRUT09",
    "result": [
        {
            "device_ip": "10.212.24.159",
            "device_name": "170915-000020",
            "device_uid": "b092267d-0f84-4e9c-931d-b30ea46dc32e",
            "first_seen": "2018-03-10T07:59:49.818Z",
            "folder": "c:\\windows\\system32",
            "last_seen": "2018-03-16T03:19:56.047Z",
            "name": "svchost.exe",
            "sha2": "93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8"
        }
    ],
    "total": 3968
}

Sample Requests

Example 51. Returns endpoint file association by device_uid with b937e5a1-1a4c-408b-ab3d-29854a1db918

{
   "verb":"query",
   "query":"device_uid:b937a5a2-1a4c-408b-ab3d-29854a1db018"
}

Example 52. Returns endpoint file association by name with vjdrxiz6tvjw4xutcxlpzxh62t1.exe

{
   "verb":"query",
   "query":"name:vjdrxiz6tvjw4xutcxlpzxh62t1.exe"
}

5.7.4. Release associations next field API example

DELETE /atpapi/v2/associations/entities/next/{next}

Curl Command Request

curl -X DELETE -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODk2MTg3NiwiaWF0IjoxNTE4OTU4Mjc2LCJqdGkiOiJtRG05SUhpNlNiMkhDR0dkSWI3TF9nIn0.T0d0XFtHXm0YG3mF-X6LMuckPbnVUYSjAuOHZBx9yFchpstGtIvRZD785Ht6wWhiC4YVMqy7Y2Dului2_o3L5OGBVmVbgKqiKpqKsr8D0PD40AyMlzyOyELae955zAMeb5aZ6Kg7hd-IJ76elm2uWnDDfslfGQyZndSs3GrhzpnGbtAPnqqJJZ7mdpXaBugAQBplBcWfLfHpzFAIAP_w0_M37YfIdHC6xg_MpTqBQBoJcmGGfVRPqM7RZL-0B1NrW8-ZAztMdESte0Pp8mNKeaLk5VRZX-8yj8QFe-4SLBzGBJ6ifA8-f4lXS1C3UcdQi3J-nEW6FJjVKFaaeJuteA" 'https://192.168.1.15/atpapi/v2/associations/entities/next/ZW50aXRpZXM7MTUxODk1ODY3NTQ3ODswOkRYRjFaWEo1UVc1a1JtVjBZMmdCQUFBQUFBQUlTek1XUmpWVFJtaExWRGxVUjIxWlNYWlFNbGRsTFZwc1FRPT0='

Sample Response

204 No content.

5.8. Sandbox API examples

5.8.1. Sandbox command API example

POST /atpapi/v2/sandbox/commands

Sample HTTP Request

POST /atpapi/v2/sandbox/commands HTTP/1.1
Host: 192.168.1.15
Authorization: Bearer <OAUTH TOKEN>
Content-Type:application/json

Curl Command Request

curl -X POST -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk90ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k https://192.168.1.15/atpapi/v2/sandbox/commands -d '{ "action":"analyze", "targets":["1b7036b518843dcb68014928a7c219a6754d6c488a413d30bcba96e51fc340e5"]}'

Sample Request Body

{
    "action":"analyze",
    "targets":[
        "1b7036b518843dcb68014928a7c219a6754d6c488a413d30bcba96e51fc340e5"
    ]
}

Sample Response Body

{
   "command_id":"f1958f013f8240c29233c0d34b4dcf09-2018-02-20"
}

5.8.2. Sandbox command status query API example

GET /atpapi/v2/sandbox/commands/{command_id}

Sample HTTP Request

GET /atpapi/v2/sandbox/commands/f1958f013f8240c29233c0d34b4dcf09-2018-02-20 HTTP/1.1
Host: 192.168.1.15
Authorization: Bearer <OAUTH TOKEN>
Content-Type:application/json

Curl Command Request

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJleDBkRzlNVlExQ0tjcktPZm9TMnZBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSUpzbkxsTUxTMkMwUjFHNE91OFVCZ1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmc4aTEzcjFqOTFsazF0aHR2ZGpvYmdlcGo5XCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uZzhpMTNyMWo5MWxrMXRodHZkam9iZ2VwajlcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxOTU0NjU5NSwiaWF0IjoxNTE5NTQyOTk1LCJqdGkiOiIwamkzZXR0T1NaVzJTU0lCdDd3RU5nIn0.iF316KzaCKOIUCH3Erdb9ZyC5FlULB4uPYGW0YBD6k8VTRjPC-ribVd1Fqp-pxkCImHWZZ2ttcl14AQa4f4dXmdCrcfu59ATPWr21juivvrYdPX8gkiP266NO4OfxylhIetPBM84m4ExLKUhqCcvVx-rOqZ3l2t_OmwH7xcei4S3ra2ho5gvkscM_kMedAxDtzZcJjqk_fxenylg1NEKzCX9dsJOPibNBLUe00pZKK-jiO1Ft05jAQsL859F9a41TXt5Ac7cO-CtrlrAUWM0cktN3WX-OBBQhcBPNIwmdS7LEJ4hyyo8_6NXwMmFB_6r4MgCWnOSv7N0S2-Dgr31LQ"  "https://192.168.1.15/atpapi/v2/sandbox/commands/f77bf2b4db624de6877186b83a64a5a2-2018-02-23" -k

Sample Response Body

{
   "status":[
      {
         "error_code":9000,
         "message":"File Is Clean",
         "state":0,
         "target":"a22cd6807cf2715cf4dd8383b881176f7aee3da03f3818be39a00d55273d3e4d"
      }
   ]
}

5.9. Blacklist Policies API examples

5.9.1. Create Blacklist policies example

POST /atpapi/v2/policies/blacklist

Sample HTTP Request

POST /atpapi/v2/policies/blacklist HTTP/1.1
Host: 192.168.1.15
Authorization: Bearer <OAUTH TOKEN>
Content-Type:application/json

Curl Command Request

curl -X POST -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist" -d '{"verb":"create","policies":[{"target_type":"ip","target_value":"1.1.1.201","comment":"Blocking malicious ip"},{"target_type":"domain","target_value":"abc.com","comment":"Blocking malicious domain"}]}'

Sample Request Body

{
    "verb":"create",
    "policies":[
        {
            "target_type":"ip",
            "target_value":"1.1.1.201",
            "comment":"Blocking malicious ip"
        },
        {
            "target_type":"domain",
            "target_value":"abc.com",
            "comment":"Blocking malicious domain"
        }
    ]
}

Sample Response Body

{
   "ids":[
      "203",
      "204"
   ]
}

5.9.2. Get Blacklist policies example

GET /atpapi/v2/policies/blacklist

Sample HTTP Request

GET /atpapi/v2/policies/blacklist HTTP/1.1
Host: 192.168.1.15
Authorization: Bearer <OAUTH TOKEN>
Content-Type:application/json

Curl Command Request

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist"

Sample Response Body

{
    "next": "YmxhY2tsaXN0Ozk5MjcwMjM1LTQ1MGMtNGNkZC05MDQ4LTJkNDNjYTc1MDU4NDs=",
    "result": [
        {
            "comment": "Test",
            "id": "203",
            "target_type": "ip",
            "target_value": "1.1.1.201"
        },
        {
            "comment": "Test",
            "id": "205",
            "target_type": "domain",
            "target_value": "abc.com"
        },
        {
            "comment": "Test",
            "id": "206",
            "target_type": "url",
            "target_value": "http://abc.com/My Company"
        }
    ]
}

Sample Requests

Example 53. Returns only 20 ip type blacklist policies matching pattern 1.1.1

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist?ip=1.1.1"

Example 54. Returns only 20 url type blacklist policies matching pattern http://www.test.com/abc

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist?url=http://www.test.com/abc"

Example 55. Returns only 20 url type blacklist policies matching pattern http://www.test.com/My%20Company/book (Notice the URL encoding format)

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist?url=http://www.test.com/My%20Company/book"

Example 56. Returns md5 blacklist policy for 23232323235656565656898989898945

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist?md5=23232323235656565656898989898945"

5.9.3. Update Blacklist policy example

PATCH /atpapi/v2/policies/blacklist/{id}

Curl Command Request

curl -v -X PATCH -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist/203" -d  '{"op":"replace","path":"/comment","value":"DEMO"}'

Sample Request Body

{
    "op":"replace",
    "path":"/comment",
    "value":"DEMO"
}

Sample Response

204 No content.

5.9.4. Delete Blacklist policy example

DELETE /atpapi/v2/policies/blacklist/{id}

Curl Command Request

curl -v -X DELETE-H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist/203"

Sample Response

204 No content.

5.10. Whitelist Policies API examples

5.10.1. Create Whitelist policies example

POST /atpapi/v2/policies/whitelist

Sample HTTP Request

POST /atpapi/v2/policies/whitelist HTTP/1.1
Host: 192.168.1.15
Authorization: Bearer <OAUTH TOKEN>
Content-Type:application/json

Curl Command Request

curl -X POST -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist" -d '{"verb":"create","policies":[{"target_type":"ip","target_value":"1.1.1.201","comment":"trusted ip"},{"target_type":"domain","target_value":"abc.com","comment":"trusted domain"}]}'

Sample Request Body

{
    "verb":"create",
    "policies":[
        {
            "target_type":"ip",
            "target_value":"1.1.1.201",
            "comment":"Trusted ip"
        },
        {
            "target_type":"domain",
            "target_value":"abc.com",
            "comment":"Trusted domain"
        }
    ]
}

Sample Response Body

{
   "ids":[
      "203",
      "204"
   ]
}

5.10.2. Get Whitelist policies example

GET /atpapi/v2/policies/whitelist

Sample HTTP Request

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist"

Curl Command Request

{
    "next": "YmxhY2tsaXN0Ozk5MjcwMjM1LTQ1MGMtNGNkZC05MDQ4LTJkNDNjYTc1MDU4NDs=",
    "result": [
        {
            "comment": "Test",
            "id": "203",
            "target_type": "ip",
            "target_value": "1.1.1.201"
        },
        {
            "comment": "Test",
            "id": "205",
            "target_type": "domain",
            "target_value": "abc.com"
        },
        {
            "comment": "Test",
            "id": "206",
            "target_type": "url",
            "target_value": "http://abc.com/My Company"
        }
    ]
}

Sample Request

Example 57. Returns only 20 ip type Whitelist policies matching pattern 1.1.1

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist?ip=1.1.1"

Example 58. Returns only 20 url type Whitelist policies matching pattern http://www.test.com/abc

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist?url=http://www.test.com/abc"

Example 59. Returns only 20 url type Whitelist policies matching pattern http://www.test.com/My%20Company/book (notice the URL encoding format)

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist?url=http://www.test.com/My%20Company/book"

Example 60. Returns sha256 Whitelist policy for 2323232323565656565689898989894523232323235656565656898989898945

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist?md5=2323232323565656565689898989894523232323235656565656898989898945"

5.10.3. Update Whitelist policy example

PATCH /atpapi/v2/policies/whitelist{id}

Curl Command Request

curl -v -X PATCH -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist/203" -d  '{"op":"replace","path":"/comment","value":"DEMO"}'

Sample Request Body

{
    "op":"replace",
    "path":"/comment",
    "value":"DEMO"
}

Sample Response Body

204 No content.

5.10.4. Delete Whitelist Policy example

DELETE /atpapi/v2/policies/whitelist/{id}

Curl Command Request

curl -v -X DELETE-H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist/203"

Sample Response Body

204 No content.

5.11. OAuth 2.0 Grant Flow example

Grant Type: "client_credentials"

This example shows how to get an access token with client_credentials of client_id and client_secret. You can obtain the client_id and client_secret pair from ATP Manager after you create an OAuth2 client. Concatenate the client_id, ':', client_secret with base64 and put it in the Authorization header after the Basic text.

Sample HTTP Request

POST /atpapi/oauth2/tokens HTTP/1.1
Host: 10.147.26.175
Accept: application/json
Authorization: Basic TzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xczpqYXNsdjZyb3Q4cDd0MW8wNTZma3FtbHZiMG10ZWhoOXFmZw==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Curl Command Request

curl -X POST -H "Accept: application/json" -H "Authorization: Basic TzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xczpqYXNsdjZyb3Q4cDd0MW8wNTZma3FtbHZiMG10ZWhoOXFmZw==" -H
"Content-Type:  application/x-www-form-urlencoded" -d 'grant_type=client_credentials&scope=customer' "https://192.168.1.15/atpapi/oauth2/tokens"

Sample Response Body

{
 "access_token":"eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ",
   "token_type":"Bearer",
   "expires_in":3600
}

5.12. OAuth 2.0 Grant Usage example

This example shows how to use an access token obtained from OAuth 2.0 Grant Flow.

Sample HTTP Request

POST /atpapi/v2/events/ HTTP/1.1
Host: 192.168.1.15
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ
{
    "verb":"query"
}

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H
"Authorization: Bearer eyJraWQiOiIwOXdoVHNEM1JRV2VISGRXOGR3cXp3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvemptSGw5Z1VRMG1TSGo2dVdJYWtWZ1wiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZXIuYXRwLWRvbWFpbi5hOXFjZWQ0dGZjcTdva2pjbDA3YjVrN25xc1wiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmE5cWNlZDR0ZmNxN29ramNsMDdiNWs3bnFzXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjYwNjM5NjcsImlhdCI6MTQ2NjA2MDM2NywianRpIjoiWXVSTXRVWmRSZEszazVXNnhYU253QSJ9.3K7eZOO0oG1QtAA_YkRWQ_OeHxG_m98FI3qdIww0DK2CFsC_rSt1hq5QZxGeX_D803VarzrvDsMR4E26u-sdMY05X12q1p5v-phQWct6ArCtqNCderEJEkHvtu_Xynuytds7vgLKDXx-0IWP1zGtQdffpO7gTW1DVg4gz2P65ymA-iU5eXTRbXjHI6na8cAA__rW3d0k0tEKPVw8RlXHBccWAVRs9F3tJWSw2WHTK4OJyqYg6_nc2uMIciDH01v97ntb7zPY5rsSxNIor9ipqNLqs__ya93_RO8S8pOR5LSANjROy8PBS-FUA-1hiHStrRCVdQ-R1aX2nO6qMThXmQ"
-d '{ "verb":"query"}'
"https://192.168.1.15/atpapi/v2/events/"

Sample Response Body

{
   "result":[
      {
         ...
      }
   ],
   "next":"NiwyMDR2LTA2LTIwVDIwOjQ2OjE2LjgyN1o=",
   "total":1
}

5.13. ResultSet request examples

5.13.1. Events, incidentevents, incidents, and command results query APIs example

All events, incidentevents, incidents, and command results query requests are result-set based. If no 'limit' is specified, then it defaults to 100. This example demonstrates the events query result set with cursoring. The same concept also applies to incidentevents, incidents, and command results query APIs.

Initial HTTP Request

Example shows a query with a limit of 1

POST /atpapi/v2/events HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "query":"<LUCENE QUERY STRING>",
   "limit":1
}

Initial HTTP Response

The response returns only one event (as per the above limit) and includes a 'next' field with the cursor as well as a total number of items in the overall query.

Sample Response Body

{
   "result": [
      {
       ...
      }
   ],
   "next": "MSwyMDE2LTA2LTIwVDIwOjQ2OjE2LjgyN1o=",
   "total": 4
}

Next Query Request

The next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set.

This example query will have a limit of 1.

Subsequent HTTP Request

POST /atpapi/v2/events HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "query":"<LUCENE QUERY STRING>",
   "limit":1,
   "next":"MSwyMDE2LTA2LTIwVDIwOjQ2OjE2LjgyN1o="
}

Sample Response Body

{
   "result":[
      {
         ...
      }
   ],
   "next":"MiwyMDE2LTA2LTIwVDIwOjQ2OjE2LjgyN1o=",
   "total":4
}

The 'next' value will continue to be returned in subsequent search requests until the final results have been retrieved.

5.13.2. Incident comments query API example

The incident comments query requests are result-set based. If no 'limit' is specified, then it defaults to 20. This example demonstrates the incident comments query result set with cursoring.

Initial HTTP Request

Example shows a query with a limit of 5

POST /atpapi/v2/incidents/a31b5a10-0f4c-11e8-f398-000000000013/comments HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "limit":5
}

Initial HTTP Response

The response returns only 5 comments (as per the above limit) and includes a 'next' field with the cursor as well as a total number of items in the overall query.

Sample Response Body

{
   "next":"NSwyMDE4LTAyLTE5VDExOjQyOjIyLjgwNlo=",
   "result":[
      {
         "comment":"API testing-10",
         "time":"2018-02-14T06:30:37.694Z",
         "user_id":100000
      },
      {
         "comment":"API testing-1",
         "time":"2018-02-12T09:35:40.490Z",
         "user_id":100000
      },
      {
         "comment":"API testing-1",
         "time":"2018-02-12T09:35:33.891Z",
         "user_id":100000
      },
      {
         "comment":"API testing-1",
         "time":"2018-02-12T08:41:25.683Z",
         "user_id":100000
      },
      {
         "comment":"UI Comment - 2",
         "time":"2018-02-12T06:24:41.337Z",
         "user_id":2
      }
   ],
   "total":9
}

Next Query Request

The next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. This example query will have a limit of 1.

Subsequent HTTP Request

POST /atpapi/v2/incidents/a31b5a10-0f4c-11e8-f398-000000000013/comments HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "limit":1,
   "next":"NSwyMDE4LTAyLTE5VDExOjQyOjIyLjgwNlo="
}

Sample Response Body

{
   "result":[
      {
         ...
      }
   ],
   "next":"MiwyMDE2LTA2LTIwVDIwOjQ2OjE2LjgyN1o=",
   "total":9
}

The 'next' value will continue to be returned in subsequent search requests until the final results have been retrieved.

5.13.3. Command status query API example

The command status query requests are result set based. If no 'limit' is specified, then it defaults to 100. This example demonstrates the command status query result set with cursoring.

Initial HTTP Request

Example shows a query with a limit of 1

POST /atpapi/v2/commands/fc90c00cb9294732992557340c1c840b-2018-03-04 HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "limit":1
}

Initial HTTP Response

The response returns only one command status object (as per the above limit) and includes a 'next' field with the cursor as well as a total number of items in the overall query.

Sample Response Body

{
    "next": "MSwyLGNvbXBsZXRlZCxmYzkwYw==",
    "state": "completed",
    "status": [
        {
         ...
        }
    ],
    "total": 2
}

Next Query Request

The next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. This example query will have a limit of 1.

Subsequent HTTP Request

POST /atpapi/v2/commands/fc90c00cb9294732992557340c1c840b-2018-03-04 HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "limit":1,
   "next":"MSwyLGNvbXBsZXRlZCxmYzkwYw=="
}

Sample Response Body

{
   "next":null,
   "state":"completed",
   "status":[
      {
         ...
      }
   ],
   "total":2
}

The 'next' value will continue to be returned in subsequent search requests until the final status objects have been retrieved.

5.13.4. Entities and associations query APIs example

By default, all associations and entities query requests are result set based. If no 'limit' is specified, then it defaults to 100. If no 'keep_alive_secs' is specified, then it default to 60 seconds. This example demonstrates the domains-files associations query result set with cursoring. The same concept also applies to all other entities and associations query APIs.

Initial HTTP Request

Example shows a sample curl request with keep_alive_secs of 120 seconds and default limit of 100

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query", "keep_alive_secs":120}' "https://192.168.1.15/atpapi/v2/associations/entities/domains-files"

Initial HTTP Response

The response returns only 100 events (as per the default limit) and includes a 'next' field with the cursor as well as a total number of items in the overall query.

Sample Response Body

{
   "next":"YXNzb2NpYXRpb25zOzE1MjAzNjM0NTkyNTc7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUJhalUwV1YxQllibDh3WjJsVVVXVnhhV3hMTlhWNU9YQmpadz09",
   "result":[
      {
         ...
      }
   ],
   "total":120
}

Next Query Request

The 'query' string in the next query request to be called must be identical to the first initial request. Otherwise, as the results are cached in the server, the modified query does not affect the overall results. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. You also must specify the desired 'keep_alive_secs' for the 'next' to be kept alive. You may change the 'limit' in the subsequent requests to the desired value. This example query will have a limit of 10 and keep_alive_secs of 100 seconds.

Subsequent Curl Request

curl -XPOST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJIZWNCQ3l5YlRvbWJZT3JvZWxYLVRBIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSThtb1VHRERSVkc0VXJ5N1F2bi0xd1wiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLjY4cmZqYmwyN2M4NjJmazJjMGluaDNhYXBvXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uNjhyZmpibDI3Yzg2MmZrMmMwaW5oM2FhcG9cIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODQ5OTQ0NSwiaWF0IjoxNTE4NDk1ODQ1LCJqdGkiOiIyNUEwZEtBUVN4bUpoMU1rdnh4MjhnIn0.UhSi7iwet6p9opKUMEBwKpZg-vAN8i0KNPXITB_6jYDu5NNNgl-9iCRx6RNLNbrJ-3rCFnAd-VXdoJY2vYptVvifRuqDE45mHgTm7THbG5z5JA8ahUMEGbQTJ-rn3bWbqq-ZdZhc1WovKteBVwLteBACPwVm8Y3wjSeUx2wXc6VZQOWLksgPj7egJTnkPZZYCa9hpm8YSzeCvIB0ptpXGXSQwAw_JuW3kjjqf3c6VDHrQLZwmoZvXYBQH_az3hWs4b6TWpA1B3CO9f2BLlEDE7AbJRg8OcGAsVCmUTrp0QaLuQptBPaSNJAru8qNux071ztKDBdSpgAFQ_mdpj-x2Q" -d '{"verb":"query", "keep_alive_secs":100, "next": "YXNzb2NpYXRpb25zOzE1MjAzNjM0NTkyNTc7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUJhalUwV1YxQllibDh3WjJsVVVXVnhhV3hMTlhWNU9YQmpadz09", "limit":10}' "https://192.168.1.15/atpapi/v2/associations/entities/domains-files"

The response returns only 10 events (as per the above limit) and includes a 'next' field with the cursor as well as a total number of items in the cached results.

Sample Response Body

{
   "next":"YXNzb2NpYXRpb25zOzE1MjAzNjc3NDgwMDY7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUJiQ0VRV1YxQllibDh3WjJsVVVXVnhhV3hMTlhWNU9YQmpadz09",
   "result":[
      {
         ...
      }
   ],
   "total":120
}

You must continue the next query request until the no result array is returned in the response.

Final Response Body

{
    "next": "YXNzb2NpYXRpb25zOzE1MjAzNjc4NjgwMDY7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUJiQ0VRV1YxQllibDh3WjJsVVVXVnhhV3hMTlhWNU9YQmpadz09",
    "total": 120
}

Upon receiving the final response, the 'next' should be released using DELETE /atpapi/v2/associations/entities/next/YXNzb2NpYXRpb25zOzE1MjAzNjc4NjgwMDY7MDpEWEYxWlhKNVFXNWtSbVYwWTJnQkFBQUFBQUJiQ0VRV1YxQllibDh3WjJsVVVXVnhhV3hMTlhWNU9YQmpadz09 API

5.13.5. Blacklist policies query API example

The Blacklist policies query requests are result set based. This example demonstrates the Blacklist policies query result set with cursoring.

Initial HTTP Request

Example shows a sample curl request with default limit of 100

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist"

Initial HTTP Response

The response returns the number of policies (as per the default limit) and includes a 'next' field with the cursor.

Sample Response Body

{
   "next":"YmxhY2tsaXN0O2NlMjc5YjJhLTZiOTgtNDU0YS04YjM2LTRjMTFmY2MxYjBmNDsxNDs=",
   "result":[
      {
         ...
      },
      {
         ...
      }
   ]
}

Next Query Request

The query parameters in the next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. You may change the 'limit' in the subsequent requests to the desired value. This example query will have a limit of 1.

Subsequent Curl Request

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/blacklist?limit=1&next=YmxhY2tsaXN0O2NlMjc5YjJhLTZiOTgtNDU0YS04YjM2LTRjMTFmY2MxYjBmNDsxNDs="

Sample Response Body

{
   "next":"YmxhY2tsaXN0O2NlMjc5YjJhLTZiOTgtNDU0YS04YjM2LTRjMTFmY2MxYjBmOzE1Ow==",
   "result":[
      {
         ...
      },
      {
         ...
      }
   ]
}

You must continue the next query request until the no result array is returned in the response.

Sample Response Body when no policy is available

{
    "next": "YmxhY2tsaXN0OzViMmNmOTcwLWE5NzItNDEwYi1iNDZkLTJmMWFkYjdlMTM2MzsxOw=="
}

5.13.6. System activities query API example

The system activities query requests are result-set based. If no 'limit' is specified, then it defaults to 100. This example demonstrates the system activities query result set with cursoring.

Initial HTTP Request

Example shows a query with a limit of 1

POST /atpapi/v2/systemactivities HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "limit":1
}

Initial HTTP Response

The response returns only 1 system activity (as per the above limit) and includes a 'next' field with the cursor as well as a total number of items in the overall query.

Sample Response Body

{
    "next": "MSwyMDE4LTA1LTE2VDA2OjMzOjU5Ljk1OVo=",
    "result": [
        {
            "atp_node_role": 5,
            "data": {
                "search_config": {
                    "atp_command_id": "cd9335799b53420e98215d8d88e2b167-2018-05-16",
                    "cmd_type": "edr_search"
                }
            },
            "device_cap": "ATP-3.2.0-35",
            "device_ip": "192.168.0.50",
            "device_name": "localhost.localdomain",
            "feature_name": "Search",
            "log_name": "atp_system_log-2018-05-16",
            "message": "Endpoint search [Search] with query [file.path:*] is complete.",
            "process": {
                "pid": 12021
            },
            "product_name": "Advanced Threat Protection",
            "product_ver": "3.2.0-35",
            "severity_id": 1,
            "status_id": 1,
            "time": "2018-05-16T06:05:01.976Z",
            "timezone": 0,
            "type_id": 1,
            "uuid": "1216d180-58cf-11e8-d001-00000000041d"
        }
    ],
    "total": 60
}

Next Query Request

The next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. This example query will have a limit of 1.

Subsequent HTTP Request

POST /atpapi/v2/systemactivities HTTP/1.1
Host: 192.168.0.3
Accept: application/json
Authorization: Bearer <OAUTH TOKEN>
Content-Type: application/json

{
   "verb":"query",
   "limit":1,
   "next":"MSwyMDE4LTA1LTE2VDA2OjMzOjU5Ljk1OVo="
}

Sample Response Body

{
   "result":[
      {
         ...
      }
   ],
   "next":"MiwyMDE4LTA1LTE2VDA2OjMzOjU5Ljk1OVo",
   "total":60
}

The 'next' value will continue to be returned in subsequent search requests until the final results have been retrieved.

5.13.7. Whitelist policies query API example

The Whitelist policies query requests are result-set based. This example demonstrates the Whitelist policies query result set with cursoring.

Initial HTTP Request

Example shows a sample curl request with a default limit of 100

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist"

Initial HTTP Response

The response returns the number of policies (as per the default limit) and includes a 'next' field with the cursor.

Sample Response Body

{
   "next":"YmxhY2tsaXN0O2NlMjc5YjJhLTZiOTgtNDU0YS04YjM2LTRjMTFmY2MxYjBmNDsxNDs=",
   "result":[
      {
         ...
      },
      {
         ...
      }
   ]
}

Next Query Request

The query parameters in the next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. You may change the 'limit' in the subsequent requests to the desired value. This example query will have a limit of 1.

Subsequent Curl Request

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/policies/whitelist?limit=1&next=YmxhY2tsaXN0O2NlMjc5YjJhLTZiOTgtNDU0YS04YjM2LTRjMTFmY2MxYjBmNDsxNDs="

Sample Response Body

{
   "next":"YmxhY2tsaXN0O2NlMjc5YjJhLTZiOTgtNDU0YS04YjM2LTRjMTFmY2MxYjBmOzE1Ow==",
   "result":[
      {
         ...
      },
      {
         ...
      }
   ]
}

You must continue the next query request until the no-result array is returned in the response.

Sample Response Body when no policy is available

{
    "next": "YmxhY2tsaXN0OzViMmNmOTcwLWE5NzItNDEwYi1iNDZkLTJmMWFkYjdlMTM2MzsxOw=="
}

5.13.8. Sandbox result query API example

The sandbox events, activities and patterns query requests are result set based. This example demonstrates the sandbox events query result set with cursoring. The same concept applies to sandbox activities and patterns query APIs as well.

Initial HTTP Request

Example shows a sample Curl Request with a limit of 10

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/sandbox/results/96f65f7e3c5385ee83235f416644203eaee141382ed4336c2cd5136bfc671955/events?limit=10"

Initial HTTP Response

The response returns only 10 sandbox events (as per the above limit) and includes a 'next' field with the cursor as well as a total number of items in the overall query.

Sample Response Body

{
   "next":"c2FuZGJveF9ldmVudHM7MTA=",
   "result":[
      {
         ...
      },
      {
         ...
      }
    ],
    "total": 39
 }

Next Query Request

The query parameters in the next query request to be called must be identical to the first initial request. Otherwise, unpredictable results will occur if parameters change between calls in the iteration. However, for this second query, the 'next' string is included in the request. Each subsequent request must include a different next cursor. You must pass in the new string to advance to the next result set. You may change the 'limit' in the subsequent requests to the desired value. This example query will have a limit of 10.

Subsequent Curl Request

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer eyJraWQiOiJIZWVjWXllaVJzNmVpWkVaOWdHeXB3IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvYWxzaHNjcVdUQk9
0ZFVqRXo4ZWNDUVwiLFwic2NvcGVcIjpcImN1c3RvbWVyXCIsXCJwcml2c1wiOlwibWFuYWdlX2RvbWFpblwiLFwiY3VzdG9tZXJfaWRcIjpcImF0cC1jdXN0b21lclwiLFwidXJpXCI6XCJcL29hdXRoMlwvY2xpZW50c1wvTzJJRC5hdHAtY3VzdG9tZ
XIuYXRwLWRvbWFpbi5xdWViaDJvZ2x1YTMzMjFoMHZpZHZzaWU0blwiLFwiY2xpZW50X2lkXCI6XCJPMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLnF1ZWJoMm9nbHVhMzMyMWgwdmlkdnNpZTRuXCJ9IiwidmVyIjoxLCJpc3MiOiJpZF9lcG1wX2kiLCJleHAiOjE0NjcxNDQxMDEsImlhdCI6MTQ2NzE0MDUwMSwianRpIjoiZlJRNlA3NVVRYjZBV1BYU25GUzU4dyJ9.O4cSydZG6K-clAk9vShwptD5eaSoIUE3h0s7oRg06VeuSaGj4Fi_8iOYKZ2chnQkeuihyBPx0zjDLOnY8nzOLDTPjtrw1feH5MHCQvgB60ht23HPI9GIcrUOJgCUT79LCD57ekXxHba50VeUixtFZyefEcriBtip8m5WwarTxFFr85-D5RY1mH-3FBShMMN8KgckD-ZKggq8kpJsnAf_FaioYyGkBX8EEJL0hICZ24JIC5sEhvhXV2a9tH0_7uZgDk5V1EemJ2C3HiCw0uwLAIssi4ZixPgJ1xDXJ_uI4zXNFI1Tme92MuVR0qRvw9hfBZeUtpBEhcWOBUP50mOobA" -k "https://192.168.1.15/atpapi/v2/sandbox/results/96f65f7e3c5385ee83235f416644203eaee141382ed4336c2cd5136bfc671955/events?limit=10&next=c2FuZGJveF9ldmVudHM7MTA="

Sample Response Body

{
   "next":"c2FuZGJveF9ldmVudHM7MjA=",
   "result":[
      {
         ...
      },
      {
         ...
      }
    ],
    "total": 39
}

The 'next' value will continue to be returned in subsequent search requests until the final results have been retrieved.

5.14. System Activities Query API example

POST /atpapi/v2/systemactivities

Warning

Stable Results Consideration: Unless specifically mentioned, the below examples can potentially return unstable results. Refer to the Stable Results section of the API documentation for how to return stable results.

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJOX2gzbzhXaFNGQ01raDFJbWZhZ2JRIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSndGZVJEWThRQk9EM2dMZVhNM2dHUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmgzdWdpc2c1MDJmYjA3M2Y4dGhvbHRiOWIzXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uaDN1Z2lzZzUwMmZiMDczZjh0aG9sdGI5YjNcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODAwMTQzOCwiaWF0IjoxNTE3OTk3ODM4LCJqdGkiOiI1amExQzFlMFFjQ3BneTNOMEZLQXhBIn0.OmBRr4NH83U5ifGKHTm1FY1542_m-46u2e82mochGpd8sSsrhgw45MU10x5jfUM1B4vdXK1zpHg2rsI2vjNm7r3qHO-XfE4adpGpKf-zTqJ20eNq1fmu48AEOdppJG3Z--gTgzuAsdhsAbsRhDCTwfzyg1FD7ci5FKF_AXzI1WOVGaFonpwrnLfED1r94TdQa9Hof1IH291sGo5Ag-irWVgM9ZNcfnabOS8SP1tgiJP3tUlLLiAGnE2yDcgm_QRGYOucg-eG4nQGj1_SJDNwVKY-OjAUTLHcH8eoKl1TLBjXrGXa1oKYThq6MEls9F9Ubf_uwGmTdRQXT5GQ8YeuIw" "https://192.168.1.15/atpapi/v2/systemactivities"

Sample Request Body

{
   "verb":"query",
   "limit":"1"
}

Sample Response Body

{
    "next": "MSwyMDE4LTA1LTE4VDA2OjUzOjIwLjk0MVo=",
    "result": [
        {
            "atp_node_role": 5,
            "data": {
                "atp_service": {
                    "action": "start",
                    "pid": 1798,
                    "service": "microservice_host"
                }
            },
            "device_cap": "ATP-3.2.0-35",
            "device_ip": "192.168.0.50",
            "device_name": "localhost.localdomain",
            "device_time": "2018-05-18T05:38:48.585Z",
            "feature_name": "SHM",
            "log_name": "atp_system_log-2018-05-18",
            "log_time": "2018-05-18T05:38:48.910Z",
            "message": "Service microservice_host started successfully",
            "process": {
                "pid": 18523
            },
            "product_name": "Advanced Threat Protection",
            "product_ver": "3.2.0-35",
            "remediation": "",
            "severity_id": 1,
            "status_detail": "",
            "status_exception": "",
            "status_id": 0,
            "timezone": 0,
            "type_id": 1000,
            "uuid": "bd19e790-5a5d-11e8-d539-00000002212c"
        }
    ],
    "total": 80
}

5.15. Webhook Push Notification examples

5.15.1. Webhook authentication check example

Sample Request for authentication check

POST /r3_epmp_i/dx/col-atp/29a281a0-9105-11e8-eb2a-000000000002 HTTP/1.1
Host: icdx.symc.symantec.com
User-Agent: ATP/3.2.0
Authorization: Basic TzJJRC5keHMuZHhzLjF0b2doMjN1ZmVxOWUzODdkN2VjN2oxZGoyOjZwZmVwbjE2aGVxcmtwcm43NWIwaGs3ZWd1bHNjbjY2Z3Jk
Content-Type: application/json; charset=utf-8
Content-Length: 63
{
    "total": 1,
    "version": 1,
    "notifications": [{
        "type": "auth_check"
    }]
}

5.15.2. Webhook Push Notification example

The following is the sample request for Webhook Push Notification including all the notification types (i.e., events_created, incidents_created, incidentevents_created and incidents_updated).

Sample Request for Webhook Push Notification

POST /r3_epmp_i/dx/col-atp/29a281a0-9105-11e8-eb2a-000000000002 HTTP/1.1
Host: icdx.symc.symantec.com
User-Agent: ATP/3.2.0
Authorization: Basic TzJJRC5keHMuZHhzLjF0b2doMjN1ZmVxOWUzODdkN2VjN2oxZGoyOjZwZmVwbjE2aGVxcmtwcm43NWIwaGs3ZWd1bHNjbjY2Z3Jk
Content-Type: application/json; charset=utf-8
Content-Length: 8254
{
    "version": 1,
    "total": 10,
    "notifications": [{
            "type": "events_created",
            "total": 1,
            "records": [{
                    "process": {
                        "file": {
                            "path": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
                            "sha2": "6a785adc0263238dab3eb37f4c185c8fba7feb5d425d034ca9864f1be1c1b473",
                            "normalized_path": "CSIDL_SYSTEM\\windowspowershell\\v1.0\\powershell.exe",
                            "name": "powershell.exe",
                            "modified": "2013-08-22T10:59:47.574Z",
                            "md5": "45f9906157e072b92140eaa2a67ae424",
                            "signature_company_name": "Microsoft Windows"
                        },
                        "cmd_line": "powershell.exe  -executionpolicy remotesigned -File abc.ps1 Root def.json",
                        "pid": 4384,
                        "user": {
                            "name": "Administrator",
                            "sid": "S-1-5-21-1778916469-68370150-4216710927-500"
                        }
                    },
                    "device_os_name": "Microsoft Windows Server 2012 R2 Standard",
                    "log_name": "epmp_events-fdr-2018-07-26/event",
                    "type_id": 8001,
                    "user_name": "Administrator",
                    "device_domain": "workgroup",
                    "uuid": "b9203a20-9123-11e8-e569-0000000008f5",
                    "log_time": "2018-07-26T22:33:53.915Z",
                    "device_ip": "10.180.248.65",
                    "device_name": "win2012-c1",
                    "device_uid": "a8691cd6-9dea-44f4-88df-e35fca020cff",
                    "enriched_data": {
                        "category_name": "Generic Data to be sent to ATP",
                        "category_id": 201,
                        "rule_name": "ePS_Launch",
                        "suspicion_score": 0
                    },
                    "event_actor": {
                        "signature_level_id": 60,
                        "file": {
                            "path": "c:\\windows\\system32\\cmd.exe",
                            "sha2": "0b9bc863e2807b6886760480083e51ba8a66118659f4ff274e7b73944d2219f5",
                            "normalized_path": "CSIDL_SYSTEM\\cmd.exe",
                            "name": "cmd.exe",
                            "modified": "2013-08-22T10:03:31.849Z",
                            "md5": "fc0b4a626881d7c5980d757214db2d25",
                            "signature_company_name": "Microsoft Windows"
                        },
                        "cmd_line": "\"C:\\Windows\\system32\\cmd.exe\" ",
                        "pid": 1120,
                        "user": {
                            "name": "Administrator",
                            "sid": "S-1-5-21-1778916469-68370150-4216710927-500"
                        }
                    },
                    "severity_id": 1,
                    "operation": 1,
                    "device_time": "2018-07-26T22:32:05.058Z"
                }
            ]
        }, {
            "type": "incidents_created",
            "total": 1,
            "records": [{
                    "summary": "Suspicious PowerShell detected: suspicious encoded command invoked",
                    "recommended_action": "Attackers encode PowerShell to obfuscate and to simplify execution of complex, multi-line commands.  Investigate the intent of the decoded command and the process that invoked PowerShell.  Investigate further activity at the endpoint by downloading a full dump of the endpoint's recorded data.",
                    "last_event_seen": "2018-07-26T22:32:07.167Z",
                    "atp_incident_id": 100006,
                    "first_event_seen": "2018-07-26T22:32:07.167Z",
                    "priority_level": 2,
                    "updated": "2018-07-26T22:33:53.918Z" ,
                    "uuid": "fa02f1e0-9123-11e8-c9df-0000000008d3",
                    "device_time": "2018-07-26T22:33:53.918Z"
                }
            ]
        }, {
            "type": "incidentevents_created",
            "total": 4,
            "records": [{
                    "process": {
                        "file": {
                            "path": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
                            "sha2": "6a785adc0263238dab3eb37f4c185c8fba7feb5d425d034ca9864f1be1c1b473",
                            "normalized_path": "CSIDL_SYSTEM\\windowspowershell\\v1.0\\powershell.exe",
                            "name": "powershell.exe",
                            "modified": "2013-08-22T10:59:47.574Z",
                            "md5": "45f9906157e072b92140eaa2a67ae424",
                            "signature_company_name": "Microsoft Windows"
                        },
                        "cmd_line": "\"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\" -w hidden -Exec Bypass -enc JgAgAC4AXABcAGIAdQBpAGwAZABfAGwAaQBuAGUAYQBnAGUALgBwAHMAMQAgAFAAYQByAGUAbgB0AC0AMQAtADEAIABjAGEAbABjAC0AMwAtAGMAaABpAGwAZAByAGUAbgAuAGoAcwBvAG4A ",
                        "pid": 3216,
                        "user": {
                            "name": "Administrator",
                            "sid": "S-1-5-21-1778916469-68370150-4216710927-500"
                        }
                    },
                    "device_os_name": "Microsoft Windows Server 2012 R2 Standard",
                    "log_name": "epmp_events-fdr-2018-07-26/event",
                    "type_id": 8001,
                    "user_name": "Administrator",
                    "event_uuid": "ba6208f0-9123-11e8-fce2-0000000008f6",
                    "device_domain": "workgroup",
                    "log_time": "2018-07-26T22:33:53.915Z",
                    "device_ip": "10.180.248.65",
                    "device_name": "win2012-c1",
                    "device_uid": "a8691cd6-9dea-44f4-88df-e35fca020cff",
                    "enriched_data": {
                        "category_name": "Suspicious PowerShell Script Executed",
                        "category_id": 102,
                        "rule_name": "ePS_hidden_encoded",
                        "suspicion_score": 65
                    },
                    "event_actor": {
                        "signature_level_id": 60,
                        "file": {
                            "path": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
                            "sha2": "6a785adc0263238dab3eb37f4c185c8fba7feb5d425d034ca9864f1be1c1b473",
                            "normalized_path": "CSIDL_SYSTEM\\windowspowershell\\v1.0\\powershell.exe",
                            "name": "powershell.exe",
                            "modified": "2013-08-22T10:59:47.574Z",
                            "md5": "45f9906157e072b92140eaa2a67ae424",
                            "signature_company_name": "Microsoft Windows"
                        },
                        "cmd_line": "powershell.exe  -executionpolicy remotesigned -File build_lineage.ps1 Root calc-3-children.json",
                        "pid": 4384,
                        "user": {
                            "name": "Administrator",
                            "sid": "S-1-5-21-1778916469-68370150-4216710927-500"
                        }
                    },
                    "severity_id": 1,
                    "incident": "fa02f1e0-9123-11e8-c9df-0000000008d3",
                    "operation": 1,
                    "device_time": "2018-07-26T22:32:07.167Z"
                }, {
                    "vlan_id": 0,
                    "process": {
                        "file": {
                            "path": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
                            "sha2": "6a785adc0263238dab3eb37f4c185c8fba7feb5d425d034ca9864f1be1c1b473",
                            "name": "powershell.exe",
                            "md5": "45f9906157e072b92140eaa2a67ae424"
                        },
                        "cmd_line": "powershell.exe  -executionpolicy remotesigned -File build_lineage.ps1 Root calc-3-children.json",
                        "pid": 4384
                    },
                    "log_name": "epmp_events-fdr-2018-07-26",
                    "type_id": 8001,
                    "network_scanner_type": 0,
                    "event_uuid": "b9203a20-9123-11e8-e569-0000000008f5",
                    "connection_method": 0,
                    "device_name": "win2012-c1",
                    "protocol": 0,
                    "device_uid": "a8691cd6-9dea-44f4-88df-e35fca020cff",
                    "action_id": 0,
                    "event_actor": {
                        "signature_level_id": 60,
                        "file": {
                            "path": "c:\\windows\\system32\\cmd.exe",
                            "sha2": "0b9bc863e2807b6886760480083e51ba8a66118659f4ff274e7b73944d2219f5",
                            "name": "cmd.exe",
                            "md5": "fc0b4a626881d7c5980d757214db2d25"
                        },
                        "cmd_line": "\"C:\\Windows\\system32\\cmd.exe\" ",
                        "pid": 1120
                    },
                    "incident": "fa02f1e0-9123-11e8-c9df-0000000008d3",
                    "operation": 1,
                    "device_time": "2018-07-26T22:32:05.167Z"
                }, {
                    "vlan_id": 0,
                    "process": {
                        "file": {
                            "path": "c:\\windows\\system32\\cmd.exe",
                            "sha2": "0b9bc863e2807b6886760480083e51ba8a66118659f4ff274e7b73944d2219f5",
                            "name": "cmd.exe",
                            "md5": "fc0b4a626881d7c5980d757214db2d25"
                        },
                        "cmd_line": "\"C:\\Windows\\system32\\cmd.exe\" ",
                        "pid": 1120
                    },
                    "log_name": "epmp_events-fdr-2018-07-23",
                    "type_id": 8001,
                    "network_scanner_type": 0,
                    "event_uuid": "3ae36b40-8ea9-11e8-eb14-000000000034",
                    "connection_method": 0,
                    "device_name": "win2012-c1",
                    "protocol": 0,
                    "device_uid": "a8691cd6-9dea-44f4-88df-e35fca020cff",
                    "action_id": 0,
                    "event_actor": {
                        "signature_level_id": 60,
                        "file": {
                            "path": "c:\\windows\\explorer.exe",
                            "sha2": "f5bbe8c4e1f85f8a157f1e0a371fb888ab641b26912a0523a01397592e1374f7",
                            "name": "explorer.exe",
                            "md5": "c1400519d76a364e974e47bba62b95b0"
                        },
                        "cmd_line": "C:\\Windows\\Explorer.EXE",
                        "pid": 2164
                    },
                    "incident": "fa02f1e0-9123-11e8-c9df-0000000008d3",
                    "operation": 1,
                    "device_time": "2018-07-26T22:32:07.167Z"
                }, {
                    "vlan_id": 0,
                    "process": {
                        "file": {
                            "path": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
                            "sha2": "6a785adc0263238dab3eb37f4c185c8fba7feb5d425d034ca9864f1be1c1b473",
                            "name": "powershell.exe",
                            "md5": "45f9906157e072b92140eaa2a67ae424"
                        },
                        "cmd_line": "\"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\" -w hidden -Exec Bypass -enc JgAgAC4AXABcAGIAdQBpAGwAZABfAGwAaQBuAGUAYQBnAGUALgBwAHMAMQAgAFAAYQByAGUAbgB0AC0AMQAtADEAIABjAGEAbABjAC0AMwAtAGMAaABpAGwAZAByAGUAbgAuAGoAcwBvAG4A ",
                        "pid": 3216
                    },
                    "log_name": "epmp_events-fdr-2018-07-26/event",
                    "type_id": 8001,
                    "network_scanner_type": 0,
                    "event_uuid": "ba6208f0-9123-11e8-fce2-0000000008f6",
                    "connection_method": 0,
                    "device_name": "win2012-c1",
                    "protocol": 0,
                    "device_uid": "a8691cd6-9dea-44f4-88df-e35fca020cff",
                    "action_id": 0,
                    "event_actor": {
                        "signature_level_id": 60,
                        "file": {
                            "path": "c:\\windows\\system32\\windowspowershell\\v1.0\\powershell.exe",
                            "sha2": "6a785adc0263238dab3eb37f4c185c8fba7feb5d425d034ca9864f1be1c1b473",
                            "name": "powershell.exe",
                            "md5": "45f9906157e072b92140eaa2a67ae424"
                        },
                        "cmd_line": "powershell.exe  -executionpolicy remotesigned -File build_lineage.ps1 Root calc-3-children.json",
                        "pid": 4384
                    },
                    "incident": "fa02f1e0-9123-11e8-c9df-0000000008d3",
                    "operation": 1,
                    "device_time": "2018-07-26T22:32:08.167Z"
                }
            ]
        }, {
            "type": "incidents_updated",
            "total": 3,
            "records": [{
                    "recommended_action": "Investigate the downloaded content and download sites. Isolate and remediate affected endpoints and delete/clean infected files if they have not been blocked already by Symantec Endpoint Protection. Investigate further activity at the endpoint by downloading a full dump of the endpoint's recorded data.",
                    "last_event_seen": "2018-07-26T22:33:53.915Z",
                    "rest_op": "replace",
                    "atp_incident_id": 100010,
                    "priority_level": 3,
                    "updated": "2018-07-26T22:33:53.915Z",
                    "uuid": "9d600930-91f2-11e8-ecdc-00000000001c",
                    "device_time": "2018-07-26T21:30:50.915Z"
                }, {
                    "user_id": 2,
                    "rest_op": "add_comment",
                    "comment": "add a note to TAA incident",
                    "time": "2018-07-26T22:28:26.075Z",
                    "uuid": "de0cc670-8ec9-11e8-e0ee-000000000063"
                }, {
                    "rest_op": "replace",
                    "state": 4,
                    "uuid": "fc7d0fc0-83d4-11e8-f387-000000000005",
                    "resolution": 3
                }
            ]
        }
    ]
}

6. Correlating incidents

6.1. Correlating an incident with the original event

This example demonstrates how to retrieve the original events for an incident.

Get the related events for the specific incident

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJOX2gzbzhXaFNGQ01raDFJbWZhZ2JRIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSndGZVJEWThRQk9EM2dMZVhNM2dHUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmgzdWdpc2c1MDJmYjA3M2Y4dGhvbHRiOWIzXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uaDN1Z2lzZzUwMmZiMDczZjh0aG9sdGI5YjNcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODAwMTQzOCwiaWF0IjoxNTE3OTk3ODM4LCJqdGkiOiI1amExQzFlMFFjQ3BneTNOMEZLQXhBIn0.OmBRr4NH83U5ifGKHTm1FY1542_m-46u2e82mochGpd8sSsrhgw45MU10x5jfUM1B4vdXK1zpHg2rsI2vjNm7r3qHO-XfE4adpGpKf-zTqJ20eNq1fmu48AEOdppJG3Z--gTgzuAsdhsAbsRhDCTwfzyg1FD7ci5FKF_AXzI1WOVGaFonpwrnLfED1r94TdQa9Hof1IH291sGo5Ag-irWVgM9ZNcfnabOS8SP1tgiJP3tUlLLiAGnE2yDcgm_QRGYOucg-eG4nQGj1_SJDNwVKY-OjAUTLHcH8eoKl1TLBjXrGXa1oKYThq6MEls9F9Ubf_uwGmTdRQXT5GQ8YeuIw" "https://10.212.24.158/atpapi/v2/incidentevents"

Sample Request Body

{
   "verb":"query",
   "query":"incident:<Incident UUID>"
}

Example 55. Returns all the related events for incident uuid# 83dfab70-266b-11e8-f6fc-000000000002

{
   "verb":"query",
   "query":"incident:83dfab70-266b-11e8-f6fc-000000000002"
}

Sample Response Body

{
    "next": null,
    "result": [
        {
            "data_direction": 0,
            "device_ip": "10.212.24.160",
            "device_name": "170915-000042",
            "device_time": "2018-03-13T03:06:24.800Z",
            "device_uid": "c2937757-3968-4eb2-a1f3-4f7efbfdaafd",
            "event_uuid": "83b78a00-266b-11e8-f1ac-000000000a95",
            "file": {
                "name": "shample[1].exe",
                "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9",
                "targeted_attack": false
            },
            "incident": "83dfab70-266b-11e8-f6fc-000000000002",
            "log_name": "epmp_incident-2018-03-13",
            "log_time": "2018-03-13T03:06:25.063Z",
            "request_source": "user_submit",
            "sandbox": {
                "sandbox_task_id": "1",
                "targeted_data": {
                    "is_targeted": false
                },
                "verdict": "malware",
                "verdict_type": "full_analysis"
            },
            "sandbox_service": "cynic",
            "sep_installed": true,
            "type_id": 4117,
            "user_name": "Administrator",
            "uuid": "83e095d0-266b-11e8-ca24-000000000060"
        }
    ],
    "total": 1
}

Get the original event for the specific related event

Curl Command Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJOX2gzbzhXaFNGQ01raDFJbWZhZ2JRIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvSndGZVJEWThRQk9EM2dMZVhNM2dHUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmgzdWdpc2c1MDJmYjA3M2Y4dGhvbHRiOWIzXCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uaDN1Z2lzZzUwMmZiMDczZjh0aG9sdGI5YjNcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUxODAwMTQzOCwiaWF0IjoxNTE3OTk3ODM4LCJqdGkiOiI1amExQzFlMFFjQ3BneTNOMEZLQXhBIn0.OmBRr4NH83U5ifGKHTm1FY1542_m-46u2e82mochGpd8sSsrhgw45MU10x5jfUM1B4vdXK1zpHg2rsI2vjNm7r3qHO-XfE4adpGpKf-zTqJ20eNq1fmu48AEOdppJG3Z--gTgzuAsdhsAbsRhDCTwfzyg1FD7ci5FKF_AXzI1WOVGaFonpwrnLfED1r94TdQa9Hof1IH291sGo5Ag-irWVgM9ZNcfnabOS8SP1tgiJP3tUlLLiAGnE2yDcgm_QRGYOucg-eG4nQGj1_SJDNwVKY-OjAUTLHcH8eoKl1TLBjXrGXa1oKYThq6MEls9F9Ubf_uwGmTdRQXT5GQ8YeuIw" "https://10.212.24.158/atpapi/v2/events"

Sample Request Body

{
    "start_time":<related event device_time>,
    "verb":"query",
    "query":"uuid:<related event event_uuid>"
}

Example 56. Returns the original event for related event_uuid# 83b78a00-266b-11e8-f1ac-000000000a95 and device_time# 2018-03-13T03:06:24.800Z

{
    "start_time":"2018-03-13T03:06:24.800Z",
    "verb":"query",
    "query":"uuid:83b78a00-266b-11e8-f1ac-000000000a95"
}

Sample Response Body

{
    "next": null,
    "result": [
        {
            "data_direction": 0,
            "device_ip": "10.212.24.160",
            "device_name": "170915-000042",
            "device_time": "2018-03-13T03:06:24.800Z",
            "device_uid": "c2937757-3968-4eb2-a1f3-4f7efbfdaafd",
            "file": {
                "name": "shample[1].exe",
                "sha2": "4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9",
                "targeted_attack": false
            },
            "log_name": "epmp_events-2018-03-13",
            "log_time": "2018-03-13T03:06:25.062Z",
            "request_source": "user_submit",
            "sandbox": {
                "sandbox_task_id": "1",
                "targeted_data": {
                    "is_targeted": false
                },
                "verdict": "malware",
                "verdict_type": "full_analysis"
            },
            "sandbox_service": "cynic",
            "sep_installed": true,
            "type_id": 4117,
            "user_name": "Administrator",
            "uuid": "83b78a00-266b-11e8-f1ac-000000000a95"
        }
    ],
    "total": 1
}

6.2. Correlate an incident with devices

This example demonstrates how to derive the related devices for an incident.

For retrieving related events for an incident see Get the related events for the specific incident.

Process the retrieved related events to get the unique device_uid values from the related events. The following sample python script demonstrates how to process the retrieved related events to get the unique values. The script accepts the attributes as a command line arguments. It reads input from standard input.

get_unique_values.py

import sys
import json

def usage(min_args, max_args):
    print "Minimum and Maximum args supported are: " + str(min_args) + " , " + str(max_args)
    print ""
    print "Example usage: "
    print "echo '{\"key\":\"value\"}' | python2.7 "+sys.argv[0]+" \"event_actor.file.sha2\" \"process.file.sha2\""

def hasKey(temp_dict, dotted_key):
    for key in dotted_key.split('.'):
        try:
            temp_dict = temp_dict[key]
        except KeyError:
            return False
    return True

def main():
    min_args = 1
    max_args = 10
    if (len(sys.argv) < (min_args+1)) or (len(sys.argv) > max_args):
        usage(min_args, max_args)
        sys.exit(1)

    input = sys.stdin

    with input:
        try:
            output = json.load(input)
        except ValueError, e:
            raise SystemExit(e)
        if not bool(output):
            print "Empty response"
            sys.exit(0)
        if "result" not in output:
            if "status" in output:
                print "Status: "+ str(output["status"])
                if "message" in output:
                    print "Message: "+ str(output["message"])
                sys.exit(1)
            print "No result in response"
            sys.exit(0)
        result = output["result"]
        if len(result) == 0:
            print "Result is empty in response"
            sys.exit(0)
        outList = set()
        for val in result:
            for dotted_key in sys.argv[1:]:
                keyExists = hasKey(val, dotted_key)
                if keyExists is True:
                    keyList = dotted_key.split('.')
                    key = "val"
                    for childKey in keyList:
                        key = key + "[\"" + childKey + "\"]"
                    target = eval(key)
                    if isinstance(target, unicode):
                        outList.add(target)
        if len(outList) == 0:
            print "Empty output for supplied filters"
            sys.exit(0)
        print '\n'.join(outList)

if __name__ == '__main__':
    main()

Example 54: Processes and lists all the unique devices

python2.7 get_unique_values.py device_uid

Curl Command Request piped to get_unique_values.py

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJ4aFhsbmxHUVItZUY3UWRPVktBVGJnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvRm11V0M3Wi1UQnVhNk5JSTRaY1czUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmI4ajNoM3M5ajJyb2lwdnVqZGx0NGZsbjA0XCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uYjhqM2gzczlqMnJvaXB2dWpkbHQ0ZmxuMDRcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUyMTQ5MTE3MSwiaWF0IjoxNTIxNDg3NTcxLCJqdGkiOiJyX3hnRGdaNlRkNmQ1dU1GXzljSjlBIn0.aB6bh7-HIB86VqjqlF7obt9GeJ5POGISMCb3nuzEj1Cn3ooWWV4tLcfYlcBAYKmOrwJ92WB03qbs90G9Xc66Mj1Zlcmccmy8qG0jNyBi3Em8FH6V6Uu5EvYR7XwsTJzjXSfmt2q0UbnRU1wwOAZFJka6mc-MmlSyKOkJvjDKD_W4nZuV-crvdNcH-xOUa6qUjHdBnor1X5-6nQTFvlWrlrkHtyfC0u-ToDyei0EZsBB2Ujf5EGICSU1YJev5qEszbDctphHcHbAKBaJds5o-eYkbDk4pq6RkhKQLFgCB2FbVm0VcZAL6GIXbsrs-ofdWBMksSaeIfeWYbwXL1dzJ8A" -d '{ "verb":"query"}' "https://10.212.24.158/atpapi/v2/incidentevents" -d '{"verb":"query", "query":"incident:b108dfa0-262e-11e8-eeae-000000000001"}' | python2.7 get_unique_values.py device_uid

Sample Processed Response

6ad1a2bf-3a37-46c6-85c6-72cfd911a32b
928f0ea0-59a6-4eb7-a9e0-90053d14188f
c2937757-3968-4eb2-a1f3-4f7efbfdaafd
6365eb19-dcaa-4375-ad5f-623682b78453
f1c5a77c-db92-4001-b5d7-288950b3ccc2
12616f11-472e-467d-928a-4b7e886243a3

6.3. Correlate an incident with file hashes

This example demonstrates how to derive the related file hashes for an incident.

For retrieving related events for an incident see Get the related events for the specific incident.

Process the retrieved related events to get the unique file.sha2, event_actor.file.sha2 and process.file.sha2 values from the related events.

For processing the retrieved related events to get the unique values see get_unique_values.py.

Example 57: Processes and lists all the unique file hashes

python2.7 get_unique_values.py file.sha2 event_actor.file.sha2 process.file.sha2

Curl Command Request piped to get_unique_values.py

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJ4aFhsbmxHUVItZUY3UWRPVktBVGJnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvRm11V0M3Wi1UQnVhNk5JSTRaY1czUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmI4ajNoM3M5ajJyb2lwdnVqZGx0NGZsbjA0XCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uYjhqM2gzczlqMnJvaXB2dWpkbHQ0ZmxuMDRcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUyMTQ5MTE3MSwiaWF0IjoxNTIxNDg3NTcxLCJqdGkiOiJyX3hnRGdaNlRkNmQ1dU1GXzljSjlBIn0.aB6bh7-HIB86VqjqlF7obt9GeJ5POGISMCb3nuzEj1Cn3ooWWV4tLcfYlcBAYKmOrwJ92WB03qbs90G9Xc66Mj1Zlcmccmy8qG0jNyBi3Em8FH6V6Uu5EvYR7XwsTJzjXSfmt2q0UbnRU1wwOAZFJka6mc-MmlSyKOkJvjDKD_W4nZuV-crvdNcH-xOUa6qUjHdBnor1X5-6nQTFvlWrlrkHtyfC0u-ToDyei0EZsBB2Ujf5EGICSU1YJev5qEszbDctphHcHbAKBaJds5o-eYkbDk4pq6RkhKQLFgCB2FbVm0VcZAL6GIXbsrs-ofdWBMksSaeIfeWYbwXL1dzJ8A" -d '{ "verb":"query"}' "https://10.212.24.158/atpapi/v2/incidentevents" -d '{"verb":"query", "query":"incident:b108dfa0-262e-11e8-eeae-000000000001"}' | python2.7 get_unique_values.py file.sha2 event_actor.file.sha2 process.file.sha2

Sample Processed Response

1d5169471831cc91e15574abbe0c9d3733eca8e13c665dea89b1251de7539996
fbad13f08bab7dd3800597ac9880dbb58bd60dea046a2fa62316953ce427f65c
b11a64b2ffe23c8c719d8e57f82a19c69855feb24fec686eeb1a7beea4d0334b
4cbaa39e03c088b7e44d31722f099fb8030753bad30ba09edcb27490f7802cd9
067fb5acff8372d140f502134ff36e8448f6260ce2b283ce756575c5ba787559
5075d74fa6b097b1bd6cc52d171659476ab38dab32c053867404cbbb5ff832bc
c26f121d3c3223a09d6637f748d5028360f2115f0fcf01ecf7db670e303321f2
6cdd675e428ba0cdaf097557c7c2bb807eee6cfabf1ea4abb55c9bdda15167c8
d961d7d8aea580c26ab0598b28d7865b3858a12082e2b4511122c8cb4e560f3a
e27ce9133d76a0173ee40408125d3dd548a01bf069c4819f9c22f7f40442263d
4727cb6ceee9b12b2f4a97524a49c0186abdcfcc9e72fe8fc076653d9e68a537
30a74587eb50932d213b67185d375d89d1e27a6c441ba82e79eeb1956d75fc31
00f355dce1b983fbbb39700364c998f49846528289bc8e25c06c836d6b138f6a
7627c86efafaa6688a1696b970fc42c135e1c15bae40a43c70720536f0f8fb24
ebdcbecc428515cf64639c0535a9ae5a913e42653b6e8e7debd1b0762ad8e9e9
5386aef5fd1eaafb4d31335499ac0cfb555b3708c06368508dc66abee60f6073
fb1cc07e393f28fed3212c96297e6aac01163dc56c0ba30bf6a0d58d6a073f10
7627354b2e8727ddcf83422c2a6614600e17bdbe138b98ed28f6ab406df5349b
50c36b3c02ed4038ea0dc2d5888bf94a4b645fc2ead7e2c189ce8ced57929940
42b1a27cef6a3dc71339a4348021c354b5f03de95d61e0e22e720a73f62f8d2c
ea3c7969603c1ad7cc367eda34e82c4b4d0c5e95b6d8588331d8f8d91fc01b2c
8b14a6fa42a924aa2952460f092e0cf228ae670203bc1d4a2a393488edb5b0a4

6.4. Correlate an incident with domains

This example demonstrates how to derive the related domains for an incident.

For retrieving related events for an incident see Get the related events for the specific incident.

Process the retrieved related events to get the unique data_source_url_domain values from the related events.

For processing the retrieved related events to get the unique values see get_unique_values.py.

Example 58: Processes and lists all unique domains

python2.7 get_unique_values.py data_source_url_domain

Curl Command Request piped to get_unique_values.py

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJ4aFhsbmxHUVItZUY3UWRPVktBVGJnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvRm11V0M3Wi1UQnVhNk5JSTRaY1czUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmI4ajNoM3M5ajJyb2lwdnVqZGx0NGZsbjA0XCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uYjhqM2gzczlqMnJvaXB2dWpkbHQ0ZmxuMDRcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUyMTQ5MTE3MSwiaWF0IjoxNTIxNDg3NTcxLCJqdGkiOiJyX3hnRGdaNlRkNmQ1dU1GXzljSjlBIn0.aB6bh7-HIB86VqjqlF7obt9GeJ5POGISMCb3nuzEj1Cn3ooWWV4tLcfYlcBAYKmOrwJ92WB03qbs90G9Xc66Mj1Zlcmccmy8qG0jNyBi3Em8FH6V6Uu5EvYR7XwsTJzjXSfmt2q0UbnRU1wwOAZFJka6mc-MmlSyKOkJvjDKD_W4nZuV-crvdNcH-xOUa6qUjHdBnor1X5-6nQTFvlWrlrkHtyfC0u-ToDyei0EZsBB2Ujf5EGICSU1YJev5qEszbDctphHcHbAKBaJds5o-eYkbDk4pq6RkhKQLFgCB2FbVm0VcZAL6GIXbsrs-ofdWBMksSaeIfeWYbwXL1dzJ8A" -d '{ "verb":"query"}' "https://10.212.24.158/atpapi/v2/incidentevents" -d '{"verb":"query", "query":"incident:b108dfa0-262e-11e8-eeae-000000000001"}' | python2.7 get_unique_values.py data_source_url_domain

Sample Processed Response

westfallave.com

6.5. Correlate an incident with scanners

This example demonstrates how to derive the related scanners for an incident.

For retrieving related events for an incident see Get the related events for the specific incident.

Process the retrieved related events to get the unique scanner_name values from the related events.

For processing the retrieved related events to get the unique values, see get_unique_values.py.

Example 59: Processes and lists all unique scanners

python2.7 get_unique_values.py scanner_name

Curl Command Request piped to get_unique_values.py

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJ4aFhsbmxHUVItZUY3UWRPVktBVGJnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ7XCJkb21haW5faWRcIjpcImF0cC1kb21haW5cIixcIm93bmVyX3VyaVwiOlwiXC92MVwvbWRyXC91c2Vyc1wvRm11V0M3Wi1UQnVhNk5JSTRaY1czUVwiLFwic2NvcGVcIjpcIm9hdXRoIGN1c3RvbWVyXCIsXCJwcml2c1wiOlwiYXRwX2FkbWluXCIsXCJjdXN0b21lcl9pZFwiOlwiYXRwLWN1c3RvbWVyXCIsXCJ1cmlcIjpcIlwvb2F1dGgyXC9jbGllbnRzXC9PMklELmF0cC1jdXN0b21lci5hdHAtZG9tYWluLmI4ajNoM3M5ajJyb2lwdnVqZGx0NGZsbjA0XCIsXCJjbGllbnRfaWRcIjpcIk8ySUQuYXRwLWN1c3RvbWVyLmF0cC1kb21haW4uYjhqM2gzczlqMnJvaXB2dWpkbHQ0ZmxuMDRcIn0iLCJ2ZXIiOjEsImlzcyI6ImlkX2VwbXBfaV9hbGRvbWFpbiIsImV4cCI6MTUyMTQ5MTE3MSwiaWF0IjoxNTIxNDg3NTcxLCJqdGkiOiJyX3hnRGdaNlRkNmQ1dU1GXzljSjlBIn0.aB6bh7-HIB86VqjqlF7obt9GeJ5POGISMCb3nuzEj1Cn3ooWWV4tLcfYlcBAYKmOrwJ92WB03qbs90G9Xc66Mj1Zlcmccmy8qG0jNyBi3Em8FH6V6Uu5EvYR7XwsTJzjXSfmt2q0UbnRU1wwOAZFJka6mc-MmlSyKOkJvjDKD_W4nZuV-crvdNcH-xOUa6qUjHdBnor1X5-6nQTFvlWrlrkHtyfC0u-ToDyei0EZsBB2Ujf5EGICSU1YJev5qEszbDctphHcHbAKBaJds5o-eYkbDk4pq6RkhKQLFgCB2FbVm0VcZAL6GIXbsrs-ofdWBMksSaeIfeWYbwXL1dzJ8A" -d '{ "verb":"query"}' "https://10.212.24.158/atpapi/v2/incidentevents" -d '{"verb":"query", "query":"incident:b108dfa0-262e-11e8-eeae-000000000001"}' | python2.7 get_unique_values.py scanner_name

Sample Processed Response

ATP-Network

7. AP Authentication

7.1. Generating an OAuth client

Symantec Advanced Threat Protection (ATP) lets you access incident and event data and perform remediation tasks using APIs and through integration with third-party applications. To secure ATP data, these integrations require that you generate an OAuth 2 client ("OAuth client"). The OAuth client authorizes third-party applications to communicate with ATP.

See the documentation for the third-party applications and API for information about how to register the OAuth client.

You must have Admin rights to generate an OAuth client. Only users with the Admin role that created the OAuth client can view the Client ID and Client Secret. Other Admin roles can only view the Client ID. Only Active Directory Admin users who log into ATP Manager using the NETBIOS format (e.g., SYMC\john_doe) can generate OAuth tokens and view the client secret.

Note

For more information about OAuth 2, see the following website: http://oauth.net/2/.

To generate an OAuth client

  1. In ATP Manager, click Settings > Data Sharing.

  2. In the OAuth Clients section, click Add Application.

  3. In the App Name field, type the name of the application that you want to register.

  4. Select the API version that you intend to use. The default setting is version 2. You can use version 2-generated OAuth clients on all version 1 APIs regardless of any version 2 assigned role and privilege. Symantec will support version 1 of ATP’s API up to one year after the release of ATP 3.1.

  5. If you select to enable version 2 APIs, a Role option appears. Click the drop-down menu and select the user role for the app.

  6. Click Generate. The client ID and client secret appear.

Admin

Permits access to all public APIs.

Controller

Permits access to all public APIs.

Note: Future versions of ATP will have differentiations between the Admin role and the Controller role.

User

Permits access to all public APIs that have view_*privileges.

Custom

Lets you select the specific privileges that you want to associate with the application.

When you select Custom, a drop-down list appears containing the privileges that you can choose from. You can select multiple privileges.

To view an existing OAuth client ID and client secret

  1. In the OAuth Clients table, hover over the row that contains the information that you want to view. Options appear to the right of the row.

  2. Click View.

7.2. Role to privilege mapping

Role

Privilege

Admin

* atp_view_appliance_details

* atp_view_events

* atp_view_incidents

* atp_view_entities

* atp_view_policy

* atp_view_remediate_cmds

* atp_view_endpoint_search

* atp_manage_incidents

* atp_manage_policy

* atp_manage_remediate_cmds

* atp_endpoint_copy_file

* atp_view_copy_file_cmds

* atp_manage_endpoint_search

Controller

* atp_view_appliance_details

* atp_view_events

* atp_view_incidents

* atp_view_entities

* atp_view_policy

* atp_view_remediate_cmds

* atp_view_endpoint_search

* atp_manage_incidents

* atp_manage_policy

* atp_manage_remediate_cmds

* atp_endpoint_copy_file

* atp_view_copy_file_cmds

* atp_manage_endpoint_search

User

* atp_view_appliance_details

* atp_view_events

* atp_view_incidents

* atp_view_entities

* atp_view_policy

* atp_view_remediate_cmds

* atp_view_endpoint_search

* atp_view_copy_file_cmds

7.3. Privileges list

Paths

Privileges

Create Blacklist policies

atp_manage_policy

Delete Blacklist policy

atp_manage_policy

Get Blacklist policies

atp_view_policy

Get Blacklist policy (update comment)

atp_view_policy

Get appliance info

atp_view_appliance_details

Get associations between domains and files

atp_view_entities

Get associations between endpoints and domains

atp_view_entities

Get associations between endpoints and files

atp_view_entities

Get domain entities

atp_view_entities

Get domain instances

atp_view_entities

Get domain instances for specific domain name

atp_view_entities

Get endpoint entities

atp_view_entities

Get endpoint instances

atp_view_entities

Get endpoint instances for specific device ID

atp_view_entities

Get entities

atp_view_entities

Get events

atp_view_events

Get file entities

atp_view_entities

Get file entity for specific SHA2

atp_view_entities

Get file instances

atp_view_entities

Get file instances for specific SHA2

atp_view_entities

Get incident comments

atp_view_incidents

Get incident-related events

atp_view_incidents

Get incidents

atp_view_incidents

Issue a command action

For required privilege

Command privileges

Issue sandbox command

atp_manage_sandbox

Patch Blacklist policy (update comment)

atp_manage_policy

Patch incident (close incidents or add comments)

atp_manage_incidents

Query command results

For required privilege

Command privileges

Query command status

For required privilege

Command privileges

Query sandbox command status

atp_view_sandbox

Release Associations next field

atp_view_entities

Release entities next field

atp_view_entities

Update comment field for Blacklist policy

atp_manage_policy

7.4. Command privileges

Privileges for issuing commands

Action

Privilege

Isolate endpoint

atp_manage_remediate_cmds

Rejoin endpoint

atp_manage_remediate_cmds

Get file

atp_endpoint_copy_file

Delete file

atp_manage_remediate_cmds

Endpoint data recorder search

atp_manage_endpoint_search

Endpoint (EOC) search

atp_manage_endpoint_search

Cancel command

* Delete file

* atp_manage_remediate_cmds

* Endpoint data recorder search

* atp_manage_endpoint_search

* Endpoint (EOC) search

* atp_manage_endpoint_search

Privileges for querying command status

Action

Privilege

Isolate endpoint

atp_view_remediate_cmds

Rejoin endpoint

atp_view_remediate_cmds

Get file

atp_view_copy_file_cmds

Delete file

atp_view_copy_file_cmds

Endpoint data recorder search

atp_view_endpoint_search

Endpoint (EOC) search

atp_view_endpoint_search

Privileges for querying command results

Action

Privilege

Endpoint data recorder search