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 Endpoint Standard 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

Requirements

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

Authentication

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level:

    • for the category Application > Reputation > “org.reputations” allow permissions for “CREATE”, “READ”, and “DELETE”

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

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

API calls

Configure Reputation Override

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

RBAC Permissions Required

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

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

RBAC Permissions Required

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

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

RBAC Permissions Required

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

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

RBAC Permissions Required

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

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

RBAC Permissions Required

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

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

RBAC Permissions Required

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

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

Endpoint Standard: Reputation Priority

Carbon Black Cloud: How to Utilize IT Tools Allow list Feature

Last modified on January 14, 2021