dissect.target.plugins.general.example
#
Module Contents#
Classes#
Example plugin. |
Attributes#
- dissect.target.plugins.general.example.ExampleRecordRecord#
- dissect.target.plugins.general.example.ExampleUserRegistryRecord#
- class dissect.target.plugins.general.example.ExamplePlugin(target: dissect.target.Target)#
Bases:
dissect.target.plugin.Plugin
Example plugin.
This plugin serves as an example for new plugins. Use it as a guideline.
Docstrings are used in help messages of plugins. Make sure to document your plugin and plugin functions. Use Google docstring format:
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
Plugins can optionally be namespaced by specifying the
__namespace__
class attribute. Namespacing results in your plugin needing to be prefixed with this namespace when being called. For example, if your plugin has specifiedtest
as namespace and a function calledexample
, you must call your plugin withtest.example
:__namespace__ = "test"
The
__init__
takes the target as only argument. Perform additional initialization here if necessary:def __init__(self, target): super().__init__(target)
- __findable__ = False#
- __skip__ = True#
- check_compatible() None #
Perform a compatibility check with the target.
This function should return
None
if the plugin is compatible with the current target (self.target
). For example, check if a certain file exists. Otherwise it should raise anUnsupportedPluginError
.- Raises:
UnsupportedPluginError – If the plugin could not be loaded.
- example(flag: bool = False) str #
Example plugin function.
Docstrings are used in help messages of plugins. Make sure to document your plugin and plugin functions. The first line must be a brief one sentence description of the plugin function.
- The
@export
decorator supports multiple arguments: - property (bool): Whether this function should act like a property.
Properties are implicitly cached.
- record (RecordDescriptor): The record descriptor this function yield,
if any. If dynamic, use
DynamicDescriptor
.- output (str): The output type of this function. Can be one of:
default: Single return value.
record: Yields records. Implicit when record argument is given.
yield: Yields printable values.
none: No return value.
Command line arguments can be added using the
@arg
decorator. Arguments to this decorator are directly forwarded to theadd_argument
function of argparse. Resulting arguments are passed to the function using kwargs. The keyword argument name must match the argparse argument name.- The
- example_record() Iterator[ExampleRecordRecord] #
Example plugin that generates records.
To create a new plugin function that yields records, you must define a record descriptor and pass it to
@export
. This will implicitly mark the output type asrecord
.
- example_user_registry_record() Iterator[ExampleUserRegistryRecord] #
Example plugin that generates records with registry key and user information.
To include registry or user information in a record, you must create a new record descriptor using
create_extended_descriptor()
withRegistryRecordDescriptorExtension
and/or :class:`~dissect.target.helpers.descriptor_extensions.UserRecordDescriptorExtension as extensions.
- example_yield() Iterator[str] #
Example plugin that yields text lines.
Setting
output="yield"
is useful for creating generators of text, such as human-readable timelines.
- example_none() None #
Example plugin with no return value.
Setting
output="none"
means you don’t return a value. This is useful when you want to print something on your own, such as verbose information.
- example_internal() str #
Example internal plugin.
Use the
@internal
plugin to mark your plugin as internal and hide it from the plugin overview.