CIS Benchmark API


Overview

CIS benchmarks are configuration guidelines published by the Center for Internet Security. The CIS Benchmark APIs enable configuration and retrieval of Benchmark Sets and Rules in Carbon Black Cloud, and retrieval of the results from scans performed using these Rules.

For more information on this feature see the Carbon Black Cloud User Guide. The APIs here enable access to the same features for automation and integration use cases.

For more information on CIS Benchmarks, see the Center for Internet Security. CIS benchmarks contain over 100 configuration guidelines created by a global community of cybersecurity experts to safeguard various systems against attacks targeting configuration vulnerabilities.

By monitoring compliance against benchmark recommendations, you can remediate issues and improve the security posture of your organization. The custom osquery extension collects the CIS benchmark results, see Live Query Extension Tables.

In December 2023, two new endpoints to search for and export devices within a Benchmark Set. See Search Devices in Benchmark Sets and Export Devices in Benchmark Sets.

Use Cases

Through these APIs you can

  • Curate benchmarks
  • Query compliance results
  • Export compliance results
  • Query, enable, or disable a compliance rule
  • Update compliance scan schedule
  • Execute compliance scan manually
  • Exclude or Include the device from compliance scan

Requirements

  • Carbon Black Cloud Workload - You must have purchased one of the Carbon Black Cloud Workload packages.
  • All API calls require an API key with appropriate permissions, see Authentication.

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.
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/_export
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/_export
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/compliance/summary/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/_clone
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules/{benchmark_set_rule_id}
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/actions
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/{device_id}/rules/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/{benchmark_set_rule_id}/devices/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/sections
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules
  • /compliance/assessment/api/v1/orgs/{org_key}/settings
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/device_actions

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Compliance > Compliance Assessment Data > complianceAssessment.data, allow permission to READ, UPDATE, DELETE, EXECUTE

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.
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/_export
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/_export
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/compliance/summary/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/_clone
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules/{benchmark_set_rule_id}
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/actions
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/{device_id}/rules/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/{benchmark_set_rule_id}/devices/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/_search
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/sections
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules
  • /compliance/assessment/api/v1/orgs/{org_key}/settings
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/device_actions
  • /compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/summary

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.Compliance:complianceAssessment.Data, allow permission to READ, UPDATE, DELETE, EXECUTE

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

Calls for managing Compliance Assessment are arranged in the following groups:

  • Settings - View and modify the scanning schedule.
  • Benchmark Set - Search for, modify and enable or disable Benchmark Sets.
  • Benchmark Rules - Search and modify rules within a Benchmark Set.
  • Execute Actions - Enable or disable a Benchmark Set or trigger a reassessment using the Benchmark Set.
  • Compliance Information - Get the results of scans using searching from different perspectives including per Device, Rule or Benchmark Set.

Settings

Manage the schedule for running Compliance Assessment scans.

Get Organization Settings

Get the current schedule for compliance scans.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 

GET {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/settings

Response Codes

Code Description Content-Type Content
200 Scan Schedule for compliance assessment application/json View example response below
Schema: Recurrence Rules, consistent with Live Query
400 Unable to update scan schedule due to bad request N/A N/A
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
GET https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/settings
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "scan_schedule": "FREQ=WEEKLY;BYDAY=FR;BYHOUR=23;BYMINUTE=30;BYSECOND=0",
    "scan_timezone": "UTC"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Organization Settings

Apply a new schedule for Compliance Assessment scans.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data UPDATE Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
PUT {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/settings


Request Body - application/json

{
  "scan_schedule": "<string>",
  "scan_timezone": "<string>"
}


Body Schema

Field Definition Data Type Values
scan_schedule Defines how frequently and when benchmark scans run for an organization String The Scan Schedule is set in accordance with the Recurrence Rules of Live Query
scan_timezone Timezone that the scan_schedule is configured in String Timezones are set in accordance with the Timezone Database Names of Live Query


Response Codes

Code Description Content-Type Content
200 Scan Schedule Updated for compliance assessment application/json View example response below
Schema: Settings
400 Error occurred while updating scan schedule application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
PUT https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/settings
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "scan_schedule": "FREQ=WEEKLY;BYDAY=TH;BYHOUR=23;BYMINUTE=30;BYSECOND=0",
    "scan_timezone": "UTC"
}
Response Body 
{
    "scan_schedule": "FREQ=WEEKLY;BYDAY=TH;BYHOUR=23;BYMINUTE=30;BYSECOND=0",
    "scan_timezone": "UTC"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Benchmark Sets

Search, modify, enable or disable, and delete Benchmark Sets.

Search Benchmark Sets

Use the search query and criteria to return the required Benchmark Sets.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
      "<fieldname>": [
          "<value>"
      ]},
  "sort": [
     {
        "field": "<string>",
        "order": "<string>"
     }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time

Response Codes

Code Description Content-Type Content
200 Get benchmark sets for the org application/json View example response below
Results Schema: Benchmark Sets
400 Error occurred while getting benchmark sets application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "windows",
  "rows": 20,
  "start": 0
}
Response Body 
{
    "num_found": "1",
    "results": [
    {
        "id": "251cc749-47d5-420d-9465-00a35a7024aa",
        "name": "Sample Benchmark Set",
        "version": "1.0.0.1",
        "os_family": "WINDOWS_SERVER",
        "enabled": false,
        "type": "Custom",
        "supported_os_info": [
            {
                "os_metadata_id": "4125c0f6-fb52-436b-a498-74b8a920075e",
                "os_type": "WINDOWS",
                "os_name": "Windows Server 2012 x64",
                "cis_version": "1.3.0"
            }
        ],
        "created_by": "Jane Doe",
        "updated_by": "jane@company.com",
        "create_time": "2023-03-01T03:07:14.383765Z",
        "update_time": "2023-03-01T03:07:14.383765Z",
        "sections": [
        {
            "id": "57428517-7E67-27DE-4EA7-699AFF2EDC61",
            "name": "Local Policies",
            "description": "This section contains recommendations for local policies.",
            "sections": [
                {
                    "id": "BE5B0852-96F7-3E07-391F-B1FA8CFF7F21",
                    "name": "User Rights Assignment",
                    "description": "This section contains recommendations for user rights assignments.",
                    "sections": [],
                    "rules": [
                        {
                            "id": "BCCAAACA-F0BE-4C0F-BE0A-A09FC1641EE2",
                            "rule_name": "(L1) Ensure 'Create a pagefile' is set to 'Administrators'",
                            "enabled": false,
                            "section_id": "BE5B0852-96F7-3E07-391F-B1FA8CFF7F21",
                            "section_name": "User Rights Assignment"
                        }
                    ]
                }]
        }]
    }]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Benchmark Set

Set new values in a Benchmark Set.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data UPDATE Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
PUT {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}


Request Body - application/json

{
    "id": "<string>",
    "name": "<string>",
    "version": "<string>",
    "os_family": "<string>",
    "enabled": <boolean>,
    "type": "<string>",
    "supported_os_info": [
        {
            "os_metadata_id": "<string>",
            "os_type": "<string>",
            "os_name": "<string>",
            "cis_version": "<string>",
        }
    ],
    "created_by": "<string>",
    "updated_by": "<string>",
    "create_time": "<string>",
    "update_time": "<string>"
}


Body Schema

Field Definition Data Type Values
Benchmark Set Fields required to define a Benchmark Set Benchmark Set N/A


Response Codes

Code Description Content-Type Content
200 Update benchmark set application/json 
{"sections": null}
400 Error occurred while updating benchmark set application/json 
{"error_code": "ERROR_DUPLICATE_BENCHMARK_SET_NAME",
 "message": "Benchmark set with the name already exists"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
PUT https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "id": "251cc749-47d5-420d-9465-00a35a7024aa",
    "name": "Sample Benchmark Set",
    "version": "1.0.0.1",
    "os_family": "WINDOWS_SERVER",
    "enabled": false,
    "type": "Custom",
    "supported_os_info": [
        {
            "os_metadata_id": "4125c0f6-fb52-436b-a498-74b8a920075e",
            "os_type": "WINDOWS",
            "os_name": "Windows Server 2012 x64",
            "cis_version": "1.3.0"
        }
    ],
    "created_by": "Jane Doe",
    "updated_by": "jane@company.com",
    "create_time": "2023-03-01T03:07:14.383765Z",
    "update_time": "2023-03-01T03:07:14.383765Z",
}
Response Body 
{
    "id": "251cc749-47d5-420d-9465-00a35a7024aa",
    "name": "Sample Benchmark Set",
    "version": "1.0.0.1",
    "os_family": "WINDOWS_SERVER",
    "enabled": false,
    "type": "Custom",
    "supported_os_info": [
        {
            "os_metadata_id": "4125c0f6-fb52-436b-a498-74b8a920075e",
            "os_type": "WINDOWS",
            "os_name": "Windows Server 2012 x64",
            "cis_version": "1.3.0"
        }
    ],
    "created_by": "Jane Doe",
    "updated_by": "jane@company.com",
    "create_time": "2023-03-01T03:07:14.383765Z",
    "update_time": "2023-03-01T03:07:14.383765Z"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Clone Benchmark Set

Make a complete copy of a Benchmark set.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ, CREATE Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ, CREATE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/_clone


Request Body - application/json

{
    "benchmark_name": "<string>"
}


Body Schema

Field Definition Data Type Values
benchmark_name Name of the new benchmark set to be copied from the one identified by ‘benchmark_set_id’ in the request param String N/A


Response Codes

Code Description Content-Type Content
200 Successful Request content/json View example response below. id is the identifier of the new benchmark set.
400 Error occurred cloning benchmark set application/json 
{"error_code": "ERROR_DUPLICATE_BENCHMARK_SET_NAME",
 "message": "Benchmark set with the name already exists"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/_clone
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "benchmark_name": "Copy of Sample Benchmark Set"
}
Response Body 
{
    "id": "1b9cc3ad-9d34-468c-8d68-0ec150d142d3"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Benchmark Set


API Permissions Required

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

Request 
DELETE {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}


Response Codes

Code Description Content-Type Content
204 Deleted benchmark set N/A N/A
400 Error occurred while deleting benchmark set application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
DELETE https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.

Benchmark Rules

Search and modify rules within a Benchmark Set

Search Rules


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules/_search


Request Body - application/json

{
   "query": "<string>",
   "rows": <integer>,
   "start": <integer>,
   "criteria": {
       "<fieldname>": [
           "<value>"
    ]},
   "sort": [
     {
        "field": "<string>",
        "order": "<string>"
     }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
   "fieldname": [
     "value"
   ]
}
Supported fields: id, rule_name, enabled, section_id, section_name
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
       "field": "<fieldname>",
       "order": "<order>"
  }
]
order supports ASC or DESC

Supported fields: id, rule_name, enabled, section_id, section_name

Response Codes

Code Description Content-Type Content
200 Get benchmark set rules application/json View example result below
Results Schema: Benchmark Rules
400 Error occurred while getting benchmark set rules application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/rules/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
     "query": "windows",
     "rows": 1,
     "start": 0,
     "sort": [
         {
             "field": "section_name",
             "order": "DESC"
         }
     ]
}
Response Body 
{
     "num_found": 57,
     "results": [
         {
             "id": "75D1C537-FF92-4B46-9875-9549AA088BC9",
             "rule_name": "(L1) Ensure 'Configure Automatic Updates' is set to 'Enabled'",
             "enabled": true,
             "section_id": "D5F265D0-6087-61C8-D6F9-9AE0B7AFB06B",
             "section_name": "Windows Update"
         }
     ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Specified Rule

Get details of a specified rule within a Benchmark Set.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules/{benchmark_set_rule_id}


Response Codes

Code Description Content-Type Content
200 Get benchmark sets for the org application/json View example response below
Schema: Benchmark Rule Information
400 Error occurred while getting benchmark rule application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server N/A N/A


Examples

Request 
GET https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/rules/BCCAAACA-F0BE-4C0F-BE0A-A09FC1641EE2
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "BCCAAACA-F0BE-4C0F-BE0A-A09FC1641EE2",
    "rule_name": "(L1) Ensure 'Create a pagefile' is set to 'Administrators'",
    "enabled": true,
    "section_id": "BE5B0852-96F7-3E07-391F-B1FA8CFF7F21",
    "section_name": "User Rights Assignment",
    "supported_os_info": [
        {
            "os_metadata_id": "4125c0f6-fb52-436b-a498-74b8a920075e",
            "os_type": "WINDOWS",
            "os_name": "Windows Server 2012 x64",
            "cis_version": "1.3.0"
        }],
    "description": "This policy setting allows users to change the size of the pagefile. By making the pagefile extremely large or extremely small, an attacker could easily affect the performance of a compromised computer.\n\nThe recommended state for this setting is: `Administrators`.",
    "rationale": "Users who can change the page file size could make it extremely small or move the file to a highly fragmented storage volume, which could cause reduced computer performance.",
    "impact": "None - this is the default behavior.",
    "remediation": {
        "procedure": "To establish the recommended configuration via GP, set the following UI path to `Administrators`",
        "steps": "\n\n ```\nComputer Configuration\\Policies\\Windows Settings\\Security Settings\\Local Policies\\User Rights Assignment\\Create a pagefile\n```"
    },
    "profile": [
        "Level 1 Domain Controller",
        "Level 1 Member Server"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Rules


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data UPDATE Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
PUT {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/rules


Request Body - application/json

[
     {
        "rule_id": "<string>",
        "enabled": <boolean>
     }
]

Body Schema

Field Definition Data Type Values
Benchmark Rule Request List List of rules and whether to set them enabled [ Benchmark Rule Request ] N/A


Response Codes

Code Description Content-Type Content
200 Update benchmark set rules application/json View example result below
Results Schema: Benchmark Rule
400 Error occurred while updating benchmark set rules application/json 
{"error_code": "BENCHMARK_RULE_INFO_NOT_FOUND", 
 "message": "Benchmark Rule: <rule id> Not found for org: ABCD1234 and Benchmark Set: <set id>"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
PUT https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/rules
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
     {
         "rule_id": "2A65B63E-89D9-4844-8290-5042FDF2A27B",
         "enabled": false
     }
]
Response Body 
[
     {
         "id": "2A65B63E-89D9-4844-8290-5042FDF2A27B",
         "rule_name": "(L1) Ensure 'Allow unencrypted traffic' is set to 'Disabled'",
         "enabled": false,
         "section_id": "BCE720DD-B5FC-1418-8576-8CF6DF906442",
         "section_name": "WinRM Client"
     }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Get All Benchmark Set Sections

Returns the Id and Name of all sections with the Id of the benchmark that contains the section.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
GET {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/sections


Response Codes

Code Description Content-Type Content
200 Fetch all BenchmarkSet Sections application/json View example response below.
Schema: Benchmark Set Section Item
400 Error occurred during fetching benchmark set sections application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
GET https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/sections
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
[
    {
        "section_id": "1752BB38-579F-D100-8F40-BF9E621D471E",
        "section_name": "Account Lockout Policy",
        "parent_id": "0BC9CD10-250C-61E8-F3D2-E3854B9DE335"
    },
    {
        "section_id": "57428517-7E67-27DE-4EA7-699AFF2EDC61",
        "section_name": "Local Policies",
        "parent_id": null
    }
    ... truncated ...
]
To download or review the Carbon Black Cloud Postman collection, click here.

Devices

Endpoints that return device information.

Search Devices in Benchmark Sets

Get the Device Summary for devices in a Benchmark Set.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/inventory/devices/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "exclusions": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time
exclusions Exclusions is an object that represents values that must not be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
    "field": "<fieldname>",
    "order": "<order>"
  }
]
order supports ASC or DESC

Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time

Response Codes

Code Description Content-Type Content
200 Get devices that are part of the benchmark set application/json View example response below
Results Schema: Benchmark Sets
400 Error occurred while getting benchmark sets application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/fa6e421c-e75a-483c-bea3-842fb1b52705/inventory/devices/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "windows",
  "rows": 1,
  "start": 0,
  "criteria": {
    "os_type": [
      "WINDOWS"
    ]
  },
  "exclusions": {
    "cis_version": [
      "1.4.0"
    ]
  },
  "sort": [
    {
      "field": "create_time",
      "order": "ASC"
    }
  ]
}
Response Body 
{
  "num_found": 4568,
  "results": [
    {
      "device_id": 12345678,
      "device_name": "TEST\\DEMO-MACHINE",
      "host_name": null,
      "os_version": "Windows Server 2019 x64",
      "reason": "ASSESSMENT_SCHEDULED",
      "sensor_version": "3.9.0",
      "last_checkin_time": "2023-12-19T08:37:03.126Z",
      "deployment_type": "WORKLOAD"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Devices in Benchmark Sets

Export the Device Summary for devices in a Benchmark Set in csv or json format.

  1. Use the endpoint defined here to create a job with required search criteria to limit the results. A job_id is returned.
  2. Use the job_id in the Download Job Output endpoint in the Jobs Service to get the results. The Download Job API requires the permission jobs.status - READ.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/inventory/devices/_export


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "exclusions": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "format": "<string>"
}


Body Schema

Field Definition Data Type Values
format Specify the desired file format for the downloaded content String JSON, CSV
Default: CSV
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time
exclusions Exclusions is an object that represents values that must not be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
    "field": "<fieldname>",
    "order": "<order>"
  }
]
order supports ASC or DESC

Supported fields: id, name, version, os_family, enabled, type, created_by, updated_by, create_time, update_time

Response Codes

Code Description Content-Type Content
200 Export job has been started, to export devices that are part of the benchmark set application/json Returns a job id 
{
  "job_id": 968091
}

See CSV or JSON example response below for the output from download job output.
400 Error occurred while getting benchmark sets application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/fa6e421c-e75a-483c-bea3-842fb1b52705/inventory/devices/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "windows",
  "rows": 1,
  "start": 0,
  "criteria": {
    "os_type": [
      "WINDOWS"
    ]
  },
  "exclusions": {
    "cis_version": [
      "1.4.0"
    ]
  },
  "sort": [
    {
      "field": "create_time",
      "order": "ASC"
    }
  ],
  "format": "CSV"
}
Response Body 
{
  "job_id": 968091
}
To download or review the Carbon Black Cloud Postman collection, click here.


Example responses after calling Download Job Output


Examples

Request 
GET https://defense.conferdeploy.net/jobs/v1/orgs/1234ABCD/jobs/968091/download
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Example response for Download Job Output with CSV format

Response Body 
"VM Name","OS Version","Sensor Version","Last Checkin Time","Reason","Asset Type"
"TEST\DEMO-MACHINE","Windows Server 2019 x64","4.0.0.1292","2023-12-19","Assessment Scheduled","WORKLOAD"
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
GET https://defense.conferdeploy.net/jobs/v1/orgs/1234ABCD/jobs/968091/download
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Example response for Download Job Output with JSON format

Response Body 
[
  {
    "VM Name": "TEST\\DEMO-MACHINE",
    "OS Version": "Windows Server 2019 x64",
    "Sensor Version": "4.0.0.1292",
    "Asset Type": "WORKLOAD",
    "Last Checkin Time": "2023-12-19",
    "Reason": "ASSESSMENT_SCHEDULED"
  }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Execute Actions

On a Benchmark Set

Enable or disable a Benchmark Set or trigger a reassessment using the Benchmark Set.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data EXECUTE Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.EXECUTE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/actions


Request Body - application/json

{
  "action": "<string>"
}


Body Schema

Field Definition Data Type Values
action The action to take on the benchmark set String ENABLE, DISABLE, REASSESS


Response Codes

Code Description Content-Type Content
200 Executed benchmark set action application/json 
{"status_code": "SUCCESS",
 "message": "<string>"}
400 Error occurred while executing benchmark set action application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/actions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "action": "ENABLE"
}
Response Body 
{
  "status_code": "SUCCESS",
  "message": "Benchmark set for Microsoft Windows Server is enabled"
}
To download or review the Carbon Black Cloud Postman collection, click here.

On Specified Devices

Take the specified action on each device within a Benchmark Set, as specified in the request.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data EXECUTE Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.EXECUTE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/device_actions


Request Body - application/json

{
  "action": "<string>",
  "device_ids": [ <integer> ]
}


Body Schema

Field Definition Data Type Values
action The action to be taken String EXCLUDE, INCLUDE, REASSESS
device_ids List of devices on which to take the action Array e.g. [13579,86422]


Response Codes

Code Description Content-Type Content
200 Executed device action application/json 
{"status_code": "SUCCESS",
 "message": "<string>"}
400 Error occurred while executing action on device application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/device_actions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "action": "REASSESS",
  "device_ids": [ <integer> ]
}
Response Body 
{
  "status_code": "SUCCESS",
  "message": "Benchmark set for Microsoft Windows Server is enabled"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Compliance Information

Search Benchmark Set Summaries


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/compliance/summary/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: org_key, benchmark_set_id, name , compliant, non_compliant, excluded
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported Fields: org_key, benchmark_set_id, name , compliant, non_compliant, excluded

Response Codes

Code Description Content-Type Content
200 Get benchmark set compliance summaries application/json View example response below
Results Schema: Benchmark Summary
400 Error occurred while getting benchmark set compliance summary application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/compliance/summary/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "firewall"
}
Response Body 
{
  "num_found": 1,
  "results": [
    {
      "org_key": "ABCD1234",
      "benchmark_set_id": "ddb18fc4-c3ac-4e32-9015-ad0aadf30164",
      "name": "CIS Compliance - Microsoft Windows Server",
      "compliant": 0,
      "non_compliant": 0,
      "excluded": 0,
      "not_assessed": 10
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Device Compliance Summaries


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
      "<fieldname>": [
          "<value>"
    ]},
  "sort": [
     {
        "field": "<string>",
        "order": "<string>"
     }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported Fields: device_id, device_name, os_version, compliance_percentage, last_assess_time, excluded_on, excluded_by, reason
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported Fields: device_id, device_name, os_version, compliance_percentage, last_assess_time, excluded_on, excluded_by, reason

Response Codes

Code Description Content-Type Content
200 Get device compliance application/json View example response below
Results Schema: Device Compliance Summaries
400 Error occurred while getting device compliance application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/devices/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "windows",
  "rows": 20,
  "start": 0
}
Response Body 
{
  "num_found": "1",
  "results": {
    "device_id": "13579",
    "device_name": "Windows 2019 desktop",
    "os_version": "Windows server 2019",
    "compliance_percentage": 95,
    "last_assess_time": "2022-05-05T010:15:30.000Z",
    "excluded_on": "2022-05-05T010:15:30.000Z",
    "excluded_by": "User",
    "reason": "Excepted By User"
  }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Device Compliance Summaries

Exporting device compliance summaries is an asynchronous process requiring two API calls.

  1. Use the endpoint defined here to create a job with required search criteria to limit the results. A job_id is returned.
  2. Use the job_id in the Download Job Output endpoint in the Jobs Service to get the results. The Download Job API requires the permission jobs.status - READ.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/_export


Request Body - application/json

{
    "query": "<string>",
    "rows": <integer>,
    "start": <integer>,
    "criteria": {
        "<fieldname>": [
            "<value>"
        ]
    },
    "sort": [
     {
        "field": "<string>",
        "order": "<string>"
     }
    ],
    "format": "<string>"
}


Body Schema

Field Definition Data Type Values
format Specify the desired file format for the downloaded content String JSON, CSV
Default: CSV
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported Fields: device_id, device_name, os_version, compliance_percentage, last_assess_time, excluded_on, excluded_by, reason
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported Fields: device_id, device_name, os_version, compliance_percentage, last_assess_time, excluded_on, excluded_by, reason


Response Codes

Code Description Content-Type Content
200 Export device compliance application/json View example response below. Output of the Download Job have records of type Export Device Compliance Summary
400 Error occurred while export device compliance summaries application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/devices/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "windows",
  "rows": 20,
  "start": 0
}
Response Body 
{
  "job_id": 1675
}
Download Job to Get Results
Request 
GET {cbc-hostname}/jobs/v1/orgs/ABCD1234/jobs/1675/download
Response Body of the Download Job Output in JSON Format 
[
    {
        "VM Name": "MYDOMAIN\\DEMOMACHINE",
        "Os Version": "Windows Server 2022 x64",
        "Compliance Percentage": "95.00",
        "Last Access Time": "2023-02-03"
    },
    {
        "VM Name": "MYDOMAIN\\WORKMACHINE",
        "Os Version": "Windows Server 2022 x64",
        "Compliance Percentage": "95.00",
        "Last Access Time": "2023-02-03"
    }
    ... truncated ...
]
Response Body of the Download Job Output in CSV Format 
"VM Name","Compliance Percentage","Last Assessment Time","OS Version"
"MYDOMAIN\\DEMOMACHINE"","95","2023-02-03","Windows Server 2022 x64"
"MYDOMAIN\\WORKMACHINE","95","2023-02-03","Windows Server 2022 x64"
To download or review the Carbon Black Cloud Postman collection, click here.

Search Rule Compliance Summaries

Returns the compliance summaries for rules that match the search criteria.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported Fields: rule_id, rule_name, section_id, section_name, compliant_assets, non_compliant_assets,profile
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported Fields: rule_id, rule_name, section_id, section_name, compliant_assets, non_compliant_assets,profile

Response Codes

Code Description Content-Type Content
200 Get rule compliance summaries for the org application/json See example response below
Results Schema: Rule Compliance Summary
400 Error occurred while getting rule compliance summaries application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/rules/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "firewall"
}
Response Body 
{
    "num_found": 26,
    "results": [
        {
            "rule_id": "00869D86-6E61-4D7D-A0A3-6F5CDE2E5753",
            "rule_name": "(L1) Ensure 'Windows Firewall: Private: Firewall state' is set to 'On (recommended)'",
            "section_id": "39285D6D-3D69-55A5-9C99-1EA0FC5ACAD3",
            "section_name": "Private Profile",
            "compliant_assets": 12,
            "non_compliant_assets": 2,
            "profile": [
                "Level 1 Domain Controller",
                "Level 1 Member Server"
            ]
        }
        ... truncated ...
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Rule Compliance Summaries

Exporting rule compliance summaries is an asynchronous process requiring two API calls.

  1. Use the endpoint defined here to create a job with required search criteria to limit the results. A job_id is returned.
  2. Use the job_id in the Download Job Output endpoint in the Jobs Service to get the results. The Download Job API requires the permission jobs.status - READ.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/_export


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "format": "<string>"
}


Body Schema

Field Definition Data Type Values
format Specify the desired file format for the downloaded content String JSON, CSV
Default: CSV
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    <"value>"
  ]
}
Supported Fields: rule_id, rule_name, section_id, section_name, compliant_assets, non_compliant_assets,profile
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported Fields: rule_id, rule_name, section_id, section_name, compliant_assets, non_compliant_assets,profile


Response Codes

Code Description Content-Type Content
200 Export rule compliance summaries for the org application/json View example response below. Output of the Download Job have records of type Export Rule Compliance Summary
400 Error occurred while exporting rule compliance summaries application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/rules/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "windows",
    "rows": 20,
    "start": 0,
    "format": "CSV"
}
Response Body 
{
  "job_id": 1675
}
Response Body of the Download Job Output in JSON Format 
[
  {
    "Non Compliant Assets Ids": [
      "46250900"
    ],
    "Compliant Assets Ids": [],
    "Benchmark Set Id": "fa6e421c-e75a-483c-bea3-842fb1b52705",
    "Non Compliant Assets": 1,
    "Benchmark Set Name": "CIS Compliance - Microsoft Windows Server",
    "Recommendation Name": "(L1) Ensure 'Windows Firewall: Private: Firewall state' is set to 'On (recommended)'",
    "Compliant Assets": 0,
    "Remediation": "To establish the recommended configuration via GP, set the following UI path to On (recommended):    Computer Configuration\\Policies\\Windows Settings\\Security Settings\\Windows Firewall with Advanced Security\\Windows Firewall with Advanced Security\\Windows Firewall Properties\\Private Profile\\Firewall state ",
    "Section Name": "Private Profile",
    "Recommendation Id": "00869D86-6E61-4D7D-A0A3-6F5CDE2E5753"
  },
  ... truncated ...
]
Response Body of the Download Job Output in CSV Format 
"Recommendation Name","Section Name","Compliant Assets","Non Compliant Assets","Compliant Assets Ids","Non Compliant Assets Ids","Benchmark Set Id","Benchmark Set Name","Recommendation Id","Remediation"
"(L1) Ensure 'Windows Firewall: Private: Firewall state' is set to 'On (recommended)'","Private Profile","0","1","","""46250900""","fa6e421c-e75a-483c-bea3-842fb1b52705","CIS Compliance - Microsoft Windows Server","00869D86-6E61-4D7D-A0A3-6F5CDE2E5753","To establish the recommended configuration via GP, set the following UI path to On (recommended):    Computer Configuration\Policies\Windows Settings\Security Settings\Windows Firewall with Advanced Security\Windows Firewall with Advanced Security\Windows Firewall Properties\Private Profile\Firewall state "
   ... truncated ...
To download or review the Carbon Black Cloud Postman collection, click here.

Search Rule Compliance Results for a Device

Search and return rule compliance results for a specified Device.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/devices/{device_id}/rules/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: id, rule_name, enabled, section_id, section_name
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported fields: id, rule_name, enabled, section_id, section_name

Response Codes

Code Description Content-Type Content
200 Get device compliance application/json View example response below
Results Schema: Compliance Rule Result
400 Error occurred while getting rule compliance results application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/devices/13579/rules/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "password",
    "rows": 1
}
Response Body 
{
    "num_found": 22,
    "results": [
        {
            "id": "7CA1D791-C92F-4205-B908-7C4FAE24499B",
            "rule_name": "(L1) Ensure 'Domain member: Maximum machine account password age' is set to '30 or fewer days, but not 0'",
            "enabled": true,
            "section_id": "01DCABE2-26E0-9F1D-702A-51C6277D98A2",
            "section_name": "Domain member",
            "compliance_result": true,
            "message": "Registry_Parameters_MaximumPasswordAge=30"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Rule Results for Devices

Search and return rule compliance results for Devices that match the search criteria within the specified Benchmark Set and Rule.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/benchmark_sets/{benchmark_set_id}/compliance/rules/{benchmark_set_rule_id}/devices/_search


Request Body - application/json

{
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "criteria": {
    "<fieldname>": [
      "<value>"
    ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
query Query in lucene syntax and/or including value searches String N/A
rows For pagination, how many results to return Integer Default: 1000
Maximum: 80,000
start For pagination, where to start retrieving results from Integer Default: 0
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "fieldname": [
    "<value>"
  ]
}
Supported fields: device_id, device_name, os_version, compliance_percentage
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[
  {
      "field": "<fieldname>",
      "order": "<order>"
  }
]
order supports ASC or DESC

Supported fields: device_id, device_name, os_version, compliance_percentage

Response Codes

Code Description Content-Type Content
200 Get device rule results application/json View sample result below
Results Schema: Device Rule Result
400 Error occurred while getting device rule results application/json 
{"error_code": "ERROR_CODE_STRING",
 "message": "Error description"}
401 Not Authenticated N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A


Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/1234ABCD/benchmark_sets/251cc749-47d5-420d-9465-00a35a7024aa/compliance/rules/BCCAAACA-F0BE-4C0F-BE0A-A09FC1641EE2/devices/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "DEMO",
  "rows": 1,
  "start": 0
}
Response Body 
{
    "num_found": 13,
    "results": [
        {
            "device_id": 37954691,
            "device_name": "DEMO\\MYDEMOSERVER",
            "os_version": "Windows Server 2022 x64",
            "compliance_result": true
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Bundles

A Bundle is a versioned set of rules. Use these endpoints to get information about and acknowledge new versions of Bundles.


Get Compliance Bundle Version Updates

Get the updates to compliance bundles that occurred after a given time. The time can be in minutes, hours, days, or weeks.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
GET {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/bundles/updates


Query Parameters

Parameter Description Values Default
acknowledged Whether to fetch acknowledged bundle updates or not true, false true
since The period of time to search for updated versions. Can be in minutes, hours, days, or weeks. e.g. 1d, 1w


Response Codes

Code Description Content-Type Content
200 Successful request for Compliance Bundle Updates application/json View example response below.
Results Schema: Bundle Update Information
400 Bad Request application/json 
{
    "error_code": "INVALID_PARAM_INPUT",
    "message": "Received Invalid Param input for since value `ZZZ` not supported"
}
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
GET https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/ABCD1234/bundles/updates?acknowledged=true&since=180d
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
[
    {
        "bundle_id": "a0423be0-eddd-4170-99fc-78d5cb8f157f",
        "new_version": "1.0.0.2",
        "old_version": "1.0.0.1",
        "update_time": "2023-09-29T07:21:43.185547Z",
        "status": "COMPLETED",
        "bundle_name": "TEST CIS Compliance - Microsoft Windows Server",
        "os_family": "TEST_WINDOWS_SERVER",
        "acknowledged": true
    }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Acknowledge Compliance Bundle Version

Acknowledges new updates for the compliance bundles specified in the request.

The response includes bundles that were successfully acknowledged. If the request includes invalid bundles or versions, they will be ignored and not included in the response.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
PUT {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/bundles/updates/_ack


Request Body - application/json

[
    {
        "bundle_id": "<string>",
        "new_version": "<string>"
    }
]


Body Schema

Field Definition Data Type Values
bundle_id Identifier of the bundle that will be acknowledged. String e.g. “a0423be0-eddd-4170-99fc-78d5cb8f157f”
new_version Version identifier of the bundle that will be acknowledged. String e.g. “1.0.0.4”


Response Codes

Code Description Content-Type Content
200 Successfully acknowledged bundle versions N/A See example response below
400 Bad Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
PUT https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/ABCD1234/bundles/updates/_ack
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
    {
        "bundle_id": "a0423be0-eddd-4170-99fc-78d5cb8f157f",
        "new_version": "1.0.0.2"
    }
]
Response Body 
[
    {
        "bundle_id": "a0423be0-eddd-4170-99fc-78d5cb8f157f",
        "new_version": "1.0.0.2"
    }
]
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
PUT https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/ABCD1234/bundles/updates/_ack
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
    {
        "bundle_id": "THIS_BUNDLE_ID_IS_NOT_VALID",
        "new_version": "1.0.0.2"
    }
]
Response Body 
[]
To download or review the Carbon Black Cloud Postman collection, click here.

Difference Between Bundle Versions

Get the differences between two Compliance Bundle versions


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/bundles/{bundle_id}/versions/_diff


Request Body - application/json

{
    "old_version": "<string>",
    "new_version": "<string>"
}


Body Schema

Field Definition Data Type Values
old_version Version identifier of the older of two bundles to compare String “1.0.0.1”
new_version Version identifier of the newer of two bundles to compare String “1.0.0.2”


Response Codes

Code Description Content-Type Content
200 Successful comparison of two versions of a bundle N/A View example response below.
Results Schema: Differencial Result
400 Bad Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
POST https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/ABCD1234/bundles/a0423be0-eddd-4170-99fc-78d5cb8f157f/versions/_diff
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
"old_version": "1.0.0.1",
"new_version": "1.0.0.2"
}
Response Body 
{
    "old_version": "1.0.0.1",
    "new_version": "1.0.0.2",
    "change_count": 2,
    "added_count": 1,
    "removed_count": 1,
    "changes": [
    {
        "action": "REMOVED",
        "rule_id": "3FD16705-1E01-47E4-AE3B-CA18FA60C433",
        "fields": [
            {
                "key": "rule_id",
                "old_value": null,
                "value": "3FD16705-1E01-47E4-AE3B-CA18FA60C433"
            },
            {
                "key": "rule_name",
                "old_value": null,
                "value": "(L1) Ensure 'Minimum password length' is set to '14 or more character(s)'"
            },
            {
                "key": "section_id",
                "old_value": null,
                "value": "5C3C74D2-42E0-6E90-E20C-F275DE67AFD4"
            },
            {
                "key": "section_name",
                "old_value": null,
                "value": "Password Policy"
            }
        ]
    },
    {
        "action": "ADDED",
        "rule_id": "004e9492-ba62-4a4c-a433-3dc44b96b074",
        "fields": [
            {
                "key": "rule_id",
                "old_value": null,
                "value": "004e9492-ba62-4a4c-a433-3dc44b96b074"
            },
            {
                "key": "rule_name",
                "old_value": null,
                "value": "(L1) Ensure 'Create a token object' is set to 'No One'"
            },
            {
                "key": "section_id",
                "old_value": null,
                "value": "c9744adf-e7a0-43b4-97b8-64da8317ed2a"
            },
            {
                "key": "section_name",
                "old_value": null,
                "value": "User Rights Assignment"
            }
        ]
    }
]
}
To download or review the Carbon Black Cloud Postman collection, click here.


Get Rule Info for Bundle Version

Gets the Rule Info for the specified compliance bundle version.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud complianceAssessment.data READ Majority of environments
VMware Cloud Services Platform _API.Compliance:complianceAssessment.Data.READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 

GET {cbc-hostname}/compliance/assessment/api/v1/orgs/{org_key}/bundles/{bundle_id}/versions/{version_id}/rules/{benchmark_set_rule_id}

Response Codes

Code Description Content-Type Content
200 Successfully got the rule information for a rule in a version of a bundle N/A See example response below
400 Bad Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
GET https://defense.conferdeploy.net/compliance/assessment/api/v1/orgs/ABCD1234/bundles/a0423be0-eddd-4170-99fc-78d5cb8f157f/versions/1.0.0.2/rules/004e9492-ba62-4a4c-a433-3dc44b96b074
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "004e9492-ba62-4a4c-a433-3dc44b96b074",
    "rule_name": "(L1) Ensure 'Create a token object' is set to 'No One'",
    "enabled": null,
    "section_id": "c9744adf-e7a0-43b4-97b8-64da8317ed2a",
    "section_name": "User Rights Assignment",
    "supported_os_info": [
        {
            "os_metadata_id": "1",
            "os_type": "WINDOWS",
            "os_name": "Windows Server 2012 x64",
            "cis_version": "2.3.0"
        },
        {
            "os_metadata_id": "2",
            "os_type": "WINDOWS",
            "os_name": "Windows Server 2012 R2 x64",
            "cis_version": "2.5.0"
        }
    ],
    "description": "This policy setting allows a process to create an access token, which may provide elevated rights to access sensitive data.\n\nThe recommended state for this setting is: `No One`.\n\n**Note:** This user right is considered a \"sensitive privilege\" for the purposes of auditing.",
    "rationale": "A user account that is given this user right has complete control over the system and can lead to the system being compromised.",
    "impact": "None - this is the default behavior.",
    "remediation": {
    "procedure": "To establish the recommended configuration via GP, set the following UI path to `No One`",
    "steps": "\n\n ```\nComputer Configuration\\Policies\\Windows Settings\\Security Settings\\Local Policies\\User Rights Assignment\\Create a token object\n```"
},
    "profile": [
        "Level 1 Domain Controller",
        "Level 1 Member Server"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Field Definitions

Benchmark Rule

Field Definition Data Type Values
id Identifier of the rule String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
rule_name Name of the rule String e.g. ‘Example rule name’
enabled Whether the rule is enabled or not boolean true, false
section_id Identifier of the section String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
section_name Name of the section String e.g. ‘Password Policy’

Benchmark Rule Information

Field Definition Data Type Values
All of Benchmark Rule fields Include all the fields from Benchmark Rule N/A N/A
supported_os_info Information about the Operating System Array: [ os_info ] N/A
description Description of the rule String e.g. ‘This setting determines the number of renewed, unique passwords’
rationale Reason for the rule String e.g. ‘The longer a user uses the same password, the greater the risk it is compromised’
impact What enforcing the rule will cause to happen String e.g. ‘The major impact of this configuration is that users must create a new password’
remediation The action to take when the rule is not met Object 
{
  "procedure": "<string>", 
  "steps":"<string>"
}
profile Profiles this rule applies to Array ‘Level 1 Member Server’

Benchmark Rule Request

Field Definition Data Type Values
rule_id Identifier of the rule String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
enabled Whether the rule is enabled boolean true, false

Benchmark Set

Field Definition Data Type Values
id Identifier of the Benchmark Set String e.g. ‘251cc749-47d5-420d-9465-00a35a7024aa’
name Name of the Benchmark Set String e.g. ‘Example Benchmark Set’
version Version of the Benchmark Set String e.g. ‘1.0.0.1’
os_family Family of operating systems this benchmark set applies to String e.g. ‘WINDOWS_SERVER’
enabled Whether the Benchmark Set is enabled boolean true, false
type Descriptive grouping String N/A
supported_os_info Operating systems that this Benchmark Set applies to supported_os_info N/A
created_by Username of the user who created the Benchmark Set String e.g. ‘jane.doe@sample.com’
updated_by Username of the user who created the Benchmark Set String e.g. ‘sample.sam@sample.com’
create_time Date time of creation in ISO 8601 UTC format to seconds String e.g. ‘2022-05-05T010:15:30.000Z’
update_time Date time the record was last updated in ISO 8601 UTC format to seconds String e.g. ‘2022-05-05T010:15:30.000Z’

Benchmark Set Section

Field Definition Data Type Values
id Identifier of the Benchmark Set Section String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
name Name of the Benchmark Set Section String e.g. ‘Account Policies’
description Description of the Benchmark Set Section String e.g. ‘This section contains recommendations for account policies.
rules Collection of rules that comprise this Section of the Set [ Benchmark Rule ] N/A

Benchmark Set Section Item

Field Definition Data Type Values
section_id Identifier of the section String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
section_name Name of the section String e.g. ‘Password Policy’
parent_id Identifier of the parent of the section String e.g. ‘0BC9CD10-250C-61E8-F3D2-E3854B9DE335’

Benchmark Summary

Field Definition Data Type Values
org_key Identifier of the Carbon Black Cloud organization String e.g. ‘1234ABCD’
benchmark_set_id Identifier of the Benchmark Set String e.g. ‘251cc749-47d5-420d-9465-00a35a7024aa’
name Name of the Benchmark Set String e.g. ‘Sample Benchmark Set’
compliant Number of assets that are compliant with the Benchmark Set Integer e.g. 13
non_compliant Number of assets that are not compliant with the Benchmark Set Integer e.g. 3
excluded Number of assets that were not included in the assessment Integer e.g. 7
not_assessed Number of assets that were not assessed Integer e.g. 21

Bundle Update Information

Field Definition Data Type Values
bundle_id Unique identifier of a set of rules String e.g. “4125c0f6-fb52-436b-a498-74b8a920075e”
old_version Identifier of the older version of the bundle that will be replaced String e.g. “1.0.0.1”
new_version Identifier of the new version of the bundle that will become current String e.g. “1.0.0.2”
update_time Date time of last update in ISO 8601 UTC format to seconds String e.g. “2022-05-05T010:15:30.000Z”
status String COMPLETED
bundle_name Descriptive name of the bundle String e.g. “CIS Compliance - Microsoft Windows Server”
os_family Operating system that this bundle of rules is applicable to String e.g. “Microsoft Windows Server”
acknowledged Whether the version of the bundle has been acknowledged Boolean e.g. true

Compliance Rule Result

Field Definition Data Type Values
benchmark_rule Information about the Benchmark Rule Array: [ benchmark_rule ] N/A
compliance_result Whether the rule was complied with boolean true, false
message Descrip`tion explaining the compliance result String N/A

Device Compliance Summary

Field Definition Data Type Values
device_id Identifier of the Device Integer e.g. 13579
device_name Name of the Device String e.g. ‘MYDOMAIN\DEMOMACHINE’
os_version Operating System of the Device String e.g. ‘Windows Server 2022 x64’
compliance_percentage Percentage of rules that the device complied with Integer e.g. 95
last_assess_time Date time of the last assessment in ISO 8601 UTC format to seconds String e.g. ‘2022-05-05T010:15:30.000Z’
excluded_on If the device was excluded from assessment the date time in ISO 8601 UTC format to seconds this occurred String e.g. ‘2022-05-05T010:15:30.000Z’
excluded_by If the device was excluded from assessment the user who performed the exclusion String e.g. john.doe@sample.com
reason Reason for exclusion from assessment String N/A
deployment_type Type of deployment String WORKLOAD, ENDPOINT, AWS, GCP, AZURE

Device Rule Result

Field Definition Data Type Values
device_id Identifier of the Device Integer e.g. 13579
device_name Name of the Device String
os_version Operating System of the Device String
compliance_percentage Percentage of rules that the dvice complied with Integer e.g. 95
compliance_result Whether the rule was complied with boolean true, false

Differential Result

Field Definition Data Type Values
old_version Identifier of the older version of the bundle that will be replaced String e.g. “1.0.0.1”
new_version Identifier of the new version of the bundle that will become current String e.g. “1.0.0.2”
change_count Number of changes between the two versions Integer e.g. 13
added_count Number of additive changes Integer e.g. 3
removed_count Number of changes where an item was removed Integer e.g. 10
changes List of the items that changed between the versions Object
changes.action The type of change String ADDED, REMOVED
changes.rule_id Identifier of the rule that changed String e.g. “4125c0f6-fb52-436b-a498-74b8a920075e”
changes.fields Details about the fields that changed Array [ Object ] 
{
    "key": "<string>",
    "old_value": "<string>",
    "value": "<string>""
}

Export Rule Compliance Summary

All of Rule Compliance Summary and:

Field Definition Data Type Values
benchmark_set_id Identifier of the Benchmark Set String e.g. ‘251cc749-47d5-420d-9465-00a35a7024aa’
benchmark_set_name Name of the Benchmark Set String e.g. ‘Sample Benchmark Set’
remediation The action to take when the rule is not met String e.g. “To establish the recommended configuration via GP, set the following UI path to Enabled”
non_compliant_asset_ids List of asset ids that are not compliant Array [ String ] [‘12356758’]
compliant_asset_ids List of asset ids that are compliant Array [ String ] [‘98765432’]

Export Device Compliance Summary

All of Device Compliance Summary and:

Field Definition Data Type Values
benchmark_set_id Identifier of the Benchmark Set String e.g. ‘251cc749-47d5-420d-9465-00a35a7024aa’
benchmark_set_name Name of the Benchmark Set String e.g. ‘Sample Benchmark Set’
host_name String e.g. “Windows 2019 desktop”
rule_id String e.g.“4125c0f6-fb52-436b-a498-74b8a920075e”
rule_name Name of the rule String e.g. ‘Example rule name’
compliance_result Whether the rule was complied with boolean true, false

Export Response

Field Definition Data Type Values
job_id Identifier of an asynchronous export job Integer e.g. 1675

Inventory Device Summary

Field Definition Data Type Values
device_id Identifier of the Device Integer e.g. 13579
device_name Name of the Device String e.g. “Windows 2019 desktop "
host_name Operating System of the Device String e.g. “Windows 2019 desktop”
os_version Operating System of the Device String e.g. “Windows server 2019”
reason Reason for exclusion from assessment String OUTDATED_SENSOR_VERSION, NOT_IN_DOMAIN_CONTROLLER, ASSESSMENT_SCHEDULED
sensor_version Version of the sensor installed on the device String e.g. “5.5”
last_checkin_time Date time of the last time the sensor checked in ISO 8601 UTC format to seconds String e.g. “2022-05-05T010:15:30.000Z”
deployment_type Type of deployment String WORKLOAD, ENDPOINT, AWS, GCP, AZURE

OS Info

Field Definition Data Type Values
os_metadata_id Identifier of this descriptive data about an operating system String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
os_type Type of operating system String e.g. ‘WINDOWS’
os_name Name of operating system String e.g. ‘Windows Server 2012 x’
cis_version Version of CIS String e.g. ‘1.3.0’

Rule Compliance Summary

Field Definition Data Type Values
rule_id Identifier of the rule String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
rule_name Name of the rule String e.g. ‘Sample rule’
section_id Identifier of the section String e.g. ‘4125c0f6-fb52-436b-a498-74b8a920075e’
section_name Name of the section String e.g. ‘Section Name’
compliant_assets Number of assets that are compliant with the Benchmark Set Integer e.g. 13
non_compliant_assets Number of assets that are not compliant with the Benchmark Set Integer e.g. 3
profile Name of the profile for these rules Array e.g. ‘Level 1 Domain Controller’
num_found The number of records found. May be greater than the number returned Integer N/A

Settings

Field Definition Data Type Values
scan_schedule Defines how frequently and when benchmark scans run for an organization String e.g. ‘FREQ:DAILY;HOUR:10’
scan_timezone Timezone that the scan_schedule is configure in string e.g. UTC

Last modified on April 26, 2024