Workload Package

CIS Benchmarks

Model and Query Classes for Compliance Assessment API

class ComplianceBenchmark(cb, model_unique_id, initial_data=None)

Bases: UnrefreshableModel

Class representing Compliance Benchmarks.

Parameters:

  • id – Unique identifier for the benchmark set.

  • name – Name of the benchmark set.

  • version – Version of the benchmark set.

  • os_family – Operating system family associated with the benchmark set (e.g., WINDOWS_SERVER).

  • enabled – Indicates whether the benchmark set is enabled or not.

  • type – Type of the benchmark set (e.g., Custom).

  • supported_os_info – Array of supported operating system information.

  • created_by – Name of the user who created the benchmark set.

  • updated_by – Email of the user who last updated the benchmark set.

  • create_time – Timestamp indicating when the benchmark set was created (in ISO 8601 format).

  • update_time – Timestamp indicating when the benchmark set was last updated (in ISO 8601 format).

  • release_time – Timestamp indicating when the benchmark set was released (in ISO 8601 format).

Initialize a ComplianceBenchmark instance.

Parameters:

  • cb (CBCloudAPI) – Instance of CBCloudAPI.

  • initial_data (dict) – Initial data for the instance.

  • model_unique_id (str) – Unique identifier for the model.

Returns:

An instance of ComplianceBenchmark.

Return type:

ComplianceBenchmark

execute_action(action, device_ids=None)

Execute a specified action for the Benchmark Set for all devices or a specified subset.

Required Permissions:

complianceAssessment.data(EXECUTE)

Parameters:

  • action (str) – The action to be executed. Options: ENABLE, DISABLE, REASSESS

  • device_ids (str or list, optional) – IDs of devices on which the action will be executed. If specified as a string, only one device will be targeted. If specified as a list, the action will be executed on multiple devices. Default is None.

Returns:

JSON response containing information about the executed action.

Return type:

dict

Raises:

ApiError – If the provided action is not one of the allowed actions.

Example

To reassess an object: benchmark_sets = cb.select(ComplianceBenchmark) benchmark_sets[0].execute_action(‘REASSESS’)

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

static get_compliance_schedule(cb)

Gets the compliance scan schedule and timezone configured for the Organization.

Parameters:

cb (CBCloudAPI) – An instance of CBCloudAPI representing the Carbon Black Cloud API.

Required Permissions:

complianceAssessment.data(READ)

Raises:

ApiError – If cb is not an instance of CBCloudAPI.

Returns:

The configured organization settings for Compliance Assessment.

Return type:

dict

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> schedule = ComplianceBenchmark.get_compliance_schedule(cb)
>>> print(schedule)
get_device_compliances(query='')

Fetches devices compliance summaries associated with the benchmark set.

Required Permissions:

complianceAssessment.data(READ)

Parameters:

query (str, optional) – The query to filter results.

Returns:

List of Device Compliances

Return type:

[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_set = cb.select(ComplianceBenchmark).first()
>>> device_compliances = benchmark_set.get_device_compliance()
get_device_rule_compliances(device_id, query='')

Fetches rule compliances for specific device.

Required Permissions:

complianceAssessment.data(READ)

Parameters:

  • device_id (int) – Device id to fetch benchmark rule compliance

  • query (str, optional) – The query to filter results.

Returns:

List of Rule Compliances

Return type:

[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_set = cb.select(ComplianceBenchmark).first()
>>> rules = benchmark_set.get_device_rule_compliance(123)
get_rule_compliance_devices(rule_id, query='')

Fetches device compliances for a specific rule.

Required Permissions:

complianceAssessment.data(READ)

Parameters:

  • rule_id (str) – Rule id to fetch device compliances

  • query (str, optional) – The query to filter results.

Returns:

List of Device Compliances

Return type:

[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_set = cb.select(ComplianceBenchmark).first()
>>> rules = benchmark_set.get_rule_compliance_devices("BCCAAACA-F0BE-4C0F-BE0A-A09FC1641EE2")
get_rule_compliances(query='')

Fetches rule compliance summaries associated with the benchmark set.

Required Permissions:

complianceAssessment.data(READ)

Parameters:

query (str, optional) – The query to filter results.

Returns:

List of Rule Compliances

Return type:

[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_set = cb.select(ComplianceBenchmark).first()
>>> rules = benchmark_set.get_rule_compliance()
get_rules(rule_id=None)

Fetches compliance rules associated with the benchmark set.

Required Permissions:

complianceAssessment.data(READ)

Parameters:

rule_id (str, optional) – The rule ID to fetch a specific rule. Defaults to None.

Returns:

List of Benchmark Rules

Return type:

[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_set = cb.select(ComplianceBenchmark).first()
>>> # To return all rules within a benchmark set, leave get_rules empty.
>>> rules = benchmark_set.get_rules()
get_sections()

Get Sections of the Benchmark Set.

Required Permissions:

complianceAssessment.data(READ)

Returns:

List of sections within the Benchmark Set.

Return type:

list[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark = cb.select(ComplianceBenchmark).first()
>>> for section in benchmark.get_sections():
...     print(section.section_name, section.section_id)
refresh()

Reload this object from the server.

static set_compliance_schedule(cb, scan_schedule, scan_timezone)

Sets the compliance scan schedule and timezone for the organization.

Required Permissions:

complianceAssessment.data(UPDATE)

Parameters:

  • cb (CBCloudAPI) – An instance of CBCloudAPI representing the Carbon Black Cloud API.

  • scan_schedule (str) – The scan schedule, specified in RFC 5545 format. Example: “RRULE:FREQ=DAILY;BYHOUR=17;BYMINUTE=30;BYSECOND=0”.

  • scan_timezone (str) – The timezone in which the scan will run, specified as a timezone string. Example: “UTC”.

Raises:

ApiError – If cb is not an instance of CBCloudAPI, or if scan_schedule or scan_timezone are not provided.

Returns:

The configured organization settings for Compliance Assessment.

Return type:

dict

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> schedule = ComplianceBenchmark.set_compliance_schedule(cb,
                    scan_schedule="RRULE:FREQ=DAILY;BYHOUR=17;BYMINUTE=30;BYSECOND=0",
                    scan_timezone="UTC")
>>> print(schedule)
to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

update_rules(rule_ids, enabled)

Update compliance rules associated with the benchmark set.

Required Permissions:

complianceAssessment.data(UPDATE)

Parameters:

  • rule_ids (list[str]) – The rule IDs to update their enabled/disabled status.

  • enabled (bool) – Whether the rule is enabled or disabled.

Returns:

List of Updated Benchmark Rules

Return type:

[dict]

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_set = cb.select(ComplianceBenchmark).first()
>>> # To return all rules within a benchmark set, leave get_rules empty.
>>> rules = benchmark_set.update_rules(["2A65B63E-89D9-4844-8290-5042FDF2A27B"], True)
class ComplianceBenchmarkQuery(doc_class, cb)

Bases: BaseQuery, QueryBuilderSupportMixin, CriteriaBuilderSupportMixin, IterableQueryMixin, AsyncQueryMixin

A class representing a query for Compliance Benchmark.

Initialize a ComplianceBenchmarkQuery instance.

Parameters:

  • doc_class (class) – The document class for this query.

  • cb (CBCloudAPI) – An instance of CBCloudAPI.

Returns:

An instance of ComplianceBenchmarkQuery.

Return type:

ComplianceBenchmarkQuery

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

  • key (str) – The key for the criteria item to be set.

  • newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
all()

Returns all the items of a query as a list.

Returns:

List of query items

Return type:

list

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:

  • q (Any) – Query string or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

execute_async()

Executes the current query in an asynchronous fashion.

Returns:

A future representing the query and its results.

Return type:

Future

first()

Returns the first item that would be returned as the result of a query.

Returns:

First query item

Return type:

obj

not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:

  • q (solrq.Q) – Query object.

  • **kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
or_(q=None, **kwargs)

Add a disjunctive filter to this query.

Parameters:

  • q (solrq.Q) – Query object.

  • **kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Parameters:

  • key (str) – The key in the schema to sort by.

  • direction (str) – The sort order, either “ASC” or “DESC”.

Returns:

The query with sorting parameters.

Return type:

Query

Raises:

ApiError – If an invalid sort direction is specified.

Example

To sort by a field in descending order:

>>> cb = CBCloudAPI(profile="example_profile")
>>> benchmark_sets = cb.select(ComplianceBenchmark).sort_by("name", direction="DESC")
>>> print(*benchmark_sets)
update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

  • key (str) – The key for the criteria item to be set.

  • newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:

  • q (Any) – Query string, QueryBuilder, or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

log = <Logger cbc_sdk.workload.compliance_assessment (WARNING)>

Compliance models

NSX Remediation Module

NSX Remediation for Workloads

class NSXRemediationJob(cb, running_job_ids)

Bases: object

An object that runs and monitors an NSX Remediation operation.

Creates a new NSXRemediationJob object.

Parameters:

  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • running_job_ids (list[str]) – The list of running job IDs.

async_await_result()

Sets up a Future which can be used to wait asynchronously for all running jobs to be completed.

Required Permissions:

appliances.registration(READ)

Returns:

A future representing the job and its results.

Return type:

Future

await_result()

Waits for all running jobs to be completed and returns the final status.

Required Permissions:

appliances.registration(READ)

Returns:

The final status, mapping individual job IDs to status value dicts.

Return type:

dict

classmethod start_request(cb, device_ids, tag, set_tag=True)

Starts an NSX Remediation request and returns the job object.

Required Permissions:

appliances.nsx.remediation(EXECUTE)

Parameters:

  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • device_ids (int|list) – The device ID(s) to run the remediation request on.

  • tag (str) – The NSX tag to apply to specified devices. Valid values are “CB-NSX-Quarantine”, “CB-NSX-Isolate”, and “CB-NSX-Custom”.

  • set_tag (bool) – True to toggle the specified tag on, False to toggle it off. Default True.

Returns:

The object representing all running jobs.

Return type:

NSXRemediationJob

Raises:

  • ApiError – If the parameters to start the request are incorrect.

  • ServerError – If the request could not be successfully started.

property status

Returns the current status.

Returns:

The current status, mapping individual job IDs to status value dicts.

Return type:

dict

Sensor Lifecycle Module

Sensor Lifecycle Management for Workloads

class SensorKit(cb, initial_data=None)

Bases: UnrefreshableModel

Represents the information about a sensor, including installation file URLs.

Parameters:

  • sensor_type – The type of information this sensor is for.

  • sensor_url – The URL for downloading the sensor installation package.

  • sensor_config_url – The URL for downloading the sensor configuration information.

  • error_code – Code for any error that occurred while getting the sensor information.

  • message – Message for any error that occurred while getting the sensor information.

Initialize the SensorKit object.

Parameters:

  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • initial_data (dict) – Initial data used to populate the sensor kit data.

classmethod from_type(cb, device_type, architecture, sensor_type, version)

Helper method used to create a temporary SensorKit object from its four components.

This method CANNOT be used to create an object that will be persisted to the server.

Parameters:

  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • device_type (str) – Device type to be used. Valid values are “WINDOWS”, “LINUX”, and “MAC”.

  • architecture (str) – Architecture to be used. Valid values are “32”, “64”, and “OTHER”.

  • sensor_type (str) – Sensor type to be used. Valid values are “WINDOWS”, “MAC”, “RHEL”, “UBUNTU”, “SUSE”, and “AMAZON_LINUX”.

  • version (str) – Sensor version number to be used.

Returns:

A SensorType object with those specified values.

Return type:

SensorType

Raises:

ApiError – If an invalid value was used for one of the three limited values.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:

  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

classmethod get_config_template(cb)

Retrieve the sample config.ini file with the properties populated from the server.

Parameters:

cb (BaseAPI) – Reference to API object used to communicate with the server.

Returns:

Text of the sample configuration file.

Return type:

str

refresh()

Reload this object from the server.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

class SensorKitQuery(doc_class, cb)

Bases: BaseQuery, CriteriaBuilderSupportMixin, IterableQueryMixin, AsyncQueryMixin

Query class used to read in SensorKit objects.

Initialize the SensorKitQuery.

Parameters:

  • doc_class (class) – The model class that will be returned by this query.

  • cb (BaseAPI) – Reference to API object used to communicate with the server.

add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Will overwrite any existing criteria for the specified key.

Parameters:

  • key (str) – The key for the criteria item to be set.

  • newlist (str or list[str]) – Value or list of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
add_sensor_kit_type(skit=None, **kwargs)

Add a sensor kit type to the request.

Parameters:

  • skit (SensorKit) – The sensor kit type to be added to the request.

  • **kwargs (dict) – If skit is None, the keyword arguments ‘device_type’, ‘architecture’, ‘sensor_type’, and ‘version’ are used to create the sensor kit type to be added.

Returns:

Reference to this object.

Return type:

SensorKitQuery

all()

Returns all the items of a query as a list.

Returns:

List of query items

Return type:

list

config_params(params)

Sets the configuration parameters for the sensor kit query request.

Parameters:

params (str) – The text of a config.ini file with a list of sensor properties to configure on installation.

Returns:

Reference to this object.

Return type:

SensorKitQuery

execute_async()

Executes the current query in an asynchronous fashion.

Returns:

A future representing the query and its results.

Return type:

Future

expires(expiration_date_time)

Sets the expiration date and time for the sensor kit query request.

Parameters:

expiration_date_time (str) – The time at which the sensor download link will expire, expressed as ISO 8601 UTC.

Returns:

Reference to this object.

Return type:

SensorKitQuery

first()

Returns the first item that would be returned as the result of a query.

Returns:

First query item

Return type:

obj

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:

  • key (str) – The key for the criteria item to be set.

  • newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.