Account Analysis Overview API

Overview

These APIs provide summary metrics and visibility of trends over time of vulnerabilities in your environment.

The endpoints are designed to serve a dashboard or similar visualisation, and could also be used to programmatically detect anomalies.

This is an example of the Carbon Black Cloud dashboard the uses these APIs:

Example of Container Vulnerabilities dashboard from Carbon Black Cloud console

Example of Container Vulnerabilities Dashboard

Requirements

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

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/v1beta/orgs/{org_key}/inventory/overview/metadata
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/scan_status
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/fixes
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/new_vulnerabilities
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/vulnerabilities_history

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Workload Management > Scan workload image > workloads.container.image, allow permission to READ, CREATE

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

Use these endpoints to get summary metrics such as the number of new vulnerabilities or the scan status for specified clusters, namespaces and repositories.

Get Cluster, Namespace and Repository Lists

Get lists of Clusters, Namespaces and Repositories that are available for searching.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.container.image READ Majority of environments

Request 
GET {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/metadata


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json See example response below
400 The server cannot or will not process the request application/json 
{"message":"Request could not be processed."}
401 User is not authorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}

Examples

Request 
GET https://defense.conferdeploy.netcontainers/v1beta/orgs/ABCD1234/inventory/overview/metadata
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "clusters": [
        "demo:cluster-one",
        "test:testing-cluster-one"
    ],
    "namespaces": [
        "demo-namespace",
        "testing-namespace"
    ],
    "repositories": [
        "demoartifactory/cluster-scanner",
        "demoartifactory/guardrails-enforcer"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Scan Status

Search for the scan status and get metrics about deployed images.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.container.image READ Majority of environments

Request 
POST {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/scan_status


Request Body - application/json

{
  "criteria": {
    "clusters": [
      "<string>"
    ],
    "namespaces": [
      "<string>"
    ],
    "repositories": [
      "<string>"
    ]
  }
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Image Overview Criteria See example below


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json Possible Scan Status':
SCANNED
NOT_SCANNED
SCANNING
SCAN_FAILED
PENDING_SCAN
SCAN_ABORTED
See example response below
400 The server cannot or will not process the request application/json 
{"message":"Request could not be processed."}
401 User is not authorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1beta/orgs/ABCD1234/inventory/overview/scan_status
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "clusters": [
        "demo:cluster-one",
        "test:testing-cluster-one"
    ],
    "namespaces": [
        "demo-namespace",
        "testing-namespace"
    ],
    "repositories": [
        "demoartifactory/cluster-scanner",
        "demoartifactory/guardrails-enforcer"
    ]
}
Response Body 
{
    "NOT_SCANNED": 14,
    "SCANNED": 72,
    "SCAN_FAILED": 1
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Fixes

Search specified clusters, namespaces and repositories and for every severity, return metrics on how many deployed images have a fix available.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.container.image READ Majority of environments

Request 
POST {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/fixes


Request Body - application/json

{
  "criteria": {
    "clusters": [
      "<string>"
    ],
    "namespaces": [
      "<string>"
    ],
    "repositories": [
      "<string>"
    ]
  }
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Image Overview Criteria See example below


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json Possible vulnerability severities:
CRITICAL
HIGH
MEDIUM
LOW
UNKNOWN
See example response below
400 The server cannot or will not process the request application/json 
{"message":"Request could not be processed."}
401 User is not authorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1beta/orgs/ABCD1234/inventory/overview/fixes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "clusters": [
        "demo:cluster-one",
        "test:testing-cluster-one"
    ],
    "namespaces": [
        "demo-namespace",
        "testing-namespace"
    ],
    "repositories": [
        "demoartifactory/cluster-scanner",
        "demoartifactory/guardrails-enforcer"
    ]
}
Response Body 
{
    "CRITICAL": 48,
    "HIGH": 53,
    "LOW": 40,
    "MEDIUM": 50,
    "UNKNOWN": 5
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search New Vulnerabilities

New vulnerabilities found in the last 24 hours of the deployed images.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.container.image READ Majority of environments

Request 
POST {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/new_vulnerabilities


Request Body - application/json

{
  "criteria": {
    "clusters": [
      "<string>"
    ],
    "namespaces": [
      "<string>"
    ],
    "repositories": [
      "<string>"
    ]
  }
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Image Overview Criteria See example below


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json Possible vulnerability severities:
CRITICAL
HIGH
MEDIUM
LOW
UNKNOWN
See example response below
400 The server cannot or will not process the request application/json 
{"message":"Request could not be processed."}
401 User is not authorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1beta/orgs/ABCD1234/inventory/overview/new_vulnerabilities
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "clusters": [
        "demo:cluster-one",
        "test:testing-cluster-one"
    ],
    "namespaces": [
        "demo-namespace",
        "testing-namespace"
    ],
    "repositories": [
        "demoartifactory/cluster-scanner",
        "demoartifactory/guardrails-enforcer"
    ]
}
Response Body 
{
    "CRITICAL": 10,
    "HIGH": 5,
    "LOW": 4,
    "MEDIUM": 10,
    "UNKNOWN": 2
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Vulnerabilities Over Time

Search for the number of the vulnerabilities found in the deployed images over the specified time range.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.container.image READ Majority of environments

Request 
POST {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/overview/vulnerabilities_history


Request Body - application/json

{
    "criteria": {
        "time": {
            "range": "<string>",
            "start": "<string>",
            "end": "<string>"
        },
        "clusters": [
            "<string>"
        ]
    }
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. History Criteria See example below


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json See example response below
400 The server cannot or will not process the request application/json 
{"message":"Request could not be processed."}
401 User is not authorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1beta/orgs/ABCD1234/inventory/overview/vulnerabilities_history
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "criteria": {
        "time": {
            "range": "-3d"
        },
        "clusters": [
            "demo:cluster-one"
        ]
    }
}
Response Body 
{
    "2023-04-29T10:00:07.596Z": {
        "CRITICAL": 9,
        "HIGH": 37,
        "LOW": 51,
        "MEDIUM": 36,
        "UNKNOWN": 1
    },
    "2023-04-30T10:00:04.419Z": {
        "CRITICAL": 11,
        "HIGH": 40,
        "LOW": 60,
        "MEDIUM": 56,
        "UNKNOWN": 13
    },
    "2023-05-01T10:00:10.253Z": {
        "CRITICAL": 13,
        "HIGH": 56,
        "LOW": 77,
        "MEDIUM": 76,
        "UNKNOWN": 32
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Criteria - History

Field Definition Data Type Values
time REQUIRED TimeSearchRequest time filter N/A
clusters Set of node machines for running containerized applications [ string ] Example: [ “mydemocluster” ]

Criteria - Image Overview

Field Definition Data Type Values
clusters Set of node machines for running containerized applications [ string ] Example: [ “mydemocluster” ]
namespaces ID that provides a mechanism for isolating groups of resources within a single cluster [ string ] Example: [ “kube-system” ]
repositories The repository where the image is stored [ string ] Example: [ “demo/demorepo” ]

Time Filter

Either range or both start and end are required.

Field Definition Data Type Values
range Relative time range for the request (defined below) string Example: “-2w”
start The earlier bound of the time range. Requires end and must be a timestamp before end. ISO 8601 Date String Example: “2023-04-01T00:00:00.000Z”
end The later bound of the time range. Requires start and must be a timestamp after start. ISO 8601 Date String Example: “2023-04-03T00:00:00.000Z”

The format of range is - where quantity is an integer, and units is one of:

  • M: month(s)
  • w: week(s)
  • d: day(s)
  • h: hour(s)
  • m: minute(s)
  • s: second(s)

Last modified on July 28, 2023