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

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.


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.


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.

  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.

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