Improve docstrings for all plugins, and reformat all docstrings.

volatility/framework/plugins/linux/__init__.py

@@ -1,7 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""All core linux plugins
+"""All core linux plugins.
 
-These modules should only be imported from volatility.plugins NOT volatility.framework.plugins
+These modules should only be imported from volatility.plugins NOT
+volatility.framework.plugins
 """

volatility/framework/plugins/linux/bash.py

@@ -1,9 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 
 import datetime
 import struct
@@ -20,7 +19,7 @@ from volatility.plugins.linux import pslist
 
 
 class Bash(plugins.PluginInterface, timeliner.TimeLinerInterface):
-    """Recovers bash command history from memory"""
+    """Recovers bash command history from memory."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:

volatility/framework/plugins/linux/check_afinfo.py

@@ -1,9 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 import logging
 from typing import List
 
@@ -18,7 +17,7 @@ vollog = logging.getLogger(__name__)
 
 
 class Check_afinfo(plugins.PluginInterface):
-    """Verifies the operation function pointers of network protocols"""
+    """Verifies the operation function pointers of network protocols."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:

volatility/framework/plugins/linux/check_syscall.py

@@ -1,9 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 import logging
 from typing import List
 
@@ -25,7 +24,7 @@ except ImportError:
 
 
 class Check_syscall(plugins.PluginInterface):
-    """Check system call table for hooks"""
+    """Check system call table for hooks."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:
@@ -36,9 +35,7 @@ class Check_syscall(plugins.PluginInterface):
         ]
 
     def _get_table_size_next_symbol(self, table_addr, ptr_sz, vmlinux):
-        """
-        Returns the size of the table based on the next symbol
-        """
+        """Returns the size of the table based on the next symbol."""
         ret = 0
 
         sym_table = self.context.symbol_space[vmlinux.name]
@@ -58,10 +55,9 @@ class Check_syscall(plugins.PluginInterface):
         return ret
 
     def _get_table_size_meta(self, vmlinux):
-        """
-        returns the number of symbols that start with __syscall_meta__
-        this is a fast way to determine the number of system calls, but not the most accurate
-        """
+        """returns the number of symbols that start with __syscall_meta__ this
+        is a fast way to determine the number of system calls, but not the most
+        accurate."""
 
         return len(
             [sym for sym in self.context.symbol_space[vmlinux.name].symbols if sym.startswith("__syscall_meta__")])
@@ -77,11 +73,9 @@ class Check_syscall(plugins.PluginInterface):
         return table_size
 
     def _get_table_info_disassembly(self, ptr_sz, vmlinux):
-        """
-        Find the size of the system call table by disassembling functions
-        that immediately reference it in their first isntruction
-        This is in the form 'cmp reg,NR_syscalls'
-        """
+        """Find the size of the system call table by disassembling functions
+        that immediately reference it in their first isntruction This is in the
+        form 'cmp reg,NR_syscalls'."""
         table_size = 0
 
         if not has_capstone:

volatility/framework/plugins/linux/elfs.py

@@ -1,9 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 
 from typing import List
 
@@ -16,7 +15,7 @@ from volatility.plugins.linux import pslist
 
 
 class Elfs(plugins.PluginInterface):
-    """Lists all memory mapped ELF files for all processes"""
+    """Lists all memory mapped ELF files for all processes."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:

volatility/framework/plugins/linux/lsmod.py

@@ -1,11 +1,10 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 
-from typing import List
+from typing import List, Generator, Iterable
 
 from volatility.framework import contexts
 from volatility.framework import renderers, constants, interfaces
@@ -17,7 +16,7 @@ from volatility.framework.renderers import format_hints
 
 
 class Lsmod(plugins.PluginInterface):
-    """Lists loaded kernel modules"""
+    """Lists loaded kernel modules."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:
@@ -28,8 +27,18 @@ class Lsmod(plugins.PluginInterface):
         ]
 
     @classmethod
-    def list_modules(cls, context: interfaces.context.ContextInterface, layer_name: str, vmlinux_symbols: str):
-        """Lists all the modules in the primary layer"""
+    def list_modules(cls, context: interfaces.context.ContextInterface, layer_name: str,
+                     vmlinux_symbols: str) -> Iterable[interfaces.objects.ObjectInterface]:
+        """Lists all the modules in the primary layer.
+
+        Args:
+            context: The context to retrieve required elements (layers, symbol tables) from
+            layer_name: The name of the layer on which to operate
+            vmlinux_symbols: The name of the table containing the kernel symbols
+
+        Yields:
+            The modules present in the `layer_name` layer's modules list
+        """
         linux.LinuxUtilities.aslr_mask_symbol_table(context, vmlinux_symbols, layer_name)
 
         vmlinux = contexts.Module(context, vmlinux_symbols, layer_name, 0)

volatility/framework/plugins/linux/lsof.py

@@ -1,9 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 import logging
 from typing import List
 
@@ -18,7 +17,7 @@ vollog = logging.getLogger(__name__)
 
 
 class Lsof(plugins.PluginInterface):
-    """Lists all memory maps for all processes"""
+    """Lists all memory maps for all processes."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:

volatility/framework/plugins/linux/malfind.py

@@ -15,7 +15,7 @@ from volatility.framework.renderers import format_hints
 
 
 class Malfind(interfaces_plugins.PluginInterface):
-    """Lists process memory ranges that potentially contain injected code"""
+    """Lists process memory ranges that potentially contain injected code."""
 
     @classmethod
     def get_requirements(cls) -> List[interfaces.configuration.RequirementInterface]:
@@ -26,9 +26,8 @@ class Malfind(interfaces_plugins.PluginInterface):
         ]
 
     def _list_injections(self, task):
-        """Generate memory regions for a process that may contain
-        injected code.
-        """
+        """Generate memory regions for a process that may contain injected
+        code."""
 
         proc_layer_name = task.add_process_layer()
         if not proc_layer_name:

volatility/framework/plugins/linux/proc.py

@@ -1,9 +1,8 @@
 # This file is Copyright 2019 Volatility Foundation and licensed under the Volatility Software License 1.0
 # which is available at https://www.volatilityfoundation.org/license/vsl_v1.0
 #
-"""A module containing a collection of plugins that produce data
-typically found in Linux's /proc file system.
-"""
+"""A module containing a collection of plugins that produce data typically
+found in Linux's /proc file system."""
 
 from volatility.framework import renderers
 from volatility.framework.configuration import requirements
@@ -14,7 +13,7 @@ from volatility.plugins.linux import pslist
 
 
 class Maps(plugins.PluginInterface):
-    """Lists all memory maps for all processes"""
+    """Lists all memory maps for all processes."""
 
     @classmethod
     def get_requirements(cls):

volatility/framework/plugins/linux/pslist.py

@@ -12,7 +12,7 @@ from volatility.framework.objects import utility
 
 
 class PsList(interfaces_plugins.PluginInterface):
-    """Lists the processes present in a particular linux memory image"""
+    """Lists the processes present in a particular linux memory image."""
 
     _version = (1, 0, 0)
 
@@ -26,6 +26,14 @@ class PsList(interfaces_plugins.PluginInterface):
 
     @classmethod
     def create_pid_filter(cls, pid_list: List[int] = None) -> Callable[[Any], bool]:
+        """Constructs a filter function for process IDs.
+
+        Args:
+            pid_list: List of process IDs that are acceptable (or None if all are acceptable)
+
+        Returns:
+            Function which, when provided a process object, returns True if the process is to be filtered out of the list
+        """
         # FIXME: mypy #4973 or #2608
         pid_list = pid_list or []
         filter_list = [x for x in pid_list if x is not None]
@@ -58,7 +66,16 @@ class PsList(interfaces_plugins.PluginInterface):
                    vmlinux_symbols: str,
                    filter_func: Callable[[int], bool] = lambda _: False
                    ) -> Iterable[interfaces.objects.ObjectInterface]:
-        """Lists all the tasks in the primary layer"""
+        """Lists all the tasks in the primary layer.
+
+        Args:
+            context: The context to retrieve required elements (layers, symbol tables) from
+            layer_name: The name of the layer on which to operate
+            vmlinux_symbols: The name of the table containing the kernel symbols
+
+        Yields:
+            Process objects
+        """
         linux.LinuxUtilities.aslr_mask_symbol_table(context, vmlinux_symbols, layer_name)
 
         vmlinux = contexts.Module(context, vmlinux_symbols, layer_name, 0)

volatility/framework/plugins/linux/pstree.py

@@ -7,7 +7,8 @@ from volatility.plugins.linux import pslist
 
 
 class PsTree(pslist.PsList):
-    """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."""
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -16,7 +17,7 @@ class PsTree(pslist.PsList):
         self._children = {}
 
     def find_level(self, pid):
-        """Finds how deep the pid is in the processes list"""
+        """Finds how deep the pid is in the processes list."""
         seen = set([])
         seen.add(pid)
         level = 0
@@ -32,7 +33,7 @@ class PsTree(pslist.PsList):
         self._levels[pid] = level
 
     def _generator(self):
-        """Generates the """
+        """Generates the."""
         for proc in self.list_tasks(self.context, self.config['primary'], self.config['vmlinux']):
             self._processes[proc.pid] = proc