Welcome to pycska’s documentation!¶

pycska package¶

pycska.api module¶

class pycska.api.Api(cska_ip, client_id_or_json, client_secret=None, oauth1_token=None, oauth1_token_secret=None)[source]¶

Bases: object

Low level interface to the OAuth API provided by the CSKA.

Initialize instance of this class with the ip of the CSKA and your OAuth1 credentials. Create credentials in the CSKA user interface under Configuration->OAuth Clients.

Example instantiation:

CLIENT_ID = 'your-client-id'
CLIENT_SECRET = 'your-client-secret'
OAUTH_TOKEN = 'your-oauth1-token'
OAUTH_TOKEN_SECRET = 'your-oauth1-token-secret'
CSKA_IP = 'cska-ip'

api = Api(CSKA_IP, CLIENT_ID, CLIENT_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET)

The above code creates a new instance of this class to be used for all API functions below.

Methods

create_config_profile(profile_name[, …]) Used to create a config profile.

create_logging_plugin(name, ip_address, …) Create a logging plugin.

create_oauth_client(name, password[, …]) Create a new oauth client.

create_rule(rule_name, action, protocol, …) Create a regular filter rule.

create_rule_bpf(rule_name, action, custom_bpf) Create an advanced BPF filter rule.

create_security_group(group_name[, …]) Create a new security group.

create_ticket(priority, short_reason, …) Create a new support ticket.

create_user(user_name, full_name, password_clear) Create a new user.

delete_config_profile(config_profile_or_name) Delete a given configuration profile.

delete_config_profiles([config_profiles, …]) Delete the list of configuration profiles.

delete_logging_plugin(plugin_or_plugin_name) Update a logging plugin.

delete_logging_plugins([logging_plugins, …]) Delete the list of logging plugins.

delete_oauth_client(oauth_client_or_client_name) Delete a given oauth_client.

delete_oauth_clients(…) Deletes a list of oauth clients.

delete_overlay() Delete the network overlay JSON used to overlay non channel locked devices on to the network graph.

delete_rule(rule_or_rule_name) Delete a specific user rule.

delete_rules([rules, delete_all]) Delete the list of rules.

delete_seat(seat) Revoke the specified seat.

delete_security_group(group_or_group_name) Delete a security group.

delete_security_groups([…]) Delete a list of security groups.

delete_stats([device_or_device_name, …]) Clear the stats for a given device or seat.

delete_threats([threats, delete_all]) Delete a list of threats or all threats.

delete_user(user_or_user_name) Delete a user.

delete_users(users) Delete a list of users.

do_block([devices_or_device_names, seats]) Block a list of devices or devices with the given seat licenses.

do_unblock([devices_or_device_names, seats]) Unblock a list of devices or devices with the given seat licenses.

get_capture(threat_or_threat_id) Get the contents of a packet capture generated from a given threat_id.

get_config_profile([profile_name, profile_id]) Get a specific configuration profile by id or by name.

get_config_profiles() Get the list of configuration profiles.

get_device([device_name, device_id]) Get the a specific device by device_id or by device_name.

get_devices([device_name, device_id, …]) Get a list of all devices.

get_licenses([license_types]) Get a list of all the licenses granted to the account.

get_logging_plugin(plugin_name) Get a logging plugin by name.

get_logging_plugins() Get the list of logging plugins.

get_logs_by_date(from_date, to_date[, …]) Get the logs from the CSKA over a date range.

get_network_graph() Get a JSON representation of the network graph.

get_oauth_client([client_name, client_id]) Get an oauth client by client_name or client_id.

get_oauth_client_secret(…) Get an oauth client secret tokens for a given oauth client.

get_oauth_clients([client_names]) Get the list of oauth clients.

get_oauth_state() Get the state of the OAuth API Explorer.

get_overlay() Get the network overlay JSON used to overlay non channel locked devices on to the network graph.

get_remote_support() Get the state of remote support ssh access.

get_rule([rule_name, rule_id]) Get a specific user rule.

get_rules([rule_name, rule_id]) Get a list of the user rules.

get_security_group([group_name, group_id]) Get the a specific security group by group_id or by group_name.

get_security_groups() Get all security groups.

get_stats([device_or_device_name, …]) Get the stats for a given device or seat.

get_system_status() Get the current system status.

get_threats([start, limit, …]) Get the current list of threats.

get_user([user_name]) Get a user by user name.

get_user_certificate(user_or_user_name) Get a user certificate by user or user_name.

get_user_certificate_state() Gets whether user certifcates are enforced.

get_users() Get all the users.

get_version() Get the current version of the CSKA.

update_config_profile(config_profile) Used to update a config profile.

update_device(device) Used to update a device.

update_logging_plugin(plugin) Update a logging plugin.

update_logging_plugins(logging_plugins) Used to set the entire list of logging plugins.

update_oauth_client(oauth_client[, …]) Used to update/create an OAuth client.

update_oauth_state(is_enabled) Set the state of the OAuth API Explorer.

update_overlay(overlay_contents) Set the network overlay JSON used to overlay non channel locked devices on to the network graph.

update_remote_support(is_on) Set the state of remote support ssh access.

update_rule(rule) Update a specific user rule or create a new rule.

update_seat(device, infersight_license) Assign the given InferSight license to the device.

update_security_group(group) Used to create or update a security_group

update_threats(ack_state[, threats, modify_all]) Update the acknowledged state on a list of threats or on all threats.

update_user(user[, password_clear]) Update a user.

update_user_certificate_state(force_certificates) Sets whether user certifcates are enforced.

create_config_profile(profile_name, license_renew_time=7200, log_level='Info', capture_threats=True, syslog_filter='')[source]¶

Used to create a config profile.

Parameters:

profile_name (String) – Name to assign to config profile.
license_renew_time (Integer) – Optional - amount of seconds between license renew.
log_level (String) – Optional - log level for devices using this profile.
capture_threats (Boolean) – Optional - do validators attempt to capture threats.
syslog_filter – Optional - do validators listen to third party syslog sources.

Return type:

Type pycska.basetypes.ConfigProfile

Example usage:

profile = api.create_config_profile('Test Profile', 3600, 'Error')

The above code creates a new profile with the name Test Profile, a renew time of 1 hour, and with a log level of Error.

create_logging_plugin(name, ip_address, port, protocol, url='', rfc3164=False)[source]¶

Create a logging plugin.

Parameters:

name (String) – Name of new logging plugin.
ip_address (String) – Address of the logging store.
port (Integer) – Port logging store is listening on.
protocol (String) – Protocol the logging store is listening for - UDP, TCP.
url (String) – Optional - landing page for the logging store.
rfc3164 (Boolean) – Optional - is the logging store expecting rfc3164 compliant logs.

Return type:

Type pycska.basetypes.LoggingPlugin

Example usage:

new_plugin = api.create_logging_plugin('New Logging Plugin', '1.1.1.1', 10000, 'UDP')

Creates a new logging plugin.

create_oauth_client(name, password, description='', allow_oauth1=True, allow_oauth2=False, default_scopes_list=None, redirect_uris_list=None)[source]¶

Create a new oauth client.

Parameters:

name (String) – Name to assign to new client.
password (String) – Clear text password to give to client for retrieving secret tokens.
description (String) – Optional - description for client.
allow_oauth1 (Boolean) – Optional - is oauth1 allowed.
allow_oauth2 (Boolean) – Optional - is oauth2 allowed.
default_scopes_list (String) – Optional - comma separated list of scopes. Default is fine.
redirect_uris_list (String) – Optional - comma separated list of redirects. Default is good for internal Mulesoft API explorer.

Return type:

Type pycska.basetypes.OAuthClient

Example usage:

new_client = api.create_oauth_client('New Client', 'mypassword', allow_oauth1=True)

Creates a new oauth client.

create_rule(rule_name, action, protocol, start_port, end_port, src_cidr, dst_cidr, layer=3, hash_algorithm='xor', include_dos_protection=True, description='')[source]¶

Create a regular filter rule.

Parameters:

rule_name (String) – Name to assign to rule.
action (String) – Action to perform on a rule match. Example RULE_ACTION_SIGN.
protocol (String) – Protocol that rule applies to. Example RULE_PROTOCOL_UDP.
start_port (Integer) – Starting port that the rule applies to.
end_port (Integer) – Starting port that the rule applies to.
src_cidr (String) – CIDR range that applies to the src ip address. Can specify Any, Public, or proper CIDR address, i.e. 192.168.0.0/24
dst_cidr (String) – CIDR range that applies to the dst ip address. Can specify Any, Public, or proper CIDR address, i.e. 192.168.0.0/24
layer (Integer) – Optional - lowest layer to apply rule to.
hash_algorithm (String) – Optional - hash applied. Example RULE_HASH_ALGORITHM_XOR.
include_dos_protection (Boolean) – Optional - whether additonal header is added to help protected against DOS attacks.
description (String) – Optional - description for rule.

Return type:

Type pycska.basetypes.Rule

Example usage:

new_rule = api.create_rule('New Rule', RULE_ACTION_SIGN, RULE_PROTOCOL_UDP, 20000, 30000,
                           '192.168.0.0/24', 'Public')

Creates a new signing rule that will match UDP packets between ports 20000 and 30000 with a source ip in the subnet 192.168.0.0/24 and with a public destination address.

create_rule_bpf(rule_name, action, custom_bpf, layer=3, hash_algorithm='xor', include_dos_protection=True, description='')[source]¶

Create an advanced BPF filter rule.

Parameters:

rule_name (String) – Name to assign to rule.
action (String) – Action to perform on a rule match. Example RULE_ACTION_SIGN.
custom_bpf (String) – Advanced BPF string for filter. CSKA will validate.
layer (Integer) – Optional - lowest layer to apply rule to.
hash_algorithm (String) – Optional - hash applied. Example RULE_HASH_ALGORITHM_XOR.
include_dos_protection (Boolean) – Optional - whether additonal header is added to help protected against DOS attacks.
description (String) – Optional - description for rule.

Return type:

Type pycska.basetypes.Rule

Example usage:

new_rule = api.create_rule_bpf('New Rule', RULE_ACTION_SIGN, 'host 1.1.1.1')

Creates a new BPF signing rule.

create_security_group(group_name, description='', signer_rules=None, validator_rules=None, validates_groups=None)[source]¶

Create a new security group.

Parameters:

group_name (String) – Name to give new security group. Must be unique.
description (String) – Optional - description for new group.
signer_rules (List of pycska.basetypes.Rule) – Optional - rules to apply for signers in the group.
validator_rules (List of pycska.basetypes.Rule) – Optional - rules to apply for validators in the group.
validates_groups (List of pycska.basetypes.SecurityGroup) – Optional - which groups will be validated.

Return type:

New security group - pycska.basetypes.SecurityGroup

Example usage:

signer_rule = api.get_rule('Sign')
validator_rule = api.get_rule('Validate Internal')
group = api.create_security_group('My Group', '', [signer_rule], [validator_rule])

The above code gets a signer and validator rule and creates a new security group using these rules.

create_ticket(priority, short_reason, long_reason, use_remote_support)[source]¶

Create a new support ticket.

Parameters:	priority (Integer) – Priority of support ticket (1-Critical, 2-Service Affecting, 3-General) short_reason (String) – Short description of issue. long_reason (String) – Long description of issue. use_remote_support (Boolean) – Should remote access be allowed to support.
Return type:	Not applicable

Example usage:

api.create_ticket(1, 'Short Reason', 'Long Reason', True)

The above code submits a ticket to support and enables remote access.

create_user(user_name, full_name, password_clear)[source]¶

Create a new user.

Parameters:	user_name (String) – Name that is used to login to the CSKA. full_name (String) – Full name of user for display purposes. password_clear (String) – Password of new user. User will be asked to change on first login.
Return type:	Type `pycska.basetypes.User`

Example usage:

new_user = api.create_user('jsmith', 'John Smith', 'goodpassword')

The above code creates a new user with the login jsmith.

delete_config_profile(config_profile_or_name)[source]¶

Delete a given configuration profile.

Parameters:	config_profile_or_name (Type `pycska.basetypes.ConfigProfile` or String) – Configuration profile to delete.
Return type:	Not applicable

Example usage:

test_profile = api.get_config_profile('Test Profile')
api.delete_config_profile(test_profile)

The above code gets the Test Profile configuration profile and deletes it.

delete_config_profiles(config_profiles=None, delete_all=False)[source]¶

Delete the list of configuration profiles.

Parameters:	config_profiles (List of `pycska.basetypes.ConfigProfile`) – List of config profiles to delete. delete_all (Boolean) – Are we deleting all config profiles.
Return type:	Not applicable

Example usage:

profile1 = api.get_config_profile('Profile 1')
profile2 = api.get_config_profile('Profile 2')
profile3 = api.get_config_profile('Profile 3')
api.delete_config_profiles([profile1, profile2, profile3])

The above code gets and deletes profile1, profile2, and profile3.

delete_logging_plugin(plugin_or_plugin_name)[source]¶

Update a logging plugin.

Parameters:	plugin_or_plugin_name (`pycska.basetypes.LoggingPlugin`) – Plugin to update.
Return type:	Not applicable

Example usage:

api.delete_logging_plugin('My Logging Plugin')

The above code deletes the plugin named My Logging Plugiin.

delete_logging_plugins(logging_plugins=None, delete_all=False)[source]¶

Delete the list of logging plugins.

Parameters:	logging_plugins (List of `pycska.basetypes.LoggingPlugin`) – List of logging plugins to delete. delete_all (Boolean) – Are we deleting all logging plugins.
Return type:	Not applicable

Example usage:

plugins = api.get_logging_plugins()
udp_plugins = [plugin for plugin in plugins if plugin.protocol.lower() == 'udp']
api.delete_logging_plugins(udp_plugins)

The above commands get the list of udp plugins and then deletes them.

delete_oauth_client(oauth_client_or_client_name)[source]¶

Delete a given oauth_client.

Parameters:	oauth_client_or_client_name (Type `pycska.basetypes.OAuthClient` or String) – OAuth client to delete.
Return type:	Not applicable

Example usage:

api.delete_oauth_client('New Client')

Delete an oauth client by name.

delete_oauth_clients(oauth_clients_or_client_names)[source]¶

Deletes a list of oauth clients.

Parameters:	oauth_clients_or_client_names (List of `pycska.basetypes.OAuthClient` or String) – OAuth clients to delete.
Return type:	Not applicable

Example usage:

clients = api.get_oauth_clients()
clients_to_delete = [client for client in clients                                  if 'other' in client.default_scopes_list]
api.delete_oauth_clients(clients_to_delete)

Deletes all the oauth clients that have ‘other’ in their default scopes.

delete_overlay()[source]¶

Delete the network overlay JSON used to overlay non channel locked devices on to the network graph.

Return type:	Not applicable.

Example usage:

api.delete_overlay(overlay_contents)

Deletes network overlay file.

delete_rule(rule_or_rule_name)[source]¶

Delete a specific user rule.

Parameters:	rule_or_rule_name (Type `pycska.basetypes.Rule` or String.) – Rule to delete.
Return type:	Not applicable

Example usage:

api.delete_rule('New Rule')

Deletes the rule with the name New Rule.

delete_rules(rules=None, delete_all=False)[source]¶

Delete the list of rules.

Parameters:	rules (List of `pycska.basetypes.Rule`) – List of user rules to delete. delete_all (Boolean) – Are we deleting all user rules.
Return type:	Not applicable

Example usage:

rule = api.get_rule('New Rule')
api.delete_rules([rule])

The above code deletes a list of rules.

delete_seat(seat)[source]¶

Revoke the specified seat.

Parameters:	seat (Type `pycska.basetypes.Seat`) – Seat to revoke.
Return type:	Not applicable.

Example usage:

device = api.get_device('test-signer-0')
api.delete_seat(device.validator_seat)

Delete the validator seat that is on the device with name test-signer-0.

delete_security_group(group_or_group_name)[source]¶

Delete a security group.

Parameters:	group_or_group_name (Type `pycska.basetypes.SecurityGroup` or String) – Group to delete.
Return type:	Not applicable

delete_security_groups(groups_or_group_names=None, delete_all=False)[source]¶

Delete a list of security groups.

Parameters:	groups_or_group_names (List of `pycska.basetypes.SecurityGroup`) – Groups to delete. delete_all (Boolean) – Are we deleting all config profiles.
Return type:	Not applicable

Example usage:

api.delete_security_groups(['My Group', 'My Group2'])

Deletes the security groups with names My Group and My Group2.

delete_stats(device_or_device_name=None, seat_or_seat_id=None)[source]¶

Clear the stats for a given device or seat.

Parameters:	device_or_device_name (Type `pycska.basetypes.Device` or String) – Optional - device to clear stats for. seat_or_seat_id (Type `pycska.basetypes.Seat` or String) – Optional - seat license to clear stats for.
Return type:	Not applicable

Example usage:

api.delete_stats('test-signer-0')

Clear stats for the device with name test-signer-0.

delete_threats(threats=None, delete_all=False)[source]¶

Delete a list of threats or all threats.

Parameters:	threats (List of `pycska.basetypes.Threat`) – Optional threat(s) to delete. delete_all (Boolean) – Optional flag indicating if all threats are to be deleted.
Return type:	Not applicable

Example usage:

threats, total = api.get_threats(0, 10)
api.delete_threats(True, threats)

The above code deletes the most recent 10 threats.

delete_user(user_or_user_name)[source]¶

Delete a user. The CSKA will not delete the default admin user.

Parameters:	user_or_user_name (Type `pycska.basetypes.User` or String) – User to delete.
Return type:	Not applicable

Example usage:

api.delete_user('jsmith')

The above code will delete the user with the username jsmith.

delete_users(users)[source]¶

Delete a list of users. The CSKA will not delete the default admin user.

Parameters:	users (List of `pycska.basetypes.User`) – List of Users to delete.
Return type:	Not applicable

Example usage:

users = api.get_users()
api.delete_users(users)

The above code is used to delete all the users. Note that the CSKA will not delete the default admin user.

do_block(devices_or_device_names=None, seats=None)[source]¶

Block a list of devices or devices with the given seat licenses. Devices can be specified either as a list of pycska.basetypes.Device or as a list of device names.

Parameters:	devices_or_device_names (List of `pycska.basetypes.Device` or String) – Optional Device objects or device names to block. seats (List of `pycska.basetypes.Seat`) – Optional Id or Ids representing the seat(s) to block.
Return type:	An integer representing the number of devices blocked.

Example usage:

api.do_block(['test-signer-0', 'test-validator-0'])

The above blocks access to devices with the names test-signer-0 and test-validator-0.

do_unblock(devices_or_device_names=None, seats=None)[source]¶

Unblock a list of devices or devices with the given seat licenses. Devices can be specified either as a list of pycska.basetypes.Device or as a list of device names.

Parameters:	devices_or_device_names (List of `pycska.basetypes.Device` or String) – Optional Device objects or device names to unblock. seats (List of `pycska.basetypes.Seat`) – Optional Id or Ids representing the seat(s) to unblock.
Return type:	An integer representing the number of devices unblocked.

Example usage:

api.do_unblock(['test-signer-0', 'test-validator-0'])

The above unblocks access to devices with the names test-signer-0 and test-validator-0.

get_capture(threat_or_threat_id)[source]¶

Get the contents of a packet capture generated from a given threat_id.

Parameters:	threat_or_threat_id (`pycska.basetypes.Threat` or String) – Threat to get a capture for.
Return type:	The raw contents of the pcap.

Example usage:

threats, total = api.get_threats(0, 100)
capture = api.get_capture(threats[0].threat_id)
open('capture.pcap', 'wb+').write(capture)

The above code gets the most recent 100 threats and then gets the pcap for the most recent threat and writes to capture.pcap.

get_config_profile(profile_name=None, profile_id=None)[source]¶

Get a specific configuration profile by id or by name.

Parameters:	profile_name (String) – Optional value to filter the results on. profile_id (Integer) – Optional value to filter the results on.
Return type:	Type `pycska.basetypes.ConfigProfile`

Example usage:

profile = api.get_config_profile('Default')

The above code gets the config profile with the name Default.

get_config_profiles()[source]¶

Get the list of configuration profiles.

Return type:	List of `pycska.basetypes.ConfigProfile`

Example usage:

profiles = api.get_config_profiles()

The above code gets the list of configuration profiles.

get_device(device_name=None, device_id=None)[source]¶

Get the a specific device by device_id or by device_name.

Parameters:	device_name (String) – Optional value to filter the results on. device_id (Integer) – Optional value to filter the results on.
Return type:	Type `pycska.basetypes.Device`

Example usage:

device = api.get_device('test-signer-0')

The above code gets a device with the name test-signer-0.

get_devices(device_name=None, device_id=None, license_types=None)[source]¶

Get a list of all devices.

Parameters:	device_name (String) – Optional value to filter the results on. device_id (Integer) – Optional value to filter the results on. license_types (List of String) – Optional list of licenses to filter on, `LICENSE_TYPE_CSKA`, `LICENSE_TYPE_SIGNER`, `LICENSE_TYPE_VALIDATOR`, `LICENSE_TYPE_ALL`.
Return type:	List of `pycska.basetypes.Device`

Example usage:

devices = api.get_devices(license_types=[LICENSE_TYPE_SIGNER])

The above code will get all devices that are signers.

get_licenses(license_types=None)[source]¶

Get a list of all the licenses granted to the account.

Parameters:	license_types – Which license types to grab or leave unspecified to get all.
Return type:	List of `pycska.basetypes.License`

Example usage:

licenses = api.get_licenses()

The above code is used to get the list of licenses granted to the account.

get_logging_plugin(plugin_name)[source]¶

Get a logging plugin by name.

Parameters:	plugin_name (String) – Name of plugin to get.
Return type:	Type `pycska.basetypes.LoggingPlugin`

Example usage:

plugin = api.get_logging_plugin('My Logging Plugin')

Get the plugin named My Logging Plugin.

get_logging_plugins()[source]¶

Get the list of logging plugins.

Return type:	List of `pycska.basetypes.LoggingPlugin`

Example usage:

plugins = api.get_logging_plugins()

The above command gets the list of logging plugins.

get_logs_by_date(from_date, to_date, is_usage=False, format_as='json')[source]¶

Get the logs from the CSKA over a date range.

Parameters:	from_date (Integer) – Date to start retrieving logs from - seconds since epoch (UTC) to_date (Integer) – Date to end retrieving logs from - seconds since epoch (UTC) is_usage (Boolean) – Usage or System logs. format_as (String) – Type of output - either json, raw, or csv
Return type:	String depending on format_as

Example usage:

from_date = time.time() - 60*60*24*7
to_date = time.time()
logs = api.get_logs_by_date(from_date, to_date, is_usage=False, format_as='json')

Retrieves the last week of logs.

get_network_graph()[source]¶

Get a JSON representation of the network graph.

Return type:	JSON object showing the nodes and edges in the network.

Example usage:

graph = api.get_network_graph()

The above command gets the current nework topology.

get_oauth_client(client_name=None, client_id=None)[source]¶

Get an oauth client by client_name or client_id.

Parameters:	client_name (String) – Name of oauth client to retrieve. client_id (String) – Id of oauth client to retrieve.
Return type:	Type `pycska.basetypes.OAuthClient`

Example usage:

client = api.get_oauth_client('New Client')

Gets the oauth client with the name New Client.

get_oauth_client_secret(oauth_client_or_client_name, client_password)[source]¶

Get an oauth client secret tokens for a given oauth client.

Parameters:	oauth_client_or_client_name (Type `pycska.basetypes.OAuthClient` or String) – Client to update. client_password (String) – Client password. Used to unlock the tokens.
Return type:	Type `pycska.basetypes.OAuthClientSecret`

Example usage:

secret = api.get_oauth_client_secret('New Client', 'mypassword')

Get the oauth client secret given a client name and password.

get_oauth_clients(client_names=None)[source]¶

Get the list of oauth clients.

Parameters:	client_names (List of String) – Optional list of names to filter results on.
Return type:	List of `pycska.basetypes.OAuthClient`

Example usage:

clients = api.get_oauth_clients()

Gets a list of all the oauth clients.

get_oauth_state()[source]¶

Get the state of the OAuth API Explorer.

Return type:	Boolean indicating if the API Explorer is enabled.

Example usage:

state = api.get_oauth_state()

Returns whether or not the internal oauth browser is enabled.

get_overlay()[source]¶

Get the network overlay JSON used to overlay non channel locked devices on to the network graph.

Return type:	String

Example usage:

overlay_contents = api.get_overlay()

Returns contents of network overlay file.

get_remote_support()[source]¶

Get the state of remote support ssh access.

Return type:	Boolean indicating whether SSH access is allowed.

Example usage:

is_on = api.get_remote_support()

Returns whether or not remote access is enabled.

get_rule(rule_name=None, rule_id=None)[source]¶

Get a specific user rule.

Parameters:	rule_name (Integer) – Optional value to filter the results on. rule_id (Integer) – Optional value to filter the results on.
Return type:	Type `pycska.basetypes.Rule`

Example usage:

rule = api.get_rule('New Rule')

Get the rule with the name New Rule.

get_rules(rule_name=None, rule_id=None)[source]¶

Get a list of the user rules.

Parameters:	rule_name (String) – Optional value to filter the results on. rule_id (Integer) – Optional value to filter the results on.
Return type:	List of `pycska.basetypes.Rule`

Example usage:

rules = api.get_rules()

The above code gets a list of rules.

get_security_group(group_name=None, group_id=None)[source]¶

Get the a specific security group by group_id or by group_name.

Parameters:	group_name (String) – Optional value to filter the results on. group_id (Integer) – Optional value to filter the results on.
Return type:	Type `pycska.basetypes.SecurityGroup`

Example usage:

group = api.get_security_group('Test Group')

Gets all the security groups created with the CSKA.

get_security_groups()[source]¶

Get all security groups.

Return type:	List of `pycska.basetypes.SecurityGroup`

Example usage:

groups = api.get_security_groups()

Gets all the security groups created with the CSKA.

get_stats(device_or_device_name=None, seat_or_seat_id=None)[source]¶

Get the stats for a given device or seat.

Parameters:	device_or_device_name (Type `pycska.basetypes.Device` or String) – Optional - device to get stats for. seat_or_seat_id (Type `pycska.basetypes.Seat` or String) – Optional - seat license to get stats for.
Return type:	List of `pycska.basetypes.Stats`

Example usage:

stats = api.get_stats('test-signer-0')

Get stats for the device with name test-signer-0.

get_system_status()[source]¶

Get the current system status.

Return type:	Type `pycska.basetypes.SystemStatus`

Example usage:

status = api.get_system_status()

Gets the current system status summary.

get_threats(start=0, limit=None, load_acknowledged=False, threat_filter_list=None, get_device=True)[source]¶

Get the current list of threats.

Parameters:

start (Integer) – Index to start getting threats from - 0 based and start from most recent.
limit (Integer) – Max number of threats to return.
load_acknowledged (Boolean) – Load acknowledged as well as unacknowledged threats.
threat_filter_list (List of Strings) – Optional list of strings to filter threats on.
get_device (Boolean) – For each threat do we attempt to lookup the device that caused the threat.

Return type:

Tuple (List of pycska.basetypes.Threat, Number of threats)

Example usage:

threats, total = api.get_threats(0, 100)

Gets the most recent 100 threats. The variable total contains the total number of theats that could be retrieved.

get_user(user_name=None)[source]¶

Get a user by user name.

Parameters:	user_name (String) – User name used to login to CSKA.
Return type:	Type `pycska.basetypes.User`

Example usage:

user = api.get_user('admin')

The above code gets the admin user.

get_user_certificate(user_or_user_name)[source]¶

Get a user certificate by user or user_name.

Parameters:	user_or_user_name (Type `pycska.basetypes.User` or String) – User to login to CSKA.
Return type:	String

Example usage:

cert = api.get_user_certificate('jsmith')

The above code will retrieve the certificate for the given user.

get_user_certificate_state()[source]¶

Gets whether user certifcates are enforced.

Return type:	Boolean

Example usage:

force_certs = api.get_user_certificate_state()

The above code gets whether or not the CSKA is enforcing user side SSL certificates.

get_users()[source]¶

Get all the users.

Return type:	List of `pycska.basetypes.User`

Example usage:

users = api.get_users()

The above code is used to get a list of all users created on the CSKA.

get_version()[source]¶

Get the current version of the CSKA.

Return type:	String

Example usage:

version = api.get_version()

The above code will get the current version of software running on the CSKA.

update_config_profile(config_profile)[source]¶

Used to update a config profile.

Parameters:	config_profile (Type `pycska.basetypes.ConfigProfile`) – Config profile to update.
Return type:	Integer representing the profile id of the profile created or updated.

Example usage:

default_profile = api.get_config_profile('Default')
default_profile.configuration.log_level = 'Error'
api.update_config_profile(default_profile)

The above code updates the log_level on the Default profile to Error.

update_device(device)[source]¶

Used to update a device. Only the profile and security groups are updated.

Parameters:	device (Type `pycska.basetypes.Device`) – Device to update.
Return type:	Integer representing the profile id of the profile created or updated.

Example usage:

profile = api.get_config_profile('Test Profile')
device = api.get_device('test-signer-0')
device.profile = profile
api.update_device(device)

The above code will update the configuration profile to Test Profile for the device with the name test-signer-0.

update_logging_plugin(plugin)[source]¶

Update a logging plugin.

Parameters:	plugin (`pycska.basetypes.LoggingPlugin`) – Plugin to update.
Return type:	Type `pycska.basetypes.LoggingPlugin`

Example usage:

plugin = api.get_logging_plugin('New Plugin')
plugin.port = 15000
api.update_logging_plugin(plugin)

The above code gets the plugin name New Plugin and updates the port to 15000.

update_logging_plugins(logging_plugins)[source]¶

Used to set the entire list of logging plugins.

Parameters:	logging_plugins (List of `pycska.basetypes.LoggingPlugin`) – List of logging plugins to update to.
Return type:	Not applicable

Example usage:

plugins = api.get_logging_plugins()
plugins[0].port = 20000
api.update_logging_plugins(plugins)

The above command gets the list of plugins and modifies the port on the first one to 20000.

update_oauth_client(oauth_client, client_password=None, reset_token=False)[source]¶

Used to update/create an OAuth client. Fields like ‘name’ and the ‘password’ are immutable.

Parameters:	oauth_client (Type `pycska.basetypes.OAuthClient`) – OAuth client to update. client_password (String) – Client password. Only relevant for new oauth clients. reset_token (False) – Should the oauth keys be reset.
Return type:	String representing the client id.

Example usage:

client = api.get_oauth_client('New Client')
client.description = "Needed a description"
api.update_oauth_client(client)

The above code adds a description to an existing oauth client.

update_oauth_state(is_enabled)[source]¶

Set the state of the OAuth API Explorer.

Parameters:	is_enabled (Boolean) – Is The OAuth API Explorer enabled.
Return type:	Not applicable.

Example usage:

api.update_oauth_state(False)

Updates whether or not the internal oauth browser is enabled.

update_overlay(overlay_contents)[source]¶

Set the network overlay JSON used to overlay non channel locked devices on to the network graph.

Parameters:	overlay_contents (String) – Contents of overlay file.
Return type:	Not applicable.

Example usage:

api.update_overlay(overlay_contents)

Updates contents of network overlay file.

update_remote_support(is_on)[source]¶

Set the state of remote support ssh access.

Parameters:	is_on (Boolean) – Is SSH access to be enabled.
Return type:	Not applicable.

Example usage:

api.update_remote_support(False)

Turn off remote ssh access.

update_rule(rule)[source]¶

Update a specific user rule or create a new rule.

Parameters:	rule (Type `pycska.basetypes.Rule`) – Rule to update/create. Leave rule_id blank to create a new rule.
Return type:	Integer - rule_id

Example usage:

rule = api.get_rule('New Rule')
rule.description = 'My good description'
api.update_rule(rule)

The above code will set the description on an existing rule.

update_seat(device, infersight_license)[source]¶

Assign the given InferSight license to the device.

Parameters:	device (Type `pycska.basetypes.Device`) – Device to assign license to. infersight_license (Type `pycska.basetypes.License`) – License to assign to device.
Return type:	Type `pycska.basetypes.Seat`

Example usage:

signer_license = api.get_licenses([LICENSE_TYPE_SIGNER])[0]
device = api.get_device('test-signer-0')
api.update_seat(device, signer_license)

Adds a signer license to the device with name test-signer-0.

update_security_group(group)[source]¶

Used to create or update a security_group

Parameters:	group (Type `pycska.basetypes.SecurityGroup`) – Security group to create or update.
Return type:	Integer representing the group id of the profile created or updated.

Example usage:

group = api.get_security_group('Test Group')
group.description = 'New Description'
api.update_security_group(group)

Changes the description of a group to New Description.

update_threats(ack_state, threats=None, modify_all=False)[source]¶

Update the acknowledged state on a list of threats or on all threats.

Parameters:	ack_state (Boolean) – Flag indicating the new state of the threat(s). threats (List of `pycska.basetypes.Threat`) – Optional threat(s) to update the ack state for. modify_all (Boolean) – Optional flag indicating if all threats are to be updated.
Return type:	Not applicable

Example usage:

threats, total = api.get_threats(0, 10)
api.update_threats(True, threats)

The above code acknowledges the most recent 10 threats.

update_user(user, password_clear=None)[source]¶

Update a user.

Parameters:	user (Type `pycska.basetypes.User`) – User to update or create. password_clear (String) – New password for user.
Return type:	Not applicable

Example usage:

user = api.get_user('jsmith')
user.full_name = 'John D Smith'
api.update_user(user)

The above code is used to update a user’s full name.

update_user_certificate_state(force_certificates)[source]¶

Sets whether user certifcates are enforced.

Parameters:	force_certificates (Boolean) – Are user certficates forced.
Return type:	Not applicable

Example usage:

api.update_user_certificate_state(True)

The above code sets the CSKA to force user side SSL certificates.

pycska.basetypes module¶

API Data Types used in pycska.

class pycska.basetypes.CSKAType(raw_type=None)[source]¶

Bases: object

Base type for all complex types used in the CSKA API.

Must be subclassed by every complex type and each subclass must at the very least implement the fields property getter. This property defines all the fields that are allowed in the type. By default there is a 1:1 mapping of the field names specified in fields with the field names actually used in the API. However, if the API changes we can keep the same field names in this file and simply implement the _field_overrides getter and specify the new mapping. For instance in the ConfigProfile class below:

@property
def _field_overrides(self):
    return {'configuration':'config'}

In the above case, the configuration field used in the CSKA Api was renamed to config in the software. In order to keep users of this file from having to change, we can simply specify the mapping above.

to_dict()[source]¶

Convert back into a dictionary form that can be used for the actual API call.

Return type:	Dictionary of fields relevant to the child type.

class pycska.basetypes.ConfigProfile(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Configuration profile for a device.

Configuration profiles are specified with the following fields:

profile_id (int): Id representing profile - leave empty for new profiles.
profile_name (string): Name to give profile.
configuration: Type pycska.basetypes.ProfileDetails

class pycska.basetypes.Device(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Details for a device.

Device details are specified with the following fields:

device_id (int): Internal Id representing the device.
device_name (string): Usually the hostname for the device.
number_interfaces (int): Number of physical interfaces (Not implemented on Windows).
platform_name (string): Linux, Windows.
profile: Type pycska.basetypes.ConfigProfile
is_blocked (bool): Is the device currently blocked.
is_signer (bool): Is the device a signer.
signer_seat: Type pycska.basetypes.Seat.
is_validator (bool): Is the device a validator.
validator_seat: Type pycska.basetypes.Seat.
is_online (bool): Is the device currently online.
security_groups: List of pycska.basetypes.SecurityGroupSummary
allocated_licenses: Object where key is the license type and value is the seat id.
requested_licenses: Object where key is the license type and value is timestamp when

license was requested (seconds since epoch). Only licenses that have not been allocated yet stay in this object. Also, licenses that haven’t been requested for after a period of time will get removed. This happens if a device that is unallocated is offline and is no longer requesting a license.

class pycska.basetypes.License(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Infersight License.

Licenses are specified with the following fields:

license_id (int): Internal Id representing the Id for the given type of license.
amount (int): Number of this type of license granted to organization.
license_type (string): License name - i.e. Channel Lock Signer.
allocated (int): Number of this type already used up.
expire_date (int): Seconds since epoch (UTC) when the license will expire.

class pycska.basetypes.LoggingPlugin(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Logging Plugin details.

Logging Plugins are specified with the following fields:

plugin_name (string): Name of logging plugin.
ip (string): Address of the logging store.
port (int): Port the logging store is listening on.
protocol (string): Protocol the logging store is listening for - UDP, TCP.
url (string): Optional landing page for the logging store.
rfc3164 (bool): Is the logging store expecting rfc3164 compliant logs.
reachable (bool): Is the configured landing page reachable.

class pycska.basetypes.OAuthClient(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

OAuth client details.

OAuth clients are specified with the following fields:

client_id (string): Server created id representing the client.
name (string): Name of the oauth client.
description (string): Optional description to give the client.
allow_oauth1 (bool): Is OAuth1 allowed with this client.
allow_oauth2 (bool): Is OAuth2 allowed with this client.
default_scopes_list (list): List of scopes.
redirect_uris_list (list): List of possible redirects.

class pycska.basetypes.OAuthClientSecret(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

OAuth client secret details.

OAuth client secrets are specified with the following fields:

client_id (string): Server created id representing the client.
client_secret (string): OAuth1/2 client secret.
oauth1_token (string): OAuth1 token or empty if OAuth1 is not allowed.
oauth1_token_secret (string): OAuth1 token secret or empty if OAuth1 is not allowed.
oauth2_token (string): OAuth2 token or empty if OAuth2 is not allowed.
oauth2_refresh_token (string): OAuth2 refresh token or empty if OAuth2 is not allowed.

class pycska.basetypes.ProfileDetails(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Configuration details of a given profile. This is a subtype to ConfigProfile.

Configuration details are specified with the following fields:

license_renew_time (int): Amount of time between license renewals in seconds.
log_level (string): Log level for devices using this profile - Error, Info, Debug.
capture_threats (bool): Are PCAPs generated for detected threats.
syslog_filter (string): Optional, syslog filter if listening to a third party syslog source.

class pycska.basetypes.Rule(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

CSKA Rule.

Rules are specified with the following fields:

rule_id (int): Internal Id representing the rule.
rule_name (string): Name of the rule.
description (string): Optional extra description specified for a rule.
meta (string): Optional extra data specified for a rule.
action (string): One of the allowed actions - i.e. Sign, Validate and Strip, Drop.
hash_algorithm (string): One of the allowed hash algorithms - i.e. xor, sha1.
layer (int): Lowest layer used for signing and validating - This layer and above are used.
include_dos_protection (bool): Is extra information added/verified for DOS protection.
custom_bpf (string): If specified then this overrides all other fields below.
protocol (string): Protocol used - TCP, UDP, UDP or TCP.
start_port (int): Beginning of port range that rule applies to.
end_port (int): End of port range that rule applies to.
src_cidr (string): Valid CIDR string representing source IP addresses.
dst_cidr (string): Valid CIDR string representing destination IP addresses.

class pycska.basetypes.RuleSummary(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Core details of a user rule.

RuleSummary contains the following fields:

rule_id (int): Internal Id representing the user rule.
rule_name (string): Name of the user rule.

class pycska.basetypes.Seat(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

license seat details.

seat details contain the following fields:

seat_id (string): internal id representing the license seat.
license_name (string): type of license for the seat.

class pycska.basetypes.SecurityGroup(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Full details of a security group.

SecurityGroup contains the following fields:

group_id (int): Internal Id representing the security group.
group_name (string): Name of the security group.
description (string): Optional description for the group.
meta (string): Optional metadata for the group.
signer_rules: List of pycska.basetypes.RuleSummary
validator_rules: List of pycska.basetypes.RuleSummary
validates_groups: List of pycska.basetypes.SecurityGroupSummary

class pycska.basetypes.SecurityGroupSummary(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Core details of a security group. This type or the core SecurityGroup type can be used when updating the security gorups that a device belongs to.

SecurityGroupSummary contains the following fields:

group_id (int): Internal Id representing the security group.
group_name (string): Name of the security group.

class pycska.basetypes.Stats(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Stats for a give seat license - either signer or validator.

Stat details contain the following fields:

seat: Type pycska.basetypes.Seat
up_time: How long has the seat been up in seconds.
last_updated: When did the seat last contact the CSKA. Seconds since epoch (UTC).
cpu_percent: Current CPU utilization for device that the seat is running on.
memory_percent: Current memory utilization for device that the seat is running on.
driver: Stats details from the low level driver.

class pycska.basetypes.StatsCounter(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Common properties for all stats counters.

Stats counters contain the following fields:

seconds: Current count per second.
minutes: Current count per minute.
hours: Current count per hour.
total: Total number of counter.

class pycska.basetypes.StatsDriver(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

The driver holds stats for different counters.

Not all the counters are implemented for each seat type but the following fields are all possible counters that are kept track of:

signed_packets (pycska.basetypes.StatsCounter) - Number of signed packets.

dropped_verify_bad_packets (pycska.basetypes.StatsCounter) - Dropped due to bad verification.

seen_packets (pycska.basetypes.StatsCounter) - Number of packets passed through driver.

accept_allow_all_packets (pycska.basetypes.StatsCounter) - Number of packets accepted because driver is configured to allow all.

accept_unverified_packets (pycska.basetypes.StatsCounter) - Number of packets accepted because rules are not set to verify the packet.

accept_verify_good_packets (pycska.basetypes.StatsCounter) - Number of packets accepted because they were verified by the driver.

accept_allow_unsigned_packets (pycska.basetypes.StatsCounter) - Number of packets accepted because they failed verification but mode is set to allow.

class pycska.basetypes.SystemStatus(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

System status details.

System status contains the following fields:

num_offline (int): Number of devices currently offline.
num_online (int): Number of devices currently online.
num_threats (int): Number of un-acknowledged threats.
num_oauth1 (int): Number of clients that are allowed to used OAuth1.
num_oauth2 (int): Number of clients that are allowed to used OAuth2.
remote_support_enabled (bool): Is remote support access allowed.

class pycska.basetypes.Threat(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

Threat details.

Threat details contain the following fields:

time (int): Seconds since epoch (UTC) when threat occurred.
threat_id (string): Unique internal id representing the threat.
threat (string): Description of the threat.
count (int): Number of threats in this record.
has_capture (bool): Is there a capture available for this threat.
acknowledged (bool): Has this threat been acknowledged.
name (string): Name of signing device or the IP address if the source is unknown.
signer_seat_id (string): Seat id of the signer if the source is known.
device_id (string): Device id of the signer if the source is known.
device (pycska.basetypes.Device) - Device of the signer if the source is known.
validator (string): Name of the validator that detected the issue.
validator_seat_id (string): Seat id of the validator that detected the issue.
seat_id (string): Seat id of the device that detected the issue - typically the validator.

class pycska.basetypes.User(raw_type=None)[source]¶

Bases: pycska.basetypes.CSKAType

User details.

Users contain the following fields:

user_name (string): Name used to login to CSKA with.
full_name (string): Full name of user.
is_certificate_downloaded (bool): Has the user cert been downloaded yet.
password_salt (string): Hex Random value of up to 64 chars - usually sha256 of a random.
password_hash (string): Hex SHA256 hash of (clear text pwd + password_salt)

Installation¶

pip install pycska

Welcome to pycska’s documentation!¶

pycska package¶

pycska.api module¶

pycska.basetypes module¶

Installation¶

Indices and tables¶