Image Analysis Inventory API

Overview

Get lists of Clusters, Namespaces and Repositories that are part of the monitored container environment.

Use Cases

  • Get information about Container inventory

Requirements

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

Key Features

  • Get summary information of all items being monitored including Clusters, Namespaces and Repositories
  • Search for items matching specified criteria

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/repositories/_search
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/images/_search
  • {cbc-hostname}/containers/v1beta/orgs/{org_key}/inventory/images/_facet

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

Search Repositories

Search for repositories and their metadata.

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/repositories/_search


Request Body - application/json

{
  "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

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/repositories/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "proxy",
    "start": 0,
    "rows": 1,
    "sort": [
        {
            "field": "last_scanned",
            "order": "DESC"
        }
    ]
}
Response Body 
{
    "num_found": 15,
    "results": [
        {
            "repo": "kube-proxy-amd64",
            "registry": "my.demo.repo",
            "all_tags": 4,
            "scanned_tags": 3,
            "last_scan_time": "2023-05-01T11:38:17Z"
        }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Images

Search for images that match specified criteria


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/images/_search


Request Body - application/json

{
    "query": "<string>",
    "start": <integer>,
    "rows": <integer>,
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "criteria": {
        "workloads": [
            {
                "cluster": "<string>",
                "kind": "<string>",
                "name": "<string>",
                "namespace": "<string>"
            }
        ],
        "vulnerabilities": [
            "<string>"
        ],
        "fixes": [
            "<string>"
        ],
        "scan_status": [
            "<string>"
        ],
        "clusters": [
            "<string>"
        ],
        "namespaces": [
            "<string>"
        ],
        "cves": [
            {
                "cve": "<string>",
                "package": "<string>",
                "type": "<string>"
            }
        ],
        "registries": [
            "<string>"
        ],
        "repositories": [
            "<string>"
        ],
        "is_running": <boolean>
    }
}


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/inventory/images/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "",
    "start": 0,
    "rows": 1,
    "sort": [
        {
            "field": "vulnerabilities",
            "order": "DESC"
        }
    ],
    "criteria": {
        "is_running": true,
        "vulnerabilities":["CRITICAL"],
        "repositories":["demoartifactory/guardrails-enforcer"]
    }
}
Response Body 
{
    "num_found": 2,
    "results": [
        {
            "full_tag": "docker.io/demoartifactory/guardrails-enforcer:1.2.3-rc1",
            "registry": "docker.io",
            "repo": "demoartifactory/guardrails-enforcer",
            "tag": "2.3.0-rc3",
            "manifest_digest": "sha256:a12b34c56789b674f5d011d8ddb82aa4f04434e083ac9de4b07b632c1cec594f",
            "repo_digests": [],
            "scan_time": "2023-01-17T12:44:18Z",
            "last_scan_time": "2023-01-17T12:44:18Z",
            "vulnerabilities_summary": {
                "CRITICAL": {
                    "amount": 1,
                    "fixes": 1
                },
                "HIGH": {
                    "amount": 4,
                    "fixes": 3
                },
                "LOW": {
                    "amount": 50,
                    "fixes": 33
                },
                "MEDIUM": {
                    "amount": 26,
                    "fixes": 24
                }
            },
            "fixes_available": 61,
            "scan_status": "SCANNED",
            "kubernetes_summary": {
                "clusters": 1,
                "deployments": 1,
                "namespaces": 1,
                "workloads": 1
            },
            "workloads_count": 1,
            "exceptions": 0,
            "can_rescan_image": true,
            "error_type": "",
            "has_malware": false
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Image Facets

Get facets that can be used to guide searches of 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/images/_facet


Request Body - application/json

{
    "query": "<string>",
    "terms": {
        "fields": [
            "<string>"
        ]
    },
    "criteria": {
        "workloads": [
            {
                "cluster": "<string>",
                "kind": "<string>",
                "name": "<string>",
                "namespace": "<string>"
            }
        ],
        "vulnerabilities": [
            "<string>"
        ],
        "fixes": [
            "<string>"
        ],
        "scan_status": [
            "<string>"
        ],
        "clusters": [
            "<string>"
        ],
        "namespaces": [
            "<string>",
            "<string>"
        ],
        "cves": [
            {
                "cve": "<string>",
                "package": "<string>",
                "type": "<string>"
            }
        ],
        "registries": [
            "<string>"
        ],
        "repositories": [
            "<string>"
        ],
        "is_running": <boolean>
    }
}


Body Schema

Field Definition Data Type Values
query Search query for simple text matching. String N/A
terms The fields to be inclued as a facet in the result. 
{
    "fields": [
        "<string>"
    ]
}
 Valid values:
fixes
scan_status
vulnerabilities
clusters
namespaces
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/inventory/images/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "",
    "criteria": {
        "is_running": true
    },
    "terms": {
        "fields": [
            "scan_status",
            "reputations",
            "vulnerabilities",
            "fixes",
            "namespaces",
            "clusters",
            "repositories"
        ],
        "rows": 50
    }
}
Response Body 
{
    "terms": [
        {
            "field": "scan_status",
            "values": [
                {
                    "name": "SCANNED",
                    "total": 72
                },
                {
                    "name": "SCAN_FAILED",
                    "total": 1
                },
                {
                    "name": "NOT_SCANNED",
                    "total": 14
                }
            ]
        },
        {
            "field": "fixes",
            "values": [
                {
                    "name": "AVAILABLE_FIXES",
                    "total": 65
                },
                {
                    "name": "NO_FIXES_AVAILABLE",
                    "total": 6
                }
            ]
        },
        {
            "field": "clusters",
            "values": [
                {
                    "name": "demo:cluster-one",
                    "total": 60
                },
                {
                    "name": "test:testing-cluster-one",
                    "total": 36
                }
            ]
        },
        {
            "field": "namespaces",
            "values": [
                {
                    "name": "demo-namespace",
                    "total": 14
                },
                {
                    "name": "testing-namespace",
                    "total": 3
                }
            ]
        },
        {
            "field": "reputations",
            "values": []
        },
        {
            "field": "repositories",
            "values": [
                {
                    "name": "demoartifactory/cluster-scanner",
                    "total": 1
                }
            ]
        },
        {
            "field": "vulnerabilities",
            "values": [
                {
                    "name": "CRITICAL",
                    "total": 53
                },
                {
                    "name": "HIGH",
                    "total": 58
                },
                {
                    "name": "MEDIUM",
                    "total": 55
                },
                {
                    "name": "LOW",
                    "total": 52
                },
                {
                    "name": "UNKNOWN",
                    "total": 12
                },
                {
                    "name": "NO_VULNERABILITIES",
                    "total": 3
                }
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

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

Image Criteria

Field Definition Data Type Values
workloads Identifier of a K8s wlrkload [string] Example: “kafka”
vulnerabilities Score calculated using the risk evaluation system. [string] Example: [ CRITICAL]
Valid values:
CRITICAL
HIGH
MEDIUM
LOW

fixes Whether a fix is available for the risk [string] Example: [ AVAILABLE_FIXES]
Valid values:
AVAILABLE_FIXES
NO_FIXES_AVAILABLE
scan_status The status of last scan [string] Example: [SCANNED]
Valid values:
SCANNED
NOT_SCANNED
SCANNING
SCAN_FAILED
PENDING_SCAN
SCAN_ABORTED
clusters Set of node machines for running containerized applications [string] [“democluster”]
namespaces ID that provides a mechanism for isolating groups of resources within a single cluster [string] Example: [“kube-system”]
cves Object that identicies CVEs (Common Vulnerabilities and Exposures) [ CVE ] N/A
registries The docker registry the image was pulled from. [string] Example: [“docker.io”]
repositories The repository images are stored in [string] Example: [“demo/demo-server”]
is_running Set to true to show only values of images that are running. Show all images when set to false boolean Example: true

Last modified on July 28, 2023