Vulnerabilities API


Overview

Vulnerability scanning helps detect known vulnerabilities to reduce the risk of security breaches. Reduces the attack surface of a containerized application.

Use these APIs to get statistics for vulnerabilities in your environment.

Use Cases

  • Search for vulnerabilities using the CVE to find affected clusters, images and workloads.

Requirements

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

Key Features

  • Search for vulnerabilities and the workloads that are affected
  • Get summary metrics about your environment using the Vulnerability Summary endpoints

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}/vulnerabilities
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/vulnerabilities/org_summary
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/vulnerabilities/_search
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/workloads/_search

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

The container vulnerabilities APIs can be used to search for information about specific CVEs, and to get information about images and workloads that are affected by vulnerabilities.

Get CVE

Return data about specific CVE.


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}/vulnerabilities

Query Parameters

Parameter Description Values Default
cve REQUIRED The CVE ID Example: “ALAS-2021-1722” No default
package REQUIRED The CVE package Example: “nspr” No default
type REQUIRED The type of CVE dpkg, APKG, java, python, rpm, npm, go No default


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json See example response below

See field definitions for Vulnerability, CVSS v2 and CVSS v3 objects 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.net/containers/v1beta/orgs/ABCD1234/vulnerabilities?cve=ALAS-2021-1722&package=nspr&type=rpm
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body
{
    "id": "ALAS-2021-1722",
    "package": "nspr",
    "package_name": "nspr",
    "package_type": "rpm",
    "package_version": "4.21.0-1.amzn2.0.2",
    "severity": "CRITICAL",
    "fix_available": "4.32.0-1.amzn2",
    "cve_key": "ALAS-2021-1722-nspr-rpm",
    "description": "NSS (Network Security Services) versions prior to 3.73 or 3.68.1 ESR are vulnerable to a heap overflow when handling DER-encoded DSA or RSA-PSS signatures. Applications using NSS for handling signatures encoded within CMS, S/MIME, PKCS \\#7, or PKCS \\#12 are likely to be impacted. Applications using NSS for certificate validation or other TLS, X.509, OCSP or CRL functionality may be impacted, depending on how they configure NSS. *Note: This vulnerability does NOT impact Mozilla Firefox.* However, email clients and PDF viewers that use NSS for signature verification, such as Thunderbird, LibreOffice, Evolution and Evince are believed to be impacted. This vulnerability affects NSS < 3.73 and NSS < 3.68.1.",
    "link": "https://alas.aws.amazon.com/AL2/ALAS-2021-1722.html",
    "cvss_v2": {
        "access_complexity": "LOW",
        "access_vector": "NETWORK",
        "authentication": "NONE",
        "availability_impact": "PARTIAL",
        "confidentiality_impact": "PARTIAL",
        "integrity_impact": "PARTIAL",
        "vector_string": "AV:N/AC:L/Au:N/C:P/I:P/A:P",
        "base_score": 7.5,
        "exploitability_score": 10,
        "impact_score": 6.4
    },
    "cvss_v3": {
        "version": "3.1",
        "attack_complexity": "LOW",
        "attack_vector": "NETWORK",
        "privileges_required": "NONE",
        "scope": "UNCHANGED",
        "user_interaction": "NONE",
        "availability_impact": "HIGH",
        "confidentiality_impact": "HIGH",
        "integrity_impact": "HIGH",
        "vector_string": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
        "base_score": 9.8,
        "exploitability_score": 3.9,
        "impact_score": 5.9
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Vulnerability Summary

Return summary of scanned images and vulnerabilities by risk level.


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}/vulnerabilities/org_summary

Query Parameters

Parameter Description Values Default
running_in_k8s Show only results that are relevant for deployed images. true, false all
is_running Whether to return results only for images that are running. true, false all


Response Codes

Code Description Content-Type Content
200 The search completed successfully. application/json Summary Results
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.net/{instance}/v1beta/orgs/ABCD1234/vulnerabilities/org_summary?running_in_k8s=true&is_running=false
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body
{
     "severity_summary": {
         "CRITICAL": {
             "vulnerabilities": 390,
             "images": 172
         },
         "HIGH": {
             "vulnerabilities": 2061,
             "images": 217
         },
         "LOW": {
             "vulnerabilities": 4130,
             "images": 174
         },
         "MEDIUM": {
             "vulnerabilities": 3289,
             "images": 195
         },
         "UNKNOWN": {
             "vulnerabilities": 109,
             "images": 60
         }
     },
     "images": 263,
     "vulnerabilities": 9979
 }
To download or review the Carbon Black Cloud Postman collection, click here.


Search Vulnerabilities

Search for vulnerabilities that meet the search criteria for information about the vulnerability and affected 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}/vulnerabilities/_search


Request Body - application/json

{
    "criteria": {
        "workloads": [
            {
                "cluster": "<string>",
                "kind": "<string>",
                "name": "<string>",
                "namespace": "<string>"
            }
        ],
        "severity": [
            "<string>"
        ],
        "is_running": <boolean>,
        "digests": [
            "<string>"
        ]
    },
    "query": "<string>",
    "start": <integer>,
    "rows": <integer>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        }
    ]
}


Body Schema

Field Definition Data Type Values
query Search query for simple text matching. String N/A
start First row to use for pagination Long Default: 0
rows Number of rows to request, can be paginated Long Default: 20
Max: 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array
[{
  "field": "<string>",
  "order": "<string>"
}]
order supports ASC or DESC
criteria Criteria is an object that represents values that must be in the results. Vulnerability Criteria


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/vulnerabilities/_search
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body
{
    "criteria": {
        "workloads": [
            {
                "cluster": "demo:democluster",
                "kind": "DaemonSet",
                "name": "aws-node",
                "namespace": "kube-system"
            }
        ],
        "severity": [
            "LOW"
        ],
        "digests": [
            "sha256:1abcd23e645f6789gh228e8d5f9cea9311a12b0b7d884b9e1dc7665aad83047b"
        ],
        "is_running": false
    },
    "query": "",
    "start": 0,
    "rows": 1,
    "sort": [
        {
            "field": "vulnerabilities",
            "order": "DESC"
        }
    ]
}
Response Body
{
    "num_found": 7,
    "results": [
        {
            "id": "ALAS-2021-1652",
            "package": "bzip2-libs",
            "package_name": "bzip2-libs",
            "package_type": "rpm",
            "package_version": "1.0.6-13.amzn2.0.2",
            "severity": "LOW",
            "fix_available": "1.0.6-13.amzn2.0.3",
            "cve_key": "",
            "is_exception": false,
            "cvss": {
                "v2": 7.5,
                "v3": 9.8
            },
            "layer_digest": "",
            "locations": null,
            "description": "BZ2_decompress in decompress.c in bzip2 through 1.0.6 has an out-of-bounds write when there are many selectors.",
            "link": "https://alas.aws.amazon.com/AL2/ALAS-2021-1652.html",
            "risk": 3,
            "nvd_data": {
                "cvss_v2": {
                    "access_complexity": "LOW",
                    "access_vector": "NETWORK",
                    "authentication": "NONE",
                    "availability_impact": "PARTIAL",
                    "confidentiality_impact": "PARTIAL",
                    "integrity_impact": "PARTIAL",
                    "vector_string": "AV:N/AC:L/Au:N/C:P/I:P/A:P",
                    "base_score": 7.5,
                    "exploitability_score": 10,
                    "impact_score": 6.4
                },
                "cvss_v3": {
                    "version": "3.1",
                    "attack_complexity": "LOW",
                    "attack_vector": "NETWORK",
                    "privileges_required": "NONE",
                    "scope": "UNCHANGED",
                    "user_interaction": "NONE",
                    "availability_impact": "HIGH",
                    "confidentiality_impact": "HIGH",
                    "integrity_impact": "HIGH",
                    "vector_string": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
                    "base_score": 9.8,
                    "exploitability_score": 3.9,
                    "impact_score": 5.9
                }
            },
            "image_count": 1,
            "workload_count": 1,
            "affected_images": [
                {
                    "manifest_digest": "sha256:1abcd23e645f6789gh228e8d5f9cea9311a12b0b7d884b9e1dc7665aad83047b",
                    "full_tag": "123456789098.my.demo.server.demoorg.com/demo-k8s:v1.1.1-releasedemo.1"
                }
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Workloads for Vulnerability

Search for workloads with specific vulnerabilities.

API Permissions Required

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

Request
POST {cbc-hostname}/containers/v1beta/orgs/{org_key}/workloads/_search


Request Body - application/json

{
    "criteria": {
        "cves": [
            {
                "cve": "<string>",
                "package": "<string>",
                "type": "<string>"
            }
        ],
        "images": [
            "<string>"
        ]
    },
    "query": "<string>",
    "start": <integer>,
    "rows": <integer>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        }
    ]
}


Body Schema

Field Definition Data Type Values
query Search query for simple text matching. String N/A
start First row to use for pagination Long Default: 0
rows Number of rows to request, can be paginated Long Default: 20
Max: 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array
[{
  "field": "<string>",
  "order": "<string>"
}]
order supports ASC or DESC
criteria Criteria is an object that represents values that must be in the results. Image Criteria


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/workloads/_search
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body
{
    "criteria": {
        "cves": [
            {
                "cve": "ALAS-2021-1722",
                "package": "nspr",
                "type": "rpm"
            }
        ]
    },
    "query": "",
    "start": 0,
    "rows": 20,
    "sort": [
        {
            "field": "vulnerabilities",
            "order": "DESC"
        }
    ]
}
Response Body
{
    "num_found": 1,
    "results": [
        {
            "cluster": "testcluster",
            "container_images": [
                {
                    "full_tag": "fulltag/demo.container",
                    "manifest_digest": "sha256:1234asdfrtyu876543fb228e8d5f9cea9311a12b0b7d884b9e1dc7665aad83047b",
                    "registry": "123456789123.demo.org.host.company.com",
                    "repo": "demo-repo",
                    "repo_digests": [
                        ""
                    ],
                    "tag": "v1.2.3-demobuild.1"
                }
            ],
            "enforcements": 0,
            "kind": "DaemonSet",
            "name": "aws-node",
            "namespace": "kube-system",
            "policy": {
                "name": "demo policy",
                "policy_id": "1a2b3456-ce51-4569-94a1-defa909e1615"
            },
            "risk": {
                "score": 9,
                "severity": "high"
            },
            "scopes": [
                {
                    "policy_id": "1a2b3456-ce51-4569-94a1-defa909e1615",
                    "policy_name": "demo policy",
                    "scope_id": "9876543a-a607-4377-8ca3-d1020ad8fb85",
                    "scope_name": "demo-scope"
                },
            ],
            "violations": 0
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Vulnerability Exceptions Management

Search for CVE Exceptions

Get metadata about CVE Exceptions

API Permissions Required

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

Request
POST {cbc-hostname}/containers/v1beta/orgs/{org_key}/vulnerability_exceptions/cve/_search


Request Body - application/json

{
  "criteria": {
     "cve": "<string>",
     "package":"<string>",
     "type": "<string>"
    },
  "query": "<string>",
  "start": <integer>,
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    },
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
query Search query for simple text matching. String N/A
start First row to use for pagination Long Default: 0
rows Number of rows to request, can be paginated Long Default: 20
Max: 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array
[{
  "field": "<string>",
  "order": "<string>"
}]
order supports ASC or DESC
criteria List of CVEs to filter by [ CVE ]
{
  "cve": "<string>",
  "package": "<string>",
  "type": "<string>"
}


Response Codes

Code Description Content-Type Content
200 Get the cve exceptions metadata 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/vulnerability_exceptions/cve/_search
Request Headers
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body
{
    "criteria": {
        "cve": "CVE-2010-0834",
        "package":"base-files",
        "type": "deb"
    },
    "query": "",
    "start": 0,
    "rows": 1,
    "sort": [
        {
            "field": "vulnerabilities",
            "order": "DESC"
        }
    ]
}
Response Body
{
    "num_found": 2,
    "results": [
        {
            "full_tag": "123456789098.my.demo.server.demoorg.com/demo-k8s:v1.1.1-releasedemo.1",
            "registry": "demoregistry.io",
            "repo": "demorepo/kube-rbac-proxy",
            "workloads_count": 1,
            "created_by": "demnouser@demoorg.com",
            "created_at": "2023-05-14T19:34:00.599Z",
            "comments": "Setting CVE Exception for Demo"
        }
    ]
}
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

Field Definition Data Type Values
cves List of CVEs to filter by [ CVE ] Example:
[
    {
        "cve": "ALAS-2021-1722",
        "package": "nspr",
        "type": "rpm"
    }
] 
images List of images to filter by [ string ] Example:
["fulltag/demo.container"] 

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” ]

Criteria - Vulnerability

Field Definition Data Type Values
workloads Schema:
  [
    {
        "cluster": "<string>",
        "kind": "<string>",
        "name": "<string>",
        "namespace": "<string>"
    }
] 
Example:
  [
    {
        "cluster": "demo:cluster01",
        "kind": "DaemonSet",
        "name": "demo-node",
        "namespace": "demo-system"
    }
] 
severity [ string ] **Example:**
 ["LOW"] 
is_running Set to true to show only values of images that are running. Show all images when set to false boolean Example: true
default: false
digests Digest of the image manifest. Only available for scanned images. [ string ] Example: [“sha256:8cba89a89aaa8445c9d385962cd915ae2e237e38f874ff90c5afbcc31a854a99”]

CVE

Field Definition Data Type Values
cve Identifier of the CVE string Example: “CVE-2020-12345”
package Name of the CVE package string Example: “libzstd1-1.3.8+dfsg-3”
type The CVE package type string Valid values: dpkg, APKG, java, python, rpm, npm, go

CVSS V2 Score

Common Vulnerability Scoring System (CVSS) version 2.x score as per the guide by First.

Field Definition Data Type Values
access_complexity Metric that measures the complexity of the attack required to exploit the vulnerability once an attacker has gained access to the target system. string HIGH, MEDIUM, LOW
access_vector Reflects how the vulnerability is exploited. string Local, Adjacent Network, Network
authentication Measures the number of times an attacker must authenticate to a target in order to exploit a vulnerability string Multiple, Single, None
availability_impact Measures the impact to availability of a successfully exploited vulnerability string None, Partial, Complete
confidentiality_impact Measures the impact on confidentiality of a successfully exploited vulnerability string None, Partial, Complete
integrity_impact Measures the impact to integrity of a successfully exploited vulnerability. string None, Partial, Complete
vector_string Each metric in the vector consists of the abbreviated metric name, followed by a “:” (colon), then the abbreviated metric value. string None, Partial, Complete
base_score Initial calculation using the base equation integer Example:“AV:L/AC:M/Au:N/C:N/I:P/A:C.”
exploitability_score This metric measures the current state of exploit techniques or code availability. integer Example: “10”
impact_score integer Example:“6.4”

CVSS V3 Score

Common Vulnerability Scoring System (CVSS) version 3.x score as per the guide by First.

Field Definition Data Type Values
version CVSS Version integer Example: “3.1”
attack_complexity Measures complexity that arrises from any software, hardware, or networking condition beyond the attacker’s control that must exist or occur in order for the vulnerability to be successfully exploited string HIGH, LOW
attack_vector Generally reflects the “remoteness” of the attacker relative to the vulnerable component. That is, the more remote an attacker is to the vulnerable component (in terms of logical and physical network distance), the greater the Base score will be. string Local, Adjacent, Network, Physical
privileges_required Captures the level of access required for a successful attack string HIGH, LOW, NONE
scope Captures whether a vulnerability in one vulnerable component impacts resources in components beyond its security scope. string Unchanged, Changed
user_interaction Captures the requirement for a human user, other than the attacker, to participate in the successful compromise of the vulnerable component. string None, Required
availability_impact Measures the impact to the availability of the impacted component resulting from a successfully exploited vulnerability. string High1, Low, None
confidentiality_impact Measures the impact to the confidentiality of the information resources managed by a software component due to a successfully exploited vulnerability. string High1, Low, None
integrity_impact Measures the impact to integrity of a successfully exploited vulnerability. Integrity refers to the trustworthiness and veracity of information. string High, Low, None
vector_string A text representation of a set of CVSS metrics. It is commonly used to record or transfer CVSS metric information in a concise form. string Example: “CVSS:3.1/AV:N/AC:L/PR:H/UI:N/S:U/C:L/I:L/A:N”
base_score Calculated using a formula that depends on sub-formulas for Impact Sub-Score (ISS), Impact, and Exploitability. integer Example:“9.8”
exploitability_score Reflects the characteristics of the thing that is vulnerable, which we refer to formally as the vulnerable component. integer Example:“3.9”
impact_score Captures the effects of a successfully exploited vulnerability on the component that suffers the worst outcome that is most directly and predictably associated with the attack. integer Example:“5.9”

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)

Summary Results

Field Definition Data Type Values
images Number of images found. integer
vulnerabilities Number of vulnerabilities found. integer
severity_summary Number of images and vulnerabilities grouped by severity.
[
    "<string>": {
          "images": <integer>,
          "vulnerabilities": <integer>,
    }
]
Example:
 [
  "CRITICAL": {
      "images": 392,
      "vulnerabilities": 173
  }
]

Vulnerability

Field Definition Data Type Values
id CVE Id of the vulnerability string Example: “ALAS-2021-1722”
package Name of package string Example: “nspr”
package_name Name of the package that contains the CVE. string Example: “perl-base”
package_type string Example: “rpm”
package_version The version of the package that contains the CVE. string Example: “1.3.2”
fix_available Version of the package that updating to that version will fix the exposures. string Example: “1.3.4”
cve_key Uniqe key made from the {CveId}-{CvePackage}-{CveType}. string Example: “CVE-2016-2781-coreutils-8.30-3ubuntu2-dpkg”
is_exception Whether the CVE is marked by the user to be an exception. boolean Example: “false”
cvss.v2 Common Vulnerability Scoring System (CVSS) version 2.x score as per the guide by First. integer Example: 5
cvss.v3 Common Vulnerability Scoring System (CVSS) version 3.x score as per the guide by First. integer Example: 7.5

Last modified on July 28, 2023