tcex.tcex module

TcEx Framework

class tcex.tcex.TcEx[source]

Bases: object

Provides basic functionality for all types of TxEx Apps.

_association_types()[source]

Retrieve Custom Indicator Associations types from the ThreatConnect API.

_authorization_token_renew()[source]

Method for handling token authorization to ThreatConnect API.

This method will automatically renew the ThreatConnect token if it has expired.

Returns:
An dictionary containing the header values for authorization to
ThreatConnect.
Return type:(dictionary)
_load_secure_params()[source]

Load secure params from the API.

# API Response:

1
2
3
4
5
6
7
8
{
    "inputs":
        {
            "tc_playbook_db_type": "Redis",
            "fail_on_error": true,
            "api_default_org": "TCI"
        }
}
Returns:Parameters (“inputs”) from the TC API.
Return type:dict
_log()[source]

Send System and App data to logs.

_log_app_data()[source]

Log the App data information.

_log_platform()[source]

Log the current Platform.

_log_python_version()[source]

Log the current Python version.

_log_tc_proxy()[source]

Log the proxy settings.

_log_tcex_version()[source]

Log the current TcEx version number.

_logger()[source]

Create TcEx app logger instance.

The logger is accessible via the tc.log.<level> call.

Logging examples

1
2
3
4
tcex.log.debug('logging debug')
tcex.log.info('logging info')
tcex.log.warning('logging warning')
tcex.log.error('logging error')
Parameters:(bool, default (stream_only) – False): If True only the Stream handler will be enabled.
Returns:An instance of logging
Return type:logger
_logger_api()[source]

Add API logging handler.

_logger_fh()[source]

Add File logging handler.

_logger_stream()[source]

Add stream logging handler.

_resources(custom_indicators=False)[source]

Initialize the resource module.

This method will make a request to the ThreatConnect API to dynamically build classes to support custom Indicators. All other resources are available via this class.

Note

Resource Classes can be accessed using tcex.resources.<Class> or using tcex.resource(‘<resource name>’).

_signal_handler(signal_interupt, frame)[source]

Handle singal interrupt.

_unknown_args(args)[source]

Log argparser unknown arguments.

Parameters:args (list) – List of unknown arguments
args

The parsed args from argparser

Note

Accessing args should only be done directly in the App.

Returns:ArgParser parsed arguments
Return type:(namespace)
authorization(request_prepped)[source]

A method to handle the different methods of authenticating to the ThreatConnect API.

Token Based Authorization:

{'Authorization': authorization}

HMAC Based Authorization:

 {
     'Authorization': authorization,
     'Timestamp': <unix timestamp>
 }

http://docs.python-requests.org/en/master/api/#requests.Session.prepare_request.
Parameters:request_prepped (object) – A instance of Python Request module requests. PreparedRequest.
Returns:
An dictionary containing the header values for authorization to
ThreatConnect.
Return type:(dictionary)
authorization_hmac(request_prepped)[source]

Method for handling HMAC authorization to ThreatConnect API.

Parameters:request_prepped (object) – A instance of Python Request prepped requests. PreparedRequest.
Returns:
An dictionary containing the header values for authorization to
ThreatConnect.
Return type:(dictionary)
batch(owner, action=None, attribute_write_type=None, halt_on_error=False, playbook_triggers_enabled=None)[source]

Return instance of Batch

bulk_enabled(owner=None, api_path=None, authorization=None)[source]

[Deprecated] Check if bulk indicators is enabled for owner.

Warning

This method is deprecated and will be removed in TcEx version 0.9.0.

Using the TC API validate that bulk indicator download is enabled and has successfully run for the provided owner.

Parameters:
  • owner (Optional [string]) – Owner name to check.
  • api_path (Optional [string]) – The url to the ThreatConnect API.
  • authorization (Optional [string]) – The authorization header value.
Returns:

True if bulk indicator download is enabled and has run

Return type:

(boolean)

data_filter(data)[source]

Return an instance of the Data Filter Class.

A simple helper module to filter results from ThreatConnect API or other data source. For example if results need to be filtered by an unsupported field the module allows you to pass the data array/list in and specify one or more filters to get just the results required.

Parameters:data (list) – The list of dictionary structure to filter.
Returns:An instance of DataFilter Class
Return type:(object)
default_args

Parse args and return default args.

epoch_seconds(delta=None)[source]

[Deprecated] Get epoch seconds for now or using a time delta.

Warning

This method is deprecated and will be removed in TcEx version 0.9.0. Use the tcex.utils date methods instead.

1
2
3
4
{'days': 1}
{'weeks': 3}
{'months': 4}
{'days': 1, 'weeks': 3, 'months': 4}

Note

More information can be found at https://dateutil.readthedocs.io/en/stable/relativedelta.html

Parameters:delta (Optional [integer]) – The exit code value for the app.
Returns:A integer representing epoch seconds.
Return type:(int)
error_codes

ThreatConnect error codes.

exit(code=None, msg=None)[source]

Application exit method with proper exit code

The method will run the Python standard sys.exit() with the exit code previously defined via exit_code() or provided during the call of this method.

Parameters:
  • code (Optional [integer]) – The exit code value for the app.
  • msg (Optional [string]) – A message to log and add to message tc output.
exit_code

Return the current exit code.

static expand_indicators(indicator)[source]

Process indicators expanding file hashes/custom indicators into multiple entries.

Parameters:indicator (string) – ” : ” delimited string
Returns:a list of indicators split on ” : “.
Return type:(list)
group_types

Return all defined ThreatConnect Group types.

Returns:A list of ThreatConnect Group types.
Return type:(list)
handle_error(code, message_values=None, raise_error=True)[source]

Raise RuntimeError

Parameters:
  • code (integer) – The error code from API or SDK.
  • message (string) – The error message from API or SDK.
indicator_associations_types_data

Return ThreatConnect associations type data.

Retrieve the data from the API if it hasn’t already been retrieved.

Returns:A dictionary of ThreatConnect associations types.
Return type:(dictionary)
indicator_types

Return ThreatConnect Indicator types.

Retrieve the data from the API if it hasn’t already been retrieved.

Returns:A list of ThreatConnect Indicator types.
Return type:(list)
indicator_types_data

Return ThreatConnect indicator types data.

Retrieve the data from the API if it hasn’t already been retrieved.

Returns:A dictionary of ThreatConnect Indicator data.
Return type:(dict)
inject_params(params)[source]

Inject params into sys.argv from secureParams API, AOT, or user provided.

install_json

Return contents of install.json configuration file, loading from disk if required.

install_json_params

Parse params from install.json into a dict by name.

job()[source]

[Deprecated] Return instance of Job module

Warning

The job module is deprecated and will be removed in TcEx version 0.9.0. Use tcex.batch instead.

jobs

[Deprecated] Include the jobs Module.

Warning

The job module is deprecated and will be removed in TcEx version 0.9.0. Use tcex.batch instead.

message_tc(message, max_length=255)[source]

Write data to message_tc file in TcEX specified directory.

This method is used to set and exit message in the ThreatConnect Platform. ThreatConnect only supports files of max_message_length. Any data exceeding this limit will be truncated by this method.

Parameters:message (string) – The message to add to message_tc file
metric(name, description, data_type, interval, keyed=False)[source]

Get instance of the Metrics module.

Parameters:
  • name (string) – The name for the metric.
  • description (string) – The description of the metric.
  • data_type (string) – The type of metric: Sum, Count, Min, Max, First, Last, and Average.
  • interval (string) – The metric interval: Hourly, Daily, Weekly, Monthly, and Yearly.
  • keyed (boolean) – Indicates whether the data will have a keyed value.
Returns:

An instance of the Metrics Class.

Return type:

(object)

notification()[source]

Get instance of the Notification module.

Returns:An instance of the Notification Class.
Return type:(object)
playbook

Include the Playbook Module.

Note

Playbook methods can be accessed using tcex.playbook.<method>.

proxies

Formats proxy configuration into required format for Python Requests module.

Generates a dictionary for use with the Python Requests module format when proxy is required for remote connections.

Example Response

{"http": "http://user:pass@10.10.1.10:3128/"}
Returns:Dictionary of proxy settings
Return type:(dictionary)
request(session=None)[source]

Return an instance of the Request Class.

A wrapper on the Python Request Module specifically for interacting with the ThreatConnect API. However, this can also be used for connecting to other API endpoints.

Returns:An instance of Request Class
Return type:(object)
request_external()[source]

Return an instance of the Request Class with Proxy Set

See request

Returns:An instance of Request Class
Return type:(object)
request_tc()[source]

[Deprecated] Return an instance of the Request Class with Proxy and Authorization Set

Warning

This method is deprecated and will be removed in TcEx version 0.9.0. Use tcex.session instead.

See request

Returns:An instance of Request Class
Return type:(object)
resource(resource_type)[source]

Get instance of Resource Class with dynamic type.

Parameters:resource_type – The resource type name (e.g Adversary, User Agent, etc).
Returns:Instance of Resource Object child class.
Return type:(object)
results_tc(key, value)[source]

Write data to results_tc file in TcEX specified directory.

The TcEx platform support persistent values between executions of the App. This method will store the values for TC to read and put into the Database.

Parameters:
  • key (string) – The data key to be stored.
  • value (string) – The data value to be stored.
results_tc_args()[source]

Read data from results_tc file from previous run of app.

This method is only required when not running from the with the TcEX platform and is only intended for testing apps locally.

Returns:A dictionary of values written to results_tc.
Return type:(dictionary)
s(data, errors='strict')[source]

Decode value using correct Python 2/3 method.

This method is intended to replace the to_string() method with better logic to handle poorly encoded unicode data in Python2 and still work in Python3.

Parameters:
  • data (any) – Data to ve validated and (de)encoded
  • errors (string) – What method to use when dealing with errors.
Returns:

Return decoded data

Return type:

(string)

static safe_group_name(group_name, group_max_length=100, ellipsis=True)[source]

Truncate group name to match limit breaking on space and optionally add an ellipsis.

Note

Currently the ThreatConnect group name limit is 100 characters.

Parameters:
  • group_name (string) – The raw group name to be truncated.
  • group_max_length (int) – The max length of the group name.
  • ellipsis (boolean) – If true the truncated name will have ‘…’ appended.
Returns:

The truncated group name with optional ellipsis.

Return type:

(string)

safe_indicator(indicator, errors='strict')[source]

Indicator encode value for safe HTTP request.

Parameters:
  • indicator (string) – Indicator to URL Encode
  • errors (string) – The error handler type.
Returns:

The urlencoded string

Return type:

(string)

static safe_rt(resource_type, lower=False)[source]

Format the Resource Type.

Takes Custom Indicator types with a space character and return a safe string.

(e.g. User Agent is converted to User_Agent or user_agent.)

Parameters:
  • resource_type (string) – The resource type to format.
  • lower (boolean) – Return type in all lower case
Returns:

The formatted resource type.

Return type:

(string)

safetag(tag, errors='strict')[source]

URL Encode and truncate tag to match limit (128 characters) of ThreatConnect API.

Parameters:tag (string) – The tag to be truncated
Returns:The truncated tag
Return type:(string)
safeurl(url, errors='strict')[source]

URL encode value for safe HTTP request.

Parameters:url (string) – The string to URL Encode.
Returns:The urlencoded string.
Return type:(string)
session

Return an instance of Requests Session configured for the ThreatConnect API.

to_string(data, errors='strict')[source]

[Deprecated] Decode value using correct Python 2/3 method

Warning

This method is deprecated and will be removed in TcEx version 0.9.0.

Parameters:
  • data (any) – Data to ve validated and re-encoded
  • errors (string) – What method to use when dealing with errors.
Returns:

Return decoded data

Return type:

(string)

utils

Include the Utils module.

Note

Utils methods can be accessed using tcex.utils.<method>.