From 1fd51772600dc14ad6893e76362c9b8f599be180 Mon Sep 17 00:00:00 2001 From: lesander <4174509+lesander@users.noreply.github.com> Date: Fri, 8 Nov 2024 11:33:20 +0100 Subject: [PATCH 1/3] move dependency definitions to pyproject.toml and bump minimal cpython version to 3.9.0 since 3.8.0 is EOL. --- README.md | 48 +++++++++++++--------------------------- mypy.ini | 4 ---- pyproject.toml | 42 ++++++++++++++++++++++++++++++----- requirements-dev.txt | 9 -------- requirements-minimal.txt | 2 -- requirements.txt | 23 ------------------- setup.py | 24 -------------------- 7 files changed, 51 insertions(+), 101 deletions(-) delete mode 100644 mypy.ini delete mode 100644 requirements-dev.txt delete mode 100644 requirements-minimal.txt delete mode 100644 requirements.txt delete mode 100644 setup.py diff --git a/README.md b/README.md index 1463c2bde9..78eb7c4910 100644 --- a/README.md +++ b/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.9.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 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 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 -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 -h` for more information on a particular command. ## Symbol Tables diff --git a/mypy.ini b/mypy.ini deleted file mode 100644 index 6fb9f9ed3d..0000000000 --- a/mypy.ini +++ /dev/null @@ -1,4 +0,0 @@ -[mypy] -mypy_path = ./stubs -show_traceback = True -ignore_missing_imports = True diff --git a/pyproject.toml b/pyproject.toml index 2e1636a437..91848e1fd6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,15 +6,39 @@ readme = "README.md" authors = [ { name = "Volatility Foundation", email = "volatility@volatilityfoundation.org" }, ] -requires-python = ">=3.8.0" +requires-python = ">=3.9.0" license = { text = "VSL" } dynamic = ["dependencies", "optional-dependencies", "version"] +dependencies = [ + "pefile>=2024.8.26", +] + +[project.optional-dependencies] +full = [ + "yara-python>=4.5.1,<5", + "capstone>=5.0.3,<6", + "pycryptodome>=3.21.0,<4", + "leechcorepyc>=2.19.2,<3; sys_platform != 'darwin'", +] + +cloud = [ + "gcsfs>=2024.10.0", + "s3fs>=2024.10.0", +] + +dev = [ + "volatility3[full,cloud]", + "jsonschema>=4.23.0,<5", + "pyinstaller>=6.11.0,<7", + "pyinstaller-hooks-contrib>=2024.9", +] + [project.urls] -Homepage = "https://github.com/volatilityfoundation/volatility3/" -"Bug Tracker" = "https://github.com/volatilityfoundation/volatility3/issues" -Documentation = "https://volatility3.readthedocs.io/" -"Source Code" = "https://github.com/volatilityfoundation/volatility3" +homepage = "https://github.com/volatilityfoundation/volatility3/" +documentation = "https://volatility3.readthedocs.io/" +repository = "https://github.com/volatilityfoundation/volatility3" +issues = "https://github.com/volatilityfoundation/volatility3/issues" [project.scripts] vol = "volatility3.cli:main" @@ -22,11 +46,17 @@ volshell = "volatility3.cli.volshell:main" [tool.setuptools.dynamic] version = { attr = "volatility3.framework.constants._version.PACKAGE_VERSION" } -dependencies = { file = "requirements-minimal.txt" } [tool.setuptools.packages.find] include = ["volatility3*"] +[tool.mypy] +mypy_path = "./stubs" +show_traceback = true + +[tool.mypy.overrides] +ignore_missing_imports = true + [build-system] requires = ["setuptools>=68"] build-backend = "setuptools.build_meta" diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index ae3482290b..0000000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,9 +0,0 @@ --r requirements.txt - -# This can improve error messages regarding improperly configured ISF files, -# but is only recommended for development -jsonschema>=2.3.0 - -# Used to build executable file -pyinstaller>=6.5.0 -pyinstaller-hooks-contrib>=2024.3 \ No newline at end of file diff --git a/requirements-minimal.txt b/requirements-minimal.txt deleted file mode 100644 index c030b332dd..0000000000 --- a/requirements-minimal.txt +++ /dev/null @@ -1,2 +0,0 @@ -# These packages are required for core functionality. -pefile>=2023.2.7 #foo \ No newline at end of file diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index e0d3663911..0000000000 --- a/requirements.txt +++ /dev/null @@ -1,23 +0,0 @@ -# Include the minimal requirements --r requirements-minimal.txt - -# The following packages are optional. -# If certain packages are not necessary, place a comment (#) at the start of the line. - -# This is required for the yara plugins -yara-python>=3.8.0 - -# This is required for several plugins that perform malware analysis and disassemble code. -# It can also improve accuracy of Windows 8 and later memory samples. -# FIXME: Version 6.0.0 is incompatible (#1336) so we'll need an adaptor at some point -capstone>=3.0.5,<6.0.0 - -# This is required by plugins that decrypt passwords, password hashes, etc. -pycryptodome - -# This is required for memory acquisition via leechcore/pcileech. -leechcorepyc>=2.4.0; sys_platform != 'darwin' - -# This is required for memory analysis on a Amazon/MinIO S3 and Google Cloud object storage -gcsfs>=2023.1.0 -s3fs>=2023.1.0 diff --git a/setup.py b/setup.py deleted file mode 100644 index 3af0331602..0000000000 --- a/setup.py +++ /dev/null @@ -1,24 +0,0 @@ -# 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 -# - -import setuptools - - -def get_requires(filename): - requirements = [] - with open(filename, "r", encoding="utf-8") as fh: - for line in fh.readlines(): - stripped_line = line.strip() - if stripped_line == "" or stripped_line.startswith(("#", "-r")): - continue - requirements.append(stripped_line) - return requirements - - -setuptools.setup( - extras_require={ - "dev": get_requires("requirements-dev.txt"), - "full": get_requires("requirements.txt"), - }, -) From a04c04c4e3789008987ef18207ed242ff606ba1e Mon Sep 17 00:00:00 2001 From: lesander <4174509+lesander@users.noreply.github.com> Date: Fri, 8 Nov 2024 14:03:08 +0100 Subject: [PATCH 2/3] fix ci --- .github/workflows/install.yml | 6 +----- .github/workflows/test.yaml | 6 ++---- .readthedocs.yml | 5 ++++- MANIFEST.in | 2 +- doc/requirements.txt | 9 --------- pyproject.toml | 15 ++++++++++++++- test/README.md | 6 ++---- test/requirements-testing.txt | 11 ----------- 8 files changed, 24 insertions(+), 36 deletions(-) delete mode 100644 doc/requirements.txt delete mode 100644 test/requirements-testing.txt diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index 398ff8ae36..9b9cbed4df 100644 --- a/.github/workflows/install.yml +++ b/.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 \ No newline at end of file + run: vol --help diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 6358dd45d3..930b685261 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -16,10 +16,8 @@ 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: | diff --git a/.readthedocs.yml b/.readthedocs.yml index e7c2b25d55..628e79ebf7 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/MANIFEST.in b/MANIFEST.in index 1cec729f69..8636213816 100644 --- a/MANIFEST.in +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index d3ba512245..0000000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,9 +0,0 @@ -# These packages are required for building the documentation. -sphinx>=4.0.0,<7 -sphinx_autodoc_typehints>=1.4.0 -sphinx-rtd-theme>=0.4.3 - -yara-python -yara-x -pycryptodome -pefile diff --git a/pyproject.toml b/pyproject.toml index 91848e1fd6..a966e41b27 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ authors = [ ] requires-python = ">=3.9.0" license = { text = "VSL" } -dynamic = ["dependencies", "optional-dependencies", "version"] +dynamic = ["version"] dependencies = [ "pefile>=2024.8.26", @@ -34,6 +34,19 @@ dev = [ "pyinstaller-hooks-contrib>=2024.9", ] +test = [ + "volatility3[dev]", + "pytest>=8.3.3,<9", + "yara-x>=0.10.0,<1", +] + +docs = [ + "volatility3[dev]", + "sphinx>=8.0.0,<7", + "sphinx-autodoc-typehints>=2.5.0,<3", + "sphinx-rtd-theme>=3.0.1,<4", +] + [project.urls] homepage = "https://github.com/volatilityfoundation/volatility3/" documentation = "https://volatility3.readthedocs.io/" diff --git a/test/README.md b/test/README.md index dcbe289b0c..5891d9508b 100644 --- a/test/README.md +++ b/test/README.md @@ -2,14 +2,12 @@ ## Requirements -The Volatility 3 Testing Framework requires the same version of Python as Volatility3 itself. To install the current set of dependencies that the framework requires, use a command like this: +The Volatility 3 Testing Framework requires the same version of Python as Volatility 3 itself. To install the current set of dependencies that the framework requires, use a command like this: ```shell -pip3 install -r requirements-testing.txt +pip3 install -e .[test] ``` -NOTE: `requirements-testing.txt` can be found in this current `test/` directory. - ## Quick Start: Manual Testing 1. To test Volatility 3 on an image, first download one with a command such as: diff --git a/test/requirements-testing.txt b/test/requirements-testing.txt deleted file mode 100644 index 51c8f602c2..0000000000 --- a/test/requirements-testing.txt +++ /dev/null @@ -1,11 +0,0 @@ -# These packages are required for core functionality. -pefile>=2017.8.1 #foo - -# The following packages are optional. -# If certain packages are not necessary, place a comment (#) at the start of the line. - -# This is required for the yara plugins -yara-python>=3.8.0 -yara-x>=0.5.0 - -pytest>=7.0.0 From b739f8d067c024f84087bfdc2443b174cf559462 Mon Sep 17 00:00:00 2001 From: lesander <4174509+lesander@users.noreply.github.com> Date: Fri, 8 Nov 2024 14:05:54 +0100 Subject: [PATCH 3/3] revert 3.8 to 3.9 soft bump --- README.md | 2 +- pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 78eb7c4910..cc33d3cc43 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ more details. ## Installing -Volatility 3 requires Python 3.9.0 or later and is published on the [PyPi registry](https://pypi.org/project/volatility3). +Volatility 3 requires Python 3.8.0 or later and is published on the [PyPi registry](https://pypi.org/project/volatility3). ```shell pip install volatility3 diff --git a/pyproject.toml b/pyproject.toml index a966e41b27..fc1ab96cbc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ readme = "README.md" authors = [ { name = "Volatility Foundation", email = "volatility@volatilityfoundation.org" }, ] -requires-python = ">=3.9.0" +requires-python = ">=3.8.0" license = { text = "VSL" } dynamic = ["version"]