Scan Logs API

Overview

Use these APIs to get information about when scans were preformed, their source and risk summary. They return historical information showing all scans results for the specified period.

Use Cases

  • Get information about when repositories were scanned
  • Search results of scans

Requirements

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

Key Features

  • Get a list of clusters and namespaces available for scanning
  • Search repository metadata
  • Search scan logs

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}/{instance}/v1beta/orgs/{org_key}/inventory/scan_logs/metadata
  • {cbc-hostname}/{instance}/v1beta/orgs/{org_key}/inventory/scan_logs/_search
  • {cbc-hostname}/{instance}/v1beta/orgs/{org_key}/inventory/scan_logs/_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

Endpoints in this section search scan logs.

Get Clusters and Namespaces

Get lists of possible clusters and namespaces to use in the search criteria for Scan Logs.


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/scan_logs/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.net/containers/v1beta/orgs/ABCD1234/inventory/scan_logs/metadata
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "clusters": [
        "demo:cluster-one",
        "test:testing-cluster-one"
    ],
    "namespaces": [
        "demo-namespace",
        "testing-namespace"
    ],
     "hostnames": [
         "demo-hostname",
         "testing-hostname"
     ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Scan Logs

Search for scan logs that match the 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/scan_logs/_search


Request Body - application/json

{
    "query": "<string>",
    "criteria": {
        "scan_time": {
            "range": "<string>",
            "start": "<string>",
            "end": "<string>"
        },
        "full_tags": [
            "<string>"
        ],
        "repositories": [
            "<string>"
        ],
        "digests": [
            "<string>"
        ],
        "sources": [
            "<string>"
        ],
        "registries": [
            "<string>"
        ],
        "vulnerabilities": [
            "<string>"
        ],
        "clusters": [
            "<string>"
        ],
        "namespaces": [
            "<string>"
        ],
        "hostnames": [
            "<string>"
        ]
    },
    "start": <integer>,
    "rows": <integer>,
    "sort": [
        {
          "field": "<string>",
          "order": "<string>"
        }
      ]
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. criteria See schema above
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/{instance}/v1beta/orgs/ABCD1234/inventory/scan_logs/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "scan_time": {
      "range": "-3h",
      "start": "2021-08-30T00:00:00Z",
      "end": "2021-09-3T00:00:00Z"
    },
    "full_tags": ["docker.io/ealen/echo-server:0.4.2"],
    "repositories": ["demo/demo-server"],
    "digests": ["sha256:8cba89a89aaa8445c9d385962cd915ae2e237e38f874ff90c5afbcc31a854a99"],
    "sources": ["CLI"],
    "registries": ["docker.io"],
    "vulnerabilities": ["HIGH"],
    "clusters": ["production"],
    "namespaces": ["kube-system"],
    "hostnames": ["demo-hostname"]
  }
}
Response Body 
{
    "num_found": 1,
    "results": [
        {
            "full_tag": "demo.io/demo-samples/microservices-demo/myservice:v0.1.2",
            "manifest_digest": "sha256:1abc234d56ef7dda66d924651df9ea89831cd8b04f2a02d412d2f3b0a92e1a7b",
            "workloads": 2,
            "scan_time": "2023-04-05T08:03:13Z",
            "source": "CLUSTER_SCAN",
            "vulnerabilities_summary": {
                "HIGH": {
                    "amount": 17
                },
                "MEDIUM": {
                    "amount": 10
                }
            },
            "has_malware": false
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Scan Log Facets

Get facets that can be used to guide searches of scan logs.

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/scan_logs/_facet


Request Body - application/json

{
    "query": "<string>",
    "criteria": {
        "scan_time": {
            "range": "<string>",
            "start": "<string>",
            "end": "<string>"
        },
        "full_tags": [
            "<string>"
        ],
        "repositories": [
            "<string>"
        ],
        "digests": [
            "<string>"
        ],
        "sources": [
            "<string>"
        ],
        "registries": [
            "<string>"
        ],
        "vulnerabilities": [
            "<string>"
        ],
        "clusters": [
            "<string>"
        ],
        "namespaces": [
            "<string>"
        ],
        "hostnames": [
            "<string>"
        ]
    },
    "terms": {
        "fields": [
            "<string>"
        ],
        "rows": <integer>
    }
}


Body Schema

Field Definition Data Type Values
query Search query. String N/A
criteria Criteria is an object that represents values that must be in the results. criteria See Request Schema above
terms The fields to facet and how many of the top entries to return. 
{
    "terms": {
       "fields": [
           "<string>"
       ],
       "rows": <integer>
    } 
}
 Valid values: sources
repositories
registries

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/scan_logs/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "query": "kube",
    "terms": {
        "fields": [
            "clusters",
            "scan_status",
            "repositories"
        ],
        "rows": 50
    },
    "criteria": {
        "namespaces": [
            "demo-namespace"
        ],
        "sources": [
            "FEED_UPDATE"
        ],
        "hostnames": [
            "demo-hostname",
            "testing-hostname"
        ],
        "scan_time": {}
    }
}
Response Body 
{
    "terms": [
        {
            "field": "scan_status",
            "values": [
                {
                    "name": "SCANNED",
                    "total": 78
                },
                {
                    "name": "SCAN_FAILED",
                    "total": 1
                },
                {
                    "name": "NOT_SCANNED",
                    "total": 8
                },
                {
                    "name": "PENDING_SCAN",
                    "total": 4
                }
            ]
        },
        {
            "field": "clusters",
            "values": [
                {
                    "name": "demo:cluster-one",
                    "total": 14
                },
                {
                    "name": "test:testing-cluster-one",
                    "total": 14
                }
            ]
        },
        {
            "field": "repositories",
            "values": [
                {
                    "name": "demoartifactory/cluster-scanner",
                    "total": 1
                }
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Field Definitions

Criteria

Field Definition Data Type Values
time_range A period to search backwards from current time or absolute start and end times. time filter N/A
full_tags Full tag of an image, containing its registry, repo, and tag (or digest). [string] Example:[ “docker.io/ealen/echo-server:0.4.2”]
repositories The repository images are stored in [string] Example: [“demo/demo-server”]
digests Digest of the image or repository manifest. (Available only for scanned images) [ string] Example: [“sha256:8cba89a89aaa8445c9d385962cd915ae2e237e38f874ff90c5afbcc31a854a99”]
sources [string]
registries The docker registry the image was pulled from. [string] Example: [“docker.io”]
vulnerabilities [string]
clusters Set of node machines for running containerized applications [string] [ “kafka” ]
namespaces ID that provides a mechanism for isolating groups of resources within a single cluster [string] [“kube-system”]

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