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.
Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
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.
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"
}
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 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 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_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 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_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 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 |
|
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"
]
}
Endpoint Standard: Reputation Priority
Carbon Black Cloud: How to Utilize IT Tools Allow list Feature