CloudPassage Halo Python SDK¶

Version 1.6.2¶

Contents:

Installation¶

Requirements¶

Supported Python versions: 2.7.10+, 3.6.5+

The only dependencies are the requests and pyaml modules, which are available through pip.

The Act Of¶

You can install from source by navigating to the directory containing setup.py and running pip install .

Getting Started¶

Usage abstract:

Here’s the premise: you store your session configuration information (API credentials, proxy settings, etc) in the cloudpassage.HaloSession object. This object gets passed into the various class methods which allow you to interact with the CloudPassage Halo API.

Practical example: We’ll print a list of all servers in our account:

import cloudpassage

api_key = MY_HALO_API_KEY
api_secret = MY_API_SECRET
session = cloudpassage.HaloSession(api_key, api_secret)
server = cloudpassage.Server(session)
list_of_servers = server.list_all()
for s in list_of_servers:
    print("ID: {}   Name: {}".format(s["id"], s["hostname"]))

Contributing¶

We appreciate pull requests, and will do our best to answer each quickly. Please issue pull requests against the develop branch, and make sure that your commit messages follow this format:

ACTION: [AUDIENCE:] COMMIT_MSG [!TAG ...]

ACTION can be chg, fix, or new
AUDIENCE can be dev, usr, pkg, test, or doc
TAG can be refactor, minor, cosmetic, or wip.

Here's an example:

chg: usr: Changes a thing that is relevant to users !minor

AUDIENCE and TAG are optional.  This format is required for our changelog
generator.  Details can be found in the comments at the beginning of the
.gitchangelog.rc file, in the root of this repository.

Testing¶

Important locations for testing¶

ONLY FOR LOCAL TESTING. FOR AUTOMATED TESTING SEE BELOW… tests/configs: You’ll find a file here called portal.yaml. Copy it to portal.yaml.local and complete the information inside with your API key and secret. the .gitignore settings will keep you from checking in your creds if you put them in the .local file. This file (portal.yaml.local) is referenced directly by all tests requiring interaction with the API.

tests/policies: These are Halo policies, used primarily for integration tests.

tests/tests: This is where you’ll find the actual tests.

Tests are written for pytest.

Environmental Requirements¶

You’ll need to have a CloudPassage Halo account available for running the tests, as many are integration-focused. These are the things you need to have (at the very least) to get a clean testing run:

Servers:

Have at least one active Linux and active Windows server.

One deactivated server of any type.

Policies:

One firewall policy

One alert profile

One Linux CSM policy

One Linux FIM policy

One Windows FIM policy

One LIDS policy

Scans:

CSM (Failed scan)

FIM (active baseline and successful scan)

One CVE exception

Events:

One event produced by a Windows server.

Server Group:

Using the default group is fine.

Assign the policies mentioned above to the group.

Run FIM baselines against the Linux and Windows servers.

Kick off a CSM scan if it doesn’t happen automatically

Running tests automagically¶

Build the container and run it.

::

docker build -t cloudpassage_halo_python_sdk .

docker run: -it –rm -e HALO_API_KEY=${HALO_API_KEY} -e HALO_API_SECRET_KEY=${HALO_API_SECRET_KEY} -e HALO_API_HOSTNAME=${HALO_API_HOSTNAME} -e HALO_API_PORT=${HALO_API_PORT} cloudpassage_halo_python_sdk /source/codeclimate.sh

If you run it with no environment variables, it will only run unit and style tests. If you pass in $HALO_API_KEY and $HALO_API_SECRET_KEY, it will run integration tests as well. You can use $HALO_API_HOSTNAME and $HALO_API_PORT to override the default settings of api.cloudpassage.com and 443, respectively. These variables are written into the tests/config/portal.yaml.local file using envsubst. The exit code encountered in testing is what you’ll get out when the container exits.

For more detailed information, check out the .travis.yml file in the github repository.

ApiKeyManager¶

class cloudpassage.ApiKeyManager(**kwargs)¶

Retrieves API keys from file or environment.

If instantiated with no arguments, it will return credentials from environment variables. If there are no credentials set in environment variables, it will look to /etc/cloudpassage.yaml.

If there is no api_hostname specified in the selected configuration source, it defaults to api.cloudpassage.com.

Environment variables::

HALO_API_KEY

HALO_API_SECRET_KEY

HALO_API_HOSTNAME

HALO_API_PORT

Yaml file structure::

defaults:

key_id:

secret_key:

api_hostname:

api_port:

Keyword Arguments:
	config_file (str) – full path to yaml config file use_config (boolean) – set True is hoping to use config_file

api_hostname¶: Hostname of api endpoint. Defaults to api.cloudpassage.com

api_port¶: API port. Defaults to 443

key_id¶: API key ID

secret_key¶: API key secret

classmethod env_vars_are_set(env_vars)¶: Determine if environment vars are correctly set

get_config_from_env()¶: Return config information from environment vars

get_config_from_file(config_file)¶: Return config from file

set_config_variables(config_variables)¶: Set configuration vars for object

HaloSession¶

class cloudpassage.HaloSession(apikey, apisecret, **kwargs)¶

Create a Halo API connection object.

On instantiation, it will attempt to authenticate against the Halo API using the apikey and apisecret provided, together with any overrides passed in through kwargs.

Parameters:

apikey (str) – API key, retrieved from your CloudPassage Halo account
apisecret (str) – API key secret, found with your API key in your CloudPassage Halo account

Keyword Arguments:

api_host (str) – Override the API endpoint hostname. Defaults to api.cloudpassage.com.
api_port (str) – Override the API HTTPS port. Defaults to 443.
proxy_host (str) – Hostname or IP address of proxy
proxy_port (str) – Port for proxy. Ignored if proxy_host is not set
requests_ca_bundle (str) – Path to SSL Certificate file.
user_agent (str) – Override for UserAgent string. We set this so that we can see what tools are being used in the field and set our development focus accordingly. To override the default, feel free to pass this kwarg in.
integration_string (str) – If set, this will cause the user agent string to include an identifier for the integration being used.

authenticate_client()¶

This method attempts to set an OAuth token

Call this method and it will use the API key and secret as well as the proxy settings (if used) to authenticate this HaloSession instance.

build_client()¶: Build client object for class instantiation.

build_endpoint_prefix()¶: This constructs everything to the left of the file path in the URL.

build_header()¶: This constructs the auth header, required for all API interaction.

classmethod build_proxy_struct(host, port)¶

Return a structure describing the environment’s HTTP proxy settings.

It returns a dictionary object that can be passed to the requests module.

get_auth_token(endpoint, headers)¶

Returns the oauth token and scope.

Parameters:	endpoint (str) – Full URL, including schema. headers (dict) – Dictionary, containing header with encoded credentials. Example: {“Authorization”: str(“Basic ” + encoded)}
Returns:	token, scope
Return type:	tuple

get_response(client_method, verb, url, params, reqbody)¶

Base method for getting response from Halo API.

Parameters:	client_method (requests.Session() method) – This method is what performs the actual interaction with the Halo API. Example: `self.connection.client.get` verb (str) – The HTTP verb used in interacting with the Halo API. url (str) – Complete URL for request. params (list) – URL params in a list of dictionaries. reqbody (dict) – Body of put/post request
Returns:	success (bool) response (requests.response) exception (Exception)

interact(verb, endpoint, params=None, reqbody=None)¶

This method allows us to wrap common Halo interaction functionality.

Most exceptions will be caught and validated here, and if retries fail, those exceptions will be raised again for catching at a higher level.

Parameters:	verb (str) – get, post, put, or delete. endpoint (str) – URL- everything past api.cloudpassage.com. params (list of dict) – This is a list of dictionary objects, represented like this: [{“k1”: “two,too”}] reqbody (dict) – Dictionary to be converted to JSON for insertion as payload for request.
Returns:	response object

try_wrapper(verb, url, params, reqbody)¶

Wraps tries.

Parameters:	endpoint (str) – Path part of URL. params (list of dict) – URL params. reqbody (dict) – Request body.
Returns:	success (bool) response (requests.response) exception (Exception)

HttpHelper¶

class cloudpassage.HttpHelper(connection)¶

This class handles communication with the CloudPassage API.

When instantiating this class, pass in a cloudpassage.HaloSession object (referred to here as connection, as it defines connection parameters for interacting with the API).

delete(endpoint, **kwargs)¶

This method performs a Delete against Halo’s API.

It will attempt to authenticate using the credentials (required to instantiate the object) if the session has either:

Not been authenticated yet
OAuth Token has expired

This is a primary method, meaning it reaches out directly to the Halo API, and should only be utilized by secondary methods with a more specific purpose, like gathering events from /v1/events. If you’re using this method because the SDK doesn’t provide a more specific method, please reach out to toolbox@cloudpassage.com so we can get an enhancement request in place for you.

Parameters:	endpoint (str) – Path component of URL

get(endpoint, **kwargs)¶

This method performs a GET against Halo’s API.

It will attempt to authenticate using the credentials (required to instantiate the object) if the session has either: 1) Not been authenticated yet 2) OAuth Token has expired

This is a primary method, meaning it reaches out directly to the Halo API, and should only be utilized by secondary methods with a more specific purpose, like gathering events from /v1/events. If you’re using this method because the SDK doesn’t provide a more specific method, please reach out to toolbox@cloudpassage.com so we can get an enhancement request in place for you.

Parameters: endpoint (str) – URL- everything between api.cloudpassage.com and any parameters to be passed. Example: /v1/events

Keyword Arguments:

params (dict) – This is a dictionary object, represented like this: {“k1”: “two,too”} which goes into the URL looking like this: ?k1=two,too. If you use a list as the value in a dictionary here, you’ll get two k/v pairs represented in the URL and the CloudPassage API doesn’t operate like that. Only the last instance of that variable will be considered, and your results may be confusing. So don’t do it. Dictionaries should be {str:str}.

get_paginated(endpoint, key, max_pages, **kwargs)¶

This method returns a concatenated list of objects from the Halo API.

It’s really a wrapper for the get() method. Pass in the path as with the get() method, and a maxpages number. Maxpages is expected to be an integer between 2 and 100

Parameters:

endpoint (str) – Path for initial query
key (str) – The key in the response containing the objects of interest. For instance, the /v1/events endpoint will have the “events” key, which contains a list of dictionary objects representing Halo events.
maxpages (int) – This is a number from 2-100. More than 100 pages can take quite a while to return, so beyond that you should consider using this SDK as a component in a multi-threaded tool.

Keyword Arguments:

params (dict) – This is a dictionary object, represented like this: {“k1”: “two,too”} which goes into the URL looking like this: ?k1=two,too . If you use a list as the value in a dictionary here, you’ll get two k/v pairs represented in the URL and the CloudPassage API doesn’t operate like that. Only the last instance of that variable will be considered, and your results may be confusing. So don’t do it. Dictionaries should be {str:str}.

post(endpoint, reqbody)¶

This method performs a POST against Halo’s API.

As with the GET method, it will attempt to (re)authenticate the session if the key is expired or has not yet been retrieved.

Also like the GET method, it is not intended for direct use (though we won’t stop you). If you need something that the SDK doesn’t already provide, please reach out to toolbox@cloudpassage.com and let us get an enhancement request submitted for you.

Parameters:	endpoint (str) – path component of URL reqbody (dict) – Dictionary to be converted to JSON for insertion as payload for request.

classmethod process_page(page, key)¶: Page goes in, list data comes out.

put(endpoint, reqbody)¶

This method performs a PUT against Halo’s API.

As with the GET method, it will attempt to (re)authenticate the session if the key is expired or has not yet been retrieved.

Also like the GET method, it is not intended for direct use (though we won’t stop you). If you need something that the SDK doesn’t already provide, please reach out to toolbox@cloudpassage.com and let us get an enhancement request submitted for you.

Parameters:	endpoint (str) – Path component of URL reqbody (dict) – Dictionary to be converted to JSON for insertion as payload for request.

TimeSeries¶

class cloudpassage.TimeSeries(session, start_time, start_url, item_key, params={})¶

Wrap time-series object retrieval in a generator.

This method enables the consumption of time-ordered API objects as a generator. This method is multi-threaded and ensures that objects are yielded in chronological order according to the created_at field. This method also automatically adjusts the number of threads in use based on the volume of objects published via the selected API endpoint.

In order to cleanly stop the generator, set the object’s stop attribute to True.

Example:

# Print event IDs as they occur
import datetime
import os
import cloudpassage
start_time = datetime.datetime.now().isoformat()
key = os.getenv("HALO_API_KEY")
secret = os.getenv("HALO_API_SECRET_KEY")
session = cloudpassage.HaloSession(key, secret)
event_stream = cloudpassage.TimeSeries(session, start_time,
                                       "/v1/events", "events")
for x in event_stream:
    print(x["id"])

Parameters:	session (object) – HaloSession object. start_time (str) – ISO 8601-formatted timestamp. start_url (str) – Path from URL, no hostname and no URL-encoded params. item_key (str) – Top-level key, below which is a list of target items. params (dict) – Parameters for URL, which will be URL-encoded.

stop¶

Set to False by default. When set to True, the generator will return, effecting a clean exit.

Type:	bool

__iter__()¶: Yields one item from a time-series query against Halo. Forever.

CspAccount¶

class cloudpassage.CspAccount(session, **kwargs)¶

Initializing the CspAccount class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

Supported keyword args for filtering CspAccount.list_all():

activate(halo_csp_account_id)¶

This method activates a CSP Account

Parameters:	halo_csp_account_id (str) – Internal Halo ID of CSP Account
Returns:	True if successful, throws exception on failure

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

deactivate(halo_csp_account_id)¶

This method deactivates a CSP Account

Parameters:	halo_csp_account_id (str) – Internal Halo ID of CSP Account
Returns:	True if successful, throws exception on failure

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

scan(halo_csp_account_id)¶

This method initiates a scan of a CSP account: manually outside of its existing schedule.

Parameters:	halo_csp_account_id (str) – Internal Halo ID of CSP Account
Returns:	True if successful, throws exception on failure

update(object_body)¶: Update. Success returns None

CspFinding¶

class cloudpassage.CspFinding(session, **kwargs)¶

Initializing the CspAccount class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

list_all(**kwargs)¶

Lists all CSP Findings.

Keyword Arguments:
	csp_rule_id (str or list) – The user-readable ID of the rule. Example: CIS:1.1 rule_id (str or list) – The UUID number of the rule that was applied; for example, 280d33b6ef3411e88ad765862e629d59 csp_resource_type (str or list) – The type of cloud resource; for example, Policy, Role, User, and so on csp_service_type (str or list) – The type of cloud service; for example, IAM, S3, EC2, and so on policy_name (str or list) – The name of the policy that was applied; for example, CIS-Benchmark rule_name (str or list) – The name of the rule that was applied; for example Ensure MFA is enabled for the “root” account
Returns:	List of CSP Findings represented as dictionary-type objects
Return type:	list

CspResource¶

class cloudpassage.CspResource(session, **kwargs)¶

Initializing the CspResource class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

CspSetting¶

class cloudpassage.CspSetting(session, **kwargs)¶

Initializing the CspSetting class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

update(object_body)¶

Update CSP scanner settings

Parameters:	object_body (dict) – Dictionary of new settings (https – //api-doc.cloudpassage.com/help#csp-update-scan-settings)
Returns:	None if successful, raises exception if not

view()¶

View current CSP scanner settings

Returns:	Dictionary of current CSP scan settings
Return type:	dict

Container¶

class cloudpassage.Container(session, **kwargs)¶

Initializing the Container class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

ContainerEvent¶

class cloudpassage.ContainerEvent(session, **kwargs)¶

Initializing the ContainerEvent class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

ContainerImage¶

class cloudpassage.ContainerImage(session, **kwargs)¶

Initializing the ContainerImage class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

ImageIssue¶

class cloudpassage.ImageIssue(session, **kwargs)¶

Initializing the ImageIssue class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

ImageRegistry¶

class cloudpassage.ImageRegistry(session, **kwargs)¶

Initializing the ImageRegistry class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

ImageRepo¶

class cloudpassage.ImageRepo(session, **kwargs)¶

Initializing the ImageRepo class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

ContainerProcess¶

class cloudpassage.ContainerProcess(session, **kwargs)¶

Initializing the ContainerProcess class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

ContainerPackage¶

class cloudpassage.ContainerPackage(session, **kwargs)¶

Initializing the ContainerPackage class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

Server¶

class cloudpassage.Server(session, **kwargs)¶

Initializing the Server class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

Supported keyword args for filtering Server.list_all():

state (list or str): A list or comma-separated string containing: any of these: active, missing, deactivated. By default, only active servers will be returned.
platform (list or str): A list or comma-separated string containing: any of these: windows, debian, ubuntu, centos, oracle, rhel.

cve (str): CVE ID. Example: CVE-2015-1234 kb (str): Search for presence of KB. Example: kb=”KB2485376” missing_kb (str): Search for absence of KB. Example:

mising_kb=”KB2485376”

assign_group(server_id, group_id)¶

Moves server to another group.

Parameters:	server_id (str) – Target server’s ID group_id (str) – ID of group to move server to.
Returns:	True if successful, throws exceptions if it fails.

command_details(server_id, command_id)¶

This method retrieves the details and status of a server command.

Parameters:	server_id (str) – ID of server runnung command command_id (str) – ID of command running on server
Returns:	Command status as a dictionary object.
Return type:	dict

Example:

{
  "name": "",
  "status: "",
  "created_at": "",
  "updated_at": "",
  "result": ""
 }

For server account creation and server account password resets, the password will be contained in the result field, as a dictionary:

{
  "name": "",
  "status: "",
  "created_at": "",
  "updated_at": "",
  "result": {
             "password": ""
             }
}

delete(server_id)¶

Deletes server indicated by server_id.

Remember, deletion causes the removal of accociated security events and scan information.

Parameters:	server_id (str) – ID of server to be deleted
Returns:	True if successful, throws exceptions otherwise.

describe(server_id)¶

Get server details by server ID

Parameters:	server_id (str) – Server ID
Returns:	Dictionary object describing server. Response fields are described in detail here: https://api-doc.cloudpassage.com/help#servers
Return type:	dict

describe_local_account(server_id, username)¶

Get deatils on local user account

Parameters:	server_id (str) – Server ID username (str) – username of the local user account
Returns:	Dictionary object describing local user account
Return type:	dict

get_firewall_logs(server_id, pages)¶

This method retrieves the detail of a server firewall log.

Parameters:	server_id (str) – ID of server
Returns:	firewall log of the server
Return type:	list

issues(server_id)¶

This method retrieves the detail of a server issues.

Parameters:	server_id (str) – ID of server
Returns:	issues of the server
Return type:	list

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

list_connections(server_id, **kwargs)¶

Return all recent connections detected on server_id.

Parameters:	server_id (str) – Server ID
Returns:	List of all recently detected connections on the server
Return type:	list

list_local_accounts(server_id)¶

Return all local user accounts associated with server_id.

Parameters:	server_id (str) – Server ID
Returns:	List of dictionary objects describing local user account
Return type:	list

list_packages(server_id)¶

Return a list of packages installed on the server.

Parameters:	server_id (str) – Server ID
Returns:	List of dictionaries with keys for `package_name` and `package_version`. This list will be empty if no SVA scans have been completed on the server.
Return type:	list

list_processes(server_id)¶

This method retrieves information about each running process on a: specified Linux or Windows server.

Parameters:	server_id (str) – Server ID
Returns:	List of all running processes on the server specified by server ID. Note: Historical scan data is not saved; Only the most recent scan results are available
Return type:	list

retire(server_id)¶

This method retires a server

Parameters:	server_id (str) – ID of server to be retired
Returns:	True if successful, throws exception on failure

ServerGroup¶

class cloudpassage.ServerGroup(session, **kwargs)¶

Initializing the ServerGroup class:

Filters for ServerGroup queries can be found in the API documentation. See here: https://api-doc.cloudpassage.com/help#object-representation-1 for more information.

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(group_name, **kwargs)¶

Creates a ServerGroup.

Keyword Arguments:
Parameters:	group_name (str) – Name for the new group
	firewall_policy_id (str) – ID of firewall policy to be assigned to the group (deprecated- use linux_firewall_policy_id) linux_firewall_policy_id (str) – ID of linux firewall policy to associate with the new group windows_firewall_policy_id (str) – ID of Windows firewall policy to associate with the new group policy_ids (list) – List of Linux configuration policy IDs windows_policy_ids (list) – List of Windows configuration policy IDs fim_policy_ids (list) – List of Linux FIM policies linux_fim_policy_ids (list) – List of Linux FIM policies windows_fim_policy_ids (list) – List of Windows FIM policies lids_policy_ids (list) – List of LIDS policy IDs tag (str) – Server group tag-used for auto-assignment of group. server_events_policy (str) – Special events policy IDs alert_profiles (list) – List of alert profile IDs
Returns:	ID of newly-created group.
Return type:	str

delete(group_id, **kwargs)¶

Delete a server group.

Keyword Arguments:
Parameters:	group_id (str) – ID of group to delete
	force (bool) – If set to True, the member servers from this group will be moved to the parent group.
Returns:	None if successful, exceptions otherwise.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

list_connections(group_id, **kwargs)¶

Return all recently detected connections in the server group.

Parameters:	server_id (str) – Group ID
Returns:	List of all recently detected connections in the server group
Return type:	list

list_members(group_id)¶

Returns a list of all member servers of a group_id

Parameters:	group_id (str) – ID of group_id
Returns:	List of dictionary objects describing member servers
Return type:	list

migrate_servers(grp_id, server_ids, srv_state=None)¶

Migrate servers in server_ids into the group identified by group_id.

Parameters:	grp_id (str) – ID of group to merge server_ids (list) – A list of server_id srv_state (str) – A comma-separated string containing filters to be applied to the list of servers to be migrated. Valid filters are active, missing, deactivated, and retired
Returns:	A list of all server_id in the identified server group.
Return type:	server ids (list)

update(group_id, **kwargs)¶

Updates a ServerGroup.

Keyword Arguments:
Parameters:	group_id (str) – ID of group to be altered
	name (str) – Override name for group linux_firewall_policy_id (str) – Override Linux firewall policy ID. windows_firewall_policy_id (str) – Override Windows firewall policy ID. policy_ids (list) – Override Linux configuration policies windows_policy_ids (list) – Override Windows firewall policies linux_fim_policy_ids (list) – Override Linux firewall policies windows_fim_policy_ids (list) – Override Windows FIM policies lids_policy_ids (list) – Override LIDS policy IDs tag (str) – Override server group tag special_events_policy (str) – Override server events policy. Note the difference in naming from the `cloudpassage.ServerGroup.create()` method alert_profiles (list) – List of alert profiles
Returns:	True if successful, throws exception otherwise.

ConfigurationPolicy¶

class cloudpassage.ConfigurationPolicy(session, **kwargs)¶

ConfigurationPolicy class:

The list_all() method allows filtering by using keyword arguments. An exhaustive list of keyword arguments can be found at https://api-doc.cloudpassage.com/help#list-configuration-policies

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

Firewall¶

Firewall Policies¶

class cloudpassage.FirewallPolicy(session, **kwargs)¶

Initializing the FirewallPolicy class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

Firewall Rules¶

class cloudpassage.FirewallRule(session, **kwargs)¶

Initializing the FirewallRule class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(firewall_policy_id, rule_body)¶

Creates a rule within a firewall policy.

Parameters:	rule_body (dict or str) – string or dict containing the json representation of the firewall policy to be created.
Returns:	ID of newly-created firewall rule
Return type:	str

Example rule_body:

{
  "firewall_rule" : {
    "chain": "INPUT",
    "active": true,
    "firewall_interface": "7b881ca072b1012ec681404096c01709",
    "firewall_service": "7b6409a072b1012ec681404096c01709",
    "connection_states": "NEW, ESTABLISHED",
    "action": "ACCEPT",
    "log": true,
    "log_prefix": "East-3 input-accept",
    "comment": "All servers in group East-3 must include this rule",
    "position": 4
    }
}

delete(firewall_policy_id, firewall_rule_id)¶

Delete a firewall policy rule

Parameters:	firewall_policy_id (str) – ID of firewall policy containing the rule to be deleted firewall_rule_id (str) – ID of firewall policy rule to delete
Returns:	None if successful. Errors will throw exceptions.

describe(firewall_policy_id, firewall_rule_id)¶

Get the detailed configuration of a firewall rule

Parameters:	firewall_policy_id (str) – ID of the policy to retrieve detailed configuration information for firewall_rule_id (str) – ID of the specific rule for which to retrieve details
Returns:	dictionary object representing the entire firewall rule.
Return type:	dict

endpoint(policy_id)¶: Return endpoint for API requests.

list_all(firewall_policy_id)¶

List all rules associated with a firewall policy.

Parameters:	firewall_policy_id (str) – ID of firewall policy
Returns:	Returns a list of rules associated with the firewall policy, each of which are represented by an object of type dict.
Return type:	list

update(firewall_policy_id, firewall_rule_id, firewall_rule_body)¶

Update a firewall policy rule.

Parameters:	firewall_policy_id (str) – ID of firewall policy containing the rule to be modified. firewall_rule_id (str) – ID of firewall policy rule to modify. firewall_rule_body (dict or str) – String- or dictionary-type object containing the fields to be updated within the firewall rule.
Returns:	None if successful. Errors will throw exceptions.

Example:

{
  "firewall_rule" : {
    "chain": "INPUT",
    "active": true,
    "firewall_interface": "7b881ca072b1012ec681404096c01709",
    "firewall_service": "7b6409a072b1012ec681404096c01709",
    "connection_states": "NEW, ESTABLISHED",
    "action": "ACCEPT",
    "log": true,
    "log_prefix": "East-3 input-accept",
    "comment": "All servers in group East-3 must include this rule",
    "position": 4
    }
}

Firewall IP Zones¶

class cloudpassage.FirewallZone(session, **kwargs)¶

Initializing the FirewallZone class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

Firewall Services¶

class cloudpassage.FirewallService(session, **kwargs)¶

Initializing the FirewallService class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

Firewall Interfaces¶

class cloudpassage.FirewallInterface(session, **kwargs)¶

Initializing the FirewallInterface class:

Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

FimPolicy¶

class cloudpassage.FimPolicy(session, **kwargs)¶

FimPolicy class:

The list_all() method allows filtering of results with keyword arguments. An exhaustive list of keyword arguments can be found here: https://api-doc.cloudpassage.com/help#file-integrity-policies

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

FimBaseline¶

class cloudpassage.FimBaseline(session, **kwargs)¶

Initializing the FimBaseline class:

Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.

create(fim_policy_id, server_id, **kwargs)¶

Creates a FIM baseline

Keyword Arguments:
Parameters:	fim_policy_id (str) – ID of FIM policy to baseline server_id (str) – ID of server to use for generating baseline
	expires (int) – Number of days from today for expiration of baseline comment (str) – Guess.
Returns:	ID of new baseline
Return type:	str

delete(fim_policy_id, fim_baseline_id)¶

Delete a FIM baseline by ID

Parameters:	fim_policy_id (str) – ID of FIM policy fim_baseline_id (str) – ID of baseline to be deleted
Returns:	None if successful, exceptions throw otherwise.

describe(fim_policy_id, baseline_id)¶

Returns the body of the baseline indicated by fim_baseline_id.

Args: fim_policy_id (str): ID of FIM policy fim_baseline_id (str): ID of baseline

Returns:	Dictionary describing FIM baseline
Return type:	dict

endpoint(policy_id)¶: Return endpoint for API requests.

list_all(fim_policy_id)¶

Returns a list of all baselines for the indicated FIM policy

Parameters:	fim_policy_id (str) – ID of fim policy
Returns:	List of all baselines for the given policy
Return type:	list

update(fim_policy_id, fim_baseline_id, server_id)¶

Update a FIM policy baseline.

Parameters:	fim_policy_id (str) – ID of fim policy fim_baseline_id (str) – ID of baseline to be updated server_id (str) – ID of server to use when generating new baseline
Returns:	None if successful, exceptions throw otherwise.

LidsPolicy¶

class cloudpassage.LidsPolicy(session, **kwargs)¶

Initializing the LidsPolicy class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

Scan¶

Scans¶

class cloudpassage.Scan(session, **kwargs)¶

Initializing the Scan class:

Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.

findings(scan_id, findings_id)¶

Get FIM, CSM, and SVA findings details by scan and findings ID

Parameters:	scan_id (str) – ID of scan_id findings_id (str) – ID of findings to retrieve
Returns:	Dictionary object descrbing findings
Return type:	dict

initiate_scan(server_id, scan_type)¶

Initiate a scan on a specific server.

Parameters:	server_id (str) – ID of server to be scanned scan_type – Type of scan to be run.
Returns:	Dictionary describing command created as a result of this call. As this scan is run asynchronously, this method returns information on the server command, not the scan itself. The server command will, in turn, cause the scan to be performed on the server. The ID that can be retrieved from the return value of this method can be used with the `cloudpassage.Server.command_details()` method to retrieve the status of the scan.
Return type:	dict
Raises:	`CloudPassageValidation` – Unsupported value for `scan_type`.

last_scan_results(server_id, scan_type)¶

Get the results of scan_type performed on server_id.

Parameters:	server_id (str) – ID of server scan_type (str) – Type of scan to filter results for

Valid scan types:: sca - Configuration scan csm - Configuration scan (same as sca) svm - Software vulnerability scan sva - Software vulnerability scan (same as svm) fim - File integrity monitoring scan

Returns:	Dictionary object describing last scan results
Return type:	dict

scan_details(scan_id)¶

Get detailed scan information

Parameters:	scan_id (str) – ID of scan
Returns:	Dictionary object describing scan details
Return type:	dict

scan_history(**kwargs)¶

Get a list of historical scans.

Keyword Arguments:
	server_id (str) – Id of server module (str or list) – sca, fim, svm, sam status (str or list) – queued, pending, running, completed_clean, completed_with_errors, failed since (str) – ISO 8601 formatted string representing the starting date and time for query until (str) – ISO 8601 formatted string representing the ending date and time for query max_pages (int) – maximum number of pages to fetch. Default: 20.
Returns:	List of scan objects
Return type:	list

CVE Exceptions¶

class cloudpassage.CveException(session, **kwargs)¶

Initializing the CveException class:

Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

Issue¶

class cloudpassage.Issue(session, **kwargs)¶

Initializing the Issue class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

list_all(max_pages=20, **kwargs)¶

Returns a list of all issues.

This query is limited to 20 pages of 100 items, totalling 2000 issues.

Default filter returns only issues in the ‘active’ state.

Keyword arguments can be used to filter results. Some keyword arguments are listed below. An exhaustive list of filters for querying Halo issues can be found at https://api-doc.cloudpassage.com/help#issues .

Keyword Arguments:

agent_id (list or str) – A list or comma-separated string containing agent ids
status (list or str) – A list or comma-separated string containing any of these: active, resolved
since (str) – Returns issues created since date in iso8601 format such as: 2017-01-01
until (str) – Returns issues created until date in iso8601 format such as 2017-01-01
issue_type – (list or str): A list or comma-separated string containing any of these: sva, csm, fim, lids, sam, fw, or agent
group_id – (list or str): A list or comma-separated string containing group ids
critical – (list or str): A list or comma-separated string containing any of these: true, false
policy_id (list or str) – A list or comma-separated string containing policy ids
os_type – A list or comma-separated string containing any of these: Linux, Windows

Event¶

class cloudpassage.Event(session, **kwargs)¶

Event class:

Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.

list_all(pages, **kwargs)¶

Return a list of all events.

Default filter returns ALL events. This is a very verbose and time-consuming operation.

Filtering is done with keyword arguments, some of which are listed below. An exhaustive list of filters can be found at https://api-doc.cloudpassage.com/help#events

Keyword Arguments:
Parameters:	pages (int) – Max number of pages (of ten items each) to retrieve
	group_id (list or str) – A list or comma-separated string containing the group IDs to retrieve events for. server_id (list or str) – A list or comma-separated string containing the server IDs to retrieve events for. server_platform (str) – (linux \| windows) critical (bool) – Returns only critical or noncritical events. type (list or str) – A list or comma-separated string containing the event types to query for. A complete list of event types is available here: https://api-doc.cloudpassage.com/help#event-types since (str) – ISO 8601 formatted string representing the starting date and time for query until (str) – ISO 8601 formatted string representing the ending date and time for query
Returns:	List of dictionary objects describing servers
Return type:	list

SystemAnnouncement¶

class cloudpassage.SystemAnnouncement(session, **kwargs)¶

Initializing the SystemAnnouncement class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

create()¶: Not implemented for this object.

delete()¶: Not implemented for this object.

describe()¶: Not implemented for this object.

endpoint()¶: Return endpoint for API requests.

list_all()¶: Return a list of all system announcements.

update()¶: Not implemented for this object.

SpecialEventsPolicy¶

class cloudpassage.SpecialEventsPolicy(session, **kwargs)¶

Initializing the SpecialEventsPolicy class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

AlertProfile¶

class cloudpassage.AlertProfile(session, **kwargs)¶

Initializing the AlertProfile class:

Filtering options for AlertProfile.list_all() can be passed in as keyword arguments. Valid filters can be found at https://api-doc.cloudpassage.com/help#list-alert-profiles.

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

CveException¶

class cloudpassage.CveException(session, **kwargs)¶

Initializing the CveException class:

Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.

create(object_body)¶

Create from JSON document.

Returns the ID of the new object

delete(object_id)¶: Delete by ID. Success returns None

describe(object_id)¶

Get the detailed configuration by ID

Parameters:	object_id (str) – ID to retrieve detailed configuration information for
Returns:	dictionary object representing the entire object.
Return type:	dict

list_all(**kwargs)¶

Lists all objects of this type.

Returns:	List of objects (represented as dictionary-type objects)
Return type:	list

Note

This method supports query parameters via keyword arguments.

update(object_body)¶: Update. Success returns None

CveDetails¶

class cloudpassage.CveDetails(session, **kwargs)¶

Initializing the CveDetail class:

Keyword Arguments:
Parameters:	session (`cloudpassage.HaloSession`) – This will define how you interact with the Halo API, including proxy settings and API keys used for authentication.
	endpoint_version (int) – Endpoint version override.

describe(cve_id)¶

Describe a CVE with complete information on one Common: Vulnerability and Exposure (CVE), as defined by the National Institute of Standards and Technology (NIST).

Parameters:	cve_id (str) – CVE number
Returns:	Dictionary object describing the details of the Common Vulnerability and Exposure specified by CVE number.
Return type:	dict

exceptions¶

class cloudpassage.CloudPassageAuthentication(error_msg, **kwargs)¶

Exception related to authentication.

This is thrown in response to an issue authenticating against the CloudPassage Halo API

Keyword Arguments:
Parameters:	error_msg (str) – Message describing error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageAuthorization(error_msg, **kwargs)¶

Exception related to authorization.

Oftentimes related to the scope of the API credentials

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageCollision(error_msg, **kwargs)¶

Exception indicates a resource collision.

This is thrown when attempting to create a resource which already exists.

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageGeneral(error_msg, **kwargs)¶

This is thrown when a more specific exception type is unavailable.

The msg attribute should have plenty of information on what went wrong.

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageInternalError(error_msg, **kwargs)¶

This exception indicates an error in the Analytics Engine.

This is thrown when a HTTP response code of 500 is detected.

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageResourceExistence(error_msg, **kwargs)¶

This exception indicates that you’re trying to access a resource that doesn’t exist.

This is oftentimes thrown in response to a 404 from the API.

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageValidation(error_msg, **kwargs)¶

Exception related to request validation.

This can be thrown as a result of invalid information being passed to the API (in response to HTTP error) or as a result of failing to pass the SDK’s internal validation routines.

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

class cloudpassage.CloudPassageRateLimit(error_msg, **kwargs)¶

This exception indicates that you have exceeded the allotted number of api calls per minute.

This is thrown when a HTTP response code of 429 is detected.

Keyword Arguments:
Parameters:	error_msg (str) – Message describing the error
	code (int) – Numeric ID for error

msg¶

Type:	str

Changelog¶

v1.6.1¶

Changes¶

Add max_pages optional param to Issue list_all method. [Paul Chang]
Add support for Container Secure endpoints. [Paul Chang]

v1.5.0 (2019-07-27)¶

Changes¶

Styling for tests. [Paul Chang]
More styles. [Paul Chang]
Styling. [Paul Chang]
Add docs for CSP. [Paul Chang]
Add support for Cloud Secure endpoints. [Paul Chang]

Fix¶

Fixed validation failures on v3 issues ID format. [Ash Wilson]

Closes #194

v1.4.0 (2019-06-11)¶

New¶

API version selectors for abstractions. [Ash Wilson]

Closes #181
Create stream() generator method in Event class. [Ash Wilson]

Closes #179

Changes¶

Using safer yaml.SafeLoader in ApiKeyManager. [Ash Wilson]
Update version pin for pytest. [Ash Wilson]
Add docs for CveDetails. [Ash Wilson]

v1.3.0 (2019-03-01)¶

New¶

Added list_packages() to Server() object. [Ash Wilson]

Closes #165

v1.2.2 (2018-10-31)¶

New¶

Python 3.6.5 support. [Ash Wilson]

v1.2 (2018-10-28)¶

New¶

Python 3.7 support. [Ash Wilson]

Changes¶

Improved deduplication in TimeSeries class. [Ash Wilson]

Expanded deduplication routine to compare against prior batch of objects from API. In some extremely rare circumstances, multiple different events with the exact same timestamp would slip through the deduplication routine TimeSeries.remove_duplicate_items. This patch improves deduplication while still using the object’s timestamp as a cursor.

Closes #142
Improve documentation of Server() instance methods. [Ash Wilson]

v1.1.5 (2018-09-15)¶

New¶

Use connection pooling. [Ash Wilson]

The SDK now uses connection pooling via the requests.Session() object. This brings performance benefits as the SDK will no longer need to open a new TLS connection for every interaction with the CloudPassage API.

Connection pool minimum of 1, max of 10 concurrent connections in session. Closes #112

Exponential backoff implemented via requests, 5 tries max.

Retry happens in requests via HTTPAdapter for everything but re-auth, which is caught and retried in SDK. Closes #113

Migrated CI testing environment. Closes #114

Changes¶

Codeclimate coverage for master branch. [Ash Wilson]

Closes #121
Testing matrix includes Python2.7.10 and 2.7.15. [Ash Wilson]

We can add more over time, as the need arises. Adding another version of Python adds around 12 minutes to total CI time per commit, and tests cannot be run in parallel. Closes #115
Updated requests version pin to >=2.18. [Ash Wilson]

Removed requirements.txt file, which was unnecessary. The setup.py file is used by easy_install to ensure dependencies are in place. Closes #118

Other¶

Use uuid to generate random alert profile and server group name. [Hana Lee]

v1.1.4 (2018-03-12)¶

V1.1.4. [Jye Lee]

v1.1.3 (2018-03-08)¶

V1.1.3. [Jye Lee]

CS-479 add 429 exception chg: usr: Add TimeSeries().stop, which allows a cleaner exit for event/scan/issue streams.
V1.1.2 added merge multiple servers to server group. [Hana Lee]
CS-458 Python SDK: Move multiple servers into a target group. [Hana Lee]

v1.1.2 (2018-02-26)¶

V1.1.2 added merge multiple servers to server group. [Hana Lee]
CS-458 Python SDK: Move multiple servers into a target group. [Hana Lee]

v1.1.1 (2018-02-17)¶

Changes¶

Adding tests for TimeSeries() for events, scans, and issues endpoints. [Ash Wilson]
Adding docs for TimeSeries class. [Ash Wilson]

Other¶

V1.1.1. [Jye Lee]

v1.1 (2018-01-05)¶

V1.1. [Hana Lee]
CS-426 add Agent Upgrades class. [Hana Lee]
CS-428 Add CveDetails class. [Hana Lee]
CS-428 Add CveDetails class. [Hana Lee]
CS-429 add cve exceptions class. [Hana Lee]
Conflict. [Hana Lee]
CS-427 add processes endpoint to servers class. [Hana Lee]
CS-427 add processes endpoint to servers class. [Hana Lee]
Add Accept-Encoding ‘gzip’ [Jye Lee]
Add Accept-Encoding ‘gzip’ [Jye Lee]
CS-359 Added traffic discovery endpoint to Server and ServerGroup classes. [Hana Lee]
Rev to v1.0.6.8. [Jye Lee]
Rev to v1.0.6.7. [Jye Lee]
CS-322 Fix naming from Server to Issue. [Jye Lee]
V1.0.6.6. [Jye Lee]

flake8: expected 2 blank lines, found 1
This is it @2. [Hana Lee]
This is it. [Hana Lee]
Test: see travis. [Hana Lee]
Test:add +x. [Hana Lee]
Test: use travis.sh. [Hana Lee]
Test: edit yml. [Hana Lee]
Test: travis.sh. [Hana Lee]
Test: script onlt. [Hana Lee]
Test: added if statement. [Hana Lee]
Test: took up typo. [Hana Lee]
Added echo branch. [Hana Lee]
Test: added travis after_success. [Hana Lee]
Test: print env. [Hana Lee]
Test: run py.test. [Hana Lee]
Test: run test_wrapper.sh. [Hana Lee]
Test: added ls. [Hana Lee]
Test: remove –it. [Hana Lee]
Test: show docker images. [Hana Lee]
Test: added image id. [Hana Lee]
Test: put docker run in before_install. [Hana Lee]
Test: using docker exec to run test_wrapper.sh. [Hana Lee]
Added test_wrapper.sh. [Hana Lee]
Edited the changelog. [Hana Lee]
Added converge version lock. [Hana Lee]
Added email notification. [Hana Lee]
Fix logic in api_key_manager class. [Hana Lee]
Modified pagination for servers endpoint. [Hana Lee]
Fixed logic in api key manager. [Hana Lee]

rev init to 1.0.6.3
Fixed logic in api key manager. [Hana Lee]
Bug/CS-283 fix kwargs params if 500. [Jye Lee]

remove unexpected spaces around =
Rev to 1.0.6.2. [Jye Lee]
Bug CS-269 edit doc server_id to issue_id. [Jye Lee]

v1.0.6 (2017-05-01)¶

Rev to v1.0.6. [Jye Lee]
Fixed flake8. [Hana Lee]
Added LocalUserGroup to __init__.py Fixed typo in server.py. [Hana Lee]
Fixed status_code 500s. [Hana Lee]
CS-267 add local user account endpoint to SDK. [Hana Lee]
CS-269 add issues endpoint to the SDK. [Jye Lee]

added list_all, describe, and resolve methods
CS-259. [Jye Lee]

Add delayed retry to http helper
Added required openssl version and python version. [Hana Lee]

v1.0.5 (2017-02-18)¶

Changes¶

Improvents to list FIM baseline with detail information. [Hana Lee]

Other¶

Fixed Flake8 styling issue. [Hana Lee]
Changed the output FIM baseline to include more detail information. [Hana Lee]
Change the child server group name to avoid “Name Peer groups cannot have the same name” [Hana Lee]

v1.0.4 (2017-01-31)¶

Rev to v1.0.4. [Jye Lee]
Fixes firewall log paging. [Spencer Herzberg]

v1.0.3 (2017-01-24)¶

Changes¶

Improvements to server group creation, use grid-side input sanitization for post data. [Ash Wilson]

Other¶

Rev setup.py version to 1.0.3. [Jye Lee]
Rev to v1.0.3 to changelog. [Jye Lee]
Scan history should use since and until. [Spencer Herzberg]

v1.0.1 (2016-12-02)¶

Changes¶

Docker image now builds with git inside, syntax fix in testing script. Set default value in ApiKeyManager for api_port to 443. New testing procedure implemented and documented. [Ash Wilson]
Re-ordering operations in test_wrapper.sh to better converge testing file for api_key_manager.py. Altered unit tests to point to converged config file. Installed package in editable mode within container in order to get coverage module working. [Ash Wilson]
Changed values in portal.yaml file to facilitate testing automation with test_wrapper.sh. [Ash Wilson]
Added test_wrapper.sh to replace bare command in Dockerfile. This allows for dynamic testing behavior, depending on the environment variables passed into the container at runtime. [Ash Wilson]
Consolidated testing procedure in official, built docs. Links provided in README.rst and README.md to published docs containing testing procedure. [Ash Wilson]

Fix¶

Fix: test: Corrected logic for running codeclimate (thanks @mong2) [Ash Wilson]

Other¶

Remove -z from codeclimate if statement. [mong2]

v1.0 (2016-11-21)¶

Revert “remove whitelist and pagination for policies and events” [mong2]
Updating CHANGELOG. [Ash Wilson]
Changing version to 1.0, removing beta references. [Ash Wilson]
Adding unit tests for useragent string composition. [Ash Wilson]
Correcting ordering of user agent string composition. [Ash Wilson]
Adding integration strings to integration tests. [Ash Wilson]
Correcting UA string building logic. [Ash Wilson]
Formatting user agent more like RFC 2616 says we should. [Ash Wilson]
Fixed sanitizer. [Hana Lee]
Fixed server.py to align with flake8. [Hana Lee]
Added url sanitizer. [Hana Lee]
Fixed expires and comments in fim_baseline create. [Hana Lee]
Take out whitelist from event. [Hana Lee]
Updating server.py. [Jye Lee]
Remove supported_search_fields from servers. [Jye Lee]
Revert “remove whitelist and pagination for policies and events” [Jye Lee]

This reverts commit b78e40d52f08984623772417fea1660122584987.
Revert “remove supported_search fields and get_paginated for scan, server, and server_group class/tests” [Jye Lee]

This reverts commit 906b1e39e55b8155340cbae340d4e8e2c813f508.
Remove supported_search fields and get_paginated for scan, server, and server_group class/tests. [Jye Lee]
Remove whitelist and pagination for policies and events. [Hana Lee]
Correcting installation document. [Ash Wilson]
Documentation improvements. Building changelog into docs, adding version indicator to index. [Ash Wilson]
Adding links to built documentation. [Ash Wilson]
Improve README.rst formatting. [Ash Wilson]
Improving setup.py to include changelog in long description, which is published on PyPI. [Ash Wilson]

v0.101 (2016-10-18)¶

New¶

.gitchangelog.rc now takes latest version from cloudpassage/__init__.py. [Ash Wilson]

Fix¶

Flake8 correction in __init__.py. [Ash Wilson]
CS-66 Remove ImportError exception for unsupported Python version. [Ash Wilson]
CS-66 implement soft failure for wrong Python version. [Ash Wilson]
Correcting docs build isssues, change revision to v0.101. [Ash Wilson]

Other¶

Add all supported search fields for servers endpoint. [Jye Lee]

v0.100 (2016-10-11)¶

Fix¶

Typo = should be == in requirements-testing.txt. [Jye Lee]

Other¶

Adding CHANGELOG.md. [Ash Wilson]
Adding .gitchangelog.rc. [Ash Wilson]
Forget to && between commands. [Jye Lee]
Add apt-get install git to Dockerfile. [Jye Lee]
Add pytest-cov to requirements-testing and codeclimate pkg install to Dockerfile. [Jye Lee]
Clean up pep8 error blank line at end of file. [Jye Lee]
Add group_name to servers.list_all() supported fields Add parent_id to server groups create and update. [Jye Lee]
CS-55 fix get sam target_id to get linux only. [Jye Lee]
CS-53 swap the order of sdk_version_string and integration_string. [Jye Lee]
CS-41-2 remove sam last_scan_results retrieve. [Jye Lee]
Fixing testing deps. [Ash Wilson]
CS-33 adding documentation for exception kwargs. [Ash Wilson]
CS-37 Corrected bad path, which was breaking doc build. [Ash Wilson]
Documentation improvements. [Ash Wilson]
CS-40 Improve user_agent string composition. [Ash Wilson]
CS-39 added get_sdk_version() to utility. [Ash Wilson]
CS-2 missed import libraries. [Jye Lee]
CS-2 fix alert_profile, does not have a self.policy_key. [Jye Lee]
Pinning pyflakes to 1.2.3. [Ash Wilson]
CS-25 fixing spelling and variable naming in __init__.py. [Ash Wilson]
CS-25 correcting unnecessary import of sys module. [Ash Wilson]
CS-25 re-structuring version comparator. [Ash Wilson]
Adding travis-ci build badges for master and develop branches. [Ash Wilson]
Fixing docs for API key manager. [Ash Wilson]
CS-34 flake8 integration tests. [Ash Wilson]
CS-35 Make unit tests flake8 compliant. [Ash Wilson]
Sanitize exception error codes. [Ash Wilson]
CS-32 Re-tooling to work with flake8 v3.0. [Ash Wilson]
CS-23 pep8 event integration tests. [Ash Wilson]
Pointed to file that would be in an environment not configured for integrationt testing. [Ash Wilson]
Re-arranging tests for special events policy, getting rid of conflicting test for NotImplementedError exception. [Ash Wilson]
Fixes to ease transition to flake8. [Ash Wilson]
CS-31 moved from pep8 to flake8. [Ash Wilson]
Requirements file for testing added, updated dockerfile for flakes testing. [Ash Wilson]
Removing duplication detector- we will use pyflakes. [Ash Wilson]
First stab at codeclimate. [Ash Wilson]
Adding codeclimate badges to READMEs. [Ash Wilson]
CS-18 Adding RST for pypi pretties. [Ash Wilson]
Dockerfile-based travis config is now working. [Ash Wilson]
Fixing WORKDIR in Dockerfile. [Ash Wilson]
Add -y to apt-get install. [Ash Wilson]
Travis to use docker for testing SDK. [Ash Wilson]
Correcting grammar in LICENSE. [Ash Wilson]
Restructuring test script. [Ash Wilson]
First stab at .travis.yml. [Ash Wilson]
Added pyflakes config. [Ash Wilson]
CS-17 remove print and move bad_statuses into if. [Jye Lee]
CS-7 adding python veresion check. [Hana Lee]
CS-7 do not support less than python 2.7.10. [Jye Lee]
Used systemError and added unit test for python version CS-7. [Hana Lee]
All references to version number point back to __init__.py file. [Ash Wilson]
LICENSE. [Ash Wilson]

Adding license file

CS-8 added issues endpoint to server.py

Update test_integration_server.py

CS-8 update agent_firewall_logs to have pagination
DOC - Adding specific tested and supported minimum Python version. [Ash Wilson]
Cleaning up bad commit, redefined methods, and pep8 issues. [Ash Wilson]
Changed from repr to str method to prevent inclusion of superfluous quotes in string. [Ash Wilson]
Fixing pep8. [Ash Wilson]
Update gitignore. [Ash Wilson]
CS-14 Add ability and instructions for building PDF docs. [Ash Wilson]
CS-5 Change (true | false) to (bool) [Jye Lee]
CS-5 Add Critical to support search field for events, Added to DocString. [Jye Lee]
CS-2 CRUD for alert_profiles, Fixes squashed. [Jye Lee]
CS-3 Remove sam from supported_historical_scans list. [Jye Lee]
CS-3 Remove sam from supported_historical_scans list. [Jye Lee]
CS-4 Add Describe to Special Events Policies. [Jye Lee]
CS-6 update scan finding comment to include CSM and SVA. [Jye Lee]
Add exception message feature/CS-13. [Hana Lee]
Adding __str__ to exceptions. [mong2]

such that error messages will be printed

v0.99 (2016-09-02)¶

LICENSE. [Ash Wilson]

Adding license file
Improved parsing. [Ash Wilson]
Enhanced README. [Ash Wilson]
Changing to v0.99 for beta period. [Ash Wilson]
Adding requests to requirements.txt. [Ash Wilson]
Fixed pep8 issue with == vs is. [Ash Wilson]
Coe-230 force key and secret to string. [Ash Wilson]
Coe-229 fixed type issues with api key manager, rev setup to 1.0. [Ash Wilson]
Remove unnecessary print statement. [Ash Wilson]
Coe-191 coe-192 Tests use port number, soft fail-around for lack of key scope. [Ash Wilson]
COE-117 Add cleanup routines for better smoking. [Ash Wilson]
COE-158 fix get_sam_target. [Ash Wilson]
COE-158 fix get_sam_target. [Ash Wilson]
Adding test cases. [Ash Wilson]
Coe-153 Bring test coverage to 95% [Ash Wilson]
Coe-149 coe-150 pylint 10/10, deduplication of functionality. [Ash Wilson]
Coe-148 Corrected cyclic import issue in cloudpassage.sanity. [Ash Wilson]
Coe-152 Documentation update. [Ash Wilson]
Coe-152 Documentation update. [Ash Wilson]
Coe-151 Add instructions for new testing layout. [Ash Wilson]
Coe-131 coe-143 coe-147 update documentation, separate tests by type, pylint http_helper. [Ash Wilson]
Coe-144 coe-142 create test cases for new functions. [Ash Wilson]
Coe-133, 132, 130, 129, 128, 127 pylint cleanup. [Ash Wilson]
Coe-135, 136, 137, 138, 139 pylint cleanup. [Ash Wilson]
Coe-140 pylint 10/10 utility.py. [Ash Wilson]
Coe-141 Add docstrings to methods that will fail if run against an empty account. [Ash Wilson]
Coe-126 10/10 pylint for event.py. [Ash Wilson]
Coe-125 pylint 10/10 for congifiguration_policy.py. [Ash Wilson]
Coe-122 Pylint 10/10, removed overrides. Refactored api_key_manager.py. [Ash Wilson]
Coe-124 pylint __init__.py. [Ash Wilson]
Corrected docstrings for pylint. [Ash Wilson]
COE-118 pylint cloudpassage/ [Dave Doolin]
Completed testing docs. [Ash Wilson]
COE-120 bring test coverage to 90%, make corrections in FirewallBaseline. [Ash Wilson]
COE-85 Cleanup of test_halo.py, test coverage improvements. [Ash Wilson]
COE-109 Cleaned up api_key_manager a bit, added since/until query for scans. [Ash Wilson]
COE-111 COE-114 Added api key manager, refactored tests to be atomic, added docs. [Ash Wilson]
COE-112 Adding input sanity checking for URLs constructed from method args. [Ash Wilson]
Coe-65 Change fn to utility, refactor all the things. [Ash Wilson]
Coe-108 - also advancing version to 0.9.9. [Ash Wilson]
Coe-108 changed name to hostname. [Ash Wilson]
Coe-58 Added CVE exceptions query, tests, and docs. [Ash Wilson]
Added server group delete method. [Ash Wilson]
Coe-99 coe-100 Docmentation update. [Ash Wilson]
Coe-86 coe-102 Added Events, improved test coverage and documentation. [Ash Wilson]
Coe-104 coe-103 coe-60 coe-84 coe-98 coe-97 coe-96 coe-94 coe-90 coe-89 coe-88 coe-87. [Ash Wilson]
Coe-82 coe-92 coe-103 Implement inheritance for policies, cleanup docs and tests. Complete firewall module. [Ash Wilson]
Coe-101 Adding exclusion for html docs. [Ash Wilson]
Coe-81 adding coverage to test runner. [Ash Wilson]
Coe-18 autogenerating docs from docstrings. [Ash Wilson]
Coe-80 coe-48 clean out imp, old cpapi functions. [Ash Wilson]
Coe-73 Adding basic firewall policy management functionality. [Ash Wilson]
Coe-72 Wrapping up FIM module. [Ash Wilson]
Coe-71 Rounding off LIDS policy-related functionality. [Ash Wilson]
Coe-78 Corrected setup.py, .gitignore. [Ash Wilson]
Coe-74 rounding out server.Server functionality. [Ash Wilson]
Coe-75 Expanding scans module. [Ash Wilson]
Coe-77 Adding basedir and config for docs. [Ash Wilson]
Coe-70 Adding configuration policy CRUD. [Ash Wilson]
Coe-69 Added server.Server.describe() method. [Ash Wilson]
Coe-64 Added server command details method. [Ash Wilson]
Coe-68 adding ServerGroup.list_members() and tests. [Ash Wilson]
Coe-67 Improve scan initiator and test cases. [Ash Wilson]
Coe-63 Added scan initiator module. Some integration tests will be fulfilled by coe-66. [Ash Wilson]
Coe-59 Add fn.determine_policy_metadata() with tests. [Ash Wilson]
Coe-44 add Server.retire() [Ash Wilson]
Coe-55 add tests for fn.verify_pages() [Ash Wilson]
Coe-57 Adding tests for sanity.py. [Ash Wilson]
Coe-61 Adding SpecialEventsPolicy.list_all() [Ash Wilson]
Coe-56 Add server group update capabilities. [Ash Wilson]
Coe-51 Added pep8 checking to all tests and SDK, from within tests. [Ash Wilson]
Coe-54 Added get_paginated(), tests, and moved ServerGroup.list_all() to it. [Ash Wilson]
Coe-53 pep-8 all the things, stub out things too. [Ash Wilson]
Coe-52 Created SystemAnouncement class. [Ash Wilson]
Coe-42 Create method and test for describing server group. [Ash Wilson]
Coe-50 Corrected according to comments on merge request. [Ash Wilson]
Coe-47 adding HTTP method-specific components. [Ash Wilson]
COE-45 Added test cases pursuant to ticket details. [Ash Wilson]
COE-43 adding getServerDetails method. [Ash Wilson]
COE-20 Added updateServerGroup() w/ sanity checking. [Ash Wilson]
COE-40 Get halo.py passing pep8. [Ash Wilson]
COE-39 removing artifacted cpapi.py and cputils.py. [Ash Wilson]
Changing layout and naming of project, incorporating tests. [Ash Wilson]
Added initiateScan() COE-36. [Ash Wilson]
Added ldevlin’s getAnnouncements() COE-34. [Ash Wilson]
Deleting foo. [Ash Wilson]
Updated cpapi to add group delete feature. [Ash Wilson]
Testing. [Ash Wilson]
Adding requirements. [Ash Wilson]
Better catching of auth faulure. [Ash Wilson]
Merged diff from cpapi.py in cpapi examples repo with this one. See COE-9. [Ash Wilson]
Added authTokenScope for exposing key access level. [Ash Wilson]
Added gitignore. [Ash Wilson]
Create README.md. [Ash Wilson]
First commit for the CloudPassage Halo Python SDK. [Apurva Singh]