Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
324 lines (263 sloc) 11.5 KB

Jobs

Important

This module is being deprecated and will be removed in a future release. Please use the new Batch module as a replacement.

The ThreatConnect |trade| TcEx Framework provides the :py:mod:`~tcex.tcex_job.TcExJob` module to automate writing certain data types to the ThreatConnect API. The App developer can dynamically build a JSON data object and the Job module will handle writing the data to the ThreatConnect API.

Once all the data has been added to the job a call to the :py:meth:`~tcex.tcex_job.TcExJob.process` method will attempt to write the data to the ThreatConnect API.

Note

Any failures will set the :py:meth:`~tcex.tcex.TcEx.exit_code` to 3 or partial failure, unless the error is defined as a critical failure (defined in the __init__ method of :py:meth:`~tcex.tcex_job.TcExJob`.

Groups

The :py:meth:`~tcex.tcex_job.TcExJob.group` method accepts the following data structure. All required fields are highlighted.

Note

The Jobs module will make multiple API calls to push all this data to the ThreatConnect API.

The module provides the :py:mod:`~tcex.tcex_job.TcExJob.group_results` property to get the status of each Group submitted.

  • Cached - The Group already existed in ThreatConnect and was pulled from cache.
  • Failed - The Group add encountered an error when submitting to the API.
  • Not Saved - The Group was not saved either due to a failure or "Halt on Error" was selected and a previous Group failed.
  • Saved - The Group was saved to ThreatConnect via the API.
  • Submitted - The complete list of submitted Group Names.

Documents

To create a document, use the same structure described above and add fileName and fileData fields. For example, the following JSON will create a document named test.txt with the content This is just a test:

Group to Indicator Associations

The :py:meth:`~tcex.tcex_job.TcExJob.group_association` method accepts the following data structure. All required fields are highlighted.

Warning

If more than one Group exist with the same name, the association created using :py:meth:`~tcex.tcex_job.TcExJob.group_association` will only associate the indicator to the first group found with the name.

Group to Group Associations

The :py:meth:`~tcex.tcex_job.TcExJob.association` method accepts the following data structure to create an association between two groups. All required fields are highlighted.

Warning

If more than one Group exist with the same name, the association created using :py:meth:`~tcex.tcex_job.TcExJob.association` will only associate the indicator to the first group found with the name.

Indicators

The :py:meth:`~tcex.tcex_job.TcExJob.indicator` method accepts the following data structure. All required fields are highlighted.

Note

To create file indicators using the tcex.tcex_job.indicator() function, the summary should be a string with each file hash (md5, sha1, and/or sha256) separated by <space>:<space>. For example, the following json would create a file indicator with the md5 hash 905ad8176a569a36421bf54c04ba7f95, sha1 hash a52b6986d68cdfac53aa740566cbeade4452124e and sha256 hash 25bdabd23e349f5e5ea7890795b06d15d842bde1d43135c361e755f748ca05d0:

{
  "summary": "905ad8176a569a36421bf54c04ba7f95 : a52b6986d68cdfac53aa740566cbeade4452124e : 25bdabd23e349f5e5ea7890795b06d15d842bde1d43135c361e755f748ca05d0",
  "type": "File"
}

The module provides the :py:mod:`~tcex.tcex_job.TcExJob.indicator_results` property to get the status of each Indicator submitted.

  • Failed - The Indicator add encountered an error when submitting to the API.
  • Not Saved - The Indicator was not saved either due to a failure or "Halt on Error" was selected and a previous Indicator failed.
  • Saved - The Indicator was saved to ThreatConnect via the API.
  • Submitted - The complete list of submitted Indicator Names.

Indicator to Indicator Associations

The :py:meth:`~tcex.tcex_job.TcExJob.association` method accepts the following data structure to create custom, Indicator to Indicator Associations. All required fields are highlighted.

The required custom_association_name key provides the name of the association you would like to use. These names can be found using the associationTypes API endpoint.

Note

When create an Indicator to Indicator association that is a File Action, make sure that the 'parent' File Indicator is provided as the resource_value (not the association_value).

For example, the following code will properly create an association between a Registry Key and a File Indicator:

assoc = {
  'association_type': 'Registry Key',
  'association_value': 'HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\6to4 : DeleteFlag : REG_NONE',
  'custom_association_name': 'File Registry Key',
  'resource_type': 'File',
  'resource_value': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
}
tcex.jobs.association(assoc)

While the code snippet below will not work properly (notice that the location of the 'parent' File Indicator and the Registry Key have been switched):

assoc = {
  'association_type': 'File',
  'association_value': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
  'custom_association_name': 'File Registry Key',
  'resource_type': 'Registry Key',
  'resource_value': 'HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\6to4 : DeleteFlag : REG_NONE'
}
tcex.jobs.association(assoc)

File Occurrence

The :py:meth:`~tcex.tcex_job.TcExJob.file_occurrence` method accepts the following data structure. All required fields are highlighted.

Note

The hash value is not part of the File Occurrence body and will be stripped out before the POST. It is used to indicate which File Indicator to add the occurrence.

Sample Job Flow

The key method calls are highlighted in the following code sample.

Note

The Batch API call allows for Group Associations via the associatedGroup field using the Group Id. However, if Groups are being added in the Job the Group Id will not be known until after the Group is added. The :py:meth:`~tcex.tcex_job.TcExJob.group_association` method allows the Group name to be used instead of the Group Id. If the Group Id is already known it can be associated using the associatedGroup field.