Reputation Override

Overview

The Reputation Override API provides an organization with the ability to create a list of approved or banned applications using a SHA-256 hash, a certificate signer, or a path to a known IT tool application. The overridden reputation allows for the Carbon Black Cloud to trigger deny or terminate actions based on policy configurations of known banned application or ignore applications that are approved. This provides ease of mind for an organization knowing that their infrastructure is secured against known bad actors and that their known good applications will not be interrupted by Carbon Black Cloud.

Use Cases

  • Override the reputation of an application by adding a SHA-256 hash, a certificate signer or a path to a known IT tool application or directory of IT tools to an Approved or Banned list
  • Search or export existing reputation overrides that have already been configured
  • Delete reputation overrides that are no longer relevant to your security posture

Enterprise EDR Only

If you are an Enterprise EDR only customer then you will have a restricted experience compared to the full functionality with Endpoint Standard. The following depicts the differences in experience:

  • Limited to adding or removing SHA256 hashes to the BLACK_LIST override_list through reputation overrides.

    Note: The API will not return an error when creating reputation overrides for certs and it_tools however they will not be applied unless Endpoint Standard is enabled.

  • Alerts created for a blocked/terminated process will always have a Severity of 4.

  • The following prevention will be enforced “Processes on the company banned list will be blocked. Processes are terminated at first detection and denied for all future instances”.

    • Supported on Windows sensor 3.7 and above
    Note: This can not be disabled.

Requirements

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

Guides and Resources

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.
  • Reputation Override: {cbc-hostname}/appservices/v6/orgs/{org_key}/reputations/overrides/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Application > Reputation > org.reputations, allow permission to CREATE, READ, 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.
  • Reputation Override: {cbc-hostname}/appservices/v6/orgs/{org_key}/reputations/overrides/

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.


API calls

Configure Reputation Override

Configure a new reputation override for a SHA-256, cert or IT tool

API Permissions Required

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

Request

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/reputations/overrides

Request Body 

{
  "description": "<string>",
  "override_list": "<string>",
  "override_type": "<string>"
}

Body Schema

Field Definition Data Type Values
override_list REQUIRED The override list to add a new reputation (BLACK_LIST only valid for SHA256) String BLACK_LIST, WHITE_LIST
override_type REQUIRED Process property match when applying override String SHA256, CERT, IT_TOOL
description Justification for override String N/A

Additional fields when override_type is SHA256

Field Definition Data Type Values
sha256_hash REQUIRED A hexadecimal string of length 64 characters representing the SHA-256 hash of the application String N/A
filename An application name for the hash String N/A

Additional fields when override_type is CERT

Field Definition Data Type Values
signed_by REQUIRED Name of the signer for the application String N/A
certificate_authority Certificate authority that authorizes the validity of the certificate String N/A

Additional fields when override_type is IT_TOOL

Field Definition Data Type Values
path REQUIRED Path to the file or directory where the IT tool(s) exist on disk.

Path may include wildcards, see here for more information		 String N/A
include_child_processes Include tool’s child processes on approved list Boolean N/A

Response

Code Description Content-Type Content
200 Successfully create reputation override application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
409 The reputation override already exists with matching properties application/json N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/reputations/overrides

Request_Body 

{
  "description": "An override for a sha256 hash",
  "override_list": "BLACK_LIST",
  "override_type": "SHA256",
  "sha256_hash": "af62e6b3d475879c4234fe7bd8ba67ff6544ce6510131a069aaac75aa92aee7a",
  "filename": "foo.exe"
}

Response 

{
  "id": "e9410b754ea011ebbfd0db2585a41b07",
  "created_by": "example@example.com",
  "create_time": "2021-01-04T15:24:18.002Z",
  "description": "An override for a foo.exe",
  "override_list": "BLACK_LIST",
  "override_type": "SHA256",
  "sha256_hash": "af62e6b3d475879c4234fe7bd8ba67ff6544ce6510131a069aaac75aa92aee7a",
  "filename": "foo.exe"
}

Get Reputation Override

Retrieve a reputation override by id

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

GET {cbc-hostname}/appservices/v6/orgs/{org_key}/reputations/overrides/{id}

Response

Code Description Content-Type Content
200 Successfully retrieved resource override application/json View example response below
404 The resource override could not be found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/reputations/overrides/e9410b754ea011ebbfd0db2585a41b07

Response 

{
  "id": "e9410b754ea011ebbfd0db2585a41b07",
  "created_by": "example@example.com",
  "create_time": "2021-01-04T15:24:18.002Z",
  "description": "An override for a foo.exe",
  "override_list": "BLACK_LIST",
  "override_type": "SHA256",
  "sha256_hash": "af62e6b3d475879c4234fe7bd8ba67ff6544ce6510131a069aaac75aa92aee7a",
  "filename": "foo.exe"
}

Delete Reputation Override

Delete a reputation override by id

API Permissions Required

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

Request

DELETE {cbc-hostname}/appservices/v6/orgs/{org_key}/reputations/overrides/{id}

Response

Code Description Content-Type Content
204 Successfully deleted resource override No Content View example response below
404 The resource override could not be found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/reputations/overrides/e9410b754ea011ebbfd0db2585a41b07

Response 

No Content

Search Reputation Overrides

Search existing reputation overrides by a search criteria

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}/appservices/v6/orgs/{org_key}/reputations/overrides/_search

Request Body 

[
  {
    "query": "<string>",
    "criteria": {
      "override_list": "<string>",
      "override_type": "<string>"
    },
    "start": <integer>,
    "rows": <integer>,
    "sort_field": "<string>",
    "sort_order": "<string>"
  }
]

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "override_type": "SHA256"
}
Supported fields: override_list,override_type
query Query in lucene syntax and/or including value searches. String N/A
rows For pagination, how many results to return Integer Default: 20
start For pagination, where to start retrieving results from Integer Default: 0
sort_field The field to sort on String create_time, override_list, override_type
sort_order The direction to sort by String asc, desc

Response

Code Description Content-Type Content
200 Successfully found reputation overrides application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/reputations/overrides/_search

Request_Body 

{
  "criteria": {
    "override_list": "BLACK_LIST",
    "override_type": "SHA256"
  },
  "start": 0,
  "rows": 10,
  "sort_field": "create_time",
  "sort_order": "asc"
}

Response 

{
  "num_found": 1,
  "results": [
    {
      "id": "e9410b754ea011ebbfd0db2585a41b07",
      "created_by": "example@example.com",
      "create_time": "2021-01-04T15:24:18.002Z",
      "description": "An override for a foo.exe",
      "override_list": "BLACK_LIST",
      "override_type": "SHA256",
      "sha256_hash": "af62e6b3d475879c4234fe7bd8ba67ff6544ce6510131a069aaac75aa92aee7a",
      "filename": "foo.exe"
    }
  ]
}

Export Reputation Overrides

Export existing reputation overrides by a search criteria

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}/appservices/v6/orgs/{org_key}/reputations/overrides/_export

Request Body 

[
  {
    "query": "<string>",
    "criteria": {
      "override_list": "<string>",
      "override_type": "<string>"
    },
    "start": <integer>,
    "rows": <integer>,
    "sort_field": "<string>",
    "sort_order": "<string>"
  }
]

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "override_type": "SHA256"
}
Supported fields: override_list,override_type
query Query in lucene syntax and/or including value searches. String N/A
rows For pagination, how many results to return Integer Default: 20
start For pagination, where to start retrieving results from Integer Default: 0
sort_field The field to sort on String create_time, override_list, override_type
sort_order The direction to sort by String asc, desc

Response

Code Description Content-Type Content
200 Successfully found reputation overrides text/csv View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/reputations/overrides/_export

Request_Body 

{
  "criteria": {
    "override_list": "BLACK_LIST",
    "override_type": "SHA256"
  },
  "query": "foo*",
  "start": 0,
  "rows": 10,
  "sort_field": "create_time",
  "sort_order": "asc"
}

Response 

"Date Updated","Changed By","List Type","Indicator Type","Indicator Value","Description","Extra Settings"
"2021-01-04T15:24:18.002Z","example@example.com","BLACK_LIST","SHA256","af62e6b3d475879c4234fe7bd8ba67ff6544ce6510131a069aaac75aa92aee7a","An override for a foo.exe","foo.exe"

Bulk Delete Reputation Overrides

Bulk delete reputation overrides by id

API Permissions Required

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

Request

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/reputations/overrides/_delete

Request Body 

[
  "<string>"
]

Body Schema

Field Definition Data Type Values
N/A List of reputation override ids Array 
[
  "e9410b754ea011ebbfd0db2585a41b07"
]

Response

Code Description Content-Type Content
200 Successfully deleted reputation overrides application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/reputations/overrides/_delete

Request_Body 

[
  "e9410b754ea011ebbfd0db2585a41b07"
]

Response 

{
  "results": [
    "e9410b754ea011ebbfd0db2585a41b07"
  ]
}

Related Resources

Reputation Priority

Add Trusted IT Tools to Approved List


Last modified on February 13, 2023