1. Getting Started¶

A list of AMP scripts can be found here.

1.1. Region Endpoints¶

The following endpoints are available and it is recommended to use v1 for every endpoint.

1.2. Creating an API Client¶

Login into the AMP for Endpoints console, click the Accounts menu and choose API Credentials.
Click New API Credential, enter the Application name and Scope (action you want to allow) and then click Create.
From the API Key Details page, copy both the 3rd Party API Client ID and the API Key.

Warning

Do not close the tab without retrieving these values; the API key is not retrievable once the tab is closed.
You can now use your credentials to make API calls in the following format:

https://<your_client_id>:<your_api_key>@<api_endpoint>

Note

Alternatively, you can use Basic HTTP Authentication Header. Base 64 encode the string “:”, and send that prefixed with the string “Basic” as the authorization header. For instance, if your client_id was 1234, and your api_key was “atest”, then it would be base64 encoded to “MTIzNDphdGVzdA==”, and an example with your header would be:

http

POST https://api.amp.cisco.com/v1/event_streams HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

For more information see RFC 1945. Without proper HTTP Basic auth, the API will respond with an error as follows:

{
"version":"v1.0.0",
"data":{},
"errors":[{
   "error_code":401,
  "description":"Unauthorized",
  "details":["Unknown API key or Client ID"]
 }]
}

1.3. Testing Clients¶

To test that a client was created successfully run the following request.

GET /v1/version

http

POST https://api.amp.cisco.com/v1/version HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

1.4. Integration Requirements¶

1.4.1. General Requirements¶

Ability for user to enter the appropriate AMP FQDN.
Ability for user to enter the API credentials.
Ability to test credentials and indicate to the user that the integration is able to communicate properly from within the configuration dialog or page.
An AMQP client used to receive events from the streaming API is preferred.
The integration should combine Threat Quarantine and Threat Detected events based on the 1.data[].detection_id` field. The value is returned as a string.
Ability to link back to AMP for Endpoints console.

1.4.2. Using AMQP Client¶

1.4.2.1. Event Stream Management Requirements¶

Ability to easily (one click) create a new event stream with all events and all groups.
Ability to create an event stream and specify which event types by name and which event groups by name they would like included.
Ability to list existing Event Streams and their associated event types and groups.
Ability to delete existing Event Streams.

1.4.3. Requirements That Are Critical For Multinational Customers Who Have Deployments in Multiple AMP Clouds, Customers That Have More Than One Private Cloud Appliance, and MSSPs¶

Ability to configure more than one event stream as a data source.
Ability to enter Event Stream URL and credentials independent of the AMP API credentials or any event streams that may be listed.

1.5. Rate Limiting¶

API Clients are allowed to make a limited number of requests every hour. Each API response will include HTTP headers detailing the status of their rate limit. If the limit is overrun, then an HTTP 429 Error will be returned.

X-Rate-Limit-Limit - Total allowed requests in the current period.

X-Rate-Limit-Remaining - Requests left.

X-Rate-Limit-Reset - Number of seconds before the limit is reset.