Container Management API

Overview

Kubernetes hardening policies combine predefined and user-defined policy rules that describe the target configuration of Kubernetes resources. Kubernetes hardening policies assure the security of the workloads configuration.

Use Cases

  • Alert, block or enforce workload and image properties to adhere to defined security and compliance standards throughout the application lifecycle.

Requirements

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

Key Features

  • Configure rules
  • Use Scopes to group Kubernetes resources for targeted security protection and analysis. For example, you can group resources by cluster and namespace and then create policies for that scope.
  • Templated Policies

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}/guardrails/management/policies/{policyId}
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/policies
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/scopes/{scopeId}
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/scopes
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/policies_scopes/{scopeId}
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/policies_scopes
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/rules
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/rules/{custom_rule_id}
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/templates
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/templates/add_rules
  • {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/templates/{template_id}

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

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 Management APIs enable manipulation of Policies, Scopes, Rules, Templates and the relationships between them.

Policy

The calls in this section manage the policy object - creation, updates and delete.

Get Policy

Returns the policy object for a provided policy id.


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}/guardrails/management/policies/{policy_id}

Response Codes

Code Description Content-Type Content
200 The policy object specified by policy_id application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
404 Policy id was not found application/json 
{"message": "policy <policy_id> not found"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}


Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/policies/12a345cde-0a9b-464a-804e-0cbb3201c68f
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "policy_id": "12a345cde-0a9b-464a-804e-0cbb3201c68f",
    "name": "kube-system",
    "scope_metadata": {
        "scope_id": "123456a7-a607-4377-8ca3-d1020ad8fb85",
        "scope_name": "sample-scope"
    },
    "creator": "demouser@demoorg.com",
    "created_on": 1631168658409,
    "created_on_iso": "2021-09-09T06:24:18.409Z",
    "modified_by": "demouser@demoorg.com",
    "modified_on": 1655988483580,
    "modified_on_iso": "2022-06-23T12:48:03.58Z",
    "rules": [
        {
            "id": "demo-rule",
            "action": "alert",
            "is_enabled": true
        }
    ],
    "exceptions": {
        "rule2": [
            {
                "cluster": "my-cluster",
                "namespace": "my-namespace",
                "kind": "*",
                "name": "sample",
                "username": "*",
                "labels": [
                    {
                        "key": "qq",
                        "value": "zz"
                    }
                ]
            }
        ]
    },
    "include_init_containers": false,
    "include_ephemeral_containers": true,
    "status": "enabled"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get All Policies

Returns the list of policies configured in the system.

Policies are used to define the misconfigurations and rules we want to enforce on resources in the selected scope.


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}/guardrails/management/policies

Response Codes

Code Description Content-Type Content
200 The list of configured policies application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/policies
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "items": [
      {
          "policy_id": "a12bc3d4-d1bb-4859-ad3d-da21efb2ca2f",
          "name": "Demo Policy",
          "scope_metadata": {
              "scope_id": "12a34b5c-519f-4580-8d95-78738075dc63",
              "scope_name": "demo-scope"
          },
          "exceptions_count": 1,
          "creator": "demouser@demoorg.com",
          "created_on": 1655190366737,
          "created_on_iso": "2022-06-14T07:06:06.737Z",
          "modified_by": "demouser@demoorg.com",
          "modified_on": 1666703636607,
          "modified_on_iso": "2022-10-25T13:13:56.607Z",
          "status": "enabled"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create or Update Policy

Enables the user to create a new policy or make updates to an existing policy.

Policies are used to in order to define the misconfigurations and rules we want to enforce on resources in the selected scope.

Note: The Create Policy and Update Policy endpoints are the same endpoint. The request differs by inclusion of policy_id for an update operation.

API Permissions Required

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

Request 
PUT {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/policies

Request Body - application/json

{
    "name": "<string>",
    "scope_id": "<uuid>",
    "status": "<string>",
    "rules": [
        {
            "id": "<string>",
            "action": "<string>",
            "is_enabled": <boolean>,
            "preset_id": "<string>",
            "preset_name": "<string>"
        }
    ],
    "exceptions": {
        "ruleId1": [
            {
                "name": "<string>",
                "username": "<string>",
                "labels": [
                    {
                        "key": "<string>",
                        "value": "<string>"
                    }
                ],
                "cluster": "<string>",
                "namespace": "<string>",
                "kind": "<string>"
            }
        ]
    },
    "include_init_containers": <boolean>,
    "include_ephemeral_containers": <boolean>,
    "policy_id": "<uuid>"
}


Body Schema

Field Definition Data Type Values
id Unique identifier of the policy string N/A Generated at creation
name REQUIRED Unique policy name string NA
scope_id REQUIRED The scope id that the policy should apply on. If missing a new policy will be created. string N/A
status REQUIRED The state the policy is in string enabled, disabled, draft
rules List of rules that are included in the policy [Rule]
exceptions Workloads to be exculded from coverage by the policy [Exception] N/A
include_init_containers True if the policy is enforcing the rules on init containers boolean N/A
include_ephemeral_containers True if the policy enforcing the rules on ephemeral containers boolean N/A


Response Codes

Code Description Content-Type Content
200 The policy was created or updated successfully application/json See example response below
400 Scope Id is a mandatory field and was not provided. application/json 
 {"message": "policy must have a scope id"}
400 Scope Id does not exist. application/json 
 {"message": "scope <scope_id> not found"}
400 Status is a mandatory field and was not provided. application/json 
{"message": "invalid policy status"}
400 Bad request, the message identifies the problem. application/json Example error messages: 
{"message": "policy must have a scope id"} 

{"message": "scope <scope_id> not found"} 

{"message": "policy must have a name"} 

{"message": "invalid policy status"} 

{"message": "creator and createdOn fields can't be changed"}
403 Forbidden application/json application/json 
{"success": false,                                                                                                                                                                                                                                                                                                                                                                                                                                      
 "message": "User is not authenticated"}
409 Duplicate error
The name property must be unique
The scope_id property must be unique		 application/json 
{"message": "policy name and policy scope must be unique"}
500 Internal Server Error application/json 
{"success": false,                                                                                                                                                                                                                                                                                                                                                                                                                                      
 "message": "Internal Server Error"}

Examples

Request 
PUT https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/policies
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "name": "Demo-Policy",
    "include_init_containers": false,
    "include_ephemeral_containers": true,
    "scope_id": "ee58a110-62f4-482b-9fb4-09f6ef8b1994",
    "rules": [
        {
            "id": "deny-ephemeral-containers",
            "action": "alert",
            "is_enabled": true
        }
    ],
    "exceptions": {
        "rule2": [
            {
                "cluster": "my-cluster",
                "namespace": "my-namespace",
                "kind": "*",
                "name": "sample",
                "username": "*",
                "labels": [
                    {
                    "key": "label_key",
                    "value": "label_value"
                    }
                ]
            }
        ]
    },
    "status": "enabled"
}
Response Body 
{
    "policy_id": "0e58ef37-15e5-482b-a4a1-68a84e179845"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Policy

Deletes the policy object specified by the policy id.


API Permissions Required

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

Request 
DELETE {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/policies/{policy_id}

Response Codes

Code Description Content-Type Content
200 Policy was deleted No body
400 Policy id was not found application/json 
{"message": "error deleting policy <policy_id>: not exists"}
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
DELETE https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/policies/{policy_id}
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No response body
To download or review the Carbon Black Cloud Postman collection, click here.

Scopes

Scopes are a way to group Kubernetes resources for targeted security protection and analysis. For example, you can group resources by cluster and namespace and then create policies for that scope.

Use the endpoints in this section to manage scopes.

Get Scope

Returns the scope object for a specified scope id.


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}/guardrails/management/scopes/{scope_id}

Response Codes

Code Description Content-Type Content
200 The scope object application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
404 Scope id was not found application/json 
{"message": "scope <scope_id> was not found"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/scopes/840a2f32-ea30-4ff8-8748-c01aa51ad40d
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "scope_id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e",
    "name": "Updated Demo Scope 01",
    "creator": "",
    "created_on": 1683174576876,
    "created_on_iso": "2023-05-04T04:29:36.876Z",
    "modified_by": "",
    "modified_on": 1683174635458,
    "modified_on_iso": "2023-05-04T04:29:36.876Z",
    "lifecycle_phase": "build",
    "is_protected": false,
    "clusters_groups": [],
    "clusters": [
        "demo:cluster"
    ],
    "namespaces": [
        "*"
    ],
    "grouping_type": "destination",
    "workloads_count": 0
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get All Scopes

Returns the list of scopes configured in the system. Scopes are used to define a set of resources we want to track.


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}/guardrails/management/scopes

Response Codes

Code Description Content-Type Content
200 The scopes were successfully retrieved application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/scopes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "items": [
        {
            "scope_id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e",
            "name": "Updated Demo Scope 01",
            "creator": "",
            "created_on": 1683174576876,
            "created_on_iso": "2023-05-04T04:29:36.876Z",
            "modified_by": "",
            "modified_on": 1683174635458,
            "modified_on_iso": "2023-05-04T04:29:36.876Z",
            "lifecycle_phase": "build",
            "is_protected": false,
            "clusters_groups": [],
            "clusters": [
                "demo:cluster"
            ],
            "namespaces": [
                "*"
            ],
            "grouping_type": "destination",
            "workloads_count": 0
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Scope With Policy

Returns the scope for a specified scope id, with the policy that is applied on it.


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}/guardrails/management/policies_scopes/{scope_id}

Response Codes

Code Description Content-Type Content
200 The scope with its policy. If policy_metadata is null then no policy is attached to the scope. application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
404 Scope id was not found in path application/json 
{"message": "Not found"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/policies_scopes/12a3bc4d-ee56-7f8g-a11b-2345cd67e89e
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "scope_id": "92aa9f26-dc59-4864-8c58-9be1230de9d5",
    "name": "demo scope",
    "policy_metadata": {
        "policy_id": "5839f6b3-1760-4288-bf75-dbad8f81fbc2",
        "policy_name": "demo policy name"
    },
    "workload_count": 0,
    "lifecycle_phase": "deployed"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get All Scopes With Policies

Get the list of scopes configured in the system and the policy that is applied on each.

Can be used to determine what scope can be used when creating a new policy.

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}/guardrails/management/policies_scopes

Response Codes

Code Description Content-Type Content
200 The list of scopes with their policies.
if policy_metadata is null then the scope does not have a policy attached.		 application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/policies_scopes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "items": [
        {
            "scope_id": "any-scope-id",
            "name": "Any",
            "policy_metadata": {
                "policy_id": "123a4b56-520f-411a-a146-3be26dfbbdbd",
                "policy_name": "default"
            },
            "workload_count": 117,
            "lifecycle_phase": "deployed"
        },
        {
            "scope_id": "123456a7-a607-4377-8ca3-d1020ad8fb85",
            "name": "demo-scope",
            "policy_metadata": {
                "policy_id": "a123bc56-ce51-4569-94a1-defa909e1615",
                "policy_name": "demo-policy"
            },
            "workload_count": 33,
            "lifecycle_phase": "any"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create Scope

Create a new scope or make changes to an existing scope.

Scopes are used to in order to define a list of resources we want to track.

Note: The Create Scope and Update Scope endpoints are the same endpoint. The request differs by inclusion of scope_id for an update operation.

API Permissions Required

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

Request 
POST {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/scopes

Request Body - application/json - Update Scope

Do not include scope_id for a create operation.

{
  "name": "<string>",
  "creator": "<email>",
  "created_on": <integer>,
  "modified_by": "<string>",
  "modified_on": <integer>,
  "is_protected": <boolean>,
  "lifecycle_phase": "<string>",
  "clusters_groups": [
    "<string>"
  ],
  "clusters": [
    "<string>"
  ],
  "namespaces": [
    "<string>"
  ]
}

Body Schema

Field Definition Data Type Values
name REQUIRED Unique user assigned identifier of the scope String N/A
clusters REQUIRED The clusters of the resources you want to track.
One of the properties [clusters_groups] or [clusters] has to have at least 1 value.		 Array * means all clusters
clusters_groups REQUIRED The cluster groups of the resources you want to track
One of the properties [clusters_groups] or [clusters] has to have at least 1 value.		 Array * means all cluster groups
Note: scope_id must not be included for a create operation. Including scope_id will make this call an update operation


Response Codes

Code Description Content-Type Content
200 Scope was updated or created successfully application/json See example response below
400 Bad request, the message identifies the problem. application/json Example error messages: 
{"message": "The scope that was provided wasn't valid."}

{"message": "name must not be empty"}

{"message": "<lifecycle_phase> is not a valid scope life cycle"}
403 Forbidden application/json application/json 
{"success": false,  "message": "User is not authenticated"}
409 Duplicate error
The name property must be unique and the combination of the fileds [clusters_groups, clusters, namespaces] must be unique		 application/json 
{"message": "Duplicate error                                                                                                                                                                                                                                                                                  
 The `name` property must be unique
 The combination of the fields [`clusters_groups`, `clusters`, `namespaces`] must be unique"}
500 Internal Server Error application/json 
{"success": false, "message": "Internal Server Error"}


Examples

Request 
POST https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/scopes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "name": "Updated Demo Scope 01",
    "lifecycle_phase": "build",
    "clusters": [
        "demo:cluster"
    ],
    "clusters_groups": [],
    "namespaces": [
        "*"
    ]
}
Response Body 
{
    "id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e",
    "scope_id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Scope

Make changes to an existing scope.

Scopes are used to in order to define a list of resources we want to track.


API Permissions Required

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

Request 
POST {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/scopes

Request Body - application/json - Update Scope

{
  "scope_id": "<uuid>",
  "name": "<string>",
  "creator": "<email>",
  "created_on": <integer>,
  "modified_by": "<string>",
  "modified_on": <integer>,
  "is_protected": <boolean>,
  "lifecycle_phase": "<string>",
  "clusters_groups": [
    "<string>"
  ],
  "clusters": [
    "<string>"
  ],
  "namespaces": [
    "<string>"
  ]
}

Body Schema

Field Definition Data Type Values
name REQUIRED Unique identifier of the scope. If not included, the request is a create operation instead of update. String N/A
namespaces REQUIRED The clusters of the resources you want to track.
One of the properties [clusters_groups] or [clusters] has to have at least 1 value.		 Array * means all namespaces
clusters REQUIRED The clusters of the resources you want to track.
One of the properties [clusters_groups] or [clusters] has to have at least 1 value.		 Array * means all clusters
clusters_groups REQUIRED The cluster groups of the resources you want to track
One of the properties [clusters_groups] or [clusters] has to have at least 1 value.		 Array * means all clusters groups


Response Codes

Code Description Content-Type Content
200 Scope was updated or created successfully application/json See example response below
400 Bad Request such as the scope that was provided wasn’t valid. Message provides detail on the error. application/json 
{"message": "The scope that was provided wasn't valid."}

{"message": "name must not be empty"}

{"message": "<lifecycle_phase> is not a valid scope life cycle"}
403 Forbidden application/json application/json 
{"success": false,  "message": "User is not authenticated"}
409 Duplicate error
The name property must be unique and the combination of the fileds [clusters_groups, clusters, namespaces] must be unique		 application/json 
{"message": "Duplicate error
 The `name` property must be unique
 The combination of the fields [`clusters_groups`, `clusters`, `namespaces`] must be unique"}
500 Internal Server Error application/json 
{"success": false, "message": "Internal Server Error"}


Examples

Request 
POST https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/scopes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "scope_id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e",
    "name": "Updated Demo Scope 01",
    "lifecycle_phase": "build",
    "clusters": [
        "demo:cluster"
    ],
    "clusters_groups": [],
    "namespaces": [
        "*"
    ]
}
Response Body 
{
    "id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e",
    "scope_id": "12a3bc4d-ee56-7f8g-a11b-2345cd67e89e"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Scope

Deletes the scope object specified by the scope id.


API Permissions Required

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

Request 
DELETE {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/scopes/{scope_id}

Response Codes

Code Description Content-Type Content
204 Scope was deleted application/json See example response below
400 Scope can’t be deleted application/json Example error messages: 
{"message": "Scope can't be deleted"}

{"message": "Scope id <scope_id> is being used by policy t1"}
403 Forbidden application/json application/json 
{"success": false,                                                                                                                                               
 "message": "User is not authenticated"}
404 Scope id was not found application/json 
{"message": "scope <scope_id> was not found"}
500 Internal Server Error application/json 
{"success": false,                                                                                                                                               
 "message": "Internal Server Error"}

Examples

Request 
DELETE https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/scopes/12a3bc4d-ee56-7f8g-a11b-2345cd67e89e
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Response Body
To download or review the Carbon Black Cloud Postman collection, click here.

Rules

Get All Rules

Returns the list of misconfiguration types that can be added to a policy.

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}/guardrails/management/rules

Response Codes

Code Description Content-Type Content
200 The list of rules available to use in policies. application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}


Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/rules
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "rules": {
        "app-armor": {
            "rule_id": "app-armor",
            "name": "AppArmor",
            "description": "AppArmor (Application Armor) is a Linux security module that protects an operating system and its applications from security threats. To use it, a system administrator associates an AppArmor security profile with each program.",
            "risk": "medium",
            "category": "Workload Security",
            "supported_actions": [
                "enforce",
                "alert",
                "block"
            ],
            "preset_support": {
                "is_required": true,
                "security_settings": [
                    {
                        "path": "metadata.annotations[container.apparmor.security.beta.kubernetes.io/*]",
                        "supported_actions": [
                            "REMOVE",
                            "ENFORCE"
                        ]
                    }
                ],
                "default_settings": null
            },
            "presets": [
                {
                    "id": "b8c2b952-960d-4ca7-b0a6-d81f1e0bc574",
                    "name": "remove",
                    "rule_id": "app-armor",
                    "policies": [],
                    "security_settings": [
                        {
                            "path": "metadata.annotations[container.apparmor.security.beta.kubernetes.io/*]",
                            "action": "REMOVE",
                            "value": ""
                        }
                    ]
                },
                {
                    "id": "e85f797b-c384-46c9-a7d4-07a87fcc40bd",
                    "name": "localhost",
                    "rule_id": "app-armor",
                    "policies": [],
                    "security_settings": [
                        {
                            "path": "metadata.annotations[container.apparmor.security.beta.kubernetes.io/*]",
                            "action": "ENFORCE",
                            "value": "localhost/test"
                        }
                    ]
                },
                {
                    "id": "ea4de48f-dc31-4dba-bf9d-9eb77adc4b97",
                    "name": "runtime-default",
                    "rule_id": "app-armor",
                    "policies": [],
                    "security_settings": [
                        {
                            "path": "metadata.annotations[container.apparmor.security.beta.kubernetes.io/*]",
                            "action": "ENFORCE",
                            "value": "runtime/default"
                        }
                    ]
                }
            ],
            "policies": [],
            "templates": [],
            "custom_rule_metadata": null
        },
        "cluster-role-binding": {
            "rule_id": "cluster-role-binding",
            "name": "Cluster role binding",
            "description": "Binds a user or service account to a role in a cluster and all its namespaces.",
            "risk": "medium",
            "category": "RBAC",
            "supported_actions": [
                "alert",
                "block"
            ],
            "preset_support": null,
            "presets": null,
            "policies": [
                {
                    "policy_id": "6cfad063-9491-455f-a12e-6f09876afc00",
                    "policy_name": "demo-policy"
                }
            ],
            "templates": [
                {
                    "template_id": "cis-benchmark-1-6-0",
                    "template_name": "CiS benchmark 1.6.0"
                }
            ],
            "custom_rule_metadata": null
        },
        "company-banned-list": {
            "rule_id": "company-banned-list",
            "name": "Company banned list",
            "description": "Prevents deployment of images with company banned files.",
            "risk": "high",
            "category": "Container Images",
            "supported_actions": [
                "alert",
                "block"
            ],
            "preset_support": null,
            "presets": null,
            "policies": [
                {
                    "policy_id": "24269c35-05bd-461c-9131-05ab6b07ec47",
                    "policy_name": "big-demo-policy"
                },
                {
                    "policy_id": "59cf71a6-c4a2-414e-9c3d-2906c282916d",
                    "policy_name": "little-demo-policy"
                }
            ],
            "templates": [],
            "custom_rule_metadata": null
        }
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Custom Rule

Deletes the custom rule specified by the rule id.

API Permissions Required

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

Request 
DELETE {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/rules/{custom_rule_id}

Response Codes

Code Description Content-Type Content
204 Custom rule was deleted application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
404 Custom Rule was not found application/json 
{"message": "error deleting custom rule <custom_rule_id>: not exists"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
DELETE https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/rules/09c851ee-46f8-4d18-847f-c0df4446472c
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No Response Body
To download or review the Carbon Black Cloud Postman collection, click here.

Templates

Get All Templates

Returns the list of templates that can be used when creating policies.


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}/guardrails/management/templates

Response Codes

Code Description Content-Type Content
200 The list of templates application/json See example response below
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
GET https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/templates
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "items": [
        {
            "template_id": "cis-benchmark-1-6-0",
            "name": "CiS benchmark 1.6.0",
            "rules": [
                {
                    "id": "privileged",
                    "action": "alert"
                },
                {
                    "id": "privilege-escalation",
                    "action": "alert"
                }
            ],
            "custom_template_metadata": {
                "creator": "demouser@demoorg.com",
                "created_on": 1644579658878,
                "created_on_iso": "2022-02-11T11:40:58.878Z"
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create or Update a Template

Creates or updates a new template.

Note: The Create Template and Update Template endpoints are the same endpoint. The request differs by inclusion of template_id for an update operation.

API Permissions Required

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

Request 
POST {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/templates

If template_id is null or missing a new template will be created. Otherwise the specified template will be updated.

Request Body - application/json

{
  "template_id": "<string>",
  "name": "<string>",
  "rules": {
    "id": "<string>",
    "action": "<string>"
  }
}


Body Schema

Field Definition Data Type Values
template_id The unique identifier of the template to be updated String e.g. “75f2315e-d6d9-4254-9f19-03001ff6fb02”
name Descriptive name of the template String e.g. “Demo Template”
rules List of rules to include in the template Object 
{
  "id": "<string>",
  "action": "<string>"
}

Response Codes

Code Description Content-Type Content
200 The template was created or updated application/json
400 The provided template was invalid application/json 
{"message": "The provided template was invalid"}

{"message": "error updating custom template sdsdsd: not exists"}

{"message": "custom template has to have a name"}
403 Forbidden application/json application/json 
{"success": false,                                                                                                                                                                                                                                                         
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,                                                                                                                                                                                                                                                         
 "message": "Internal Server Error"}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/templates
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "name": "Demo Template One",
  "rules": [
    {
      "id": "demo_rule_one",
      "action": "alert"
    }
  ]
}
Response Body 
{
    "template_id": "75f2315e-d6d9-4254-9f19-03001ff6fb02"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Add Rules to Templates

Add the list of provided rules to the list of templates


API Permissions Required

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

Request 
POST {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/templates/add_rules

Request Body - application/json

{
  "template_ids": [
    "<string>"
  ],
  "rules": [
    {
      "id": "<string>",
      "action": "<string>"
    }
  ]
}


Body Schema

Field Definition Data Type Values
template_ids List of the id’s of templates to be updated [ string ] e.g. [ “75f2315e-d6d9-4254-9f19-03001ff6fb02” ]
rules List of rules to include in the template Object 
[
  { "id": "<string>",
   "action": "<string>"
  }
]

Response Codes

Code Description Content-Type Content
204 The rules were added to the templates N/A No response body
400 The provided body was invalid application/json 
{"message": "error updating rules for custom templates, acount <account> templateId [<template_id>]"}
403 Forbidden application/json application/json 
{"success": false,
 "message": "User is not authenticated"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
POST https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/templates/add_rules
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "template_ids": [
        "ac6a5ef2-6b7f-4d4e-bc5d-4934f8d28a59"
    ],
    "rules": [
        {
            "id": "be54f44a-6a18-4365-ada9-aa30c0460ffa",
            "action": "alert"
        }
    ]
}
Response Body - 204 
No response body
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Custom Template

Deletes the specified custom template


API Permissions Required

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


Request 

DELETE {cbc-hostname}/containers/v1/orgs/{org_key}/guardrails/management/templates/{template_id}


Response Codes

Code Description Content-Type Content
204 Custom Template was deleted N/A No response body
400 Template id was not found application/json 
{"message": "error deleting custom template <template_id>: not exists"}
403 Forbidden application/json application/json 
{"success": false, "message": "User is not authenticated"}
400 Template id was not found application/json 
{"message": "error deleting custom template <template_id>: not exists"}
500 Internal Server Error application/json 
{"success": false,
 "message": "Internal Server Error"}

Examples

Request 
DELETE https://defense.conferdeploy.net/containers/v1/orgs/ABCD1234/guardrails/management/templates/ac6a5ef2-6b7f-4d4e-bc5d-4934f8d28a59
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No response body
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Exception

Use an Exception to exclude workloads from the coverage of a Kubernetes policy due to known and accepted behavior.

  • For most rules, the exceptions are based on a workload name.
  • For Role-Based Access Control (RBAC) rules, the exceptions are based on resource name and username.
  • For rules that allow the Enforce action, the exceptions are based on workload name or workload label.
Field Definition Data Type Values
name Name of the exception string N/A
username Match the name of the user modifiying the workload N/A
labels Match the labels on the workload Array N/A
cluster The cluster scope of the exception will be applied to string * means all clusters
namespace The namespace scope of the exception will be applied to string * means all namespaces
kind The resource kind scope that the exception will be applied to string * means all resource kinds

Rule

Field Definition Data Type Values
rule_id The rule id string N/A
name The rule name string N/A
description The rule description string N/A
risk The perceived risk when violating this rule. Will be null for custom rules. string low, medium, high

Last modified on July 28, 2023