tcex.tcex_playbook module

TcEx Framework Playbook module

class tcex.tcex_playbook.TcExPlaybook(tcex)

Bases: object

Playbook methods for accessing key value store.

_parse_out_variable()

Internal method to parse the tc_playbook_out_variable arg.

Example Variable Format:

#App:1234:status!String,#App:1234:status_code!String

add_output(key, value, variable_type)

Dynamically add output to output_data dictionary to be written to DB later.

This method provides an alternative and more dynamic way to create output variables in an App. Instead of storing the output data manually and writing all at once the data can be stored inline, when it is generated and then written before the App completes.

for color in ['blue', 'red', 'yellow']:
    tcex.playbook.add_output('app.colors', color, 'StringArray')

tcex.playbook.write_output()  #  writes the output stored in output_data

{
    "my_color-String": {
        "key": "my_color",
        "type": "String",
        "value": "blue"
    },
    "my_numbers-String": {
        "key": "my_numbers",
        "type": "String",
        "value": "seven"
    },
    "my_numbers-StringArray": {
        "key": "my_numbers",
        "type": "StringArray",
        "value": ["seven", "five"]
    }
}

Parameters:

• key (string) – The variable name to write to storage.
• value (any) – The value to write to storage.
• variable_type (string) – The variable type being written.

aot_blpop()

Subscribe to AOT action channel.

aot_rpush(exit_code)

Push message to AOT action channel.

check_output_variable(variable)

Check to see if output variable was requested by downstream app.

Using the auto generated dictionary of output variables check to see if provided variable was requested by downstream app.

Parameters:variable (string) – The variable name, not the full variable. Returns:Boolean value indicator whether a match was found. Return type:(boolean)

create(key, value)

Create method of CRUD operation for working with KeyValue DB.

This method will automatically determine the variable type and call the appropriate method to write the data. If a non standard type is provided the data will be written as RAW data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result string of DB write.

Return type:

(string)

create_binary(key, value)

Create method of CRUD operation for binary data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_binary_array(key, value)

Create method of CRUD operation for binary array data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_data_types

Map of standard playbook variable types to create method.

create_key_value(key, value)

Create method of CRUD operation for key/value data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write

Return type:

(string)

create_key_value_array(key, value)

Create method of CRUD operation for key/value array data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_output(key, value, variable_type=None)

Wrapper for Create method of CRUD operation for working with KeyValue DB.

This method will automatically check to see if provided variable was requested by a downstream app and if so create the data in the KeyValue DB.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.
• variable_type (string) – The variable type being written.

Returns:

Result string of DB write.

Return type:

(string)

create_raw(key, value)

Create method of CRUD operation for raw data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_string(key, value)

Create method of CRUD operation for string data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_string_array(key, value)

Create method of CRUD operation for string array data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_tc_entity(key, value)

Create method of CRUD operation for TC entity data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

create_tc_entity_array(key, value)

Create method of CRUD operation for TC entity array data.

Parameters:

• key (string) – The variable to write to the DB.
• value (any) – The data to write to the DB.

Returns:

Result of DB write.

Return type:

(string)

db

Return the correct KV store for this execution.

delete(key)

Delete method of CRUD operation for all data types.

Parameters:key (string) – The variable to write to the DB. Returns:Result of DB write. Return type:(string)

static entity_to_bulk(entities, resource_type_parent)

Convert Single TC Entity to Bulk format.

Attention

This method is subject to frequent changes

Parameters:

• entities (dictionary) – TC Entity to be converted to Bulk.
• resource_type_parent (string) – The resource parent type of the tc_data provided.

Returns:

A dictionary representing TC Bulk format.

Return type:

(dictionary)

exit(code=None, msg=None)

Playbook wrapper on TcEx exit method

Playbooks do not support partial failures so we change the exit method from 3 to 1 and call it a partial success instead.

Parameters:code (Optional [integer]) – The exit code value for the app.

hgetall()

Return all values for a context.

static indicator_arrays(tc_entity_array)

Convert TCEntityArray to Indicator Type dictionary.

Parameters:tc_entity_array (dictionary) – The TCEntityArray to convert. Returns:Dictionary containing arrays of indicators for each indicator type. Return type:(dictionary)

static json_to_bulk(tc_data, value_fields, resource_type, resource_type_parent)

Convert ThreatConnect JSON response to a Bulk Format.

Attention

This method is subject to frequent changes

Parameters:

• tc_data (dictionary) – Array of data returned from TC API call.
• value_fields (list) – Field names that contain the “value” data.
• resource_type (string) – The resource type of the tc_data provided.
• resource_type_parent (string) – The resource parent type of the tc_data provided.

Returns:

A dictionary representing a TCEntityArray

Return type:

(list)

static json_to_entity(tc_data, value_fields, resource_type, resource_type_parent)

Convert ThreatConnect JSON response to a TCEntityArray.

Attention

This method is subject to frequent changes.

Parameters:

• tc_data (dictionary) – Array of data returned from TC API call.
• value_fields (list) – Field names that contain the “value” data.
• resource_type (string) – The resource type of the tc_data provided.
• resource_type_parent (string) – The resource parent type of the tc_data provided.

Returns:

A list representing a TCEntityArray.

Return type:

(list)

static json_to_key_value(json_data, key_field, value_field=None, array=False)

Convert JSON data to a KeyValue/KeyValueArray.

Parameters:

• json_data (dictionary|list) – Array/List of JSON data.
• key_field (string) – Field name for the key.
• value_field (string) – Field name for the value or use the value of the key field.
• array (boolean) – Always return array even if only on result.

Returns:

A dictionary or list representing a KeyValue or KeyValueArray.

Return type:

(dictionary|list)

out_variables

Return output variables stored as name dict.

out_variables_type

Return output variables stored as name-type dict.

parse_variable(variable)

Method to parse an input or output variable.

Example Variable:

#App:1234:output!String

Parameters:variable (string) – The variable name to parse. Returns:Result of parsed string. Return type:(dictionary)

read(key, array=False, embedded=True)

Read method of CRUD operation for working with KeyValue DB.

This method will automatically check to see if a single variable is passed or if “mixed” data is passed and return the results from the DB. It will also automatically determine the variable type to read.

Parameters:

• key (string) – The variable to read from the DB.
• array (boolean) – Convert string/dict to Array/List before returning.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB

Return type:

(any)

read_array(key, embedded=True)

Alias for read method that will read any type (e.g., String, KeyValue) and always

return array.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB

Return type:

(any)

read_binary(key, b64decode=True, decode=False)

Read method of CRUD operation for binary data.

Parameters:

• key (string) – The variable to read from the DB.
• b64decode (bool) – If true the data will be base64 decoded.
• decode (bool) – If true the data will be decoded to a String.

Returns:

Results retrieved from DB.

Return type:

(bytes|string)

read_binary_array(key, b64decode=True, decode=False)

Read method of CRUD operation for binary array data.

Parameters:

• key (string) – The variable to read from the DB.
• b64decode (bool) – If true the data will be base64 decoded.
• decode (bool) – If true the data will be decoded to a String.

Returns:

Results retrieved from DB.

Return type:

(list)

read_data_types

Map of standard playbook variable types to read method.

read_embedded(data, parent_var_type)

Read method for “mixed” variable type.

Note

The read() method will automatically determine if the input is a variable or needs to be searched for embedded variables. There usually is no reason to call this method directly.

This method will automatically covert variables embedded in a string with data retrieved from DB. If there are no keys/variables the raw string will be returned.

Examples:

DB Values
#App:7979:variable_name!String:
    "embedded \"variable\""
#App:7979:two!String:
    "two"
#App:7979:variable_name!StringArray:
    ["one", "two", "three"]

Examples 1:
    Input:  "This input has a embedded #App:7979:variable_name!String"

Examples 2:
    Input: ["one", #App:7979:two!String, "three"]

Examples 3:
    Input: [{
        "key": "embedded string",
        "value": "This input has a embedded #App:7979:variable_name!String"
    }, {
        "key": "string array",
        "value": #App:7979:variable_name!StringArray
    }, {
        "key": "string",
        "value": #App:7979:variable_name!String
    }]

Parameters:

• data (string) – The data to parsed and updated from the DB.
• parent_var_type (string) – The parent type of the embedded variable.

Returns:

Results retrieved from DB

Return type:

(string)

read_key_value(key, embedded=True)

Read method of CRUD operation for key/value data.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB.

Return type:

(dictionary)

read_key_value_array(key, embedded=True)

Read method of CRUD operation for key/value array data.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB.

Return type:

(list)

read_raw(key)

Read method of CRUD operation for raw data.

Parameters:key (string) – The variable to read from the DB. Returns:Results retrieved from DB. Return type:(any)

read_string(key, embedded=True)

Read method of CRUD operation for string data.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB.

Return type:

(string)

read_string_array(key, embedded=True)

Read method of CRUD operation for string array data.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB.

Return type:

(list)

read_tc_entity(key, embedded=True)

Read method of CRUD operation for TC entity data.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB.

Return type:

(dictionary)

read_tc_entity_array(key, embedded=True)

Read method of CRUD operation for TC entity array data.

Parameters:

• key (string) – The variable to read from the DB.
• embedded (boolean) – Resolve embedded variables.

Returns:

Results retrieved from DB.

Return type:

(list)

variable_type(variable)

Get the Type from the variable string or default to String type.

The default type is “String” for those cases when the input variable is contains not “DB variable” and is just a String.

Example Variable:

#App:1234:output!StringArray returns **StringArray**

Example String:

"My Data" returns **String**

Parameters:variable (string) – The variable to be parsed Returns:The variable type. Return type:(string)

wrap_embedded_keyvalue(data)

Wrap keyvalue embedded variable in double quotes.

Parameters:data (string) – The data with embedded variables. Returns:Results retrieved from DB Return type:(string)

write_output()

Write all stored output data to storage.