Setup API

Overview

The Setup-API provides the means for the user/client to install Carbon black tools for container security.

Use Cases

  • Install the image scanning CLI (called cbctl) for detecting image vulnerabilities.
  • Install the monitoring sensor (also called agent) on their k8s cluster.
  • Get details about operator version and k8s version compatibilities. The operator is the component that deploys the sensor.
  • Get details about sensor capabilities including network runtime, cluster scanning, cluster secrets scanning, and CNDR.

Requirements

  • Container Security Product
  • All API calls require an API key with appropriate permissions, see Authentication for details

Key Features

  • Get the installation command to install and deploy the operator on the users k8s cluster
  • Get the CLI (cbctl) image scanning binary installation command and download links
  • Get the compatibility list of every operator version to which k8s version it’s compatible
  • Get capability list for each sensor version

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.
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/kubernetes_resource_definitions
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/cli_instances/download_links
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/kubernetes_resource_definitions/{id}
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/compatibility
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/compatibility/{operator_version}
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/cli_instances/setup_command
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/sensors
  • {cbc-hostname}/containers/v1/orgs/{org_key}/deploy

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Workloads Management > Manage Kubernetes Security > kubernetes.security, allow permission to READ, CREATE, 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.

API Calls

Get Operator Installation Data

Returns data about the Carbon Black Containers Operator with metadata on how to install the Operator. This includes URLs to the Operator YAML for different Kubernetes versions as well as URLs to helper scripts that automate this for the customer.

Note: It is used and managed internally by the users browser.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy

Response Codes

Code Description Content-Type Content
200 The Operator installation data application/json Operator Installation Data
Example Response Below
404 Not Found application/json 
{"message": "Not Found"}
500 Internal Server Error application/json 
{"message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "operator_url": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator.yaml",
    "install_script_bash_url": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator-apply.sh",
    "install_script_powershell_url": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator-apply.ps1",
    "operator_setup_data": [
        {
            "min_kubernetes_version": "1.13",
            "max_kubernetes_version": "1.15",
            "url_to_yaml": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator-kubernetes-under-1-16.yaml"
        },
        {
            "min_kubernetes_version": "1.16",
            "max_kubernetes_version": "",
            "url_to_yaml": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator.yaml"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Sensor Metadata

Provides the list of Carbon Black Containers Sensor versions and what features are available for each version including what is the latest sensor version available.

Note: It is used and managed internally by the users browser.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/sensors

Response Codes

Code Description Content-Type Content
200 Metadata about the available sensor versions application/json Sensor Metadata
Example Response Below
404 Not Found application/json 
{"message": "Not Found"}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/sensors
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "sensors": [
        {
            "version": "3.0.1",
            "is_latest": true,
            "supports_runtime": true,
            "supports_cluster_scanning": true,
            "supports_cluster_scanning_secrets": true,
            "supports_cndr": true
        },
        {
            "version": "3.0.0",
            "is_latest": false,
            "supports_runtime": true,
            "supports_cluster_scanning": true,
            "supports_cluster_scanning_secrets": true,
            "supports_cndr": true
        },
        {
            "version": "2.12.2",
            "is_latest": false,
            "supports_runtime": true,
            "supports_cluster_scanning": true,
            "supports_cluster_scanning_secrets": false,
            "supports_cndr": true
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Full Operator Compatibility

Returns the compatibility matrix specifying which sensor are compatible to which operator version.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/compatibility

Response Codes

Code Description Content-Type Content
200 The compatibility data application/json Compatibility Matrix
Example Response Below
404 Not Found application/json 
{"message": "Not Found"}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/compatibility
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "matrix": {
        "5.5.0": {
            "min_agent": "2.10.0",
            "max_agent": "2.11.0"
        },
        "5.6.0": {
            "min_agent": "2.10.0",
            "max_agent": "2.12.2"
        },
        "5.6.1": {
            "min_agent": "2.10.0",
            "max_agent": "2.12.2"
        },
        "5.6.2": {
            "min_agent": "2.10.0",
            "max_agent": "2.12.2"
        },
        "6.0.0": {
            "min_agent": "2.10.0",
            "max_agent": "latest"
        },
        "6.0.1": {
            "min_agent": "2.10.0",
            "max_agent": "latest"
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Operator Compatibility

Returns the compatibility matrix entry specifying which sensor versions are compatible with {operator_version}.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/compatibility/{operator_version}

Response Codes

Code Description Content-Type Content
200 The compatibility data application/json Compatibility Entry
Example Response Below
404 Not Found application/json 
{"message": "Not Found"}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/compatibility/6.0.1
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "min_agent": "2.10.0",
    "max_agent": "latest"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Returns the CLI download links for OSX, Linux and Windows.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/cli_instances/download_links

Response Codes

Code Description Content-Type Content
200 CLI binaries download links and checksums application/json CLI Download Links
Example Response Below
404 Not Found application/json 
{"message": "Not Found"}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/cli_instances/download_links
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "mac": {
        "version": "v1.10.2",
        "download_link": "https://setup.containers.carbonblack.io/cbctl/v1.10.2/darwin/cbctl",
        "md5_sum": "d6c257425dd403be0c097c7f54e6acad",
        "sha1_sum": "3a6d8b38ca135b77bf30a8564e16d9e60d21bee0",
        "sha256_sum": "ac9f1b220e116658b47f3349e93faab940d23b0d2c4651e3b746a02d6270efb5"
    },
    "linux": {
        "version": "v1.10.2",
        "download_link": "https://setup.containers.carbonblack.io/cbctl/v1.10.2/linux/cbctl",
        "md5_sum": "bfa9e95b6b5df4d1bcd32af7f6cd7907",
        "sha1_sum": "355d694bd2c36a04bfd3e758fdba997f3a70d396",
        "sha256_sum": "d4781d7b3597847e62d9e2f7d1713762d8083a2c380c277e1035ae4f0bcc8f1f"
    },
    "windows": {
        "version": "v1.11.0-rc2",
        "download_link": "https://setup.containers.carbonblack.io/cbctl/v1.11.0-rc2/windows/cbctl.exe",
        "md5_sum": "8b43dba65f910d6ae98b3d18a363f85b",
        "sha1_sum": "c793e84d6706bee92858b37f1aa35e2e252b0b28",
        "sha256_sum": "1161eedbfa3a0b4861e1c26e9fcd696593b32e4d91c616ed08bf56d90db2548b"
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get CLI Installation Command

Returns the CLI instance installation command.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/cli_instances/setup_command

Response Codes

Code Description Content-Type Content
200 CLI installation setup command application/json CLI Installation Command
Example Response Below
404 Not Found application/json 
{"message": "Not Found"}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/cli_instances/setup_command
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "command": "\nmkdir -p ~/.cbctl\ncat > ~/.cbctl/.cbctl.yaml <<EOF\nactive_user_profile: cbctl_default\ncbctl_default:\n  cb_api_id: $CONNECTOR_ID\n  cb_api_key: $API_KEY\n  org_key: $ORG_KEY\n  saas_url: $ENV_URL\n  default_build_step: $DEFAULT_BUILD_STEP\nEOF\n"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create Custom Resource

Generates a YAML definition for a Kubernetes Custom Resource for the Carbon Black Containers' CRD (as deployed by the Carbon Black Containers Operator installation). The Custom Resource definition will be hosted by CBC for some time and can be applied directly on the cluster via kubectl or similar tools.

Note: It is used and managed internally by the users browser.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security CREATE, READ, UPDATE, DELETE, EXECUTE Majority of environments

Request 
POST {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/kubernetes_resource_definitions

Request Body - application/json

{
  "domain": "<string>",
  "sensor_version": "<string>",
  "api_host": "<string>",
  "adapter_name": "<string>",
  "gateway_host": "<string>",
  "runtime_gateway_host": "<string>",
  "agent_components": "<object>",
  "cluster_labels": "<object>"
}

Body Schema

Field Definition Data Type Values
domain Cluster name and group String Example:
demo:demodomain
sensor_version The version of the sensor to deploy String Example:
2.0.0
api_host Hostname that the sensor agents use to access Carbon Black Cloud services String Example:
defense-prod06.cbdtest.io
adapter_name The adapter to use for Carbon Black Containers String Example:
containers
gateway_host* Hostname that the cluster should use to send data to Carbon Black Cloud String Example:
events.containers.carbonblack.io
runtime_gateway_host* Hostname that the cluster should use to send data to Carbon Black Cloud for Runtime detection String Example:
runtime.events.containers.carbonblack.io
agent_components Whether to enable runtime protection and cluster scanning on the cluster Object 
{
  "runtime_protection": <boolean>,
  "cluster_scanning": <boolean>
}
Default: true, true
cluster_labels A string-to-string dictionary that represent the desired labels for the cluster Object 
{
  "additionalProp1": "<string>",
  "additionalProp2": "<string>"
}

*When creating a custom resource, the gateway host and runtime gateway hosts must be configured for communication with Carbon Black Cloud. Use the values in the following table that match the Product URL you use to log into Carbon Black Cloud.

Carbon Black Cloud Product URL Hardening - gateway_host Runtime - runtime_gateway_host
eap01: https://defense-eap01.conferdeploy.net
prod01: https://dashboard.confer.net
prod02: https://defense.conferdeploy.net
prod05: https://defense-prod05.conferdeploy.net		 https://events.containers.carbonblack.io https://runtime.events.containers.carbonblack.io
prod06: https://defense-eu.conferdeploy.net https://events-eu.containers.carbonblack.io https://runtime.events-eu.containers.carbonblack.io
prodnrt: https://defense-prodnrt.conferdeploy.net https://events-prodnrt.containers.carbonblack.io https://runtime.events-prodnrt.containers.carbonblack.io
prodsyd: https://defense-prodsyd.conferdeploy.net https://events-prodsyd.containers.carbonblack.io https://runtime.events-prodsyd.containers.carbonblack.io

Response Codes

Code Description Content-Type Content
200 The generated Custom resource response application/json Custom Resource
Example Response Below
400 Some required data is missing from the request and a Custom Resource can’t be generated application/json Create Custom Resource Error 
{
  "error_code": "Bad Request",
  "message": "Error: Key: 'crData.Domain' Error:Field validation for 'Domain' failed on the 'required' tag"
}
404 Not Found application/json 
{"message": "Not Found"}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/kubernetes_resource_definitions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "sensor_version": "main",
    "domain": "demo:demodomain",
    "api_host": "defense-dev01.cbdtest.io",
    "adapter_name": "containers",
    "gateway_host": "events.myserver.dev.containers.mydomain.io",
    "runtime_gateway_host": "runtime.events.myserver.dev.containers.mydomain.io",
    "cluster_labels": {},
    "agent_components": {
        "runtime_protection": true,
        "cluster_scanning": true
    }
}
Response Body 
{
    "id": "cr-7d4e32c2-ae39-4a9a-8911-e50fa4d92c7f",
    "resource_yaml": "apiVersion: operator.containers.mydomain.io/v1\nkind: CBContainersAgent\nmetadata:\n  name: cbcontainers-agent\nspec:\n  account: ABCDE12345\n  clusterName: demo:demodomain\n  version: \"main\"\n  gateways:\n    apiGateway:\n      host: defense-dev01.cbdtest.io\n      adapter: containers\n    coreEventsGateway:\n      host: events.myserver.dev.containers.mydomain.io\n    hardeningEventsGateway:\n      host: events.myserver.dev.containers.mydomain.io\n    runtimeEventsGateway:\n      host: runtime.events.myserver.dev.containers.mydomain.io \n\n",
    "resource_url": "setup.test.containers.mydomain.io/cr-7d4e32c2-ae39-4a9a-8911-e50fa4d92c7f"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Check Status of a Custom Resource

Checks whether a Custom resource is still available on the Carbon black host location.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud kubernetes.security CREATE, READ, UPDATE, DELETE, EXECUTE Majority of environments

Request 
GET {cbc-hostname}/containers/v1/orgs/{org_key}/deploy/kubernetes_resource_definitions/{id}

Response Codes

Code Description Content-Type Content
200 The custom resource is still available in the original location and can be downloaded application/json Custom Resource
Example Response Below
404 The custom resource has been deleted. It can be regenerated to create another temporary hosted copy. application/json 
{"message": "The custom resource has been deleted. It can be regenerated to create another temporary hosted copy."}
500 Internal server error application/json 
{"message": "Internal server error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/deploy/kubernetes_resource_definitions/cr-7d4e32c2-ae39-4a9a-8911-e50fa4d92c7f
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "cr-7d4e32c2-ae39-4a9a-8911-e50fa4d92c7f",
    "resource_yaml": "apiVersion: operator.containers.mydomain.io/v1\nkind: CBContainersAgent\nmetadata:\n  name: cbcontainers-agent\nspec:\n  account: ABCDE12345\n  clusterName: demo:demodomain\n  version: \"main\"\n  gateways:\n    apiGateway:\n      host: defense-dev01.cbdtest.io\n      adapter: containers\n    coreEventsGateway:\n      host: events.myserver.dev.containers.mydomain.io\n    hardeningEventsGateway:\n      host: events.myserver.dev.containers.mydomain.io\n    runtimeEventsGateway:\n      host: runtime.events.myserver.dev.containers.mydomain.io \n\n",
    "resource_url": "setup.test.containers.mydomain.io/cr-7d4e32c2-ae39-4a9a-8911-e50fa4d92c7f"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Operator Installation Data

Field Definition Data Type Values
operator_url URL pointing to the latest operator YAML built for the most up-to-date Kubernetes version String
install_script_url URL pointing to a BASH shell script that automates the choice of Operator YAML based on the Kubernetes version String
install_script_bash_url URL pointing to a BASH shell script that automates the choice of Operator YAML based on the Kubernetes version String
install_script_powershell_url URL pointing to a Powershell shell script that automates the choice of Operator YAML based on the Kubernetes version String
operator_setup_data List of Operator YAML files based on their Kubernetes version support. Note that all Operator YAMLs bundle the same Operator version - the difference is in the internal object definition based on the cluster’s version. The helper scripts provided in this object are an alternative to implementing the logic to choose from this array on the client. The entry that supports the latest Kubernetes version will point to the same URL as operator_url. If the max_kubernetes_version is empty, then all Kubernetes versions up to the latest released are supported. The URL pointing to the actual YAML file can be used with “kubectl -f”. Array 
[
    {
        "min_kubernetes_version": "1.13",
        "max_kubernetes_version": "1.15",
        "url_to_yaml": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator-kubernetes-under-1-16.yaml"
    },
    {
        "min_kubernetes_version": "1.16",
        "max_kubernetes_version": "",
        "url_to_yaml": "setup.test.containers.carbonblack.io/v6.0.2-rc1/operator.yaml"
    }
]

Sensor Metadata

Field Definition Data Type Values
sensors List of available sensors, sorted from latest to oldest.

version: Sensor version
is_latest: Whether this is the latest released sensor version
supports_runtime: Whether the sensor supports the runtime protection feature
supports_cluster_scanning: Whether the sensor supports cluster scanning feature
supports_cluster_scanning_secrets: Whether the sensor supports secret detection in cluster scanning feature
supports_cndr: Whether the sensor supports CNDR feature. This is a temporaty field for ORGs with this feature flag enabled in the UI		 Array 
 [
    {
        "version": "<string>",
        "is_latest": <boolean>,
        "supports_runtime": <boolean>,
        "supports_cluster_scanning": <boolean>,
        "supports_cluster_scanning_secrets": <boolean>,
        "supports_cndr": <boolean>
    }
]

Compatibility Matrix

Field Definition Data Type Values
matrix Holds keys of operator versions and their respective agent compatibility Object Compatibility Entry

Example: 
{
    "matrix": {
        "6.0.0": {
            "min_agent": "2.10.0",
            "max_agent": "latest"
        },
        "6.0.1": {
            "min_agent": "2.10.0",
            "max_agent": "latest"
        }
    }
}

Compatibility Entry

Field Definition Data Type Values
min_agent The minimum agent version that can be managed by the current operator version String
max_agent The maximum agent version that can be managed by the current operator version String
Field Definition Data Type Values
mac CLI download links for OSX Object CLI Link Information
Example: 
"mac": {
    "version": "v1.10.2",
    "download_link": "https://setup.containers.carbonblack.io/cbctl/v1.10.2/darwin/cbctl",
    "md5_sum": "d6c257425dd403be0c097c7f54e6acad",
    "sha1_sum": "3a6d8b38ca135b77bf30a8564e16d9e60d21bee0",
    "sha256_sum": "ac9f1b220e116658b47f3349e93faab940d23b0d2c4651e3b746a02d6270efb5"
}
linux CLI download links for Linux Object CLI Link Information
Example: 
"linux": {
    "version": "v1.10.2",
    "download_link": "https://setup.containers.carbonblack.io/cbctl/v1.10.2/linux/cbctl",
    "md5_sum": "bfa9e95b6b5df4d1bcd32af7f6cd7907",
    "sha1_sum": "355d694bd2c36a04bfd3e758fdba997f3a70d396",
    "sha256_sum": "d4781d7b3597847e62d9e2f7d1713762d8083a2c380c277e1035ae4f0bcc8f1f"
}
windows CLI download links for Windows Object CLI Link Information
Example: 
"windows": {
    "version": "v1.11.0-rc2",
    "download_link": "https://setup.containers.carbonblack.io/cbctl/v1.11.0-rc2/windows/cbctl.exe",
    "md5_sum": "8b43dba65f910d6ae98b3d18a363f85b",
    "sha1_sum": "c793e84d6706bee92858b37f1aa35e2e252b0b28",
    "sha256_sum": "1161eedbfa3a0b4861e1c26e9fcd696593b32e4d91c616ed08bf56d90db2548b"
}
Field Definition Data Type Values
version CLI version String
download_link Download link String
md5_sum md5 sum of the CLI binary String
sha1_sum sha1 sum of the CLI binary String
sha256_sum sha256 sum of the CLI binary String

CLI Installation Command

Field Definition Data Type Values
command CLI Installation bash Command String

Custom Resource

Field Definition Data Type Values
resource_yaml Resource long description in yaml format String
resource_url A URL pointing to a hosted version of the Custom resource. This Custom resource is only hosted for a specific time before being deleted. String
id Name of the resource String

Create Custom Resource Error

Field Definition Data Type Values
error_code Code of the error occured String
message Description of the error and possible solutions String

Last modified on October 4, 2023