dissect.target.plugins.general.example#

Module Contents#

Classes#

ExamplePlugin

Example plugin.

Attributes#

ExampleRecordRecord

ExampleUserRegistryRecord

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 specified test as namespace and a function called example, you must call your plugin with test.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 an UnsupportedPluginError.

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 the add_argument function of argparse. Resulting arguments are passed to the function using kwargs. The keyword argument name must match the argparse argument name.

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 as record.

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() with RegistryRecordDescriptorExtension 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.