certau.transform Module

Classes for transforming STIX packages to various formats.

The base class StixTransform provides helper functions for processing STIXPackage elements.

There are two broad types of transform currently supported:

  1. Transforms to a text format (these transforms extend the StixTextTransform class):

  2. Transforms that interact with a service:
class certau.transform.StixTransform(package)

Base class for transforming a STIX package to an alternate format.

This class provides helper functions for processing STIXPackage elements. This class should be extended by other classes that transform STIX packages into alternate formats.

The default constructor processes a STIX package to initialise self._observables, a dict keyed by object type. Each entry contains a list list of dict objects with three keys: ‘id’, ‘observable’, and ‘fields’, containing the observable ID, the Observable object itself, and extracted fields, respectively.

Parameters:package – the STIX package to transform
OBJECT_FIELDS

a dict of supported Cybox object types and fields (‘properties’). The dictionary is keyed by Cybox object type string (see _observable_object_type()) with each entry containing a list of field names from that object that will be utilised during the transformation.

Field names may reference sub-objects using dot notation. For example the Cybox EmailMessage class contains a header field referring to an EmailHeader object which contains a to field. This field can be referenced using the notation header.to.

If OBJECT_FIELDS evaluates to False (e.g. empty dict()), it is assumed all object types are supported.

OBJECT_CONSTRAINTS

a dict of constraints on the supported object types based on ‘categories’ associated with that type. For example, the Cybox Address object uses the field category to distinguish between IPv4, IPv6 and even email addresses. Like OBJECT_FIELDS, the dictionary is keyed by object type. Each entry contains a dictionary keyed by field name, containing a list of values, or categories, (for that field name) that are supported by the transform.

Note. Does not support the expression of more complex constraints, for example combining different categories.

STRING_CONDITION_CONSTRAINT

a list of string condition values supported by the transform. For example, some transforms may not support ‘FitsPattern’ or ‘StartsWith’ string condition values. Use this to list the supported values. Note the values are strings, even ‘None’.

classmethod _observables_for_package(package)

Extract observables from a STIX package.

Collects observables from a STIX package and groups them by object type. Only observables with an ID and containing a Cybox object are returned. Results are returned in a dictionary keyed by object type - see _observable_object_type().

If OBJECT_FIELDS are specified only observables containing the object types listed will be returned, and only those with at least one of the listed fields containing a non-trivial value. OBJECT_CONSTRAINTS and STRING_CONDITION_CONSTRAINT are also applied.

If no OBJECT_FIELDS are specified no constraints are applied and all identified observables are returned.

Observables are sought from the following locations:

  • the root of the STIX package
  • within Indicator objects (where the indicators are in the package root)
  • within ObservableComposition objects found in either of the two previous locations
Parameters:package – a STIXPackage object
Returns:
a dictionary of valid observables, keyed by object type
(See description above). May be empty.
Return type:dict
package_description(default='')

Retrieves the STIX package description (str) from the header.

package_title(default='')

Retrieves the STIX package title (str) from the header.

package_tlp(default='AMBER')

Retrieves the STIX package TLP (str) from the header.

class certau.transform.StixTextTransform(package, separator='|', include_header=True, header_prefix='#')

A transform for converting a STIX package to simple text.

This class and its subclasses implement the text() class method which returns a string representation of the STIX package. The entire text output may optionally be preceded by a header string. Typically, each line of the output will contain details for a particular Cybox observable. Output is grouped by observable type. Each group of observables (by type) may also contain an additional header string.

Parameters:
  • package – the STIX package to transform
  • separator – the delimiter used in text output
  • include_header – a boolean value indicating whether or not headers should be included in the output
  • header_prefix – a string prepended to each header row
HEADER_LABELS

a list of field names that are printed by the header() function.

OBJECT_HEADER_LABELS

a dict, keyed by object type, containing field names associated with an object type. These are printed by the header_for_object_type() function.

header()

Returns a header string to display with transform.

header_for_object_type(object_type)

Returns a header string associated with an object type.

text()

Returns a string representation of the STIX package.

text_for_fields(fields, object_type)

Returns a string representing the given object fields.

text_for_object_type(object_type)

Returns a string representing observables of the given type.

text_for_observable(observable, object_type)

Returns a string representing the given observable.

class certau.transform.StixStatsTransform(package, separator='t', include_header=True, header_prefix='', pretty_text=True)

Generate summary statistics for a STIX package.

Prints a count of the number of observables for each object type contained in the package.

Parameters:
  • package – the STIX package to process
  • separator – a string separator used in the text output
  • include_header – a boolean value that indicates whether or not header information should be included in the text output
  • header_prefix – a string prepended to header lines in the output
  • pretty_text – a boolean that indicates whether or not the text should be made pretty by aligning the columns in the text output
class certau.transform.StixCsvTransform(package, separator='|', include_header=True, header_prefix='#', include_observable_id=True, include_condition=True)

Generate a CSV formatted summary of observables from a STIX package.

This class can be used to generate a delimited text dump of the observable fields contained in a STIX package. Output is grouped by the object type contained in the observable.

Parameters:
  • package – the STIX package to process
  • separator – a string separator used in the text output
  • include_header – a boolean value that indicates whether or not header information should be included in the text output
  • header_prefix – a string prepended to header lines in the output
  • include_observable_id – a boolean value indicating whether or not the output should include the observable’s UUID
  • include_condition – a boolean value indicating whether or not the output should include additional fields containing the Cybox string matching condition (which may be empty)
class certau.transform.StixBroIntelTransform(package, separator='t', include_header=False, header_prefix='#', source='UNKNOWN', url='', do_notice='T')

Generate observable details for the Bro Intelligence Framework.

This class can be used to generate a list of indicators (observables) from a STIX package in a format suitable for importing into the Bro network-based intrusion detection system using its Intelligence Framework (see https://www.bro.org/sphinx-git/frameworks/intel.html).

Parameters:
  • package – the STIX package to process
  • separator – a string separator used in the text output
  • include_header – a boolean value that indicates whether or not header information should be included in the text output
  • header_prefix – a string prepended to header lines in the output
  • source – a value to include in the output metadata field ‘meta.source’
  • url – a value to include in the output field metadata ‘meta.url’
  • do_notice – a value to include in the output metadata field ‘meta.do_notice’, if set to ‘T’ a Bro notice will be raised by Bro on a match of this indicator
class certau.transform.StixMispTransform(package, misp, distribution=0, threat_level=1, analysis=2, information=None, published=False)

Insert data from a STIX package into a MISP event.

This class inserts data from a STIX package into MISP (the Malware Information Sharing Platform - see http://www.misp-project.org/). A PyMISP (https://github.com/CIRCL/PyMISP) object is passed to the constructor and used for communicating with the MISP host. The helper function get_misp_object() can be used to instantiate a PyMISP object.

Parameters:
  • package – the STIX package to process
  • misp – the PyMISP object used to communicate with the MISP host
  • distribution – the distribution setting for the MIST event (0-3)
  • threat_level – the threat level setting for the MISP event (0-3)
  • analysis – the analysis level setting for the MISP event (0-2)
  • information – info field value (string) for the MISP event
  • published – a boolean indicating whether the event has been published
static get_misp_object(misp_url, misp_key, use_ssl=False)

Returns a PyMISP object for communicating with a MISP host.

Parameters:
  • misp_url – URL for MISP API end-point
  • misp_key – API key for accessing MISP API
  • use_ssl – a boolean value indicating whether or not the connection should use HTTPS (instead of HTTP)