TcEx¶
tcex.tcex¶
TcEx Framework
-
class
tcex.tcex.
TcEx
(**kwargs)[source]¶ Bases:
object
Provides basic functionality for all types of TxEx Apps.
Parameters: - config (dict, kwargs) – A dictionary containing configuration items typically used by external Apps.
- config_file (str, kwargs) – A filename containing JSON configuration items typically used by external Apps.
- logger (logging.Logger, kwargs) – An pre-configured instance of logger to use instead of tcex logger.
-
_association_types
()[source]¶ Retrieve Custom Indicator Associations types from the ThreatConnect API.
-
_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>’).
-
args
¶ Argparser args Namespace.
-
batch
(owner, action=None, attribute_write_type=None, halt_on_error=False, playbook_triggers_enabled=None)[source]¶ Return instance of Batch
-
cache
(domain, data_type, ttl_minutes=None, mapping=None)[source]¶ Get instance of the Cache module.
Parameters: - domain (str) – The domain can be either “system”, “organization”, or “local”. When using “organization” the data store can be accessed by any Application in the entire org, while “local” access is restricted to the App writing the data. The “system” option should not be used in almost all cases.
- data_type (str) – The data type descriptor (e.g., tc:whois:cache).
- ttl_minutes (int) – The number of minutes the cache is valid.
Returns: An instance of the Cache Class.
Return type: object
-
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)
-
datastore
(domain, data_type, mapping=None)[source]¶ Get instance of the DataStore module.
Parameters: - domain (str) – The domain can be either “system”, “organization”, or “local”. When using “organization” the data store can be accessed by any Application in the entire org, while “local” access is restricted to the App writing the data. The “system” option should not be used in almost all cases.
- data_type (str) – The data type descriptor (e.g., tc:whois:cache).
Returns: An instance of the DataStore Class.
Return type: object
-
default_args
¶ Argparser args Namespace.
-
error_codes
¶ Return TcEx 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)
-
get_type_from_api_entity
(api_entity)[source]¶ Return the object type as a string given a api entity.
Parameters: api_entity – Returns:
-
group_types
¶ Return all defined ThreatConnect Group types.
Returns: A list of ThreatConnect Group types. Return type: (list)
-
group_types_data
¶ Return supported ThreatConnect Group types.
-
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)
-
log
¶ Return a valid logger.
-
logger
¶ Return logger.
-
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. The last <max_length> characters will be preserved.
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)
-
parser
¶ Instance tcex args parser.
-
playbook
¶ Include the Playbook Module.
Note
Playbook methods can be accessed using
tcex.playbook.<method>
.
-
proxies
¶ Format the proxy configuration 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:[email protected]:3128/"}
Returns: Dictionary of proxy settings Return type: (dictionary)
-
rargs
¶ Return argparser args Namespace with Playbook args automatically resolved.
-
request
(session=None)[source]¶ Return an instance of the Request Class.
A wrapper on the Python Requests module that provides a different interface for creating requests. The session property of this instance has built-in logging, session level retries, and preconfigured proxy configuration.
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.
-
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]¶ Format indicator 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)
-
safe_tag
(tag, errors='strict')[source]¶ 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)
-
safe_url
(url, errors='strict')[source]¶ Encode value for safe HTTP request.
Parameters: url (string) – The string to URL Encode. Returns: The urlencoded string. Return type: (string)
-
service
¶ Include the Service Module.
Note
Service methods can be accessed using
tcex.service.<method>
.
-
session
¶ Return an instance of Requests Session configured for the ThreatConnect API.
-
session_external
¶ Return an instance of Requests Session configured for the ThreatConnect API.
-
ti
¶ Include the Threat Intel Module.
Note
Threat Intell methods can be accessed using
tcex.ti.<method>
.
-
token
¶ Return token object.
-
utils
¶ Include the Utils module.
Note
Utils methods can be accessed using
tcex.utils.<method>
.