Skip to content

Latest commit

 

History

History
256 lines (153 loc) · 15.7 KB

README.md

File metadata and controls

256 lines (153 loc) · 15.7 KB
Raw

Volatility, on Docker 🐳

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:

sk4la/volatility3 sk4la/volatility sk4la/dwarf2json

By the way, why are these images not (yet) official?

What's in the box?

The latest and stable tags, as well as the literal version number (e.g 2.7.0) all point to the latest official release. In order to follow the development cycle of Volatility 3, an edge tag has been added, which points to the current state of the master branch—which could be unstable. Power-users should feel free to use this one at their own expense. The sk4la/volatility3 and sk4la/volatility3:edge images are built every week in order to include the newest symbols.

Please let me know if there is anything missing or if you would like to see something else added to the mix.

Getting started

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.

Building the images

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 the sk4la/volatility3 image, which brings the size up for quite a bit. See my pull request on the official repository for more details on this.

Basic usage

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/volatility3

Or a more complete example:

docker run -v $PWD:/workspace sk4la/volatility3 -f /workspace/volatile.mem windows.pslist

In order to use the Volatility shell (a.k.a. the volshell) or other entrypoints, use the --entrypoint option when instantiating the container:

docker run -it -v $PWD:/workspace --entrypoint volshell sk4la/volatility3 -f /workspace/volatile.mem

The --interactive and --tty options (or their short versions, respectively -i and -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 --interactive flag) is preferred, although retrieving the configuration file using a volume is also possible. See the examples for practical use cases.

Examples

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)

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/volatility3

Then, 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 --save-config volatile.mem.json windows.info

The configuration file volatile.mem.json 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 volatile.mem.json --file volatile.mem --log volatile.mem.log --renderer pretty windows.pslist

For post-processing, it is usually easier to dump the results in CSV or JSON format:

mkdir volatile.mem.results

volatility3 --config volatile.mem.json --file volatile.mem --log volatile.mem.log --quiet --renderer csv windows.pslist | tee -a volatile.mem.results/pslist.csv

The 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 volatile.mem.json --file volatile.mem --log volatile.mem.log --output-dir volatile.mem.dat --renderer pretty windows.pslist --dump --pid 2700

The 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 -vvv for 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

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.pdb

This 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

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 isolated 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/volatility3

Then, export it to disk as a compressed tar archive:

docker image save sk4la/volatility3 | gzip --best --stdout > sk4la-volatility3-latest.tar.gz

Compression (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 load

The 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 list
Example #4: Overloading the Docker images to fit your needs

Example #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 the unprivileged user. For actions necessitating superuser 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 Dockerfile if you need a hint on how everything is setup.

Example #5: Using community plugins with Volatility 2

Example #5: Using community plugins with Volatility 2

The sk4la/volatility image includes all community plugins from the official volatilityfoundation/community repository. By default, those are stored in /usr/local/share/volatility/plugins/community.

You can list all included plugins using the --help or --info flags (e.g. podman run sk4la/volatility:edge --plugins=/usr/local/share/volatility/plugins --info). The loading order is non-deterministic and some plugins fail to load because of missing dependencies (some are just not on PyPI anymore) or because their design is not quite suitable for distribution, so you may need to run it multiple times for it to load the plugin you are looking for. I advise instead using each plugin individually in order to avoid loading dysfunctional plugins.

To load a specific community plugin (example with JPCERT's APT17 plugin):

docker container run sk4la/volatility:edge --plugins /usr/local/share/volatility/plugins/community/JPCERT apt17scan --help

Please note that many plugins made for Volatility 2 have not been maintained for years and might be dysfunctional.

Example #6: Using community plugins with Volatility 3

Example #6: Using community plugins with Volatility 3

The sk4la/volatility3 and sk4la/volatility3:edge images include all community plugins from the official volatilityfoundation/community3 repository. By default, those are stored in /usr/local/share/volatility3/plugins/community3.

You can list all included plugins using the --help flag (e.g. podman run sk4la/volatility3:edge --plugin-dirs=/usr/local/share/volatility3/plugins --help). Please note that many of these plugins have not been maintained a while and might be dysfunctional. I advise instead using each plugin individually in order to avoid loading dysfunctional plugins.

To load a specific community plugin (example with the Multi YARA plugin):

docker container run sk4la/volatility3:edge --plugin-dirs /usr/local/share/volatility3/plugins/community3/Silva_Multi_Yara/ multiyara --help

Support

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.

License

This piece of software is licensed under the Volatility Software License.