Merge branch 'develop' into fbdev_plugin

.github/workflows/black.yml

@@ -1,4 +1,4 @@
-name: Black python linter
+name: Black python formatter
 
 on: [push, pull_request]
 

.github/workflows/install.yml

@@ -20,12 +20,8 @@ jobs:
     - 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
+      run: vol --help

.github/workflows/ruff.yaml

@@ -0,0 +1,15 @@
+---
+name: Ruff
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/ruff-action@v1
+        with:
+          args: check
+          src: "."

.github/workflows/test.yaml

@@ -16,21 +16,22 @@ jobs:
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install Cmake
-        pip install build
-        pip install -r ./test/requirements-testing.txt
+        python -m pip install --upgrade pip Cmake build
+        pip install .[test]
 
     - name: Build PyPi packages
       run: |
         python -m build
 
     - name: Download images
       run: |
+        mkdir test_images
+        cd test_images
         curl -sLO "https://downloads.volatilityfoundation.org/volatility3/images/linux-sample-1.bin.gz"
         gunzip linux-sample-1.bin.gz
         curl -sLO "https://downloads.volatilityfoundation.org/volatility3/images/win-xp-laptop-2005-06-25.img.gz"
         gunzip win-xp-laptop-2005-06-25.img.gz
+        cd -
 
     - name: Download and Extract symbols
       run: |
@@ -41,13 +42,17 @@ jobs:
 
     - name: Testing...
       run: |
-        py.test ./test/test_volatility.py --volatility=vol.py --image win-xp-laptop-2005-06-25.img -k test_windows -v
-        py.test ./test/test_volatility.py --volatility=vol.py --image linux-sample-1.bin -k test_linux -v
+        # VolShell
+        pytest ./test/test_volatility.py --volatility=volshell.py --image-dir=./test_images -k test_windows_volshell -v
+        pytest ./test/test_volatility.py --volatility=volshell.py --image-dir=./test_images -k test_linux_volshell -v
+
+        # Volatility
+        pytest ./test/test_volatility.py --volatility=vol.py --image-dir=./test_images -k "test_windows and not test_windows_volshell" -v
+        pytest ./test/test_volatility.py --volatility=vol.py --image-dir=./test_images -k "test_linux and not test_linux_volshell" -v
 
     - name: Clean up post-test
       run: |
-        rm -rf *.bin
-        rm -rf *.img
+        rm -rf test_images
         cd volatility3/symbols
         rm -rf linux
         rm -rf linux.zip

.readthedocs.yml

@@ -20,4 +20,7 @@ build:
 # Optionally set the version of Python and requirements required to build your docs
 python:
   install:
-    - requirements: doc/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

MANIFEST.in

@@ -1,6 +1,6 @@
 prune development
 include * .*
-include doc/make.bat doc/Makefile doc/requirements.txt
+include pyproject.toml doc/make.bat doc/Makefile
 recursive-include doc/source *
 recursive-include volatility3 *.json
 recursive-exclude doc/source volatility3.*.rst

README.md

@@ -18,62 +18,44 @@ the Volatility Software License (VSL). See the
 [LICENSE](https://www.volatilityfoundation.org/license/vsl-v1.0) file for 
 more details.
 
-## Requirements
+## Installing
 
-Volatility 3 requires Python 3.8.0 or later. To install the most minimal set of dependencies (some plugins will not work) use a command such as:
+Volatility 3 requires Python 3.8.0 or later and is published on the [PyPi registry](https://pypi.org/project/volatility3).
 
 ```shell
-pip3 install -r requirements-minimal.txt
+pip install volatility3
 ```
 
-Alternately, the minimal packages will be installed automatically when Volatility 3 is installed using pip. However, as noted in the Quick Start section below, Volatility 3 does not *need* to be installed prior to using it.
+If you want to use the latest development version of Volatility 3 we recommend you manually clone this repository and install an editable version of the project.
+We recommend you use a virtual environment to keep installed dependencies separate from system packages.
 
-```shell
-pip3 install .
-```
-
-To enable the full range of Volatility 3 functionality, use a command like the one below. For partial functionality, comment out any unnecessary packages in [requirements.txt](requirements.txt) prior to running the command.
-
-```shell
-pip3 install -r requirements.txt
-```
-
-## Downloading Volatility
-
-The latest stable version of Volatility will always be the stable branch of the GitHub repository. You can get the latest version of the code using the following command:
+The latest stable version of Volatility will always be the `stable` branch of the GitHub repository. The default branch is `develop`.
 
 ```shell
 git clone https://github.com/volatilityfoundation/volatility3.git
+cd volatility3/
+python3 -m venv venv && . venv/bin/activate
+pip install -e .[dev]
 ```
 
 ## Quick Start
 
-1. Clone the latest version of Volatility from GitHub:
-
-    ```shell
-    git clone https://github.com/volatilityfoundation/volatility3.git
-    ```
+1. Install Volatility 3 as documented in the Installing section of the readme.
 
 2. See available options:
 
     ```shell
-    python3 vol.py -h
+    vol -h
     ```
 
-3. To get more information on a Windows memory sample and to make sure
-Volatility supports that sample type, run
-`python3 vol.py -f <imagepath> windows.info`
-
-   Example:
+3. To get more information on a Windows memory sample and to make sure Volatility supports that sample type, run `vol -f <imagepath> windows.info`:
 
     ```shell
-    python3 vol.py -f /home/user/samples/stuxnet.vmem windows.info
+    vol -f /home/user/samples/stuxnet.vmem windows.info
     ```
 
-4. Run some other plugins. The `-f` or `--single-location` is not strictly
-required, but most plugins expect a single sample. Some also
-require/accept other options.  Run `python3 vol.py <plugin> -h`
-for more information on a particular command.
+4. Run some other plugins. The `-f` or `--single-location` is not strictly required, but most plugins expect a single sample.
+Some also require/accept other options.  Run `vol <plugin> -h` for more information on a particular command.
 
 ## Symbol Tables
 

development/banner_server.py

@@ -28,48 +28,65 @@ def convert_url(self, url):
 
     def run(self):
         context = contexts.Context()
-        json_output = {'version': 1}
+        json_output = {"version": 1}
 
         path = self._path
-        filename = '*'
+        filename = "*"
 
         for banner_cache in [linux.LinuxBannerCache, mac.MacBannerCache]:
             sub_path = banner_cache.os
             potentials = []
             for extension in constants.ISF_EXTENSIONS:
                 # Hopefully these will not be large lists, otherwise this might be slow
                 try:
-                    for found in pathlib.Path(path).joinpath(sub_path).resolve().rglob(filename + extension):
+                    for found in (
+                        pathlib.Path(path)
+                        .joinpath(sub_path)
+                        .resolve()
+                        .rglob(filename + extension)
+                    ):
                         potentials.append(found.as_uri())
                 except FileNotFoundError:
                     # If there's no linux symbols, don't cry about it
                     pass
 
-            new_banners = banner_cache.read_new_banners(context, 'BannerServer', potentials, banner_cache.symbol_name,
-                                                        banner_cache.os, progress_callback = PrintedProgress())
+            new_banners = banner_cache.read_new_banners(
+                context,
+                "BannerServer",
+                potentials,
+                banner_cache.symbol_name,
+                banner_cache.os,
+                progress_callback=PrintedProgress(),
+            )
             result_banners = {}
             for new_banner in new_banners:
                 # Only accept file schemes
-                value = [self.convert_url(url) for url in new_banners[new_banner] if
-                         urllib.parse.urlparse(url).scheme == 'file']
+                value = [
+                    self.convert_url(url)
+                    for url in new_banners[new_banner]
+                    if urllib.parse.urlparse(url).scheme == "file"
+                ]
                 if value and new_banner:
                     # Convert files into URLs
-                    result_banners[str(base64.b64encode(new_banner), 'latin-1')] = value
+                    result_banners[str(base64.b64encode(new_banner), "latin-1")] = value
 
             json_output[banner_cache.os] = result_banners
 
-        output_path = os.path.join(self._path, 'banners.json')
-        with open(output_path, 'w') as fp:
+        output_path = os.path.join(self._path, "banners.json")
+        with open(output_path, "w") as fp:
             vollog.warning(f"Banners file written to {output_path}")
             json.dump(json_output, fp)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
 
     parser = argparse.ArgumentParser()
-    parser.add_argument('--path', default = os.path.dirname(__file__))
-    parser.add_argument('--urlprefix', help = 'Web prefix that will eventually serve the ISF files',
-                        default = 'http://localhost/symbols')
+    parser.add_argument("--path", default=os.path.dirname(__file__))
+    parser.add_argument(
+        "--urlprefix",
+        help="Web prefix that will eventually serve the ISF files",
+        default="http://localhost/symbols",
+    )
 
     args = parser.parse_args()