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

Carbon Black Cloud Endpoint Standard
All API calls require an API key with appropriate permissions see Authentication

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.

CBC Managed Identity

Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

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

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:

Applications > Reputation > org.reputations, allow permission to CREATE, READ and DELETE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.

CSP Managed Identity

Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.

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

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:

_API.Applications:org.Reputations, allow permission to CREATE, READ, DELETE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

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.

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
}

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

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.reputations`	`READ`	Majority of environments
VMware Cloud Services Platform	`_API.Applications:org.Reputations:read`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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.

API Permissions Required

Identity Manager	Permission (.notation name)	Operation(s)	Environment
Carbon Black Cloud	`org.reputations`	`CREATE, READ, DELETE`	Majority of environments
VMware Cloud Services Platform	`_API.Applications:org.Reputations:create, read, delete`	N/A - included in permission name	Prod UK and AWS GovCloud (US)

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

Fields

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 September 4, 2022

Carbon Black Cloud

Page Contents

Recommendation API

Overview

Use Cases

Requirements

Authentication

Quick Start

API calls

Search Recommendations

Recommendation Workflow

Fields

Search Recommendation Request

Criteria

Sort

Recommendation Workflow Request

Recommendation

Impact

New Rule

Workflow

Application