InsightConnect Marketplace

BlackBerry CylancePROTECT

Back to Marketplace

BlackBerry CylancePROTECT

v1.4.0

Automate detection and response operations using CylancePROTECT

Tags: cylance, protect, edr, blacklist


Actions
  • Blacklist
  • Get Agent Details
  • Quarantine
  • Search Agents
  • Get Devices Affected by Threat
  • Search Threats
  • Update Agent
  • Update Agent Threat

Description

The BlackBerry CylancePROTECT plugin allows you to automate response operations for CylancePROTECT and CylanceOPTICS.

Key Features

  • Get agent details
  • Blacklist a malicious hash
  • Quarantine endpoints
  • Search threats

Requirements

  • CylancePROTECT configured with an Custom Application

Documentation

Setup

You must create a Custom Application by following this procedure from the CylancePROTECT console:

  1. Go to the Integrations tab on the Settings page
  2. Click "Add Application"
  3. Provide a name for the integration and choose the permissions related to the actions you want to use
  4. Copy and paste the Application ID, Application Secret, and Tenant ID (from the Integrations tab) into the connection

The connection configuration accepts the following parameters:

Name Type Default Required Description Enum Example
application_id credential_secret_key None True Application ID for CylancePROTECT instance None 1abc234d-5efa-6789-bcde-0f1abcde23f5
application_secret credential_secret_key None True Generated token that allows access to Cylance Resources None 1abc234d-5efa-6789-bcde-0f1abcde23f5
tenant_id credential_secret_key None True The unique tenant ID of the tenant that the device belongs to None 1abc234d-5efa-6789-bcde-0f1abcde23f5
url string https://protectapi.cylance.com True Web API URL None https://protectapi.cylance.com

Example input:

{
  "application_id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
  "application_secret": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
  "tenant_id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
  "url": "https://protectapi.cylance.com"
}

Technical Details

Actions

Update Agent Threat

This action updates the status (waive or quarantine) of a convicted threat on a selected device.

Input
Name Type Default Required Description Enum Example
agent string None True Device to update threat on. Accepts IP address, MAC address, hostname, or device ID None Example-Hostname
quarantine_state boolean None True True to quarantine threat, false to waive threat None True
threat_identifier string None True The threat to search for. The input should be a threat name, MD5 or SHA256 hash None 44d88612fea8a8f36de82e1278abb02f

Example input:

{
  "add_zones": [
    "1abc234d-5efa-6789-bcde-0f1abcde23f5"
  ],
  "agent": "Example-Hostname",
  "policy": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
  "remove_zones": [
    "1abc234d-5efa-6789-bcde-0f1abcde23f5"
  ]
}
Output
Name Type Required Description
success boolean True Return true if the threat was updated

Example output:

{
  "success": true
}

Update Agent

This action adds or removes zones and/or updates the policy of a specific Console device resource belonging to a Tenant.

Input
Name Type Default Required Description Enum Example
add_zones []string None False The list of zone identifiers which the device is to be assigned. The input should be an array of zone IDs None ["1abc234d-5efa-6789-bcde-0f1abcde23f5"]
agent string None True Agent to update device information from. Accepts IP address, MAC address, hostname, or device ID None Example-Hostname
policy string None False The unique identifier for the policy to assign to the device. Specify policy, or leave the string empty to remove the current policy from the device None 1abc234d-5efa-6789-bcde-0f1abcde23f5
remove_zones []string None False The list of zone identifiers from which the device is to be removed. The input should be an array of zone IDs None ["1abc234d-5efa-6789-bcde-0f1abcde23f5"]

Example input:

{
  "add_zones": [
    "1abc234d-5efa-6789-bcde-0f1abcde23f5"
  ],
  "agent": "Example-Hostname",
  "policy": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
  "remove_zones": [
    "1abc234d-5efa-6789-bcde-0f1abcde23f5"
  ]
}
Output
Name Type Required Description
success boolean True Return true if the agent was updated

Example output:

{
  "success": true
}

Search Agents

This action searches for agents and returns device information details about them.

Input
Name Type Default Required Description Enum Example
agent string None True Agent to retrieve device information from. Accepts IP address, MAC address, name, or device ID None EXAMPLE-HOSTNAME

Example input:

{
  "agent": "EXAMPLE-HOSTNAME"
}
Output
Name Type Required Description
agents []agents True Detailed information about agents found

Example output:

{
  "agents": [
    {
      "mac_addresses": [
        "08-00-27-2F-43-60"
      ],
      "name": "Example-Hostname",
      "policy": {
        "id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
        "name": "Default"
      },
      "state": "Offline",
      "agent_version": "2.0.1540",
      "date_first_registered": "2020-06-21T15:53:43",
      "id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
      "ip_addresses": [
        "198.51.100.100"
      ]
    }
  ]
}

Search Threats

This action finds and displays detailed information about one or more threats.

Input
Name Type Default Required Description Enum Example
score integer None False Filter the search by the Cylance score assigned to the threat. Accepts an integer within the range [-1,1] None -1
threat_identifier []string None True The threat(s) to search for. The input should be an array of threat names, MD5, or SHA256 hashes None ["44d88612fea8a8f36de82e1278abb02f", "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f", "Example-Threat-Name"]

Example input:

{
  "score": -1,
  "threat_identifier": [
    "44d88612fea8a8f36de82e1278abb02f",
    "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
    "Example-Threat-Name"
  ]
}
Output
Name Type Required Description
threats []threat True Detailed information about threats found

Example output:

{
  "threats": [
    {
      "file_size": 109395,
      "md5": "9DE5069C5AFE602B2EA0A04B66BEB2C0",
      "safelisted": false,
      "unique_to_cylance": true,
      "classification": "Malware",
      "cylance_score": -1,
      "global_quarantined": false,
      "last_found": "2020-05-29T10:12:45",
      "name": "honeyhashx86.exe",
      "sha256": "02699626F388ED830012E5B787640E71C56D42D8",
      "sub_classification": "Exploit"
    }
  ]
}

Get Devices Affected by Threat

This action is used to retrieve a list of devices affected by a threat.

Input
Name Type Default Required Description Enum Example
threat_identifier string None True The threat to search for. The input should be a threat name, MD5, or SHA256 hash None 44d88612fea8a8f36de82e1278abb02f

Example input:

{
  "threat_identifier": "44d88612fea8a8f36de82e1278abb02f"
}
Output
Name Type Required Description
agents []threat_device True Detailed information about threat agents found

Example output:

{
  "agents": [
    {
      "id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
      "name": "Example-Hostname",
      "state": "OffLine",
      "agent_version": "2.0.1540",
      "policy_id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
      "date_found": "2020-05-29T10:12:45",
      "file_status": "Default",
      "file_path": "C:\\Program Files (x86)\\Rapid7\\Endpoint Agent\\honeyhashx86.exe",
      "ip_addresses": [
        "198.51.100.100"
      ],
      "mac_addresses": [
        "00-60-26-26-D5-19"
      ]
    }
  ]
}

Quarantine

This action is used to quarantine (isolate) an endpoint.

Input
Name Type Default Required Description Enum Example
agent string None True Device to perform quarantine action on. Accepts IP address, MAC address, hostname, or device ID None Example-Hostname
whitelist []string None False This list contains a set of hosts that should not be blocked. This can include IPs, hostnames or device IDs None ["198.51.100.100", "Example-Hostname", "1abc234d-5efa-6789-bcde-0f1abcde23f5"]

Example input:

{
  "agent": "Example-Hostname",
  "whitelist": [
    "198.51.100.100",
    "Example-Hostname",
    "1abc234d-5efa-6789-bcde-0f1abcde23f5"
  ]
}
Output
Name Type Required Description
lockdown_details lockdown_response True Detailed information about the device lockdown

Example output:

{
  "status": "COMPLETE",
  "data": {
      "id": "1ABC234D5EFA6789BCDE0F1ABCDE23F5",
      "hostname": "Example-Hostname",
      "tenant_id": "1abc234d5efa6789bcde0f1abcde23f5",
      "connection_status": "locked",
      "optics_device_version": "2.4.2100.1015",
      "password": "unlock-pa22-w0rd",
      "lockdown_expiration": "2020-07-11T21:15:29Z",
      "lockdown_initiated": "2020-07-08T21:15:29Z"
  }
}

Blacklist

This action is used to blacklist (quarantine) a hash globally.

Input
Name Type Default Required Description Enum Example
blacklist_state boolean None True True to blacklist hash, false to unblacklist hash None True
description string Hash Blacklisted from InsightConnect True Description for why the hash is blacklisted None Hash Blacklisted from InsightConnect
hash string None True Create a blacklist item from a SHA256 hash None 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f

Example input:

{
  "blacklist_state": true,
  "description": "Hash Blacklisted from InsightConnect",
  "hash": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
}
Output
Name Type Required Description
success boolean True Return true if blacklist item was created or deleted

Example output:

{
  "success": true
}

Get Agent Details

This action is used to obtain agent information.

Input
Name Type Default Required Description Enum Example
agent string None True Agent to retrieve device information from. Accepts MAC address, hostname, or agent ID None cylance-agent-win12

Example input:

{
  "agent": "cylance-agent-win12"
}
Output
Name Type Required Description
agent agent True Details for an agent

Example output:

{
  "agent": {
    "id": "1abc234d-5efa-6789-bcde-0f1abcde23f5",
    "name": "NA-TESTX-NAM11",
    "host_name": "na-testx-nam11",
    "os_version": "Microsoft Windows Server 2012 Standard",
    "state": "Online",
    "agent_version": "2.0.1540",
    "policy": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Default"
    },
    "last_logged_in_user": "NA-TESTX-NAM11\\Administrator",
    "update_available": false,
    "background_detection": false,
    "is_safe": false,
    "date_first_registered": "2020-05-28T14:00:50",
    "ip_addresses": [
      "198.51.100.100"
    ],
    "mac_addresses": [
      "00-60-26-26-D5-19"
    ]
  }
}

Triggers

This plugin does not contain any triggers.

Custom Output Types

This plugin does not contain any custom output types.

Troubleshooting

This plugin does not contain any troubleshooting information.

Version History

  • 1.4.0 - New actions Update Agent Threat, Update Agent
  • 1.3.0 - New action Search Agents
  • 1.2.0 - New actions Search Threats, Get Devices Affected by Threat
  • 1.1.0 - New action Quarantine
  • 1.0.3 - Match official branding in plugin title
  • 1.0.2 - Update to fix connection test
  • 1.0.1 - Add SHA256 input validation in Blacklist action
  • 1.0.0 - Initial plugin

Links

References

plugin_spec_version: v2
extension: plugin
products: [insightconnect]
name: cylance_protect
title: BlackBerry CylancePROTECT
description: Automate detection and response operations using CylancePROTECT
version: 1.4.0
vendor: rapid7
support: rapid7
status: []
tags: [cylance, protect, edr, blacklist]
hub_tags:
  use_cases: [threat_detection_and_response]
  keywords: [cylance, protect, edr, blacklist]
  features: []
resources:
  source_url: https://github.com/rapid7/insightconnect-plugins/tree/master/cylanceprotect
  license_url: https://github.com/rapid7/insightconnect-plugins/blob/master/LICENSE
  vendor_url: https://www.cylance.com
types:
  policy:
    id:
      title: ID
      type: string
      description: ID
      required: false
    name:
      title: Name
      type: string
      description: Name
      required: false
  agent:
    agent_version:
      title: Agent Version
      type: string
      description: Agent version
      required: false
    background_detection:
      title: Background Detection
      type: boolean
      description: Background detection
      required: false
    date_first_registered:
      title: Date First Registered
      type: string
      description: Date first registered
      required: false
    date_last_modified:
      title: Date Last Modified
      type: string
      description: Date last modified
      required: false
    date_offline:
      title: Date Offline
      type: string
      description: Date offline
      required: false
    distinguished_name:
      title: Distinguished Name
      type: string
      description: Distinguished name
      required: false
    host_name:
      title: Host Name
      type: string
      description: Host name
      required: false
    id:
      title: ID
      type: string
      description: ID
      required: false
    ip_addresses:
      title: IP Addresses
      type: "[]string"
      description: IP addresses
      required: false
    is_safe:
      title: Is Safe
      type: boolean
      description: Is safe
      required: false
    last_logged_in_user:
      title: Last Logged In User
      type: string
      description: Last logged in user
      required: false
    mac_addresses:
      title: MAC Addresses
      type: "[]string"
      description: MAC addresses
      required: false
    name:
      title: Name
      type: string
      description: Name
      required: false
    os_version:
      title: OS Version
      type: string
      description: OS version
      required: false
    policy:
      title: Policy
      type: policy
      description: Policy
      required: false
    state:
      title: State
      type: string
      description: State
      required: false
    update_available:
      title: Update Available
      type: boolean
      description: Update available
      required: false
    update_type:
      title: Update Type
      type: string
      description: Update type
      required: false
  lockdown_history:
    user_id:
      title: User ID
      description: The unique ID of the user who locked down the device
      type: string
      required: false
    timestamp:
      title: Timestamp
      description: The timestamp (in UTC) of when the command was initiated
      type: string
      required: false
    command:
      title: Command
      description: The command that was executed
      type: string
      required: false
  lockdown:
    id:
      title: ID
      description: The unique device ID that the lockdown command was issued to
      type: string
      required: false
    hostname:
      title: Hostname
      description: The hostname of the device that the lockdown command was issued to
      type: string
      required: false
    tenant_id:
      title: Tenant ID
      description: The unique tenant ID of the tenant that the device belongs to
      type: string
      required: false
    connection_status:
      title: Connection Status
      description: Whether or not the device is connected to Cylance's cloud services
      type: string
      required: false
    optics_device_version:
      title: Optics Device Version
      description: The numerical version of CylanceOPTICS running on the device
      type: string
      required: false
    password:
      title: Password
      description: The password required to unlock the device
      type: string
      required: false
    lockdown_expiration:
      title: Lockdown Expiration
      description: The timestamp (in UTC) of when the current device lockdown is set to expire
      type: string
      required: false
    lockdown_initiated:
      title: Lockdown Initiated
      description: The timestamp (in UTC) of when the current device lockdown was initiated
      type: string
      required: false
    lockdown_history:
      title: Lockdown History
      description: A list of historical device lockdown commands issued to this particular device
      type: "[]lockdown_history"
      required: false
  lockdown_response:
    status:
      title: Status
      description: Status of the action performed
      type: string
      required: false
    lockdown_details:
      title: Lockdown Details
      description: Detailed information about the lockdown action performed
      type: lockdown
      required: false
  agents:
    id:
      title: ID
      type: string
      description: ID
      required: false
    name:
      title: Name
      type: string
      description: Name
      required: false
    state:
      title: State
      type: string
      description: State
      required: false
    agent_version:
      title: Agent Version
      type: string
      description: Agent version
      required: false
    policy:
      title: Policy
      type: policy
      description: Policy
      required: false
    date_first_registered:
      title: Date First Registered
      type: string
      description: Date first registered
      required: false
    ip_addresses:
      title: IP Addresses
      type: "[]string"
      description: IP addresses
      required: false
    mac_addresses:
      title: MAC Addresses
      type: "[]string"
      description: MAC addresses
  threat:
    name:
      title: Name
      description: The name of the threat
      type: string
      required: false
    sha256:
      title: SHA256
      description: The SHA256 hash for the threat
      type: string
      required: false
    md5:
      title: MD5
      description: The MD5 hash for the threat
      type: string
      required: false
    cylance_score:
      title: Cylance Score
      description: The Cylance Score assigned to the threat
      type: float
      required: false
    av_industry:
      title: AV Industry
      description: The score provided by the antivirus industry
      type: float
      required: false
    classification:
      title: Classification
      description: The threat classification for the threat
      type: string
      required: false
    sub_classification:
      title: Sub Classification
      description: The threat sub-classification for the threat
      type: string
      required: false
    global_quarantined:
      title: Global Quarantined
      description: Identifies if the threat is on the Global Quarantine list
      type: boolean
      required: false
    safelisted:
      title: Safelisted
      description: Identifies if the threat is on the Safe List
      type: boolean
      required: false
    file_size:
      title: File Size
      description: The size of the file, in bytes
      type: int
      required: false
    unique_to_cylance:
      title: Unique to Cylance
      description: The threat was identifies by Cylance but not by other antivirus sources
      type: boolean
      required: false
    last_found:
      title: Last Found
      description: The date and time the threat was last found on any device in your organization
      type: string
      required: false
  threat_device:
    id:
      title: ID
      description: The endpoint's unique identifier
      type: string
      required: false
    name:
      title: Name
      description: The name of the device
      type: string
      required: false
    state:
      title: State
      description: The state of the device
      type: string
      required: false
    agent_version:
      title: Agent Version
      description: The CylancePROTECT Agent version installed on the device
      type: string
      required: false
    policy_id:
      title: Policy ID
      description: The unique identifier for the policy assigned to the device, or null if no policy is assigned
      type: string
      required: false
    date_found:
      title: Date Found
      description: The date and time (in UTC) when the threat was found on the device
      type: string
      required: false
    file_status:
      title: File Status
      description: Current quarantine status of the file on the device
      type: string
      required: false
    file_path:
      title: File Path
      description: The path where the file was found on the device
      type: string
      required: false
    ip_addresses:
      title: IP Addressess
      description: The list of IP addresses for the device
      type: "[]string"
      required: false
    mac_addresses:
      title: MAC Addressess
      description: The list of MAC addresses for the device
      type: "[]string"
      required: false

connection:
  tenant_id:
    title: Tenant ID
    description: The unique tenant ID of the tenant that the device belongs to
    type: credential_secret_key
    required: true
    example: 1abc234d-5efa-6789-bcde-0f1abcde23f5
  url:
    title: URL
    description: Web API URL
    type: string
    required: true
    default: https://protectapi.cylance.com
    example: https://protectapi.cylance.com
  application_secret:
    title: Application Secret
    description: Generated token that allows access to Cylance Resources
    type: credential_secret_key
    required: true
    example: 1abc234d-5efa-6789-bcde-0f1abcde23f5
  application_id:
    title: Application ID
    description: Application ID for CylancePROTECT instance
    type: credential_secret_key
    required: true
    example: 1abc234d-5efa-6789-bcde-0f1abcde23f5

actions:
  get_agent_details:
    title: Get Agent Details
    description: Retrieve agent information
    input:
      agent:
        title: Agent
        description: Agent to retrieve device information from. Accepts MAC address, hostname, or agent ID
        type: string
        required: true
        example: cylance-agent-win12
    output:
      agent:
        title: Agent
        description: Details for an agent
        type: agent
        required: true
  blacklist:
    title: Blacklist
    description: Blacklist (quarantine) a hash globally
    input:
      hash:
        title: Hash
        description: Create a blacklist item from a SHA256 hash
        type: string
        required: true
        example: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
      description:
        title: Description
        description: Description for why the hash is blacklisted
        type: string
        required: true
        default: Hash Blacklisted from InsightConnect
        example: Hash Blacklisted from InsightConnect
      blacklist_state:
        title: Blacklist State
        description: True to blacklist hash, false to unblacklist hash
        type: boolean
        required: true
        example: True
    output:
      success:
        title: Success
        description: Return true if blacklist item was created or deleted
        type: boolean
        required: true
  quarantine:
    title: Quarantine
    description: Quarantine (isolate) an endpoint
    input:
      agent:
        title: Agent
        description: Device to perform quarantine action on. Accepts IP address, MAC address, hostname, or device ID
        type: string
        required: true
        example: Example-Hostname
      whitelist:
        title: Whitelist
        description: This list contains a set of hosts that should not be blocked. This can include IPs, hostnames or device IDs
        type: "[]string"
        required: false
        example: ["198.51.100.100", "Example-Hostname", "1abc234d-5efa-6789-bcde-0f1abcde23f5"]
    output:
      lockdown_details:
        title: Lockdown Details
        description: Detailed information about the device lockdown
        type: lockdown_response
        required: true
  search_agents:
    title: Search Agents
    description: This action searches for agents and returns device information details
    input:
      agent:
        title: Agent
        description: Agent to retrieve device information from. Accepts IP address, MAC address, name, or device ID
        type: string
        required: true
        example: EXAMPLE-HOSTNAME
    output:
      agents:
        title: Agents
        description: Detailed information about agents found
        type: "[]agents"
        required: true
  search_threats:
    title: Search Threats
    description: Finds and displays detailed information about one or more threats
    input:
      threat_identifier:
        title: Threat Identifier
        description: The threat(s) to search for. The input should be an array of threat names, MD5, or SHA256 hashes
        type: "[]string"
        required: true
        example: ["44d88612fea8a8f36de82e1278abb02f", "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f", "Example-Threat-Name"]
      score:
        title: Score
        description: Filter the search by the Cylance score assigned to the threat. Accepts an integer within the range [-1,1]
        type: integer
        required: false
        example: -1
    output:
      threats:
        title: Threats
        description: Detailed information about threats found
        type: "[]threat"
        required: true
  search_threat_agents:
    title: Get Devices Affected by Threat
    description: Retrieve a list of devices affected by a threat
    input:
      threat_identifier:
        title: Threat Identifier
        description: The threat to search for. The input should be a threat name, MD5, or SHA256 hash
        type: string
        required: true
        example: 44d88612fea8a8f36de82e1278abb02f
    output:
      agents:
        title: Agents
        description: Detailed information about threat agents found
        type: "[]threat_device"
        required: true
  update_agent_threat:
    title: Update Agent Threat
    description: Updates the status (waive or quarantine) of a convicted threat on a selected device
    input:
      agent:
        title: Agent
        description: Device to update threat on. Accepts IP address, MAC address, hostname, or device ID
        type: string
        required: true
        example: Example-Hostname
      threat_identifier:
        title: Threat Identifier
        description: The threat to search for. The input should be a threat name, MD5 or SHA256 hash
        type: string
        required: true
        example: 44d88612fea8a8f36de82e1278abb02f
      quarantine_state:
        title: Quarantine State
        description: True to quarantine threat, false to waive threat
        type: boolean
        required: true
        example: True
    output:
      success:
        title: Success
        description: Return true if the threat was updated
        type: boolean
        required: true
  update_agent:
    title: Update Agent
    description: Adds or removes zones and/or updates the policy of a specific Console device resource belonging to a Tenant
    input:
      agent:
        title: Agent
        description: Agent to update device information from. Accepts IP address, MAC address, hostname, or device ID
        type: string
        required: true
        example: Example-Hostname
      add_zones:
        title: Add Zones
        description: The list of zone identifiers which the device is to be assigned. The input should be an array of zone IDs
        type: "[]string"
        required: false
        example: ["1abc234d-5efa-6789-bcde-0f1abcde23f5"]
      remove_zones:
        title: Remove Zones
        description: The list of zone identifiers from which the device is to be removed. The input should be an array of zone IDs
        type: "[]string"
        required: false
        example: ["1abc234d-5efa-6789-bcde-0f1abcde23f5"]
      policy:
        title: Policy
        description: The unique identifier for the policy to assign to the device. Specify policy, or leave the string empty to remove the current policy from the device
        type: string
        required: false
        example: 1abc234d-5efa-6789-bcde-0f1abcde23f5
    output:
      success:
        title: Success
        description: Return true if the agent was updated
        type: boolean
        required: true
Other plugins
Microsoft Windows Defender ATP
Rapid7   |   v4.3.0
Plugin
Get
JSON
Rapid7   |   v1.1.5
Plugin
Get
Basename
Rapid7   |   v1.1.0
Plugin
Get
Gmail
Rapid7   |   v6.0.2
Plugin
Get
Microsoft Teams
Rapid7   |   v2.2.0
Plugin
Get