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.
- 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
andcalls
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 thegenerate()
method is not advised.
- property configuration
Parsed configuration parameters.
This is populated by the
configure
method, controlled by theoptions
parameter. If this has not yet been configured, this raises aNotConfigured
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 inconfiguration
.- 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 theconfigure
method. Components are reconfigurable, soconfigure
may still be called ifconfigured
isTrue
.A Configurable with no configuration options is considered to be already configured.
- 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 byconfigure
) for configuration parameters. This function may be used to populate/modify thefunctions
andcalls
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.
- 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, andFalse
otherwise.
- abstract property name
A simple name.
Names should consist of [a-z-]. Make use of the optional
verbose_name
property if you would like a pretty-printable version of this name.
- property 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 raiseConfigurationError
. Parsed configuration values are stored inconfiguration
by the time this is called.
- abstract property verbose_name
Optional verbose name for pretty printing.
By default this will just return
name
.
- abstract property version
A version number.
This should be a string using Semantic Versioning.
- finalize()
Make this Component unique.
Uses the
globals
list to generate and insert globally unique values into thefunctions
andcalls
properties to prepare this Component to be used by a Blueprint.