mirror of
https://github.com/NetherlandsForensicInstitute/hansken-extraction-plugin-sdk-documentation.git
synced 2026-02-14 14:09:49 +00:00
73 lines
3.6 KiB
Plaintext
73 lines
3.6 KiB
Plaintext
# Anatomy of a plugin
|
|
|
|
This page describes the general anatomy of a plugin, and its (simplified) execution in Hansken.
|
|
|
|
## The plugin itself
|
|
|
|
Each plugin must implement two methods:
|
|
|
|
* `pluginInfo()`: This method returns information about the plugin.
|
|
* `process()`: This method performs the extraction task of the plugin.
|
|
|
|
Lets dive a bit deeper into these methods in the next sections!
|
|
|
|
### The method `pluginInfo()`
|
|
|
|
The `pluginInfo()` method returns a `PluginInfo` object. Hansken needs this object to be able to know the capabilities
|
|
of the plugin, and to show the plugin in the list of tools. The most important fields that must be set on `PluginInfo`
|
|
are the following:
|
|
|
|
| `id` | The identifier of the plugin. This will be used as a unique name for the plugin Hansken. |
|
|
| `description` | A description of the plugin that is shown in Hansken. |
|
|
| `author` | The author of the plugin that is shown in Hansken. |
|
|
| `license` | The type of license of the plugin that is shown in Hansken. |
|
|
| `matcher` | This matcher is used by Hansken to determine which Traces are sent to the Plugin during extraction. |
|
|
|
|
### The method `process()`
|
|
|
|
During extraction, Hansken calls the `process()` method for every matching trace. The `matcher` attribute of
|
|
the `PluginInfo` is very important as it determines which traces will be sent to the `process` method.
|
|
|
|
Although the plugin developer is free to program whatever seems useful, the following tasks are typically performed
|
|
within the `process()` method:
|
|
|
|
* Creating child-traces
|
|
* Reading trace properties
|
|
* Adding trace properties
|
|
* Reading the data that the Trace represents
|
|
* Writing data on a Trace
|
|
|
|
Depending on the type of plugin that is implemented, different functionality is available in the `process()` method.
|
|
See [Plugin Types](plugin_types.md) for more details.
|
|
|
|
## The execution in Hansken
|
|
|
|
This describes the process of running a plugin from the perspective of Hansken. The perspective of the user is described
|
|
in [Hansken Extraction Plugins](extraction_plugins.md).
|
|
|
|
### Plugin discovery
|
|
|
|
Hansken manages a list of tools that can be used in extractions. The available plugins must be added to this list so
|
|
that the user can select them. To accomplish this, Hansken scans the Docker registry for docker images that are plugins.
|
|
Each image is started up, and a call is done to its `pluginInfo()` method. If the call resulted in a valid `PluginInfo`
|
|
object, the Extraction Plugin is added to the list of tools visible to users. After the `PluginInfo` is retrieved, the
|
|
docker image is shutdown again.
|
|
|
|
### Starting an extraction
|
|
|
|
Hansken checks if any plugins are selected by the user that started the extraction. For each selected plugin, at least
|
|
one docker image will be started. See [Kubernetes autoscaling](kubernetes_autoscaling.md) for more details on expanding
|
|
the number of instances for each plugin.
|
|
|
|
### Extracting
|
|
|
|
During an extraction, Hansken will iteratively loop through all selected tools, including Extraction Plugins. For each
|
|
trace that matches on a tool, Hansken will call its `process` method. For Extraction Plugins, this means that
|
|
the `process` method is called via the gRPC protocol. The trace to be processed is sent over gRPC to the plugin, and any
|
|
other communication between Hansken and the Extraction Plugin (like created properties and child traces, search requests
|
|
and written data) are done using gRPC.
|
|
|
|
### Finishing an extraction
|
|
|
|
At the end of an extraction, Hansken will stop all associated plugins.
|