Merge pull request #1091 from volatilityfoundation/release/v2.5.2

Documentation: Update copyright in README.md for 2024

.github/workflows/install.yml

@@ -0,0 +1,31 @@
+name: Install Volatility3 test
+on: [push, pull_request]
+jobs:
+
+  install_test:
+    runs-on: ${{ matrix.host }}
+    strategy:
+      fail-fast: false
+      matrix:
+        host: [ ubuntu-latest, windows-latest ]
+        python-version: [ "3.7", "3.8", "3.9", "3.10", "3.11" ]
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Setup python-pip
+      run: python -m pip install --upgrade pip
+
+    - name: Install dependencies
+      run: |
+        pip install -r requirements.txt
+
+    - name: Install volatility3
+      run: pip install .
+
+    - name: Run volatility3
+      run: vol --help

.github/workflows/stale.yml

@@ -0,0 +1,23 @@
+name: Close inactive issues
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v5
+        with:
+          days-before-issue-stale: 200
+          days-before-issue-close: 60
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 200 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 60 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          exempt-issue-labels: "enhancement,plugin-request,question"

CITATION.cff

@@ -0,0 +1,37 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: Volatility 3
+message: >-
+  If you reference this software, please feel free to cite
+  it using the information below.
+type: software
+authors:
+  - name: Volatility Foundation
+    country: US
+    website: 'https://www.volatilityfoundation.org/'
+identifiers:
+  - type: url
+    value: 'https://github.com/volatilityfoundation/volatility3'
+    description: Volatility 3 source code respository
+repository-code: 'https://github.com/volatilityfoundation/volatility3'
+url: 'https://github.com/volatilityfoundation/volatility3'
+abstract: >-
+  Volatility is the world's most widely used framework for
+  extracting digital artifacts from volatile memory (RAM)
+  samples. The extraction techniques are performed
+  completely independent of the system being investigated
+  but offer visibility into the runtime state of the system.
+  The framework is intended to introduce people to the
+  techniques and complexities associated with extracting
+  digital artifacts from volatile memory samples and provide
+  a platform for further work into this exciting area of
+  research.
+keywords:
+  - malware
+  - forensics
+  - memory
+  - python
+  - ram
+  - volatility

README.md

@@ -107,7 +107,7 @@ The latest generated copy of the documentation can be found at: <https://volatil
 
 ## Licensing and Copyright
 
-Copyright (C) 2007-2023 Volatility Foundation
+Copyright (C) 2007-2024 Volatility Foundation
 
 All Rights Reserved
 

doc/source/conf.py

@@ -27,7 +27,7 @@ def setup(app):
 
     source_dir = os.path.abspath(os.path.dirname(__file__))
     sphinx.ext.apidoc.main(
-        argv=["-e", "-M", "-f", "-T", "-o", source_dir, volatility_directory]
+        ["-e", "-M", "-f", "-T", "-o", source_dir, volatility_directory]
     )
 
     # Go through the volatility3.framework.plugins files and change them to volatility3.plugins
@@ -169,7 +169,7 @@ def setup(app):
 
 # General information about the project.
 project = "Volatility 3"
-copyright = "2012-2022, Volatility Foundation"
+copyright = "2012-2024, Volatility Foundation"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/source/using-as-a-library.rst

@@ -54,6 +54,12 @@ also be included, which can be found in `volatility3.constants.PLUGINS_PATH`.
         volatility3.plugins.__path__ = <new_plugin_path> + constants.PLUGINS_PATH
         failures = framework.import_files(volatility3.plugins, True)
 
+.. note::
+
+    Volatility uses the `volatility3.plugins` namespace for all plugins (including those in `volatility3.framework.plugins`).
+    Please ensure you only use `volatility3.plugins` and only ever import plugins from this namespace.
+    This ensures the ability of users to override core plugins without needing write access to the framework directory.
+
 Once the plugins have been imported, we can interrogate which plugins are available.  The
 :py:func:`~volatility3.framework.list_plugins` call will
 return a dictionary of plugin names and the plugin classes.

requirements-dev.txt

@@ -1,5 +1,5 @@
 # The following packages are required for core functionality.
-pefile>=2017.8.1
+pefile>=2023.2.7
 
 # The following packages are optional.
 # If certain packages are not necessary, place a comment (#) at the start of the line.

requirements-minimal.txt

@@ -1,2 +1,2 @@
 # These packages are required for core functionality.
-pefile>=2017.8.1 #foo
+pefile>=2023.2.7 #foo

requirements.txt

@@ -1,5 +1,5 @@
 # The following packages are required for core functionality.
-pefile>=2017.8.1
+pefile>=2023.2.7
 
 # The following packages are optional.
 # If certain packages are not necessary, place a comment (#) at the start of the line.
@@ -16,3 +16,7 @@ pycryptodome
 
 # This is required for memory acquisition via leechcore/pcileech.
 leechcorepyc>=2.4.0
+
+# This is required for memory analysis on a Amazon/MinIO S3 and Google Cloud object storage
+gcsfs>=2023.1.0
+s3fs>=2023.1.0

setup.py

@@ -12,14 +12,15 @@
 
 def get_install_requires():
     requirements = []
-    with open("requirements-minimal.txt", "r", encoding = "utf-8") as fh:
+    with open("requirements-minimal.txt", "r", encoding="utf-8") as fh:
         for line in fh.readlines():
             stripped_line = line.strip()
             if stripped_line == "" or stripped_line.startswith("#"):
                 continue
             requirements.append(stripped_line)
     return requirements
 
+
 setuptools.setup(
     name="volatility3",
     description="Memory forensics framework",
@@ -36,12 +37,12 @@ def get_install_requires():
         "Documentation": "https://volatility3.readthedocs.io/",
         "Source Code": "https://github.com/volatilityfoundation/volatility3",
     },
-    python_requires=">=3.7.0",
-    include_package_data=True,
-    exclude_package_data={"": ["development", "development.*"], "development": ["*"]},
     packages=setuptools.find_namespace_packages(
-        exclude=["development", "development.*"]
+        include=["volatility3", "volatility3.*"]
     ),
+    package_dir={"volatility3": "volatility3"},
+    python_requires=">=3.7.0",
+    include_package_data=True,
     entry_points={
         "console_scripts": [
             "vol = volatility3.cli:main",

volatility3/cli/__init__.py

@@ -662,7 +662,7 @@ def __init__(self, filename: str):
             def close(self):
                 # Don't overcommit
                 if self.closed:
-                    return
+                    return None
 
                 self.seek(0)
 
@@ -712,7 +712,7 @@ def close(self):
                 """Closes and commits the file (by moving the temporary file to the correct name"""
                 # Don't overcommit
                 if self._file.closed:
-                    return
+                    return None
 
                 self._file.close()
                 output_filename = self._get_final_filename()

volatility3/cli/text_renderer.py

@@ -389,9 +389,11 @@ class JsonRenderer(CLIRenderer):
         interfaces.renderers.Disassembly: quoted_optional(display_disassembly),
         format_hints.MultiTypeData: quoted_optional(multitypedata_as_text),
         bytes: optional(lambda x: " ".join([f"{b:02x}" for b in x])),
-        datetime.datetime: lambda x: x.isoformat()
-        if not isinstance(x, interfaces.renderers.BaseAbsentValue)
-        else None,
+        datetime.datetime: lambda x: (
+            x.isoformat()
+            if not isinstance(x, interfaces.renderers.BaseAbsentValue)
+            else None
+        ),
         "default": lambda x: x,
     }
 

volatility3/cli/volshell/generic.py

@@ -108,7 +108,7 @@ def help(self, *args):
         """Describes the available commands"""
         if args:
             help(*args)
-            return
+            return None
 
         variables = []
         print("\nMethods:")
@@ -325,7 +325,7 @@ def display_type(
             (str, interfaces.objects.ObjectInterface, interfaces.objects.Template),
         ):
             print("Cannot display information about non-type object")
-            return
+            return None
 
         if not isinstance(object, str):
             # Mypy requires us to order things this way
@@ -453,7 +453,7 @@ def display_symbols(self, symbol_table: str = None):
         """Prints an alphabetical list of symbols for a symbol table"""
         if symbol_table is None:
             print("No symbol table provided")
-            return
+            return None
         longest_offset = longest_name = 0
 
         table = self.context.symbol_space[symbol_table]

volatility3/cli/volshell/linux.py

@@ -35,9 +35,9 @@ def change_task(self, pid=None):
                 process_layer = task.add_process_layer()
                 if process_layer is not None:
                     self.change_layer(process_layer)
-                    return
+                    return None
                 print(f"Layer for task ID {pid} could not be constructed")
-                return
+                return None
         print(f"No task with task ID {pid} found")
 
     def list_tasks(self):

volatility3/cli/volshell/mac.py

@@ -35,9 +35,9 @@ def change_task(self, pid=None):
                 process_layer = task.add_process_layer()
                 if process_layer is not None:
                     self.change_layer(process_layer)
-                    return
+                    return None
                 print(f"Layer for task ID {pid} could not be constructed")
-                return
+                return None
         print(f"No task with task ID {pid} found")
 
     def list_tasks(self, method=None):

volatility3/cli/volshell/windows.py

@@ -32,7 +32,7 @@ def change_process(self, pid=None):
             if process.UniqueProcessId == pid:
                 process_layer = process.add_process_layer()
                 self.change_layer(process_layer)
-                return
+                return None
         print(f"No process with process ID {pid} found")
 
     def list_processes(self):

volatility3/framework/__init__.py

@@ -206,9 +206,9 @@ def _zipwalk(path: str):
             if not file.is_dir():
                 dirlist = zip_results.get(os.path.dirname(file.filename), [])
                 dirlist.append(os.path.basename(file.filename))
-                zip_results[
-                    os.path.join(path, os.path.dirname(file.filename))
-                ] = dirlist
+                zip_results[os.path.join(path, os.path.dirname(file.filename))] = (
+                    dirlist
+                )
     for value in zip_results:
         yield value, zip_results[value]
 

volatility3/framework/automagic/mac.py

@@ -138,9 +138,9 @@ def stack(
                 config_path = join("automagic", "MacIntelHelper", new_layer_name)
                 context.config[join(config_path, "memory_layer")] = layer_name
                 context.config[join(config_path, "page_map_offset")] = dtb
-                context.config[
-                    join(config_path, MacSymbolFinder.banner_config_key)
-                ] = str(banner, "latin-1")
+                context.config[join(config_path, MacSymbolFinder.banner_config_key)] = (
+                    str(banner, "latin-1")
+                )
 
                 new_layer = intel.Intel32e(
                     context,

volatility3/framework/automagic/module.py

@@ -29,21 +29,21 @@ def __call__(
                     requirement.requirements[req],
                     progress_callback,
                 )
-            return
+            return None
         if not requirement.unsatisfied(context, config_path):
-            return
+            return None
         # The requirement is unfulfilled and is a ModuleRequirement
 
-        context.config[
-            interfaces.configuration.path_join(new_config_path, "class")
-        ] = "volatility3.framework.contexts.Module"
+        context.config[interfaces.configuration.path_join(new_config_path, "class")] = (
+            "volatility3.framework.contexts.Module"
+        )
 
         for req in requirement.requirements:
             if (
                 requirement.requirements[req].unsatisfied(context, new_config_path)
                 and req != "offset"
             ):
-                return
+                return None
 
         # We now just have the offset requirement, but the layer requirement has been fulfilled.
         # Unfortunately we don't know the layer name requirement's exact name

volatility3/framework/automagic/stacker.py

@@ -103,7 +103,7 @@ def stack(
                 appropriate_config_path, layer_name = result
                 context.config.merge(appropriate_config_path, subconfig)
                 context.config[appropriate_config_path] = top_layer_name
-                return
+                return None
             self._cached = None
 
         new_context = context.clone()
@@ -156,6 +156,9 @@ def stack(
                 self._cached = context.config.get(path, None), context.config.branch(
                     path
                 )
+        vollog.debug(
+            f"physical_layer maximum_address: {physical_layer.maximum_address}"
+        )
         vollog.debug(f"Stacked layers: {stacked_layers}")
 
     @classmethod

volatility3/framework/automagic/symbol_cache.py

@@ -429,7 +429,7 @@ def update(self, progress_callback=None):
             progress_callback(0, "Reading remote ISF list")
             cursor = self._database.cursor()
             cursor.execute(
-                f"SELECT cached FROM cache WHERE local = 0 and cached < datetime('now', {self.cache_period})"
+                f"SELECT cached FROM cache WHERE local = 0 and cached < datetime('now', '{self.cache_period}')"
             )
             remote_identifiers = RemoteIdentifierFormat(constants.REMOTE_ISF_URL)
             progress_callback(50, "Reading remote ISF list")
@@ -438,9 +438,13 @@ def update(self, progress_callback=None):
                     {}, operating_system=operating_system
                 )
                 for identifier, location in identifiers:
+                    identifier = identifier.rstrip()
+                    identifier = (
+                        identifier[:-1] if identifier.endswith(b"\x00") else identifier
+                    )  # Linux banners dumped by dwarf2json end with "\x00\n". If not stripped, the banner cannot match.
                     cursor.execute(
                         "INSERT OR REPLACE INTO cache(identifier, location, operating_system, local, cached) VALUES (?, ?, ?, ?, datetime('now'))",
-                        (location, identifier, operating_system, False),
+                        (identifier, location, operating_system, False),
                     )
             progress_callback(100, "Reading remote ISF list")
             self._database.commit()