Cisco AMP for Endpoints Integration Workflows

Getting Started

Cisco AMP for Endpoints API Docs

A list of AMP scripts can be found here.

Region Endpoints

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

Creating an API Client

  1. Login into the AMP for Endpoints console, click the Accounts menu and choose API Credentials.

  2. Click New API Credential, enter the Application name and Scope (action you want to allow) and then click Create.

  3. 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.

  4. 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"]
 }]
}

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==

Integration Requirements

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.

Using AMQP Client

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.

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.

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.

Pivot into AMP for Endpoints

Pivoting to Dashboard

Example for the SHA-256 from the last 30 days:

https://console.amp.cisco.com/dashboard?duration=720&artifact_type=sha&artifact=<SHA256>

https://console.amp.cisco.com/dashboard?duration=720&artifact_type=sha&artifact=ed01ebfbc9eb5bbea545af4d01bf5f1071661840480439c6e5babe8e080e41aa

Example for the IP Addresses from the last 30 days:

https://console.amp.cisco.com/dashboard?duration=720&artifact_type=ip&artifact=<IP_ADDRESS>

https://console.amp.cisco.com/dashboard?duration=720&artifact_type=ip&artifact=82.165.37.127

Example for the Event Type from the last 30 days:

https://console.amp.cisco.com/dashboard?duration=720&event_type=<EVENT_TYPE_ID>

https://console.amp.cisco.com/dashboard?duration=720&event_type=553648130

Pivoting to Events

Example for the Event Type(s) from the last 30 days:

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[<EVENT_TYPE_ID>]},"sort_by":"ts","sort_order":"desc","name":""}

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[553648130]},"sort_by":"ts","sort_order":"desc","name":""}

Example for the Connector GUID from the last 30 days:

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[],"ag":["<CONNECTOR_GUID>"]},"sort_by":"ts","sort_order":"desc","name":""}

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[],"ag":["d821e2d9-9280-489c-a6c3-be02d85ba8a0"]},"sort_by":"ts","sort_order":"desc","name":""}

Example for the Group GUID from the last 30 days:

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"time":["all"],"agg":["<GROUP_GUID>"]},"sort_by":"ts","sort_order":"desc","name":""}

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"time":["all"],"agg":["5cdf70dd-1b14-46a0-be90-e08da14172d8"]},"sort_by":"ts","sort_order":"desc","name":""}

Example for the SHA-256 from the last 30 days:

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[],"sha":["<SHA256>"]},"sort_by":"ts","sort_order":"desc","name":""}

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[],"sha":["55666eb6728a4e81bd4d12eee7f085a83adc8cb1a1570b70ed2ffb508b064fc3"]},"sort_by":"ts","sort_order":"desc","name":""}

Example for the Detection Name from the last 30 days:

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[],"det_name":["<DETECTION>"]},"sort_by":"ts","sort_order":"desc","name":""}

https://console.amp.cisco.com/dashboard/overview#/events/show/{"filters":{"agg":[],"time":"all","tid":[],"det_name":["W32.File.MalParent%22"]},"sort_by":"ts","sort_order":"desc","name":""}

Pivoting to File Trajectory

Example for pivoting by file trajectory:

https://console.amp.cisco.com/file/trajectory/<SHA256>

https://console.amp.cisco.com/file/trajectory/55666eb6728a4e81bd4d12eee7f085a83adc8cb1a1570b70ed2ffb508b064fc3

Pivoting to Device Trajectory

Example to load to most recent event:

https://console.amp.cisco.com/computers/<CONNECTOR_GUID>/trajectory2

https://console.amp.cisco.com/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory2

Example to load to specific event:

https://console.amp.cisco.com/computers/<CONNECTOR_GUID>/trajectory2?id=<EVENT_ID>

https://console.amp.cisco.com/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory2?id=553648130

Example to filter to an observable:

https://console.amp.cisco.com/computers/<COMPUTER_GUID>/trajectory?q=<QUERY>

https://console.amp.cisco.com/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory?q=<QUERY>

Example using SHA-256:

https://console.amp.cisco.com/computers/6c0c5f52-8992-4ae7-80c0-c10a3f3973b7/trajectory?q=<SHA-256>

https://console.amp.cisco.com/computers/6c0c5f52-8992-4ae7-80c0-c10a3f3973b7/trajectory?q=ed01ebfbc9eb5bbea545af4d01bf5f1071661840480439c6e5babe8e080e41aa

Example using Process or Filename:

https://console.amp.cisco.com/computers/6c0c5f52-8992-4ae7-80c0-c10a3f3973b7/trajectory?q=<ProcessOrFilename>

https://console.amp.cisco.com/computers/6c0c5f52-8992-4ae7-80c0-c10a3f3973b7/trajectory?q=tasksche.exe

Example using IP Address:

https://console.amp.cisco.com/computers/36b46210-30f6-4236-bbb2-5dbaa23947b6/trajectory?q=<IPAddress>

https://console.amp.cisco.com/computers/36b46210-30f6-4236-bbb2-5dbaa23947b6/trajectory?q=82.165.37.127

Example using Domain:

https://console.amp.cisco.com/computers/1d485168-407a-4b01-855c-20522f365046/trajectory?q=<Domain>

https://console.amp.cisco.com/computers/1d485168-407a-4b01-855c-20522f365046/trajectory?q=propay24.ru

Example using URL:

https://console.amp.cisco.com/computers/1d485168-407a-4b01-855c-20522f365046/trajectory?q=<URL>

https://console.amp.cisco.com/computers/1d485168-407a-4b01-855c-20522f365046/trajectory?q=http://propay24.ru/4/pict.jpg

Ingest Events

Streaming API (Preferred)

AMP for Endpoints Streaming API

The AMP for Endpoints Streaming API is used to collect events from AMP for Endpoints. It is based on AMQP 0.9.1 and is implemented using Rabbit MQ. Communication with with the streaming API requires an AMQP client, a list of clients libraries can be found here.

  • The passive and durable bits should be set on the queue
  • The protocol is over SSL/TLS.

The events in an event stream can be received using a persistent connection or queried on an interval. When using a persistent connection the client will connect to the stream and wait for events to be generated. When the events are generated they will be consumed immediately. If queried on an interval the events will sit in the queue waiting to be consumed. When the client connects it will consume all of the events in the queue and then close the connection. Events will sit in the queue for 10 days maximum, at which point they will be deleted.

An event can only be consumed by a single consumer. If multiple consumers are connected to the same event stream, the events will be divided between them in no particular order. It is not recommended to have more than one consumer connected to a given event stream.

Create Stream

Customers must create an Event Stream using the following request.

POST /v1/event_streams

http

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

They have the options of specifying which event types they would like in the stream as well as which groups they would like to receive events from. Organizations are limited to a maximum of 5 event streams.

The credentials for an event stream are only provided at time of creation. If they are not stored at this point in time there is no ability to retrieve or reset the credentials for the stream. The stream will have to be deleted and a new stream with the same settings will have to be created.

Example Create Stream Script

Example Duplicate Stream Script

Connect to Stream

Any AMQP 0.9.1 client can be used to connect to the stream. You can find an example in Ruby in the API documentation here. There is an example implementation in Python using Pika to connect to a stream that can be found in the example below:

Example Stream Consumer

Delete Stream

Customers can delete an Event Stream using the following request.

DELETE /v1/event_streams/{:id}

http

DELETE https://api.amp.cisco.com/v1/event_streams/{:id} HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

Example Delete Stream Script

Correlating Events

In the AMP for Endpoints UI a Quarantine event (success or failure) is correlated with a Threat Detected event. The UI combines these into a single event making it easy for users to see which things to focus on. In the API these events are separated. To correlate Threat Detected with Quarantined actions you have to track .data[].detection_id. The value is returned as a string.

Correlating these events together makes for a much better user experience as it allows to the user to differentiate between a quarantined threat that poses a less immediate risk and a threat that may still be on the machine. There are multiple event types that can all have the same detection_id for a detection. Examples of these events are:

Event Name Event Type ID
Threat Detected 1090519054
Threat Quarantined 553648143
Quarantine Failure 2164260880
Cloud Recall Detection 553648147
Cloud Recall Quarantine Successful 553648155

The integration should combine these events events based on the .data[].detection_id field. It is possible for a single detection to have a Threat Detected, Threat Quarantine, and a Quarantine Failure. These events may be returned in the API in any order.

The following event JSON shows the correlation of the detection_id value of 6533241145273614338:

[
    {
      "id": 6533241145273614340,
      "timestamp": 1593079552,
      "timestamp_nanoseconds": 619000000,
      "date": "2020-06-25T10:05:52+00:00",
      "event_type": "Threat Quarantined",
      "event_type_id": 553648143,
      "detection_id": "6533241145273614338",
      "connector_guid": "0b4883d4-8ecf-4404-9453-13cba0ee7662",
      "group_guids": [
        "d7cf8b98-e830-4ce1-a0e5-d943ed6bab17"
      ],
      "severity": "Medium",
      "computer": {
        "connector_guid": "0b4883d4-8ecf-4404-9453-13cba0ee7662",
        "hostname": "Demo_AMP_Threat_Quarantined",
        "external_ip": "163.32.98.150",
        "active": true,
        "network_addresses": [
          {
            "ip": "50.88.43.2",
            "mac": "87:9c:f8:c6:c9:cf"
          }
        ],
        "links": {
          "computer": "https://api.amp.cisco.com/v1/computers/0b4883d4-8ecf-4404-9453-13cba0ee7662",
          "trajectory": "https://api.amp.cisco.com/v1/computers/0b4883d4-8ecf-4404-9453-13cba0ee7662/trajectory",
          "group": "https://api.amp.cisco.com/v1/groups/d7cf8b98-e830-4ce1-a0e5-d943ed6bab17"
        }
      },
      "file": {
        "disposition": "Malicious",
        "identity": {
          "sha256": "a78c29d1fa05c2b23d1dc9b75da8c053399143682fe3779bc466f10e1a997850"
        }
      }
    },
    {
      "id": 6533241145273614339,
      "timestamp": 1593079552,
      "timestamp_nanoseconds": 619000000,
      "date": "2020-06-25T10:05:52+00:00",
      "event_type": "Threat Detected",
      "event_type_id": 1090519054,
      "detection_id": "6533241145273614338",
      "connector_guid": "0b4883d4-8ecf-4404-9453-13cba0ee7662",
      "group_guids": [
        "d7cf8b98-e830-4ce1-a0e5-d943ed6bab17"
      ],
      "severity": "Medium",
      "computer": {
        "connector_guid": "0b4883d4-8ecf-4404-9453-13cba0ee7662",
        "hostname": "Demo_AMP_Threat_Quarantined",
        "external_ip": "163.32.98.150",
        "active": true,
        "network_addresses": [
          {
            "ip": "50.88.43.2",
            "mac": "87:9c:f8:c6:c9:cf"
          }
        ],
        "links": {
          "computer": "https://api.amp.cisco.com/v1/computers/0b4883d4-8ecf-4404-9453-13cba0ee7662",
          "trajectory": "https://api.amp.cisco.com/v1/computers/0b4883d4-8ecf-4404-9453-13cba0ee7662/trajectory",
          "group": "https://api.amp.cisco.com/v1/groups/d7cf8b98-e830-4ce1-a0e5-d943ed6bab17"
        },
        "user": "johndoe"
      },
      "file": {
        "disposition": "Malicious",
        "identity": {
          "sha256": "a78c29d1fa05c2b23d1dc9b75da8c053399143682fe3779bc466f10e1a997850",
          "sha1": "cf162622e29bca072d01b274fbbc3ceaacdd13c7",
          "md5": "0fe5be3811a98ee6a9c997d3812d911a"
        },
        "file_name": "SqGGuYXyy.exe",
        "file_path": "\\\\?\\C:\\SqGGuYXyy.exe",
        "parent": {
          "process_id": 896,
          "disposition": "Clean",
          "file_name": "svchost.exe",
          "identity": {
            "sha256": "121118a0f5e0e8c933efd28c9901e54e42792619a8a3a6d11e1f0025a7324bc2",
            "sha1": "4af001b3c3816b860660cf2de2c0fd3c1dfb4878",
            "md5": "54a47f6b5e09a77e61649109c6a08866"
          }
        }
      },
      "detection": "W32.Overdrive.RET"
    }
]

Grouping Events

When creating incidents from AMP for Endpoints events, grouping the events that occur within a defined time period helps reduce alert fatigue. Here are three common scenarios that can be used to group events.

Same Detection (Hash) on Multiple Endpoints in N Time Period

Assuming N time period is 5 minutes the following “events” would be in one incident:

{"sha256":"8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8", "date":"2019-09-19T18:00:00+00:00", "computer":"alpha"}
{"sha256":"8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8", "date":"2019-09-19T18:00:23+00:00", "computer":"bravo"}
{"sha256":"8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8", "date":"2019-09-19T18:02:47+00:00", "computer":"charlie"}
{"sha256":"8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8", "date":"2019-09-19T18:03:51+00:00", "computer":"delta"}
{"sha256":"8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8", "date":"2019-09-19T18:04:44+00:00", "computer":"echo"}

The next “event” would go to a new incident:

{"sha256":"8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8", "date":"2019-09-19T18:09:13+00:00", "computer":"foxtrot"}

Same Detection (Hash) on Multiple Endpoints on Same Endpoint in N Time Period

Assuming N time period is 5 minutes the following “events” would be in one incident:

{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:00:00+00:00", "computer":"golf"}
{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:00:23+00:00", "computer":"golf"}
{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:02:47+00:00", "computer":"golf"}
{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:03:51+00:00", "computer":"golf"}
{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:04:44+00:00", "computer":"golf"}

The next “event” would go to a new incident:

{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:09:13+00:00", "computer":"golf"}

Multiple Detections (Hash or IP) on the Same Computer in N Time Period

Assuming N time period is 5 minutes the following “events” would be in one incident:

{"sha256":"b9dd960c1753459a78115d3cb845a57d924b6877e805b08bd01086ccdf34433c", "date":"2019-09-19T18:00:00+00:00", "computer":"hotel"}
{"sha256":"4f4a9410ffcdf895c4adb880659e9b5c0dd1f23a30790684340b3eaacb045398", "date":"2019-09-19T18:00:23+00:00", "computer":"hotel"}
{"sha256":"092c79e8f80e559e404bcf660c48f3522b67aba9ff1484b0367e1a4ddef7431d", "date":"2019-09-19T18:02:47+00:00", "computer":"hotel"}
{"black_list_ip":"1.2.3.4", "date":"2019-09-19T18:03:51+00:00", "computer":"hotel"}
{"black_list_ip":"4.3.2.1", "date":"2019-09-19T18:04:44+00:00", "computer":"hotel"}

The next “event” would go to a new incident:

{"sha256":"f144a6907dc4284d1f9fe6a7d9b9ff53c02c1d07ba68f24d413d7ff7f757a782", "date":"2019-09-19T18:09:13+00:00", "computer":"hotel"}

Query Events

Trajectory Events

Note

Cisco AMP for Endpoints uses the term trajectory to describe the execution timeline of activities on a computer (multi-file execution).

For example, if Computer A was under investigation and you wanted to review the SHA-256s of processes and files on the computer you would follow these steps:

  1. First, query the Computer Activity endpoint:

    GET /v1/computers/{:connector_guid}/trajectory

    http

    GET https://api.amp.cisco.com/v1/computers/{:connector_guid}/trajectory HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

    An example request:

    GET /v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory

    http

    GET https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

    An example response:

    {
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory"
    }
  },
  "data": {
    "computer": {
      "connector_guid": "d821e2d9-9280-489c-a6c3-be02d85ba8a0",
      "hostname": "Demo_Command_Line_Arguments_Kovter",
      "windows_processor_id": "1937b8e046adf25",
      "active": true,
      "links": {
        "computer": "https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0",
        "trajectory": "https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory",
        "group": "https://api.amp.cisco.com/v1/groups/68665863-74d5-4bc1-ac7f-5477b2b6406e"
      },
      "connector_version": "99.0.99.11594",
      "operating_system": "Windows 10, SP 0.0",
      "internal_ips": [
        "48.228.237.163"
      ],
      "external_ip": "87.18.29.150",
      "group_guid": "68665863-74d5-4bc1-ac7f-5477b2b6406e",
      "install_date": "2020-02-17T08:47:17Z",
      "network_addresses": [
        {
          "mac": "cd:e0:30:42:21:f7",
          "ip": "48.228.237.163"
        }
      ],
      "policy": {
        "guid": "75f5a2b7-2875-41c1-9a11-0b212f347a08",
        "name": "Triage Policy"
      },
      "faults": [

      ],
      "isolation": {
        "available": false,
        "status": "not_isolated"
      },
      "orbital": {
        "status": "not_enabled"
      }
    },
    "events": [
      {
        "timestamp": 1581940174,
        "timestamp_nanoseconds": 842009819,
        "date": "2020-02-17T11:49:34+00:00",
        "event_type": "Executed by",
        "group_guids": [
          "68665863-74d5-4bc1-ac7f-5477b2b6406e"
        ],
        "file": {
          "disposition": "Clean",
          "file_name": "taskmgr.exe",
          "file_path": "/c:/windows/system32/taskmgr.exe",
          "file_type": "PE Executable",
          "identity": {
            "sha256": "292106dfdfacdc0ab33e3cb580ae23f0506cb2402b9b3ca2811a0a1c2f6ebf6c"
          },
          "parent": {
            "disposition": "Clean",
            "identity": {
              "sha256": "438b6ccd84f4dd32d9684ed7d58fd7d1e5a75fe3f3d12ab6c788e6bb0ffad5e7"
            }
          }
        }
      },
      {
        "timestamp": 1581940173,
        "timestamp_nanoseconds": 543023082,
        "date": "2020-02-17T11:49:33+00:00",
        "event_type": "Executed by",
        "group_guids": [
          "68665863-74d5-4bc1-ac7f-5477b2b6406e"
        ],
        "file": {
          "disposition": "Clean",
          "file_name": "taskmgr.exe",
          "file_path": "/c:/windows/system32/taskmgr.exe",
          "file_type": "PE Executable",
          "identity": {
            "sha256": "292106dfdfacdc0ab33e3cb580ae23f0506cb2402b9b3ca2811a0a1c2f6ebf6c"
          },
          "parent": {
            "disposition": "Unknown",
            "identity": {
              "sha256": "0bd0a04d7b32648f627387894a165b321ac277bd8103a4ca6790607458adf778"
            }
          }
        }
      }
    ]
  }
}

  2. Next, you would parse the response for .data.events[].file.identity.sha256 and .data.events[].file.parent.identity.sha256.

  3. You would then evaluate these hashes with your product or a 3rd party observable service.

Detection Events

To hunt for computers that have seen a SHA-256 but have not created an event for that SHA-256 follow these steps:

1.First, query the Computer Activity to get a list of computers that have seen the SHA-256 observable:

GET /v1/computers/activity

http

GET https://api.amp.cisco.com/v1/computers/activity HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

An example request:

GET /v1/computers/activity?q=814a37d89a79aa3975308e723bc1a3a67360323b7e3584de00896fe7c59bbb8e&offset=0&limit=5

http

GET https://api.amp.cisco.com/v1/computers/activity?q=814a37d89a79aa3975308e723bc1a3a67360323b7e3584de00896fe7c59bbb8e&offset=0&limit=5 HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

An example response:

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/computers/activity?q=814a37d89a79aa3975308e723bc1a3a67360323b7e3584de00896fe7c59bbb8e&offset=0&limit=5"
    },
    "results": {
      "total": 1,
      "current_item_count": 1,
      "index": 0,
      "items_per_page": 5
    }
  },
  "data": [
    {
      "connector_guid": "367a2c23-d0e7-464b-ac3f-9a209868b31d",
      "hostname": "Demo_Stabuniq",
      "windows_processor_id": "83f976a0db415e2",
      "active": true,
      "links": {
        "computer": "https://api.amp.cisco.com/v1/computers/367a2c23-d0e7-464b-ac3f-9a209868b31d",
        "trajectory": "https://api.amp.cisco.com/v1/computers/367a2c23-d0e7-464b-ac3f-9a209868b31d/trajectory?q=814a37d89a79aa3975308e723bc1a3a67360323b7e3584de00896fe7c59bbb8e",
        "group": "https://api.amp.cisco.com/v1/groups/b077d6bc-bbdf-42f7-8838-a06053fbd98a"
      }
    }
  ]
}

  1. Store the values of .data[].connector_guid.

  2. Query the Events Endpoint to see what events were generated for the same SHA-256 observable:

    GET /v1/events

    http

    GET https://api.amp.cisco.com/v1/events HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

    An example request:

    GET /v1/events?detection_sha256=b630e72639cc7340620adb0cfc26332ec52fe8867b769695f2d25718d68b1b40&limit=1

    http

    GET https://api.amp.cisco.com/v1/events?detection_sha256=b630e72639cc7340620adb0cfc26332ec52fe8867b769695f2d25718d68b1b40&limit=1 HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

    An example response:

    {
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/events?detection_sha256=b630e72639cc7340620adb0cfc26332ec52fe8867b769695f2d25718d68b1b40&limit=1",
      "next": "https://api.amp.cisco.com/v1/events?detection_sha256=b630e72639cc7340620adb0cfc26332ec52fe8867b769695f2d25718d68b1b40&limit=1&offset=1"
    },
    "results": {
      "total": 4,
      "current_item_count": 1,
      "index": 0,
      "items_per_page": 1
    }
  },
  "data": [
    {
      "id": 6180352115244794000,
      "timestamp": 1582222838,
      "timestamp_nanoseconds": 279000000,
      "date": "2020-02-20T18:20:38+00:00",
      "event_type": "Threat Detected",
      "event_type_id": 1090519054,
      "detection": "W32.GenericKD:ZVETJ.18gs.1201",
      "detection_id": "6180352115244793858",
      "connector_guid": "20a0ce9f-44d1-4cbb-ab04-8a0705448b72",
      "group_guids": [
        "6c3c2005-4c74-4ba7-8dbb-c4d5b6bafe03"
      ],
      "severity": "Medium",
      "computer": {
        "connector_guid": "20a0ce9f-44d1-4cbb-ab04-8a0705448b72",
        "hostname": "Demo_Upatre",
        "external_ip": "69.226.122.127",
        "user": "A@TEMPLATE-W7X86",
        "active": true,
        "network_addresses": [
          {
            "ip": "230.122.135.241",
            "mac": "3f:1e:b2:28:25:24"
          }
        ],
        "links": {
          "computer": "https://api.amp.cisco.com/v1/computers/20a0ce9f-44d1-4cbb-ab04-8a0705448b72",
          "trajectory": "https://api.amp.cisco.com/v1/computers/20a0ce9f-44d1-4cbb-ab04-8a0705448b72/trajectory",
          "group": "https://api.amp.cisco.com/v1/groups/6c3c2005-4c74-4ba7-8dbb-c4d5b6bafe03"
        }
      },
      "file": {
        "disposition": "Malicious",
        "file_name": "wsymqyv90.exe",
        "file_path": "\\\\?\\C:\\Users\\Administrator\\AppData\\Local\\Temp\\OUTLOOK_TEMP\\wsymqyv90.exe",
        "identity": {
          "sha256": "b630e72639cc7340620adb0cfc26332ec52fe8867b769695f2d25718d68b1b40",
          "sha1": "70aef829bec17195e6c8ec0e6cba0ed39f97ba48",
          "md5": "e2f5dcd966e26d54329e8d79c7201652"
        },
        "parent": {
          "process_id": 4040,
          "disposition": "Clean",
          "file_name": "iexplore.exe",
          "identity": {
            "sha256": "b4e5c2775de098946b4e11aba138b89d42b88c1dbd4d5ec879ef6919bf018132",
            "sha1": "8de30174cebc8732f1ba961e7d93fe5549495a80",
            "md5": "b3581f426dc500a51091cdd5bacf0454"
          }
        }
      }
    }
  ]
}

  3. Store the values of .data[].connector_guid.

  4. Diff the connector_guid values found in step two with the connector_guid values found in step four.

  5. Create a high priority alert for the endpoints that have seen the file but did not generate any events for it. This means that there is malicious activity that needs to be sent as an alert to the SOC.

Note

Example implementations of similar workflows can be found here:

Response Actions

Simple Custom Detections

A best practice for organizations is to only have one Simple Custom Detection (SCD) list and to use that SCD list in all policies. A policy can only have one SCD list configured at a time. A SHA256 added to an SCD list will not be alerted on or quarantined, if it is seen on a computer that does not have that SCD list applied to the policy that is applied to the group the computer is in.

Get SCD List GUIDs

To add a SHA256 to a SCD list use the following request to first get a list of the SCD file lists that are available:

GET /v1/file_lists/simple_custom_detections

http

GET https://api.amp.cisco.com/v1/file_lists/simple_custom_detections HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

This will return a list of SCD file lists for the organization:

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/file_lists/simple_custom_detections?limit=3&offset=2",
      "prev": "https://api.amp.cisco.com/v1/file_lists/simple_custom_detections?limit=3&offset=0",
      "next": "https://api.amp.cisco.com/v1/file_lists/simple_custom_detections?limit=3&offset=5"
    },
    "results": {
      "total": 7,
      "current_item_count": 3,
      "index": 2,
      "items_per_page": 3
    }
  },
  "data": [
    {
      "name": "Sample SCD List 1",
      "guid": "e773a9eb-296c-40df-98d8-bed46322589d",
      "type": "simple_custom_detections",
      "links": {
        "file_list": "https://api.amp.cisco.com/v1/file_lists/021f6434-0b67-4790-8601-b535d66ca0fb"
      }
    },
    {
      "name": "Sample SCD List 2",
      "guid": "db2b9dd6-94d2-4acc-a6cb-c4c66c9199a1",
      "type": "simple_custom_detections",
      "links": {
        "file_list": "https://api.amp.cisco.com/v1/file_lists/db2b9dd6-94d2-4acc-a6cb-c4c66c9199a1"
      }
    }
  ]
}

From the response parse out .data[].guid and .data[].name. Present the user with the list of names found in .data[].name. When the user selects the SCD list they would like to add or remove a SHA256 to save the .data[].guid for that SCD list.

Add a SHA256 to a SCD List

To add a SHA256 to a SCD list use the following request:

POST /v1/file_lists/{:file_list_guid}/files/{:sha256}

http

POST https://api.amp.cisco.com/v1/file_lists/{:file_list_guid}/files/{:sha256} HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

If the user chose Sample SCD List 1 and wanted to add the SHA256 d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b the request would be:

POST /v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d/files/d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b

http

POST https://api.amp.cisco.com/v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d/files/d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

Optionally a description can be send in the request body:

{"description":"Added from Product XYZ as part of Incident 123"}

A successful request will return a 201 status with a response body like this:

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d/files/d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b`"
    }
  },
  "data": {
    "sha256": "d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b",
    "description": "Added from Product XYZ as part of Incident 123",
    "source": "Created by entering SHA-256 via Public api.",
    "links": {
      "file_list": "https://api.amp.cisco.com/v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d"
    }
  }
}

Remove a SHA256 from a SCD List

To remove a SHA256 from a SCD list use the following request:

DELETE /v1/file_lists/{:file_list_guid}/files/{:sha256}

http

DELETE https://api.amp.cisco.com/v1/file_lists/{:file_list_guid}/files/{:sha256} HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

If the user chose Sample SCD List 1 and wanted to remove the SHA256 d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b the request would be:

DELETE /v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d/files/d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b

http

DELETE https://api.amp.cisco.com/v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d/files/d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

A successful request will return 200 status with a response body like this:

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/file_lists/e773a9eb-296c-40df-98d8-bed46322589d/files/d5cb3ef9816e8fd30cc9537bb394a7cc6c46c1dff1c65f11b527ef1df14edc3b"
    }
  },
  "data": {
  }
}

Application Block List

Application Block Lists are only applicable to binaries. When the SHA-256 of a binary is added to the Application Block List, AMP will prevent that file from being executed. Adding the SHA-256 of a document or other file that is not a binary to an Application Block List will not result in any action occurring when the file is interacted with. When File Conviction Mode is set to Audit Application Block Lists will not be enforced.

Get Application Block List GUIDs

To add a SHA-256 to an Application Block List the following request to first get a list of the Application Block Lists that are available:

GET /v1/file_lists/application_blocking

http

GET https://api.amp.cisco.com/v1/file_lists/application_blocking HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

This will return a list of Application Block Lists for the organization:

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/file_lists/application_blocking?limit=3&offset=2",
      "prev": "https://api.amp.cisco.com/v1/file_lists/application_blocking?limit=3&offset=0",
      "next": "https://api.amp.cisco.com/v1/file_lists/application_blocking?limit=3&offset=5"
    },
    "results": {
      "total": 6,
      "current_item_count": 3,
      "index": 2,
      "items_per_page": 3
    }
  },
  "data": [
    {
      "name": "Sample Application Blocking List 2",
      "guid": "e4984c9b-651a-499e-a6fe-9ee938dab661",
      "type": "application_blocking",
      "links": {
        "file_list": "https://api.amp.cisco.com/v1/file_lists/e4984c9b-651a-499e-a6fe-9ee938dab661"
      }
    },
    {
      "name": "Sample Application Blocking List 3",
      "guid": "0fda9022-9491-4982-9066-adc4f65007bc",
      "type": "application_blocking",
      "links": {
        "file_list": "https://api.amp.cisco.com/v1/file_lists/0fda9022-9491-4982-9066-adc4f65007bc"
      }
    }
  ]
}

From the response parse out .data[].guid and .data[].name. Present the user with the list of names found in .data[].name. When the user selects the Application Block List they would like to add or remove a SHA256 to save the .data[].guid for that Application Block List.

Add a SHA256 to an Application Block List

To add a SHA256 to an Application Block list use the following request:

POST /v1/file_lists/{:file_list_guid}/files/{:sha256}

http

POST https://api.amp.cisco.com/v1/file_lists/{:file_list_guid}/files/{:sha256} HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

Remove a SHA256 from an Application Block List

To remove a SHA256 from an Application Block List use the following request:

DELETE /v1/file_lists/{:file_list_guid}/files/{:sha256}

http

DELETE https://api.amp.cisco.com/v1/file_lists/{:file_list_guid}/files/{:sha256} HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

Move Host to Group

To change which engines are enabled or disabled for an endpoint, the endpoint must be moved to a different group with a policy that enables or disables the desired engines.

Get Group GUIDs

To fetch a list of all groups and their associated GUIDs use the following request:

GET /v1/groups

http

GET https://api.amp.cisco.com/v1/groups HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

From the response parse out .data[].guid and .data[].name. Present the user with the list of groups found in .data[].name. When the user selects the group they would like to move hosts to save the .data[].guid for that group.

Moving a Host to a Group

To move a computer to a group with a given connector_guid and group_guid use the following request:

http

PATCH https://api.amp.cisco.com/v1/computers/{:connector_guid} HTTP/1.1

{"group_guid": "{:group_guid}"}

An example cURL request:

curl -X PATCH \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'content-length: 53' \
--compressed -H 'Accept-Encoding: gzip, deflate' \
-d '{"group_guid":"68665863-74d5-4bc1-ac7f-5477b2b6406e"}' \
-u YOUR_API_CLIENT_ID \
'https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0'

Example response:

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0"
    }
  },
  "data": {
    "connector_guid": "d821e2d9-9280-489c-a6c3-be02d85ba8a0",
    "hostname": "Demo_Command_Line_Arguments_Kovter",
    "windows_processor_id": "1937b8e046adf25",
    "active": true,
    "links": {
      "computer": "https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0",
      "trajectory": "https://api.amp.cisco.com/v1/computers/d821e2d9-9280-489c-a6c3-be02d85ba8a0/trajectory",
      "group": "https://api.amp.cisco.com/v1/groups/68665863-74d5-4bc1-ac7f-5477b2b6406e"
    },
    "connector_version": "99.0.99.11594",
    "operating_system": "Windows 10, SP 0.0",
    "internal_ips": [
      "48.228.237.163"
    ],
    "external_ip": "87.18.29.150",
    "group_guid": "68665863-74d5-4bc1-ac7f-5477b2b6406e",
    "install_date": "2020-02-17T08:47:17Z",
    "network_addresses": [
      {
        "mac": "cd:e0:30:42:21:f7",
        "ip": "48.228.237.163"
      }
    ],
    "policy": {
      "guid": "75f5a2b7-2875-41c1-9a11-0b212f347a08",
      "name": "Triage Policy"
    },
    "faults": [

    ],
    "isolation": {
      "available": false,
      "status": "not_isolated"
    },
    "orbital": {
      "status": "not_enabled"
    }
  }
}

Isolate Host

API Workflow: Isolate Host Based on Presence of File Hash

To isolate hosts based on a SHA256 hash that is present on the system first query the following request with the q parameter set to the SHA256 you want to lookup:

GET /v1/computers/activity?q=SHA256

http

GET https://api.amp.cisco.com/v1/computers/activity?q=SHA256 HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

This will return a list of computers that have seen that SHA256 regardless of any AMP for Endpoint event, the response will return a maximum of 500 endpoints per page. The .metadata.next URL can be queried to get the next page of endpoints and will only be present if there is more than one page of results.

{
  "version": "v1.2.0",
  "metadata": {
    "links": {
      "self": "https://api.amp.cisco.com/v1/computers/activity?q=SearchProtocolHost.exe&limit=5",
      "next": "https://api.amp.cisco.com/v1/computers/activity?q=SearchProtocolHost.exe&limit=5&offset=5"
    },
    "results": {
      "total": 10,
      "current_item_count": 5,
      "index": 0,
      "items_per_page": 5
    }
  },
  "data": [
    {
      "connector_guid": "043a414d-5520-4374-b545-dff6a0e74195",
      "hostname": "Demo_CozyDuke",
      "windows_processor_id": "d83597eb420f61a",
      "active": true,
      "links": {
        "computer": "https://api.amp.cisco.com/v1/computers/043a414d-5520-4374-b545-dff6a0e74195",
        "trajectory": "https://api.amp.cisco.com/v1/computers/043a414d-5520-4374-b545-dff6a0e74195/trajectory?q=SearchProtocolHost.exe",
        "group": "https://api.amp.cisco.com/v1/groups/6c3c2005-4c74-4ba7-8dbb-c4d5b6bafe03"
      }
    },
    {
      "connector_guid": "20a0ce9f-44d1-4cbb-ab04-8a0705448b72",
      "hostname": "Demo_Upatre",
      "windows_processor_id": "70bd6284e15af93",
      "active": true,
      "links": {
        "computer": "https://api.amp.cisco.com/v1/computers/20a0ce9f-44d1-4cbb-ab04-8a0705448b72",
        "trajectory": "https://api.amp.cisco.com/v1/computers/20a0ce9f-44d1-4cbb-ab04-8a0705448b72/trajectory?q=SearchProtocolHost.exe",
        "group": "https://api.amp.cisco.com/v1/groups/6c3c2005-4c74-4ba7-8dbb-c4d5b6bafe03"
      }
    }
  ]
}

From the response parse out the .data[].connector_guid values and run the following request for each connector GUID to validate the endpoint can be put into isolation:

OPTIONS /v1/computers/{:connector_guid}/isolation

http

OPTIONS https://api.amp.cisco.com/v1/computers/{:connector_guid}/isolation HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

An example response from the OPTIONS query:

strict-transport-security: max-age=31536000
status: 204 No Content
x-ratelimit-limit: 3000
x-ratelimit-reset: 3595
x-ratelimit-remaining: 2982
x-frame-options: SAMEORIGIN
allow: OPTIONS, GET, PUT
x-ratelimit-resetdate: 2020-02-20T19:42:33Z
transfer-encoding: chunked

The allow values will show which options are available. If PUT is available use the following request to start isolation for that host:

PUT /v1/computers/{:connector_guid}/isolation

http

PUT https://api.amp.cisco.com/v1/computers/{:connector_guid}/isolation HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

If you skip checking what options are available and try to start isolation you will receive an error if the host is not a supported OS, isolation is not enabled in the policy, or the endpoint is in a transitional state or is already isolated.

Checking an Endpoint for Vulnerable Software

General Organization Collection

List of all Vulnerabilities in an Organization

For a general query of all vulnerabilities in the organization use the following request:

GET /v1/vulnerabilities

http

GET https://api.amp.cisco.com/v1/vulnerabilities HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==
List of Specific Computers Within an Organization That Have Observed a Vulnerability With a Given SHA-256

To provide a list of computers on which the vulnerability has been observed with given SHA-256 use the following request:

GET /v1/vulnerabilities/{:sha256}/computers

http

GET https://api.amp.cisco.com/v1/vulnerabilities/{:sha256}/computers HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

Specific Endpoint Collection

To fetch a list of events from a specific computer that has vulnerabilities use the following request:

GET /v1/events?connector_guid[]={:connector_guid}&event_type[]=1107296279

http

GET https://api.amp.cisco.com/v1/events?connector_guid%5B%5D=%7B%3Aconnector_guid%7D&event_type%5B%5D=1107296279 HTTP/1.1
Authorization: Basic MTIzNDphdGVzdA==

Managed Deployment Techniques

Deploy Agent

Cisco AMP supports managed installs and has different command line flags/switches that can be used to customize agent installation, which vary by operating system.

Windows

Note

Common flags and what they do:

  • /R: For all Connector versions 5.1.13 and higher this must be the first switch used.
  • /S: Used to put the installer into silent mode.
  • /skiptetra 1: Skip installation of the TETRA driver.
  • /skipdfc 1: Skip installation of the DFC driver.

/skiptetra and /skipdfc are both binary switches where 0 is false/off and 1 is true/on. This logic applies to any command switch, as detailed in the documentation below.

For more information please see Chapter 3 of Deployment Strategy Guide or Chapter 7 of the User Guide here.

Deploy Windows AMP for Endpoint

When installing on a Windows Server/Domain Controller:

amp_GroupName.exe /R /S /skiptetra 1 /skipdfc 1

When installing on Windows Desktops:

amp_GroupName.exe /R /S
Deploy Windows AMP for Endpoint With No UI Elements

When installing on a Windows Server/Domain Controller:

amp_GroupName.exe /R /S /skiptetra 1 /skipdfc 1 /desktopicon 0 /startmenu 0 /contextmenu 0

When installing on Windows Desktops:

amp_GroupName.exe /R /S /desktopicon 0 /startmenu 0 /contextmenu 0
Deploy Windows AMP for Endpoint and Specify the Installation Parameters

For a complete list of command line switches that can be used during installation please see Chapter 3 of Deployment Strategy Guide or Chapter 7 of the User Guide here. You can then prompt the user for the value of each switch.

Upgrade Windows AMP for Endpoints Connector

To upgrade the connector keeping the deployment settings you must read the command line switches used during the previous installation from the local.xml:

Note

The local.xml is found in Cisco AMP install directory which can be found by checking the registry key value of HKEY_LOCAL_MACHINE\SOFTWARE\Immunet Protect\InstallDir.

  • /config/install/switches/skipdfc
  • /config/install/switches/skiptetra
  • /config/install/switches/skipexprevprereqcheck
  • /config/install/switches/desktopicon
  • /config/install/switches/startmenu
  • /config/install/switches/contextmenu
  • /config/install/switches/overridepolicy

For example if the local.xml contained:

...
  </agent>
  <install>
   <switches>
    <skipdfc>1</skipdfc>
    <desktopicon>0</desktopicon>
    <sendfile>1</sendfile>
    <versioncheck>0</versioncheck>
    <noadmin>0</noadmin>
    <skiposcheck>0</skiposcheck>
    <skiptetra>1</skiptetra>
    <contextmenu>0</contextmenu>
    <startmenu>0</startmenu>
    <trayicon>0</trayicon>
    <overridepolicy>1</overridepolicy>
    <skipexprevprereqcheck>0</skipexprevprereqcheck>
    <overrideinstpathlength>0</overrideinstpathlength>
    <renameinstalldir>1</renameinstalldir>
   </switches>
  </install>
  <janus>
...

Then you would use the following command to upgrade:

amp_GroupName.exe /R /S /skipdfc 1 /skiptetra 1 /skipexprevprereqcheck 0 /desktopicon 0
/startmenu 0 /contextmenu 0 /overridepolicy 1

Linux

Deploy Linux AMP for Endpoint Connector

For RHEL/CentOS versions 6-8 please go here and select the group you will be deploying a connector for. Next, select the distribution of Linux you will be using and copy the URL it creates. Then, run the following two commands:

wget <CopiedURL> -o amp_<GroupName>_rhel-<LinuxDistribution>.rpm
yum install -y amp_<GroupName>_rhel-<LinuxDistribution>.rpm
Upgrade Linux AMP for Endpoints Connector

To upgrade RHEL/CentOS versions 6-8 connectors please go here and select the group for the connector. Next, select the distribution of Linux that was used and copy the URL it creates. Then, run the following two commands:

wget <CopiedURL> -o amp_<GroupName>_rhel-<LinuxDistribution>.rpm
yum install -y amp_<GroupName>_rhel-<LinuxDistribution>.rpm

MacOS

Deploy MacOS AMP for Endpoint Connector

Once you have the connector on the endpoint, execute the following commands to install:

Please modify the file name to whatever the file was saved as.

hdiutil attach amp_GroupName.dmg
installer -pkg /Volumes/ampmac_connector/ciscoampmac_connector.pkg -target /
hdiutil detach /Volumes/ampmac_connector
Upgrade MacOS AMP for Endpoints Connector

To upgrade, get the connector on the endpoint and execute the following commands to install:

Please modify the file name to whatever the file was saved as.

hdiutil attach amp_GroupName.dmg
installer -pkg /Volumes/ampmac_connector/ciscoampmac_connector.pkg -target /
hdiutil detach /Volumes/ampmac_connector

Check Agent Status

Windows

Installation Status

To confirm installation was successful look for a service that contains the string CiscoAMP.

Connector Status

To find the connector state and version for Windows computers check for a running service that contains CiscoAMP. If a service exists you can then check the version of the service.

Linux

Installation Status

To confirm if the AMP connector is installed check for the following file /opt/cisco/amp/bin/ampdaemon.

Connector Status

To find the connector state and version for Linux computers with the AMP for Endpoints connector you first check if there is a running process named ampdaemon. To get the version read the value of /Signature/Object/config/agent/version from /opt/cisco/amp/etc/global.xml.

MacOS

Installation Status

To check if the AMP connector is installed check for the following file /opt/cisco/amp/ampdaemon.

Connector Status

To find the connector state and version for MacOS computers with the AMP for Endpoints connector you first check if there is a running process named ampdaemon. To get the version read the value of /Signature/Object/config/agent/version from /opt/cisco/amp/etc/global.xml.

Get Agent GUID

Windows

To get the AMP InstallDir check the registry key value of HKEY_LOCAL_MACHINE\SOFTWARE\Immunet Protect\InstallDir.

Read the value of /config/agent/uuid from $AMP_InstallDir\local.xml.

Default location is: C:\Program Files\Cisco\AMP\local.xml

Linux

Read the value of /config/agent/uuid from /opt/cisco/amp/etc/local.xml.

MacOS

Read the value of /config/agent/uuid from /Library/Application Support/Cisco/AMP for Endpoints Connector/local.xml.

Uninstall

Full Uninstall

This action will uninstall AMP for Endpoints and remove all data from disk. If you later re-install AMP on the computer it will register with a new GUID.

Windows

To remove AMP from Windows please do the following:

  1. Find the directory path for the uninstall.exe %AMP_InstallDir\%VERSION by checking the image path of the Cisco AMP for Endpoints process. The Service name will be CiscoAMP_%VERSION. The image path will be %AMP_InstallDir\%VERSION\sfc.exe.
  2. Navigate to the directory. Here is an example C:\Program Files\Cisco\AMP\7.2.7.
  3. Run the following command:
uninstall.exe /S /full 1 /password <PASSWORD>

Note

The /password switch is only required if a Connector Protection Password is configured. If it is not provided the /password switch is ignored.

Linux

To remove AMP from Linux please run these commands:

yum remove ciscoampconnector -y
/opt/cisco/amp/bin/purge_amp_local_data
MacOS

To remove AMP from MacOS please run this command:

installer -pkg "/Applications/Cisco AMP/Uninstall AMP for Endpoints Connector.pkg" -target /

Uninstall But Leave Configuration

If you plan to re-install AMP for Endpoints at a later date you should use this action to leave configuration on the disk. This will result in the connector re-registering with the cloud using the same GUID. This capability is not available for Mac OS.

Windows

To remove AMP from Windows but leave the configuration please do the following:

  1. Find the directory path for uninstall.exe %AMP_InstallDir%VERSION by checking the image path of the Cisco AMP for Endpoints process. The Service name will be CiscoAMP_%VERSION. The image path will be %AMP_InstallDir%VERSION\sfc.exe.
  2. Navigate to the directory. Here is an example C:\Program Files\Cisco\AMP\7.2.7.
  3. Run the following command:
uninstall.exe /S /full 0 /password <PASSWORD>

Note

The /password switch is only required if a Connector Protection Password is configured. If it is not provided the /password switch is ignored.

Linux

To remove AMP from Linux but leave the configuration please run this command:

yum remove ciscoampconnector -y

Starting and Stopping Agents

Starting Agents

Windows

Start agent with the net start and the Cisco AMP Service display name:

cmd.exe /c "net start Cisco AMP for Endpoints Connector 7.2.7"

Or start agent with powershell and the Cisco AMP Service name:

powershell.exe Start-Service CiscoAMP_7.2.7

Note

To get the name of the service check for a Service name that starts with CiscoAMP_.

Note

The Service name and Display name will both change based on the version number installed.

Linux

Start agent in RHEL/CentOS versions 6 and below:

initctl start cisco-amp

Start agent in RHEL/CentOS versions 7 and above:

systemctl start cisco-amp
MacOS

Start agent with the following command:

launchctl load /Library/LaunchDaemons/com.cisco.amp.daemon.plist

Stopping Agents

Windows

Find the directory path for sfc.exe %AMP_InstallDir%VERSION by checking the image path of the Cisco AMP for Endpoints process. The Service name will be CiscoAMP_%VERSION. The image path will be %AMP_InstallDir%VERSION\sfc.exe. To stop the agent run the following command:

sfc.exe -k <PASSWORD>

Note

The <PASSWORD> parameter is only required if a Connector Protection Password is configured.

Linux

Stop agent in RHEL/CentOS versions 6 and below:

initctl stop cisco-amp

Stop agent in RHEL/CentOS versions 7 and above:

systemctl stop cisco-amp
MacOS

Stop agent with the following command:

launchctl unload /Library/LaunchDaemons/com.cisco.amp.daemon.plist

Troubleshooting

Support Tools

The AMP Support Tool will create a snapshot of system and AMP settings include AMP logs to be used by Cisco support to help diagnose issue with an AMP deployment. You should only need to run this tool at the request of Cisco Support.

Note

The -o in the following commands is where the support snapshot will be saved.

Windows

Find the directory path for ipsupporttool.exe %AMP_InstallDir%VERSION by checking the image path of the Cisco AMP for Endpoints process. The Service name will be CiscoAMP_%VERSION. The image path will be %AMP_InstallDir%VERSION\sfc.exe. Then run the following command:

"C:\Program Files\Cisco\AMP\7.2.7\ipsupporttool.exe" -o "<DesiredOutputDirectory>"
Linux

Run the following command:

"/opt/cisco/amp/bin/ampsupport" -o "<DesiredOutputDirectory>"
MacOS

Run the following command:

/Library/Application Support/Cisco/AMP for Endpoints Connector/SupportTool" -o "<DesiredOutputDirectory>"

Reboot Required

To check if AMP needs a Windows Client to Reboot, look for the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Immunet Protect\Reboot. Reboot Windows machines that have a pending reboot caused by AMP for Endpoints. Pending reboots can be caused by an upgrade or an uninstallation.

Enable Debug Logging

Note

Debug logging will automatically turn off after the next policy update.

Windows

Find the directory path for sfc.exe %AMP_InstallDir%VERSION by checking the image path of the Cisco AMP for Endpoints process. The Service name will be CiscoAMP_%VERSION. The image path will be %AMP_InstallDir%VERSION\sfc.exe. To enable logging run the following command:

sfc.exe -l start
Linux

To enable logging run the following command:

echo "debuglevel 1" | /opt/cisco/amp/bin/ampcli
MacOS

To enable logging run the following commands:

echo "debuglevel 1" | /opt/cisco/amp/ampcli

Clear Cache

Windows

Find the directory path for sfc.exe %AMP_InstallDir%VERSION by checking the image path of the Cisco AMP for Endpoints process. The Service name will be CiscoAMP_%VERSION. The image path will be %AMP_InstallDir%VERSION\sfc.exe. To clear the cache run the following commands:

Note

You can get the Cisco AMP install directory by checking the registry key value of HKEY_LOCAL_MACHINE\SOFTWARE\Immunet Protect\InstallDir.

Note

The <PASSWORD> parameter is only required if a Connector Protection Password is configured.

Note

To get the name of the service check for a Service name that starts with CiscoAMP_.

sfc.exe -k <PASSWORD>
delete "C:\Program Files\Cisco\AMP\cache.db"
delete "C:\Program Files\Cisco\AMP\nfm_cache.db"
delete "C:\Program Files\Cisco\AMP\nfm_url_file_map.db"
delete "C:\Program Files\Cisco\AMP\event.db"
delete "C:\Program Files\Cisco\AMP\jobs.db"
delete "C:\Program Files\Cisco\AMP\history.db"
delete "C:\Program Files\Cisco\AMP\historyex.db"
powershell.exe Start-Service <ServiceNameOfCiscoAMP>
Linux

To clear cache in RHEL/CentOS versions 6 and below use the following commands:

initctl stop cisco-amp
rm -f "/opt/cisco/amp/etc/cloud_query.cache"
rm -f "/opt/cisco/amp/etc/cloud_nfm_query.cache"
rm -f "/opt/cisco/amp/etc/events.db"
initctl start cisco-amp

To clear cache in RHEL/CentOS versions 7 and above use the following commands:

systemctl stop cisco-amp
rm -f "/opt/cisco/amp/etc/cloud_query.cache"
rm -f "/opt/cisco/amp/etc/cloud_nfm_query.cache"
rm -f "/opt/cisco/amp/etc/events.db"
systemctl start cisco-amp
MacOS

To clear cache in MacOS run the following commands:

launchctl unload /Library/LaunchDaemons/com.cisco.amp.daemon.plist
rm -f "/Library/Application Support/Cisco/AMP for Endpoints Connector/cloud_query.cache"
rm -f "/Library/Application Support/Cisco/AMP for Endpoints Connector/cloud_nfm_query.cache"
rm -f "/Library/Application Support/Cisco/AMP for Endpoints Connector/events.db"
launchctl load /Library/LaunchDaemons/com.cisco.amp.daemon.plist