Merge branch 'volatilityfoundation:develop' into linux_tracing_ftrace

volatility3/cli/__init__.py

@@ -363,11 +363,21 @@ class CommandLine:
             metavar="PLUGIN",
         )
         for plugin in sorted(plugin_list):
+            # First line of a plugin docstring will be the short description for -h.
+            # Text after the first two consecutive new lines will be
+            # the additional description (argparse epilog).
+            short_help = additional_help = None
+            if plugin_list[plugin].__doc__ is not None:
+                doc_split = plugin_list[plugin].__doc__.split("\n\n", 1)
+                short_help = doc_split[0].strip()
+                if len(doc_split) > 1:
+                    additional_help = doc_split[1].strip()
+
             plugin_parser = subparser.add_parser(
                 plugin,
-                help=plugin_list[plugin].__doc__,
-                description=plugin_list[plugin].__doc__,
-                epilog=plugin_list[plugin].additional_description,
+                help=short_help,
+                description=short_help,
+                epilog=additional_help,
             )
             self.populate_requirements_argparse(plugin_parser, plugin_list[plugin])
 

volatility3/framework/automagic/pdbscan.py

@@ -392,38 +392,42 @@ class KernelPDBScanner(interfaces.automagic.AutomagicInterface):
         # Try locating kernel base via x64 Low Stub in lower 1MB starting from second page (4KB)
         # If "Discard Low Memory" setting is disabled in BIOS, the Low Stub may be at the third/fourth or further pages
         for offset in range(0x1000, 0x100000, 0x1000):
-            jmp_and_completion_values = int.from_bytes(
-                physical_layer.read(offset, 0x8), "little"
-            )
-            if (
-                0xFFFFFFFFFFFF00FF & jmp_and_completion_values
-                != constants.windows.JMP_AND_COMPLETION_SIGNATURE
-            ):
-                continue
-            cr3_value = int.from_bytes(
-                physical_layer.read(
-                    offset + constants.windows.PROCESSOR_START_BLOCK_CR3_OFFSET, 0x8
-                ),
-                "little",
-            )
+            try:
+                jmp_and_completion_values = int.from_bytes(
+                    physical_layer.read(offset, 0x8), "little"
+                )
+                if (
+                    0xFFFFFFFFFFFF00FF & jmp_and_completion_values
+                    != constants.windows.JMP_AND_COMPLETION_SIGNATURE
+                ):
+                    continue
+                cr3_value = int.from_bytes(
+                    physical_layer.read(
+                        offset + constants.windows.PROCESSOR_START_BLOCK_CR3_OFFSET, 0x8
+                    ),
+                    "little",
+                )
 
-            # Compare previously observed valid page table address that's stored in vlayer._initial_entry
-            # with PROCESSOR_START_BLOCK->ProcessorState->SpecialRegisters->Cr3
-            # which was observed to be an invalid page address, so add 1 (to make it valid too)
-            if (cr3_value + 1) != vlayer._initial_entry:
+                # Compare previously observed valid page table address that's stored in vlayer._initial_entry
+                # with PROCESSOR_START_BLOCK->ProcessorState->SpecialRegisters->Cr3
+                # which was observed to be an invalid page address, so add 1 (to make it valid too)
+                if (cr3_value + 1) != vlayer._initial_entry:
+                    continue
+                potential_kernel_hint = int.from_bytes(
+                    physical_layer.read(
+                        offset
+                        + constants.windows.PROCESSOR_START_BLOCK_LM_TARGET_OFFSET,
+                        0x8,
+                    ),
+                    "little",
+                )
+                if 0x3 & potential_kernel_hint:
+                    continue
+                kernel_hint = potential_kernel_hint & 0xFFFFFFFFFFFF
+                kernel_base = kernel_hint & (~0x1FFFFF) & 0xFFFFFFFFFFFF
+                break
+            except exceptions.InvalidAddressException:
                 continue
-            potential_kernel_hint = int.from_bytes(
-                physical_layer.read(
-                    offset + constants.windows.PROCESSOR_START_BLOCK_LM_TARGET_OFFSET,
-                    0x8,
-                ),
-                "little",
-            )
-            if 0x3 & potential_kernel_hint:
-                continue
-            kernel_hint = potential_kernel_hint & 0xFFFFFFFFFFFF
-            kernel_base = kernel_hint & (~0x1FFFFF) & 0xFFFFFFFFFFFF
-            break
 
         if kernel_base:
             # Scanning 32mb in 2mb chunks for the 'ntoskrnl' base address

volatility3/framework/interfaces/plugins.py

@@ -112,8 +112,6 @@ class PluginInterface(
     # Be careful with inheritance around this (We default to requiring a version which doesn't exist, so it must be set)
     _required_framework_version: Tuple[int, int, int] = (0, 0, 0)
     """The _version variable is a quick way for plugins to define their current interface, it should follow SemVer rules"""
-    additional_description: str = None
-    """Display additional description of the plugin after the description of the arguments. See: https://docs.python.org/3/library/argparse.html#epilog"""
 
     def __init__(
         self,

volatility3/framework/plugins/configwriter.py

@@ -14,8 +14,8 @@ vollog = logging.getLogger(__name__)
 
 
 class ConfigWriter(plugins.PluginInterface):
-    """Runs the automagics and both prints and outputs configuration in the
-    output directory."""
+    """Runs the automagics and both prints and outputs configuration in the \
+output directory."""
 
     _required_framework_version = (2, 0, 0)
 

volatility3/framework/plugins/linux/modxview.py

@@ -15,8 +15,8 @@ vollog = logging.getLogger(__name__)
 
 
 class Modxview(interfaces.plugins.PluginInterface):
-    """Centralize lsmod, check_modules and hidden_modules results to efficiently
-    spot modules presence and taints."""
+    """Centralize lsmod, check_modules and hidden_modules results to efficiently \
+spot modules presence and taints."""
 
     _version = (1, 0, 0)
     _required_framework_version = (2, 17, 0)

volatility3/framework/plugins/linux/pstree.py

@@ -9,8 +9,7 @@ from volatility3.plugins.linux import pslist
 
 
 class PsTree(interfaces.plugins.PluginInterface):
-    """Plugin for listing processes in a tree based on their parent process
-    ID."""
+    """Plugin for listing processes in a tree based on their parent process ID."""
 
     _required_framework_version = (2, 13, 0)
     _version = (1, 1, 1)

volatility3/framework/plugins/mac/mount.py

@@ -11,8 +11,8 @@ from volatility3.framework.symbols import mac
 
 
 class Mount(plugins.PluginInterface):
-    """A module containing a collection of plugins that produce data typically
-    found in Mac's mount command"""
+    """A module containing a collection of plugins that produce data typically \
+found in Mac's mount command"""
 
     _required_framework_version = (2, 0, 0)
 

volatility3/framework/plugins/mac/pstree.py

@@ -10,8 +10,7 @@ from volatility3.plugins.mac import pslist
 
 
 class PsTree(plugins.PluginInterface):
-    """Plugin for listing processes in a tree based on their parent process
-    ID."""
+    """Plugin for listing processes in a tree based on their parent process ID."""
 
     _required_framework_version = (2, 0, 0)
 

volatility3/framework/plugins/timeliner.py

@@ -41,8 +41,8 @@ class TimeLinerInterface(metaclass=abc.ABCMeta):
 
 
 class Timeliner(interfaces.plugins.PluginInterface):
-    """Runs all relevant plugins that provide time related information and
-    orders the results by time."""
+    """Runs all relevant plugins that provide time related information and \
+orders the results by time."""
 
     _required_framework_version = (2, 0, 0)
     _version = (1, 1, 0)

volatility3/framework/plugins/windows/pstree.py

@@ -14,8 +14,7 @@ vollog = logging.getLogger(__name__)
 
 
 class PsTree(interfaces.plugins.PluginInterface):
-    """Plugin for listing processes in a tree based on their parent process
-    ID."""
+    """Plugin for listing processes in a tree based on their parent process ID."""
 
     _required_framework_version = (2, 0, 0)
 

volatility3/framework/plugins/windows/psxview.py

@@ -21,9 +21,10 @@ vollog = logging.getLogger(__name__)
 
 
 class PsXView(plugins.PluginInterface):
-    """Lists all processes found via four of the methods described in \"The Art of Memory Forensics,\" which may help
-    identify processes that are trying to hide themselves. I recommend using -r pretty if you are looking at this
-    plugin's output in a terminal."""
+    """Lists all processes found via four of the methods described in \"The Art of Memory Forensics\" which may help \
+identify processes that are trying to hide themselves.
+
+We recommend using -r pretty if you are looking at this plugin's output in a terminal."""
 
     # I've omitted the desktop thread scanning method because Volatility3 doesn't appear to have the functionality
     # which the original plugin used to do it.

volatility3/framework/plugins/windows/registry/hivescan.py

@@ -12,8 +12,7 @@ from volatility3.plugins.windows import poolscanner, bigpools
 
 
 class HiveScan(interfaces.plugins.PluginInterface):
-    """Scans for registry hives present in a particular windows memory
-    image."""
+    """Scans for registry hives present in a particular windows memory image."""
 
     _required_framework_version = (2, 0, 0)
     _version = (1, 0, 0)

volatility3/framework/plugins/windows/scheduled_tasks.py

@@ -1099,9 +1099,8 @@ class DynamicInfo:
 
 
 class ScheduledTasks(interfaces.plugins.PluginInterface, timeliner.TimeLinerInterface):
-    """Decodes scheduled task information from the Windows registry, including
-    information about triggers, actions, run times, and creation times.
-    """
+    """Decodes scheduled task information from the Windows registry, including \
+information about triggers, actions, run times, and creation times."""
 
     _required_framework_version = (2, 11, 0)
     _version = (1, 0, 0)