About the connector
Cisco Advanced Malware Protection (AMP) for Endpoints is a cloud-managed endpoint security solution that not only provides the visibility, context, and control to prevent breaches, but also the ability to rapidly detect, contain, and remediate threats if they evade front-line defenses and get inside, all cost-effectively and without affecting operational efficiency.
This document provides information about the Cisco AMP For Endpoints connector, which facilitates automated interactions, with the Cisco AMP cloud using FortiSOAR™ playbooks. Add the Cisco AMP For Endpoints connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving information about computers, moving computers to a group, and hunting indicators on the Cisco AMP cloud.
Version information
Connector Version: 1.0.0
Compatibility with FortiSOAR™ Versions: 4.10.2-225 and later
Compatibility with Cisco AMP For Endpoints Version: v5.4.2018021317 and later
Installing the connector
For the procedure to install a connector, click here.
Prerequisites to configuring the connector
- You must have the URL of the Cisco AMP cloud to which you will connect and perform the automated operations.
- You must have the API key used to access the Cisco AMP REST API.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™ , on the Connectors page, select the Cisco AMP For Endpoints connector and click Configure to configure the following parameters:
| Parameter |
Description |
| Server URL |
IP address or Hostname URL of the Cisco AMP cloud to which you will connect and perform the automated operations.
If you not specify either the http or https protocol in this field, then by default the httpsprotocol is used. |
| Client ID |
Client ID that is provided for your account by the Cisco AMP administrator. |
| API Key |
API key that is configured for your account to access the Cisco AMP REST API. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Get All Computers |
Retrieves a list of all computers and their details from Cisco AMP cloud. |
search_endpoints
Investigation |
| Get Computer Information |
Retrieves details for a particular computers from Cisco AMP cloud, based on the connector GUID that you have specified. |
get_endpoint_info
Investigation |
| Search Computers |
Retrieves details for a filtered list of computer from Cisco AMP cloud, based on the parameters that you have specified. |
search_endpoints
Investigation |
| Hunt Indicator |
Retrieves details for a particular endpoint from Cisco AMP cloud, based on the input parameters and indicator value type that you have specified. |
search_endpoints
Investigation |
| Get Device Trajectory |
Retrieves details of all events associated with a particular computer from Cisco AMP cloud, based on the parameters that you have specified. |
get_trajectory
Investigation |
| Get Device Trajectory By User |
Retrieves details of all events associated with a particular computer and particular user from Cisco AMP cloud, based on the parameters that you have specified. |
get_trajectory
Investigation |
| Move Computer to Group |
Moves a computer to a group in Cisco AMP cloud, based on the computer GUID and group GUID that you have specified. |
update_group
Investigation |
| Search Events |
Searches for events on Cisco AMP cloud, based on the parameters that you have specified. |
search_event
Investigation |
| Get Event Types |
Retrieves a list of all event types and their details from Cisco AMP cloud. |
get_event_types
Investigation |
| Get Application Blocking Filelist |
Retrieves details for all application blocking filelists or details for a specific application blocking filelist from Cisco AMP cloud, based on the filelist name that you have specified. |
get_hash_blacklist
Investigation |
| Get Specific Filelist |
Retrieves details for a specific filelist from Cisco AMP cloud, based on the Filelist ID that you have specified. |
get_hash_blacklist
Investigation |
| Get Simple Custom Detection Filelist |
Retrieves details for all Simple Custom Detection List files or details for a specific Simple Custom Detection List file from Cisco AMP cloud, based on the filelist name that you have specified.
You can use the Simple Custom Detection List files list retrieved from Cisco AMP cloud to detect and quarantine files for your organization. |
get_hash_blacklist
Investigation |
| Add Hash to Blacklist |
Adds a filehash that you have specified in the SHA256 format to a filelist that you have specified on Cisco AMP cloud. |
update_hash_blacklist
Investigation |
| Get Items from Filelist |
Retrieves a list of items and their details from Cisco AMP cloud, based on the filelist name that you have specified. |
get_blacklist_items
Investigation |
| Get Item from Filelist |
Retrieves details for a specific item from a specified filelist from Cisco AMP cloud, based on the filehash and filelist name that you have specified. |
get_blacklist_items
Investigation |
| Delete Filelist Item |
Deletes a specific item from a specified filelist from Cisco AMP cloud, based on the filehash and filelist name that you have specified. |
update_hash_blacklist
Remediation |
| Create Group |
Creates a new group in Cisco AMP cloud based on the group name that you have specified. |
create_group
Investigation |
| Get Group List |
Retrieves details for all groups or details for a specific group from Cisco AMP cloud, based on the group name that you have specified. |
search_group
Investigation |
| Get Specific Group |
Retrieves details for a specific group from Cisco AMP cloud, based on the group GUID that you have specified. |
search_group
Investigation |
| Update Group |
Updates a specified group on Cisco AMP cloud, with the policy you have specified. |
update_group
Investigation |
| Get All Policies |
Retrieves details of all policies from Cisco AMP cloud. |
search_policy
Investigation |
| Get Specific Policy |
Retrieves details for a particular policy from Cisco AMP cloud, based on the policy GUID that you have specified. |
search_policy
Investigation |
operation: Get All Computers
Input parameters
None
Output
The JSON output contains a list of all the computers and their details from Cisco AMP cloud. Details include connector GUID, connector version, hostname, external IP, internal IP, network Address, operating system, and policy.
Following image displays a sample output:
operation: Get Computer Information
Input parameters
| Parameter |
Description |
| Connector GUID |
GUID of the connector installed on the computer (endpoint) for which you want to retrieve information from Cisco AMP cloud. |
Output
The JSON output contains details for the computer retrieved based on the connector GUID you have specified from Cisco AMP cloud. Details include connector GUID, connector version, hostname, external IP, internal IP, network Address, operating system, and policy.
Following image displays a sample output:
operation: Search Computers
Input parameters
| Parameter |
Description |
| Hostname (In CSV or List Format) |
Serialized list containing the Hostname of the endpoint for which you want to retrieve system information from Cisco AMP cloud.
For example: Demo_Cta, Demo_Dridex. |
| Group GUID (In CSV or List Format) |
Serialized list containing the Group GUID that contains the endpoints for which you want to retrieve system information from Cisco AMP cloud.
For example: "31aa857b-xxxx-xxxx-xxxx-a3878f869bc2", "31aa857b-xxxx-xxxx-xxxx-a3878f869bd3". |
| Internal IP Address |
Internal IP address of the endpoint for which you want to retrieve system information from Cisco AMP cloud. Input formats acceptable for this field is either single IPv4 or CIDR.
For example: 192.168.0.1 or 192.168.0.0/24. |
| External IP Address |
External IP address of the endpoint for which you want to retrieve system information from Cisco AMP cloud. Input formats acceptable for this field is either single IPv4 or CIDR.
For example: 192.168.0.1 or 192.168.0.0/24. |
| Limit |
Maximum number of endpoints that this operation should return. By default, this is set to 5. |
Note: None of the above parameters are mandatory. However, if you do not provide any parameter then this operation will return unfiltered results, i.e. it will return details of all computers from Cisco AMP cloud.
Output
The JSON output contains details for all computers or details for a specific computer based on the input parameters you have specified from Cisco AMP cloud. Details include connector GUID, connector version, hostname, external IP, internal IP, network Address, operating system, and policy.
Following image displays a sample output:
operation: Hunt Indicator
Input parameters
| Parameter |
Description |
| Filter Options |
Filter option based on which you want to search for endpoints on Cisco AMP cloud.
Choose between Computer Activity and Computer User Activity. |
| Value Type |
Value type of the indicator based on which you want to search for indicators on Cisco AMP cloud. Choose from the following options:
IP Address: Single IPv4 address. CIRD is not supported.
SHA256: SHA256 of the file that is observed on endpoints.
Filename: Name of the file that is observed on endpoints.
URL: URL fragment.
Note: The above options are used when you select the filter as Computer Activity.
Usename (Use in case of Computer User Activity): Name of the user whose activities you want to fetch from Cisco AMP cloud.
Note: The option is used when you select the filter as Computer User Activity. |
| Limit |
(Optional) Maximum number of endpoints that this operation should return. By default, this is set to 5. |
| Offset |
(Optional) Index of the first item to return from the search result. |
Output
The JSON output contains the details for the endpoint(s) retrieved from Cisco AMP cloud, based on the input parameters and indicator value type you have specified. Details include hostname, connector GUID, and links.
Following image displays a sample output:
operation: Get Device Trajectory
Input parameters
| Parameter |
Description |
| Connector GUID |
GUID of the connector installed on the computer (endpoint) whose associated events (activities) you want search for from Cisco AMP cloud. |
| Filter Options |
(Optional) Filter option based on which you want to filter events associated with the particular computer on Cisco AMP cloud.
Choose from the following options: IP Address, SHA256, and URL. |
| Value |
(Optional) Specify the value of the filter you have selected.
For example, if you select IP Address, then enter the IP address based on which you want to filter activities. |
| Limit |
(Optional) Maximum number of activities associated with a particular endpoint that this operation should return. By default, this is set to 5. |
Output
The JSON output contains the details of events retrieved from Cisco AMP cloud, based on the input parameters you have specified. Details include id, event type, and detection id, and computer details, such as connector version, hostname, and links.
Following image displays a sample output:
operation: Get Device Trajectory By User
Input parameters
| Parameter |
Description |
| Connector GUID |
GUID of the connector installed on the computer (endpoint) whose associated events (activities) you want search for on Cisco AMP cloud. |
| User |
Name of the user whose associated events on the specified computer you want search for on Cisco AMP cloud. |
| Limit |
(Optional) Maximum number of activities associated with a particular user that this operation should return. By default, this is set to 5. |
Output
The JSON output contains the details of events and computers retrieved from Cisco AMP cloud, based on the input parameters you have specified. Event details include id, event type, and detection id and computer details include connector version, hostname, and links.
Following image displays a sample output:
operation: Move Computer to Group
Input parameters
| Parameter |
Description |
| Connector GUID |
GUID of the connector installed on the computer (endpoint) that requires to be moved to another group in Cisco AMP cloud based on the GUID of the group you specify. |
| Group GUID |
GUID of the group to which you want to move the endpoint. |
Output
The JSON output contains the details of the computer that you want to move to another group in Cisco AMP cloud, based on the input parameters you have specified. Details include connector GUID, connector version, hostname, Group GUID, external IP, and internal IP.
Following image displays a sample output:
operation: Search Events
Input parameters
| Parameter |
Description |
| Connector GUID (In CSV or List Format) |
Serialized comma-separated list containing the GUIDs of the connector whose associated events you want to search for on Cisco AMP cloud.
For example: "1e2af190-57a2-4ea1-871e-cb12b9ed7594", "a2ea7f96-a84c-4ebb-9fed-fe673f132b01". |
| Group GUID (In CSV or List Format) |
Serialized comma-separated list containing the Group GUID whose associated events you want search for on Cisco AMP cloud.
For example: "07df7062-dc9e-4c96-934f-7b230395b21f", "55f15d0c-637d-4540-96ce-bb4c1ad53b03". |
| Event Type IDs (In CSV or List Format) |
(Optional) Serialized comma-separated list containing the IDs of the event types whose associated events you want to search for on Cisco AMP cloud. |
| File Detection (SHA256) |
(Optional) Filehash whose associated events you want to search for on Cisco AMP cloud.
Only SHA256 value is allowed in this field. |
| Application (SHA256) |
(Optional) Application hash whose associated events you want to search for on Cisco AMP cloud.
Only SHA256 value is allowed in this field. |
| Start From |
(Optional) Starting datetime from which you want to search events on Cisco AMP cloud. |
| Limit |
(Optional) Maximum number of events associated with a particular endpoint that this operation should return. By default, this is set to 5. |
| Offset |
(Optional) Index of the first item to return from the search result. |
Output
The JSON output contains the event details retrieved from Cisco AMP cloud, based on the input parameters you have specified. Event details include event type id, id, date detection id, and group GUID.
Following image displays a sample output:
operation: Get Event Types
Input parameters
None
Output
The JSON output contains a list of all the event types and their details from Cisco AMP cloud. Details include id, name, and description.
Following image displays a sample output:
operation: Get Application Blocking Filelist
Input parameters
| Parameter |
Description |
| Filelist Name |
Name of the application blocking filelist for which you want to retrieve details from Cisco AMP cloud. |
| Limit |
Maximum number of filelists that this operation should return. By default, this is set to 5. |
| Offset |
Index of the first item to return from the search result. |
Note: None of the above parameters are mandatory. However, if you do not provide any parameter then this operation will return unfiltered results, i.e. it will return details of all application blocking filelists from Cisco AMP cloud.
Output
The JSON output contains details for all application blocking lists or details for a specific application blocking list based on the filelist name you have specified from Cisco AMP cloud. Blocking list details include GUID, name, links, and type.
Following image displays a sample output:
operation: Get Specific Filelist
Input parameters
| Parameter |
Description |
| Filelist GUID |
GUID of the filelist for which you want to retrieve details from Cisco AMP cloud. |
Output
The JSON output contains the filelist details retrieved from Cisco AMP cloud, based on the filelist ID you have specified. Filelist details include GUID, name, links, and type.
Following image displays a sample output:
operation: Get Simple Custom Detection Filelist
Input parameters
| Parameter |
Description |
| Filelist Name |
Name of the simple custom detection filelist for which you want to retrieve details from Cisco AMP cloud. |
| Limit |
Maximum number of filelists that this operation should return. By default, this is set to 5. |
Note: None of the above parameters are mandatory. However, if you do not provide any parameter then this operation will return unfiltered results, i.e. it will return details of all simple custom detection filelists from Cisco AMP cloud.
Output
The JSON output contains details for all simple custom detection filelists or details for a specific simple custom detection filelist based on the filelist name you have specified from Cisco AMP cloud. Simple Custom Detection Filelist details include GUID, name, links, and type.
Following image displays a sample output:
operation: Add Hash to Blacklist
Input parameters
| Parameter |
Description |
| Filelist GUID |
GUID of the filelist to which you want to add the specified filehash. |
| Filehash |
Filehash that you want to add to a specified filelist in Cisco AMP cloud. |
| Description |
Description of the filehash that you want to add to a specified filelist in Cisco AMP cloud. |
Output
The JSON output contains the filehash details that you have added to the specified filelist in Cisco AMP cloud. Filelist details include description, sha256, source, and links.
Following image displays a sample output:
operation: Get Items for Filelist
Input parameters
| Parameter |
Description |
| Filelist GUID |
GUID of the filelist from which you want to retrieve details of items. |
| Limit |
(Optional) Maximum number of items associated with a particular filelist that this operation should return. By default this is set to 5. |
| Offset |
(Optional) Index of the first item to return from the search result. |
Output
The JSON output contains a list of items and their details retrieved from Cisco AMP cloud, based on the filelist name you have specified. Item details include the description, sha256, source, and links.
Following image displays a sample output:
operation: Get Item for Filelist
Input parameters
| Parameter |
Description |
| Filelist GUID |
GUID of the filelist from which you want to retrieve details of the specified item. |
| Filehash |
Filehash that is associated with the filelist that you have specified for which you want to retrieve item details from Cisco AMP cloud. |
Output
The JSON output contains details for the specified item retrieved from Cisco AMP cloud, based on the filelist GUID and filehash you have specified. Item details include the description, sha256, source, and links.
Following image displays a sample output:
operation: Delete Filelist Item
Input parameters
| Parameter |
Description |
| Filelist GUID |
GUID of the filelist from which you want to delete the specified item. |
| Filehash |
Filehash that is associated with the filelist that you have specified from which you want to delete the item from Cisco AMP cloud. |
Output
The JSON output contains details for the specified item that you want to delete from Cisco AMP cloud, based on the filelist GUID and filehash you have specified. Item details include metadata, data, and links.
Following image displays a sample output:
operation: Create Group
Input parameters
| Parameter |
Description |
| Name |
Name of the group that you want to create in Cisco AMP cloud. |
| Description |
Description of the group that you want to create in Cisco AMP cloud. |
Output
The JSON output contains the details of the newly created group in Cisco AMP cloud. Group details include name, GUID, description, policies, and source.
Following image displays a sample output:
operation: Get Group List
Input parameters
| Parameter |
Description |
| Name |
Name of the group for which you want to retrieve details from Cisco AMP cloud. |
| Limit |
Maximum number of groups that this operation should return. By default, this is set to 5. |
Note: None of the above parameters are mandatory. However, if you do not provide any parameter then this operation will return unfiltered results, i.e. it will return details of all available groups from Cisco AMP cloud.
Output
The JSON output contains details for all groups or details for a specific group based on the group name you have specified from Cisco AMP cloud. Group details include GUID, name, source, and type.
Following image displays a sample output:
operation: Get Specific Group
Input parameters
| Parameter |
Description |
| Group GUID |
GUID of the group for which you want to retrieve details from Cisco AMP cloud. |
Output
The JSON output contains the group details retrieved from Cisco AMP cloud, based on the group GUID you have specified. Group details include GUID, name, links, and source.
Following image displays a sample output:
operation: Update Group
Input parameters
| Parameter |
Description |
| Group GUID |
GUID of the group that you want to update on Cisco AMP cloud. |
| Windows Policy GUID |
GUID of the Windows policy that you want to update on the group you have specified. |
| Mac Policy GUID |
GUID of the MAC policy that you want to update on the group you have specified. |
| Linux Policy GUID |
GUID of the Linux policy that you want to update on the group you have specified. |
| Android Policy GUID |
GUID of the Android policy that you want to update on the group you have specified. |
Note: You must specify one of the policies: Windows Policy GUID, MAC Policy GUID, Linux Policy GUID, or Android Policy GUID so that the specified group can be updated on Cisco AMP cloud with the specified policy.
Output
The JSON output contains the details of the group that you want to update on Cisco AMP cloud, based on the input parameters you have specified. Group details include GUID, name, description, policies, and source.
Following image displays a sample output:
operation: Get All Policies
Input parameters
None
Output
The JSON output contains details for all policies retrieved from Cisco AMP cloud. Details include product, name, file lists, links, groups, and execution set.
Following image displays a sample output:
operation: Get Specific Policy
Input parameters
| Parameter |
Description |
| Policy GUID |
GUID of the policy for which you want to retrieve details from Cisco AMP cloud. |
Output
The JSON output contains details for the policy retrieved based on the policy GUID you have specified from Cisco AMP cloud. Details include product, name, file lists, links, groups, and execution set.
Following image displays a sample output:
Included playbooks
The Sample-Cisco AMP For Endpoints - 1.0.0 playbook collection comes bundled with the Cisco AMP For Endpoints connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Cisco AMP For Endpoints connector.
- Add Hash to Blacklist
- Create Group
- Delete Filelist Item
- Get All Computers
- Get All Policies
- Get Application Blocking Filelist
- Get Computer Information
- Get Device Trajectory
- Get Device Trajectory By User
- Get Event Types
- Get Group List
- Get Item from Filelist
- Get Items from Filelist
- Get Simple Custom Detection Filelist
- Get Specific Filelist
- Get Specific Group
- Get Specific Policy
- Hunt Indicator
- Move Computer to Group
- Search Computers
- Search Events
- Update Group
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.
