Components

class helix.component.Component(*args, **kwargs)

A common base class for all components.

A component represents a single, configurable unit of functionality. This may be as simple as a single function or as complex as an entire command and control library.

DATE_FORMAT = '%Y-%m-%d %H:%M:%S.%f'

abstract property date

A relevant date.

Possibly the initial publication date of this sample or compile timestamp. This does not need to be exact but may be useful for some applications of the final dataset and will be included.

Note

The date should be in a string format parsable with DATE_FORMAT

abstract property blueprints

A list of the Blueprints supported by this component.

This should be a list of the string names of supported Blueprint and must match the corresponding Blueprint.name property.

functions = []

A list of functions included in this Component.

This list of functions may be defined either in the Component class (for relatively simple components) or may be populated by the implementation of the generate() method.

calls = {}

A dictionary of callsites (defined by Blueprints) to call strings.

This dictionary of calls may be defined either in the Component class (for relatively simple components) or may be populated by the implementation of the generate() method.

globals = []

A list of template parameter names that must be globally unique.

These template parameters are present in the functions and calls parameters and will be substituted for a globally unique value when this Component is finalized. This list should encompass all of the parts of this Component that must be globally unique (e.g., function names, global variable names). A good test to ensure that all of the globally unique parameters have been templated is to try to build a Blueprint with two instances of this component.

property generated: Indicates if this Component has been generated yet.

Note

This assumes that the Component has been generated if functions or calls have been set. This means that components which define a generate method should leave these parameters empty and set them inside of the generate() method only. A hybrid aproach of partially setting these parameters and then updating them inside of the generate() method is not advised.

generate()

Generate configured source code for this component.

This function is responsible for any necessary code generation. configure will be called before generate so this function may draw from any instance attributes (set by configure) for configuration parameters. This function may be used to populate/modify the functions and calls properties of this Component.

Note

Defining this method is optional - relatively simple components may find it easy enough to simply define all of the data they may need directly on the class.

finalized = False

finalize()

Make this Component unique.

Uses the globals list to generate and insert globally unique values into the functions and calls properties to prepare this Component to be used by a Blueprint.

property configuration

Parsed configuration parameters.

This is populated by the configure method, controlled by the options parameter. If this has not yet been configured, this raises a NotConfigured exception.

configure(**kwargs)

Parse configuration data passed as kwargs.

Configuration values taken from options will be passed to this function as kwargs. This function is responsible for parsing and storing those configuration options and storing them in configuration.

Parameters: **kwargs – Arbitrary keyword arguments corresponding to fields in options

Note

Although it is possible to pass values of varying types to this method, it is recommended that code which makes use of configuration parameters assumed that they are a string, since configuration parameters parsed from command line arguments and configuration files will be passed as strings.

property configured

Indicates if this has been configured.

This attribute is set True by the configure method. Components are reconfigurable, so configure may still be called if configured is True.

A Configurable with no configuration options is considered to be already configured.

dependencies = []

A list of external dependencies which must be installed.

This list is optional, but must consist of zero or more instances of Dependency (or subclasses) which may be installed by users.

abstract property description

classmethod install(verbose=False)

Install all dependencies.

This reruns dependency installation regardless of if it has been installed already. This should be safe because of the requirement that dependency installation methods be repeatable but can be inefficient. Users can check the installed() method to determine if the installation should be rerun.

Parameters: verbose (bool) – Verbosity.

classmethod installed()

Check if all dependencies have been installed.

Returns: True if all dependencies have been installed already, and False otherwise.

abstract property name

A simple name.

Names should consist of [a-z-]. Make use of the verbose_name property if you would like a pretty-printable version of this name.

options = {}

A dictionary of configurable options and default values.

This defines which options which may be edited with a call to configure.

Example

A subclass with both required and default parameters may be defined as:

options = {
    "server": {},
    "port": {"default": 1337}
}

classmethod string()

tags = ()

An optional iterable of human-readable tag tuples.

Tags may represent family or component groupings and are fairly loosely defined.

Example

An APT29/SEDINT sample may be defined as (("family", "APT29"), ("sample", "SEDINT"))

abstract property type

A short type descriptor.

This should be set to some constant (a short string) defined in some common location.

validate_configuration()

Custom option validation code.

This optional method may be implemented on subclasses to provide custom configuration validation and is called by the configure method. If invalid configuration is detected, this method should raise ConfigurationError. Parsed configuration values are stored in configuration by the time this is called.

abstract property verbose_name: Verbose name for pretty printing.

abstract property version

A version number.

This should be a string using Semantic Versioning.

class helix.component.Loader

A method of loading one or more Components from a file.

This interface allows external libraries which expose Components to support loading those components from a file. This can be useful for libraries which cannot expose components as an entrypoint for whatever reason (e.g., there are far too many Components to reasonably expose).

Implementing libraries should expose their Loader by their library name at the helix.components.loaders entrypoint.

abstract load(f)

Implement Component loading here.

Parameters: f (file) – A file-like object from which to read.
Returns: A list of ready to use Component classes.

helix.component.load(f)

Load a list of Components from a file.

This attempts to load one or more Components from the given file using any installed and available Component Loader.

Parameters

f (file) – A file-like object from which to read.

Returns

A list of ready to use Component classes.

Raises

ValueError – if the given file cannot be parsed with any installed Component loader
NotImplementedError – if no Component loaders are installed.