Recommendation API


Overview

When Endpoint Standard is first deployed to an environment, Policy configurations can be tuned more quickly by accepting Carbon Black Cloud Recommendations rather than by investigating endpoint activity ad-hoc and manually configuring CBC Policies in response to that investigation.

A “Recommendation” is a Reputation Override which you may choose to apply to improve your Policies’ efficacy. With this API, you can get Recommendations, manage their workflow state, or apply them as a Reputation Override. The workflow of a Recommendation has 3 states - NEW, REJECTED, or ACCEPTED. You can take an action using the Recommendation Workflow to ACCEPT or REJECT the Recommendation. The state of an ACCEPTED or REJECTED Recommendation can also be reverted to NEW using the RESET action of the Recommendation Workflow request.

Use Cases

  • Rapidly configure a Policy tailored for your environment.
  • New configurations can be tuned based on the system Recommendations rather than requiring manual investigation of activity in that environment

Requirements


Authentication

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
    • for the category Applications > Reputation > “org.reputations”, allow permission to CREATE, READ and DELETE (or see each call below for individual requirements)
  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)
  • API Route: /recommendation-service/v1/orgs/{org_key}/recommendation/

Note: when you insert your org_key, you must also remove the { } brackets.


Quick Start

Use the Search Recommendations call to view all available Recommendations. Then use the Recommendation Workflow to convert a particular one to a Reputation Override.

  1. To view all available Recommendations, start by calling the Search Recommendations request. Using the criteria filters, search only for the Recommendations with the state NEW. This will list only the Recommendations that have not been ACCEPTED or REJECTED.

Request

POST https://defense.conferdeploy.net/recommendation-service/v1/orgs/ABCD1234/recommendation/_search

Request Body

{
  "criteria": {
    "status": ["NEW"]
  },
  "sort": [
    {
      "order": "DESC",
      "field": "impact_score"
    }
  ]
}

Response

{
  "results": [
    {
      "recommendation_id": "d60a6b3a-9fb6-49c3-acdc-696d757cef29",
      "rule_type": "reputation_override",
      "policy_id": 0,
      "new_rule": {
        "override_type": "SHA256",
        "override_list": "WHITE_LIST",
        "sha256_hash": "60763a25d3b35a569d3876f1bb8a3948b712f28416a7a31f8b653646cea44c21",
        "filename": "mimecast for outlook 7.8.0.125 (x64).msi"
      },
      "workflow": {
        "status": "NEW",
        "changed_by": "demo@vmware.com",
        "create_time": "2021-05-18T16:37:07.000Z",
        "update_time": "2021-05-18T16:37:07.000Z",
        "comment": ""
      },
      "impact": {
        "org_adoption": "MEDIUM",
        "impacted_devices": 72,
        "event_count": 27,
        "impact_score": 0,
        "update_time": "2021-05-18T16:37:07.000Z"
      }
    }
  ],
  "num_found": 1
}

  1. ACCEPT the Recommendation as a Reputation Override by calling the Recommendation Workflow with "action": "ACCEPT" in the body.

Request

PUT https://defense.conferdeploy.net/recommendation-service/v1/orgs/ABCD1234/recommendation/8b1c6c99-f327-45b2-a40b-44211a62b32c/workflow

Request Body

{
  "action": "ACCEPT"
}

Response

No Content

  1. Search for all ACCEPTED Recommendations with the Search Recommendations and filter by keyword ACCEPTED in the status parameter. The ref_id in the response body is the id of the new Reputation Override.

Request

POST https://defense.conferdeploy.net/recommendation-service/v1/orgs/ABCD1234/recommendation/_search

Request Body

{
  "criteria": {
    "status": ["ACCEPTED"]
  },
  "sort": [
    {
      "order": "DESC",
      "field": "impact_score"
    }
  ]
}

Response

{
  "results": [
    {
      "recommendation_id": "d60a6b3a-9fb6-49c3-acdc-696d757cef29",
      "rule_type": "reputation_override",
      "policy_id": 0,
      "new_rule": {
        "override_type": "SHA256",
        "override_list": "WHITE_LIST",
        "sha256_hash": "60763a25d3b35a569d3876f1bb8a3948b712f28416a7a31f8b653646cea44c21",
        "filename": "mimecast for outlook 7.8.0.125 (x64).msi"
      },
      "workflow": {
        "status": "ACCEPTED",
        "changed_by": "",
        "create_time": "2021-05-18T16:37:07.000Z",
        "update_time": "2021-08-19T15:18:07.000Z",
        "ref_id": "a82ad595010011ec982adf5acfdb4c03",
        "comment": "test"
      },
      "impact": {
        "org_adoption": "MEDIUM",
        "impacted_devices": 72,
        "event_count": 27,
        "impact_score": 0,
        "update_time": "2021-05-18T16:37:07.000Z"
      }
    }
  ],
  "num_found": 1
}



API calls

Search Recommendations

Request to search and filter recommendations.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.reputations READ

Request

POST {cbc-hostname}/recommendation-service/v1/orgs/{org_key}/recommendation/_search

Request Body - application/json

{
  "criteria": {
    "policy_type": ["<string>"],
    "status": ["<string>"],
    "hashes": ["<string>"]
  },
  "rows": integer,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": integer
}

Body Schema

Field Definition Data Type Values
criteria An object that represents values that must be in the results Object criteria Schema
rows Maximum number of results to return, defaults to 50 Integer N/A
sort An array of Fields and Order to sort recommendations on Array sort Schema
start Zero-indexed starting row, defaults to 0 Integer N/A

Response

Code Description Content-Type Content
200 Request has succeeded application/json Example response below

Example

Request

POST https://defense.conferdeploy.net/recommendation-service/v1/orgs/ABCD1234/recommendation/_search

Request_Body

{
  "criteria": {
    "policy_type": ["reputation_override"],
    "status": ["NEW"]
  },
  "sort": [
    {
      "field": "impact_score",
      "order": "DESC"
    }
  ]
}

Response

{
  "results": [
    {
      "recommendation_id": "d60a6b3a-9fb6-49c3-acdc-696d757cef29",
      "rule_type": "reputation_override",
      "policy_id": 0,
      "new_rule": {
        "override_type": "SHA256",
        "override_list": "WHITE_LIST",
        "sha256_hash": "60763a25d3b35a569d3876f1bb8a3948b712f28416a7a31f8b653646cea44c21",
        "filename": "mimecast for outlook 7.8.0.125 (x64).msi"
      },
      "workflow": {
        "status": "NEW",
        "changed_by": "demo@vmware.com",
        "create_time": "2021-05-18T16:37:07.000Z",
        "update_time": "2021-08-17T02:06:54.000Z",
        "comment": ""
      },
      "impact": {
        "org_adoption": "MEDIUM",
        "impacted_devices": 72,
        "event_count": 27,
        "impact_score": 0,
        "update_time": "2021-05-18T16:37:07.000Z"
      }
    }
  ],
  "num_found": 1
}


Recommendation Workflow

A request which can convert a certain Recommendation to a Reputation Override or update and reset an existing Recommendation workflow. An ACCEPTED or REJECTED Recommendation can be reverted back to the status of NEW using the RESET keyword in the action parameter. The ref_id of an ACCEPTED Recommendation is the id of the newly created Reputation Override.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.reputations CREATE, READ, DELETE

Request

PUT {cbc-hostname}/recommendation-service/v1/orgs/{org_key}/recommendation/{id}/workflow

Request Body

{
  "action": "<string>",
  "comment": "<string>"
}

Body Schema

Field Definition Data Type Values
action The action to take on the Recommendation to progress it through the workflow String ACCEPT, REJECT, RESET
comment Description of the updated recommendation. Maximum of 400 characters. String N/A

Response

Code Description Content-Type Content
204 Request has succeeded application/json N/A

Example

Request

PUT https://defense.conferdeploy.net/recommendation-service/v1/orgs/ABCD1234/recommendation/8b1c6c99-f327-45b2-a40b-44211a62b32c/workflow

Request_Body

{
  "action": "ACCEPT"
}

Response

No Content


Schemas

Search Recommendation Request

Field Definition Data Type Values
criteria An object that represents values that must be in the results Object criteria Schema
rows Maximum number of results to return, defaults to 50 Integer N/A
sort An object that enables the caller to specify how the search results are sorted Array sort Schema
start Zero-indexed starting row, defaults to 0 Integer N/A

Criteria

An object that represents values that must be in the results

Field Definition Data Type Values
policy_type An array of which policy_type to return, between reputation_override or sensor_policy, defaults to both. Array reputation_override, sensor_policy
status Only return recommendations that have the specified status, defaults to NEW. Array NEW, REJECTED, ACCEPTED
hashes Only search for recommendations with these hashes, by default no hashes are added to the search. Array N/A

Sort

An object that enables the caller to specify how the search results are sorted.

Field Definition Data Type Values
field Property to sort the response on, defaults to impact_score String changed_by, event_count, impact_score, impacted_devices, rule_type, create_time, update_time, status, comment
order Order on which to sort the field values, defaults to DESC String DESC, ASC

Recommendation Workflow Request

Field Definition Data Type Values
action The action to take on the Recommendation to progress it through the workflow. String ACCEPT, REJECT, RESET
comment Description of the updated recommendation. Maximum of 400 characters. String N/A

Recommendation

Field Definition Data Type Values
impact Metadata about the Recommendation for this org to help you decide whether to ACCEPT or REJECT the Recommendation Object impact Schema
new_rule Proposed atomic change to your organizations policies Object new_rule Schema
policy_id Unique identifier for the Policy Integer N/A
recommendation_id Identifier associated with the Recommendation String N/A
rule_type The type of rule for the Recommendation String sensor_policy, reputation_override
workflow Defines the lifecycle state of a Recommendation Object workflow Schema

Impact

Metadata about the Recommendation for this org to help you decide whether to ACCEPT or REJECT the Recommendation

Field Definition Data Type Values
event_count Number of events encountered Integer N/A
impact_score Impact score Number N/A
impacted_devices Impacted devices Integer N/A
org_adoption Org adoption String LOW, MEDIUM, HIGH
update_time The last time impact was updated String N/A

New Rule

Proposed atomic change to your organizations policies

Field Definition Data Type Values
action Rule action String N/A
application Rule application Object application Schema
certificate_authority Certificate authority String N/A
filename File name String N/A
include_child_processes Include child processes Boolean true, false
operation Operation String sensor_policy
override_list Override list String N/A
override_type Override type String IT_TOOL
path Path String N/A
sha256_hash SHA256 hash String SHA256
signed_by Signed by String CERT

Workflow

Defines the lifecycle state of a Recommendation

Field Definition Data Type Values
changed_by Who made the last update to the workflow String N/A
create_time The time the Recommendation was created String N/A
ref_id Reference id for an ACCEPTED Recommendation which is the id of the created Reputation Override String N/A
status Status of the recommendation String NEW, REJECTED, ACCEPTED
update_time The last time the Recommendation was updated String N/A
comment A comment added when the recommendation was updated String N/A

Application

Field Definition Data Type Values
type Application type String N/A
value Application value String N/A
Last modified on August 27, 2021