This repository hosts some ready-to-use Docker images based on Alpine Linux embedding the Volatility framework, including the newest Volatility 3 framework. Check out the official Volatility and Volatility 3 repositories for more information.
All images are directly available on Docker Hub:
By the way, why are these images not (yet) official?
sk4la/volatility3⭐ (version 2.0.1 from March 17, 2022)- The latest release of the official Volatility 3 project ;
- The community-maintained plugins for Volatility 3 ;
- The official symbol tables for Windows, macOS and GNU/Linux provided by the Volatility Foundation ;
- The symbol tables provided by the JPCERT/CC for the ongoing Windows 10+ support ;
The
latestandstabletags, as well as the literal version number (e.g2.0.1) all point to the latest official release. In order to follow the development cycle of Volatility 3, anedgetag has been added, which points to the current state of themasterbranch—which could be unstable. Power-users should feel free to use this one at their own expense.
-
- The latest release of the official Volatility project (unmaintained since 2020) ;
- The community-maintained plugins for Volatility.
-
- The official dwarf2json project.
Please let me know if there is anything missing or if you would like to see something else added to the mix.
Building and/or using these images requires Docker to be installed on the system. Please refer to the official documentation for more details on how to install and use the Docker toolchain.
As these images are built using GitHub Actions, the steps for building them are not explicitly documented here. Please refer directly to the CI workflows if you wish to build them locally.
⚠️ Be aware that symbol packs for Volatility 3 are directly embedded into thesk4la/volatility3image, which brings the size up for quite a bit. See my pull request on the official repository for more details on this.
Once the images have been pulled (or built), they can be instantiated inside fresh containers using docker run, for example:
docker run -v $PWD:/workspace sk4la/volatility3Or a more complete example:
docker run -v $PWD:/workspace sk4la/volatility3 -f /workspace/volatile.mem windows.pslistIn order to use the Volatility shell (a.k.a. the volshell) or other entrypoints, use the --entrypoint option when instantiating the container:
docker run -i -t -v $PWD:/workspace --entrypoint volshell sk4la/volatility3The
--interactiveand--ttyoptions (or their short versions, respectively-iand-t) are needed in order to keep the terminal open while interacting with the containerized application.
Note that every produced artifact will be lost unless stored using a volume or bind mount (as demonstrated here using the --volume option).
As determining the correct memory layout usually takes a bit of time, running Volatility interactively (i.e. instantiating the container using the
--interactiveflag) is preferred, although retrieving the configuration file using a volume is also possible. See the examples for practical use cases.
These images can be used either interactively or as a throwaway solution for punctual issues.
Example #1: Interactive session using Volatility3 command-line interface (CLI)
The following is a practical example of using Volatility 3 (and more precisely the sk4la/volatility3 Docker image) to dump a process executable from a volatile memory image.
💡 Long options are used here on purpose. For more details on the Docker CLI, please refer to the official documentation.
First, begin by instantiating a new container based on the sk4la/volatility3 image:
docker container run \
--entrypoint ash \
--interactive \
--tty \
--volume "$PWD:/home/unprivileged/workspace" \
--workdir /home/unprivileged/workspace \
sk4la/volatility3Then, inside the newly-created container, use Volatility 3 to parse the memory image and write the configuration to disk:
volatility3 \
--file volatile.mem \
--log volatile.mem.log \
--renderer pretty \
--write-config \
windows.infoThe configuration file config.json should reside in the current directory. This configuration can then be used as a basis for the upcoming runs using the --config flag—so that Volatility no longer has to crawl the image to find the right structures.
Next, extract the list of processes by executing Volatility 3 again using the previously generated configuration:
volatility3 \
--config config.json \
--file volatile.mem \
--log volatile.mem.log \
--renderer pretty \
windows.pslistFor post-processing, it is usually easier to dump the results in CSV or JSON format:
mkdir volatile.mem.results
volatility3 \
--config config.json \
--file volatile.mem \
--log volatile.mem.log \
--quiet \
--renderer csv \
windows.pslist \
| tee -a volatile.mem.results/pslist.csvThe file ~/workspace/volatile.mem.results/pslist.csv should contain the CSV-formatted results of the windows.pslist.PsList plugin.
For dumping a process image, first create a directory that will contain all future extractions, then execute Volatility again using the same windows.pslist.PsList plugin, but this time adding the --dump flag:
mkdir volatile.mem.dat
volatility3 \
--config config.json \
--file volatile.mem \
--log volatile.mem.log \
--output-dir volatile.mem.dat \
--renderer pretty \
windows.pslist \
--dump \
--pid 2700The binary sample should reside in the ~/workspace/volatile.mem.dat directory, ready to be analyzed by a reverse engineer.
Actually, all dumper plugins (i.e. a Volatility plugin that is able to dump raw content from the memory image) should support the --output-dir option, which is quite convenient in an analysis workflow.
Volatility is verbose but not necessarily precise when it comes to errors. When an error is raised, you should always increase the verbosity level (using
-vvvfor example) in order to get maximum details about what is going on, and eventually submit an issue on the official Volatility 3 repository if you deem it necessary.
Example #2: Generate an ISF file for a specific NT kernel build using pdbconv
This is very straightforward, simply instanciate a new container based on the sk4la/volatility3 image using the pdbconv entrypoint:
docker container run \
--entrypoint pdbconv \
--volume "$PWD:/home/unprivileged/workspace" \
--workdir /home/unprivileged/workspace \
sk4la/volatility3 --guid ce7ffb00c20b87500211456b3e905c471 --keep --pattern ntkrnlmp.pdbThis will generate the Intermediate Symbol File (ISF) file ce7ffb00c20b87500211456b3e905c47-1.json.xz in the current working directory, which will hint Volatility at how to handle this specific build in order to retrieve the information.
Note that this will fetch the correct PDB file from the official Microsoft Internet Symbol Server so this method will not work inside air-gapped environments. See JPCERTCC's repository and blog post for more details on how to retrieve the GUID from your own binaries and use Volatility 3 inside air-gapped environments.
The ISF file must then be placed either in the main symbols directory (located at $INSTALL_PREFIX/lib/volatility3/volatility3/symbols/windows by default) or in the current working directory, under the symbols subdirectory (e.g. ./symbols/windows/ntkrnlmp.pdb/ce7ffb00c20b87500211456b3e905c47-1.json.xz). You can also use the --symbol-dirs option in addition to Docker's --volume option in order to provide the newly-created ISF files to Volatility.
Example #3: Using the Docker images inside air-gapped environments
This section explains how to use the Docker images inside air-gapped (or disconnected) environments. This can turn out to be useful when analyzing volatile memory samples inside air-gapped forensic labs.
💡 This procedure is not specific to the Docker images hosted in this repository and can be used for any Docker image.
First, fetch the image locally—here using the sk4la/volatility3 image as an example:
docker image pull sk4la/volatility3Then, export it to disk as a compressed tar archive:
docker image save sk4la/volatility3 | gzip --best --stdout > sk4la-volatility3-latest.tar.gzCompression (here using GNU
gzip) is not necessary but is usually recommended for heavier images, since it usually allows to save up a lot of space—although at the expense of speed.
The resulting archive should be present in the current directory as sk4la-volatility3-latest.tar.gz.
This compressed image can then be shipped to the air-gapped workstation (using a USB flash drive for example) and then loaded as follows:
gzip --decompress --stdout sk4la-volatility3-latest.tar.gz | docker image loadThe image should then be ready for use. It is possible to check the presence of the image on the system by running the command:
docker image listExample #4: Overloading the Docker images to fit your needs
If you feel that the original image lacks useful stuff, you can either suggest it by submitting a ticket or you can overload the base image yourself in order to adapt it to your needs.
In order to do this, simply create a new Dockerfile based off one of the images from this repository—for example sk4la/volatility3:
FROM sk4la/volatility3
USER root
RUN apk add $STUFF
USER unprivileged
By default, all of the images provided in this repository do not run as
root—they run as theunprivilegeduser. For actions necessitating super-user privileges, it is necessary to switch user temporarily, as shown in the example.
Then, build the image by executing the docker image build --tag volatility3-overloaded . command. The newly-created Docker image should then appear in the local repository.
Please have a look at the original
Dockerfileif you need a hint on how everything is setup.
In case you encounter a problem or want to suggest a new feature relative to these Docker images, please submit a ticket. Pull requests are also greatly appreciated.
This piece of software is licensed under the Volatility Software License.