dissect.target 3.15.dev2__tar.gz → 3.15.dev4__tar.gz

{dissect.target-3.15.dev2/dissect.target.egg-info → dissect.target-3.15.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dissect.target
-Version: 3.15.dev2
+Version: 3.15.dev4
 Summary: This module ties all other Dissect modules together, it provides a programming API and command line tools which allow easy access to various data sources inside disk images or file collections (a.k.a. targets)
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3

{dissect.target-3.15.dev2 → dissect.target-3.15.dev4}/dissect/target/plugin.py

@@ -292,18 +292,43 @@ class OSPlugin(Plugin):
     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.
+
+    All derived classes MUST implement ALL the classmethods and exported
+    methods with the same ``@classmethod`` or ``@export(...)`` annotation.
     """
 
+    def __init_subclass__(cls, **kwargs):
+        # Note that cls is the subclass
+        super().__init_subclass__(**kwargs)
+
+        for os_method in get_nonprivate_attributes(OSPlugin):
+            if isinstance(os_method, property):
+                os_method = os_method.fget
+            os_docstring = os_method.__doc__
+
+            method = getattr(cls, os_method.__name__, None)
+            if isinstance(method, property):
+                method = method.fget
+            # This works as None has a __doc__ property (which is None).
+            docstring = method.__doc__
+
+            if method and not docstring:
+                if hasattr(method, "__func__"):
+                    method = method.__func__
+                method.__doc__ = os_docstring
+
     def check_compatible(self) -> bool:
-        """OSPlugin's use a different compatibility check, override the default one."""
+        """OSPlugin's use a different compatibility check, override the one from the :class:`Plugin` class.
+
+        Returns:
+            This function always returns ``True``.
+        """
         return True
 
     @classmethod
     def detect(cls, fs: Filesystem) -> Optional[Filesystem]:
         """Provide detection of this OSPlugin on a given filesystem.
 
-        Note: must be implemented as a classmethod.
-
         Args:
             fs: :class:`~dissect.target.filesystem.Filesystem` to detect the OS on.
 
@@ -316,11 +341,9 @@ class OSPlugin(Plugin):
     def create(cls, target: Target, sysvol: Filesystem) -> OSPlugin:
         """Initiate this OSPlugin with the given target and detected filesystem.
 
-        Note: must be implemented as a classmethod.
-
         Args:
-            target: The Target object.
-            sysvol: The filesystem that was detected in the detect() function.
+            target: The :class:`~dissect.target.target.Target` object.
+            sysvol: The filesystem that was detected in the ``detect()`` function.
 
         Returns:
             An instantiated version of the OSPlugin.
@@ -329,9 +352,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def hostname(self) -> Optional[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return the target's hostname.
 
         Returns:
             The hostname as string.
@@ -340,9 +361,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def ips(self) -> list[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return the IP addresses configured in the target.
 
         Returns:
             The IPs as list.
@@ -351,9 +370,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def version(self) -> Optional[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return the target's OS version.
 
         Returns:
             The OS version as string.
@@ -362,9 +379,7 @@ class OSPlugin(Plugin):
 
     @export(record=EmptyRecord)
     def users(self) -> list[Record]:
-        """Required OS function.
-
-        Implementations must be decorated with @export.
+        """Return the users available in the target.
 
         Returns:
             A list of user records.
@@ -373,9 +388,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def os(self) -> str:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return a slug of the target's OS name.
 
         Returns:
             A slug of the OS name, e.g. 'windows' or 'linux'.
@@ -384,9 +397,7 @@ class OSPlugin(Plugin):
 
     @export(property=True)
     def architecture(self) -> Optional[str]:
-        """Required OS function.
-
-        Implementations must be decorated with ``@export(property=True)``.
+        """Return a slug of the target's OS architecture.
 
         Returns:
             A slug of the OS architecture, e.g. 'x86_32-unix', 'MIPS-linux' or
@@ -1128,29 +1139,45 @@ def find_plugin_functions(
     ignore_load_errors = kwargs.get("ignore_load_errors", False)
 
     for pattern in patterns.split(","):
-        # backward compatibility fix for namespace-level plugins (i.e. chrome)
+        # Backward compatibility fix for namespace-level plugins (i.e. chrome)
+        # If an exact namespace match is found, the pattern is changed to the tree to that namespace.
+        # Examples:
+        #     -f browser -> apps.browser.browser
+        #     -f iexplore -> apps.browser.iexplore
+        namespace_match = False
         for index_name, func in functions.items():
             if func["namespace"] == pattern:
-                pattern = func["module"] + "*"
+                pattern = func["module"]
+                namespace_match = True
+                break
 
         wildcard = any(char in pattern for char in ["*", "!", "?", "[", "]"])
         treematch = pattern.split(".")[0] in rootset and pattern != "os"
         exact_match = pattern in functions
 
-        # Allow for exact matches, otherwise you cannot reach documented namespace plugins like
-        # browsers.browser.downloads. You can *always* run these using the namespace/classic-style like:
-        # browser.downloads (but -l lists them in the tree for documentation purposes so it would be misleading
-        # not to allow tree access as well). Note that these tree items will never respond to wildcards though
-        # (browsers.browser.* won't work) to avoid duplicate results.
-        if exact_match:
+        # Allow for exact and namespace matches even if the plugin does not want to be found, otherwise you cannot
+        # reach documented namespace plugins like apps.browser.browser.downloads.
+        # You can *always* run these using the namespace/classic-style like: browser.downloads (but -l lists them
+        # in the tree for documentation purposes so it would be misleading not to allow tree access as well).
+        #
+        # Note that these tree items will never respond to wildcards though to avoid duplicate results, e.g. when
+        # querying apps.browser.*, this also means apps.browser.browser.* won't work.
+        if exact_match or namespace_match:
             show_hidden = True
 
-        if treematch and not wildcard and not exact_match:
-            # Examples:
-            #     -f browsers -> browsers* (the whole package)
-            #     -f apps.webservers.iis -> apps.webservers.iis* (logs etc)
-            # We do not include  a dot because that does not work if the full path is given:
-            #     -f apps.webservers.iis.logs != apps.webservers.iis.logs.* (does not work)
+        # Change the treematch pattern into an fnmatch-able pattern to give back all functions from the sub-tree
+        # (if there is a subtree).
+        #
+        # Examples:
+        #     -f browser -> apps.browser.browser* (the whole package, due to a namespace match)
+        #     -f apps.webservers.iis -> apps.webservers.iis* (logs etc)
+        #     -f apps.webservers.iis.logs -> apps.webservers.iis.logs* (only the logs, there is no subtree)
+        # We do not include a dot because that does not work if the full path is given:
+        #     -f apps.webservers.iis.logs != apps.webservers.iis.logs.* (does not work)
+        #
+        # In practice a namespace_match would almost always also be a treematch, except when the namespace plugin
+        # is in the root of the plugin tree.
+        if (treematch or namespace_match) and not wildcard and not exact_match:
             pattern += "*"
 
         if wildcard or treematch:

{dissect.target-3.15.dev2 → dissect.target-3.15.dev4/dissect.target.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dissect.target
-Version: 3.15.dev2
+Version: 3.15.dev4
 Summary: This module ties all other Dissect modules together, it provides a programming API and command line tools which allow easy access to various data sources inside disk images or file collections (a.k.a. targets)
 Author-email: Dissect Team <dissect@fox-it.com>
 License: Affero General Public License v3

{dissect.target-3.15.dev2 → dissect.target-3.15.dev4}/tests/test_plugin.py

@@ -1,13 +1,15 @@
 import os
 from functools import reduce
 from pathlib import Path
+from typing import Optional
 from unittest.mock import MagicMock, Mock, patch
 
 import pytest
+from flow.record import Record
 
 from dissect.target.exceptions import UnsupportedPluginError
 from dissect.target.helpers.descriptor_extensions import UserRecordDescriptorExtension
-from dissect.target.helpers.record import create_extended_descriptor
+from dissect.target.helpers.record import EmptyRecord, create_extended_descriptor
 from dissect.target.plugin import (
     PLUGINS,
     NamespacePlugin,
@@ -393,7 +395,98 @@ def test_plugins_default_plugin(target_default: Target) -> None:
         "architecture",
     ],
 )
-def test_os_plugin_property_methods(target_bare: Target, method_name: str) -> str:
+def test_os_plugin_property_methods(target_bare: Target, method_name: str) -> None:
     os_plugin = OSPlugin(target_bare)
     with pytest.raises(NotImplementedError):
         getattr(os_plugin, method_name)
+
+
+class TestOS1(OSPlugin):
+    @export(property=True)
+    def hostname(self) -> Optional[str]:
+        pass
+
+    @export(property=True)
+    def ips(self) -> list[str]:
+        pass
+
+    @export(property=True)
+    def version(self) -> Optional[str]:
+        pass
+
+    @export(record=EmptyRecord)
+    def users(self) -> list[Record]:
+        pass
+
+    @export(property=True)
+    def os(self) -> str:
+        pass
+
+    @export(property=True)
+    def architecture(self) -> Optional[str]:
+        pass
+
+
+class TestOS2(OSPlugin):
+    @export(property=True)
+    def hostname(self) -> Optional[str]:
+        """Test docstring hostname"""
+        pass
+
+    @export(property=True)
+    def ips(self) -> list[str]:
+        """Test docstring ips"""
+        pass
+
+    @export(property=True)
+    def version(self) -> Optional[str]:
+        """Test docstring version"""
+        pass
+
+    @export(record=EmptyRecord)
+    def users(self) -> list[Record]:
+        """Test docstring users"""
+        pass
+
+    @export(property=True)
+    def os(self) -> str:
+        """Test docstring os"""
+        pass
+
+    @export(property=True)
+    def architecture(self) -> Optional[str]:
+        """Test docstring architecture"""
+        pass
+
+
+@pytest.mark.parametrize(
+    "subclass, replaced",
+    [
+        (TestOS1, True),
+        (TestOS2, False),
+    ],
+)
+def test_os_plugin___init_subclass__(subclass: type[OSPlugin], replaced: bool) -> None:
+    exported_methods = {
+        "hostname",
+        "ips",
+        "version",
+        "users",
+        "os",
+        "architecture",
+    }
+
+    for method_name in exported_methods:
+        os_method = getattr(OSPlugin, method_name)
+        if isinstance(os_method, property):
+            os_method = os_method.fget
+        os_docstring = os_method.__doc__
+
+        subclass_method = getattr(subclass, method_name)
+        if isinstance(subclass_method, property):
+            subclass_method = subclass_method.fget
+        subclass_docstring = subclass_method.__doc__
+
+        assert (os_docstring == subclass_docstring) is replaced
+        if not replaced:
+            assert subclass_docstring == f"Test docstring {method_name}"