dissect.target.plugin
#
Dissect plugin system.
See dissect/target/plugins/general/example.py for an example plugin.
Module Contents#
Classes#
Sortable and serializible string-based enum |
|
Base class for plugins. |
|
Base class for OS plugins. |
|
A Child target is a special plugin that can list more Targets. |
|
Base class for plugins. |
|
Parent class for internal plugins. |
|
Functions#
Decorator to be used on Plugin functions that should be exported. |
|
Retrieve all attributes that do not start with |
|
Retrieve all public attributes of a |
|
Retrieve all public methods of a |
|
Return record descriptors set on nonprivate methods in cls class. |
|
Register a plugin, and put related data inside |
|
Decorator to be used on plugin functions that should be internal only. |
|
Decorator to be used on Plugin functions that accept additional command line arguments. |
|
Retrieve all plugin descriptors. |
|
Retrieve all OS plugin descriptors. |
|
Retrieve all child plugin descriptors. |
|
Lookup a plugin descriptor by function name. |
|
Get a plugin descriptor by function name. |
|
Get a plugin descriptor by namespace. |
|
Helper function that loads a plugin from a given plugin description. |
|
Return all plugins that failed to load. |
|
Store errors that occurred during plugin import. |
|
Walk all the files and directories in |
|
Load a module from |
|
Internal function to generate the list of available plugins. |
|
Loads a module from a file indicated by |
|
Iterate over the |
|
Create a deduplicated list of paths. |
|
Returns an index-list for plugins. |
|
Finds plugins that match the target and the patterns. |
Attributes#
A dictionary type, for what the plugin descriptor looks like. |
|
The base module path to the in-tree plugins. |
|
The different output types supported by |
|
- dissect.target.plugin.GENERATED = True#
- dissect.target.plugin.PluginDescriptor#
A dictionary type, for what the plugin descriptor looks like.
- dissect.target.plugin.MODULE_PATH = 'dissect.target.plugins'#
The base module path to the in-tree plugins.
- dissect.target.plugin.OUTPUTS = ('default', 'record', 'yield', 'none')#
The different output types supported by
@export
.
- dissect.target.plugin.log#
- class dissect.target.plugin.OperatingSystem#
Bases:
dissect.target.helpers.utils.StrEnum
Sortable and serializible string-based enum
- LINUX = 'linux'#
- WINDOWS = 'windows'#
- ESXI = 'esxi'#
- BSD = 'bsd'#
- OSX = 'osx'#
- UNIX = 'unix'#
- ANDROID = 'android'#
- VYOS = 'vyos'#
- IOS = 'ios'#
- FORTIGATE = 'fortigate'#
- CITRIX = 'citrix-netscaler'#
- dissect.target.plugin.export(*args, **kwargs) Callable #
Decorator to be used on Plugin functions that should be exported.
- Supported keyword arguments:
- property (bool): Whether this export should be regarded as a property.
Properties are implicitly cached.
cache (bool): Whether the result of this function should be cached. record (RecordDescriptor): The
flow.record.RecordDescriptor
for the records that this function yields.If the records are dynamically made, use DynamicRecord instead.
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.
The
export
decorator adds some additional private attributes to an exported method or property:__output__
: The output type to expect for this function, this is the same asoutput
.__record__
: The type of record to expect, this value is the same asrecord
.__exported__
: set toTrue
to indicate the method or property is exported.
- Raises:
ValueError – if there was an invalid output type.
- Returns:
An exported function from a plugin.
- dissect.target.plugin.get_nonprivate_attribute_names(cls: Type[Plugin]) list[str] #
Retrieve all attributes that do not start with
_
.
- dissect.target.plugin.get_nonprivate_attributes(cls: Type[Plugin]) list[Any] #
Retrieve all public attributes of a
Plugin
.
- dissect.target.plugin.get_nonprivate_methods(cls: Type[Plugin]) list[Callable] #
Retrieve all public methods of a
Plugin
.
- dissect.target.plugin.get_descriptors_on_nonprivate_methods(cls: Type[Plugin]) list[flow.record.RecordDescriptor] #
Return record descriptors set on nonprivate methods in cls class.
- class dissect.target.plugin.Plugin(target: dissect.target.Target)#
Base class for plugins.
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
:A
Plugin
class has the following private class attributes:__namespace__
__record_descriptors__
With the following three being assigned in
register()
:__plugin__
__functions__
__exports__
Additionally, the methods and attributes of
Plugin
receive more private attributes by using decorators.The
export()
decorator adds the following private attributes__exported__
__output__
: Set with theexport()
decorator.__record__
: Set with theexport()
decorator.
The
internal()
decorator andInternalPlugin
set the__internal__
attribute. Finally.args()
decorator sets the__args__
attribute.- Parameters:
target – The
Target
object to load the plugin for.
- __namespace__: str#
Defines the plugin namespace.
- __record_descriptors__: list[flow.record.RecordDescriptor]#
Defines a list of
RecordDescriptor
of the exported plugin functions.
- __register__: bool = True#
Determines whether this plugin will be registered.
- __findable__: bool = True#
Determines whether this plugin will be revealed when using search patterns.
Some (meta)-plugins are not very suitable for wild cards on CLI or plugin searches, because they will produce duplicate records or results. For instance a plugin that offers the same functions as subplugins will produce redundant results when used with a wild card (browser.* -> browser.history + browser.*.history).
- __skip__: bool = False#
Prevents plugin functions from indexing this plugin at all.
- classmethod __init_subclass__(**kwargs)#
- is_compatible() bool #
Perform a compatibility check with the target.
- abstract 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.
- get_all_records() Iterator[flow.record.Record] #
Return the records of all exported methods.
- Raises:
PluginError – If the subclass is not a namespace plugin.
- __call__(*args, **kwargs)#
A shortcut to
get_all_records()
.- Raises:
PluginError – If the subclass is not a namespace plugin.
- class dissect.target.plugin.OSPlugin(target: dissect.target.Target)#
Bases:
Plugin
Base class for OS plugins.
This provides a base class for certain common functions of OS’s, which each OS plugin has to implement separately.
For example, it provides an interface for retrieving the hostname and users of a target.
- check_compatible() bool #
OSPlugin’s use a different compatibility check, override the default one.
- abstract classmethod detect(fs: dissect.target.filesystem.Filesystem) dissect.target.filesystem.Filesystem | None #
Provide detection of this OSPlugin on a given filesystem.
Note: must be implemented as a classmethod.
- Parameters:
fs –
Filesystem
to detect the OS on.- Returns:
The root filesystem / sysvol when found.
- abstract classmethod create(target: dissect.target.Target, sysvol: dissect.target.filesystem.Filesystem) OSPlugin #
Initiate this OSPlugin with the given target and detected filesystem.
Note: must be implemented as a classmethod.
- Parameters:
target – The Target object.
sysvol – The filesystem that was detected in the detect() function.
- Returns:
An instantiated version of the OSPlugin.
- abstract hostname() str | None #
Required OS function.
Implementations must be decorated with
@export(property=True)
.- Returns:
The hostname as string.
- abstract ips() list[str] #
Required OS function.
Implementations must be decorated with
@export(property=True)
.- Returns:
The IPs as list.
- abstract version() str | None #
Required OS function.
Implementations must be decorated with
@export(property=True)
.- Returns:
The OS version as string.
- abstract users() list[flow.record.Record] #
Required OS function.
Implementations must be decorated with @export.
- Returns:
A list of user records.
- abstract os() str #
Required OS function.
Implementations must be decorated with
@export(property=True)
.- Returns:
A slug of the OS name, e.g. ‘windows’ or ‘linux’.
- abstract architecture() str | None #
Required OS function.
Implementations must be decorated with
@export(property=True)
.- Returns:
A slug of the OS architecture, e.g. ‘x86_32-unix’, ‘MIPS-linux’ or ‘AMD64-win32’, or ‘unknown’ if the architecture is unknown.
- class dissect.target.plugin.ChildTargetPlugin(target: dissect.target.Target)#
Bases:
Plugin
A Child target is a special plugin that can list more Targets.
For example,
ESXiChildTargetPlugin
can list all of the Virtual Machines on the host.- __type__#
- abstract list_children() Iterator[dissect.target.helpers.record.ChildTargetRecord] #
Yield
ChildTargetRecord
records of all possible child targets on this target.
- dissect.target.plugin.register(plugincls: Type[Plugin]) None #
Register a plugin, and put related data inside
PLUGINS
.This function uses the following private attributes that are set using decorators:
__exported__
: Set inexport()
.__internal__
: Set ininternal()
.
Additionally,
register
sets the following private attributes on the plugincls:__plugin__
: Always set toTrue
.__functions__
: A list of all the methods and properties that are__internal__
or__exported__
.__exports__
: A list of all the methods or properties that were explicitly exported.
- Parameters:
plugincls – A plugin class to register.
- Raises:
ValueError – If
plugincls
is not a subclass ofPlugin
.
- dissect.target.plugin.internal(*args, **kwargs) Callable #
Decorator to be used on plugin functions that should be internal only.
Making a plugin internal means that it’s only callable from the Python API and not through
target-query
.This decorator adds the
__internal__
private attribute to a method or property. The attribute is always set toTrue
, to tellregister()
that it is an internal method or property.
- dissect.target.plugin.arg(*args, **kwargs) Callable #
Decorator to be used on Plugin functions that accept additional command line arguments.
Command line arguments can be added using the
@arg
decorator. Arguments to this decorator are directly forwarded to theArgumentParser.add_argument
function ofargparse
. Resulting arguments are passed to the function using kwargs. The keyword argument name must match the argparse argument name.This decorator adds the
__args__
private attribute to a method or property. This attribute holds all the command line arguments that were added to the plugin function.
- dissect.target.plugin.plugins(osfilter: type[OSPlugin] | None = None) Iterator[PluginDescriptor] #
Retrieve all plugin descriptors.
- Parameters:
osfilter – The
OSPlugin
to use as template to find os specific plugins for.- Returns:
An iterator of all plugin descriptors, optionally filtered on OS.
- dissect.target.plugin.os_plugins() Iterator[PluginDescriptor] #
Retrieve all OS plugin descriptors.
- dissect.target.plugin.child_plugins() Iterator[PluginDescriptor] #
Retrieve all child plugin descriptors.
- dissect.target.plugin.lookup(func_name: str, osfilter: type[OSPlugin] | None = None) Iterator[PluginDescriptor] #
Lookup a plugin descriptor by function name.
- Parameters:
func_name – Function name to lookup.
osfilter – The
OSPlugin
to use as template to find os specific plugins for.
- dissect.target.plugin.get_plugins_by_func_name(func_name: str, osfilter: type[OSPlugin] | None = None) Iterator[PluginDescriptor] #
Get a plugin descriptor by function name.
- Parameters:
func_name – Function name to lookup.
osfilter – The
OSPlugin
to use as template to find os specific plugins for.
- dissect.target.plugin.get_plugins_by_namespace(namespace: str, osfilter: type[OSPlugin] | None = None) Iterator[PluginDescriptor] #
Get a plugin descriptor by namespace.
- Parameters:
namespace – Plugin namespace to match.
osfilter – The
OSPlugin
to use as template to find os specific plugins for.
- dissect.target.plugin.load(plugin_desc: dict) Type[Plugin] #
Helper function that loads a plugin from a given plugin description.
- Parameters:
plugin_desc – Plugin description as returned by plugin.lookup().
- Returns:
The plugin class.
- Raises:
PluginError – Raised when any other exception occurs while trying to load the plugin.
- dissect.target.plugin.failed() list[dict[str, Any]] #
Return all plugins that failed to load.
- dissect.target.plugin.save_plugin_import_failure(module: str) None #
Store errors that occurred during plugin import.
- dissect.target.plugin.find_py_files(plugin_path: pathlib.Path) Iterator[pathlib.Path] #
Walk all the files and directories in
plugin_path
and return all files ending in.py
.Do not walk or yield paths containing the following names:
__pycache__
__init__
Furthermore, it logs an error if
plugin_path
does not exist.- Parameters:
plugin_path – The path to a directory or file to walk and filter.
- dissect.target.plugin.load_module_from_name(module_path: str) None #
Load a module from
module_path
.
- dissect.target.plugin.generate() dict[str, Any] #
Internal function to generate the list of available plugins.
Walks the plugins directory and imports any .py files in there. Plugins will be automatically registered due to the decorators on them.
- Returns:
The global
PLUGINS
dictionary.
- dissect.target.plugin.load_module_from_file(path: pathlib.Path, base_path: pathlib.Path)#
Loads a module from a file indicated by
path
relative tobase_path
.The module is added to
sys.modules
so it can be found everywhere.- Parameters:
path – The file to load as module.
base_path – The base directory of the module.
- dissect.target.plugin.load_modules_from_paths(plugin_dirs: list[pathlib.Path]) None #
Iterate over the
plugin_dirs
and load all.py
files.
- dissect.target.plugin.get_external_module_paths(path_list: list[pathlib.Path]) list[pathlib.Path] #
Create a deduplicated list of paths.
- dissect.target.plugin.environment_variable_paths() list[pathlib.Path] #
- class dissect.target.plugin.NamespacePlugin(target: dissect.target.Target)#
Bases:
Plugin
Base class for plugins.
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
:A
Plugin
class has the following private class attributes:__namespace__
__record_descriptors__
With the following three being assigned in
register()
:__plugin__
__functions__
__exports__
Additionally, the methods and attributes of
Plugin
receive more private attributes by using decorators.The
export()
decorator adds the following private attributes__exported__
__output__
: Set with theexport()
decorator.__record__
: Set with theexport()
decorator.
The
internal()
decorator andInternalPlugin
set the__internal__
attribute. Finally.args()
decorator sets the__args__
attribute.- Parameters:
target – The
Target
object to load the plugin for.
- 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.
- __init_subclass_namespace__(**kwargs)#
- __init_subclass_subplugin__(**kwargs)#
- classmethod __init_subclass__(**kwargs)#
- class dissect.target.plugin.InternalPlugin(target: dissect.target.Target)#
Bases:
Plugin
Parent class for internal plugins.
InternalPlugin marks all non-private methods internal by default (same as
@internal
decorator).- classmethod __init_subclass__(**kwargs)#
- class dissect.target.plugin.PluginFunction#
- name: str#
- path: str#
- output_type: str#
- method_name: str#
- plugin_desc: dict#
- dissect.target.plugin.plugin_function_index(target: dissect.target.Target) tuple[dict[str, Any], set[str]] #
Returns an index-list for plugins.
This list is used to match CLI expressions against to find the desired plugin. Also returns the roots to determine whether a CLI expression has to be compared to the plugin tree or parsed using legacy rules.
- dissect.target.plugin.find_plugin_functions(target: dissect.target.Target, patterns: str, compatibility: bool = False, **kwargs) tuple[list[PluginFunction], set[str]] #
Finds plugins that match the target and the patterns.
Given a target, a comma separated list of patterns and an optional compatibility flag, this function finds matching plugins, optionally checking compatibility and returns a list of plugin function descriptors (including output types).