From e52cb3f82c91fea927cbc5d08eca3dc414f26342 Mon Sep 17 00:00:00 2001 From: Ilya Chukhman Date: Tue, 11 Feb 2020 17:36:54 -0500 Subject: [PATCH] docker container support Dockerfile and makefile rules to build several volatility docker images. The images share a common builder image. A generic volatility image is used for staging. The 3 docker images that are produced have the same layers and only differ in entrypoint definition. The images are: * vol -- used to run plugins with vol.py * volshell -- used to enter a volshell * pdbconv -- used to convert pdb files to json files The symbols used for analysis need to be provided via a defined /symbols volume. The image used for analysis also needs to be provided via a user-defined volume. --- docker/Dockerfile | 142 ++++++++++++++++++++++++++++++++++++++++++++++ docker/Makefile | 33 +++++++++++ docker/README.md | 50 ++++++++++++++++ 3 files changed, 225 insertions(+) create mode 100644 docker/Dockerfile create mode 100644 docker/Makefile create mode 100644 docker/README.md diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 000000000..34e07db76 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,142 @@ +# Docker image based on Alpine Linux embedding the Volatility 3 framework (https://github.com/volatilityfoundation/volatility3). +# +# To build: +# $ make +# +# Additionaly, one can set the following build arguments (using the Makefile variable) to customize the build: +# - ALPINE_VERSION [3.11] +# - USERNAME [root] +# + +ARG ALPINE_VERSION=3.11 + +# +# Volatility builder image +# + +FROM alpine:${ALPINE_VERSION} AS builder + +ARG USERNAME=root + +USER ${USERNAME} + +WORKDIR /tmp/build/ + +# Install system dependencies +RUN apk add --no-cache --virtual .build \ + curl \ + gcc \ + git \ + musl-dev \ + python3-dev \ + unzip + +# Build the Python bindings for YARA +RUN git clone --recursive https://github.com/VirusTotal/yara-python && \ + cd yara-python && \ + python3 setup.py install --root /tmp/root && \ + # build and install volatility + git clone https://github.com/volatilityfoundation/volatility3.git && \ + cd volatility3 && \ + python3 setup.py install --root /tmp/root && \ + # build and install pdbparse + python3 -m pip install --root /tmp/root pdbparse && \ + apk --purge del .build + +# +# Volatility generic image +# + +FROM alpine:${ALPINE_VERSION} as volbase + +ARG USERNAME=root + +USER ${USERNAME} + +WORKDIR /usr/lib + +# Install system dependencies +RUN apk add --no-cache \ + python3 capstone && \ + python3 -m pip install --no-cache \ + pefile capstone + +# Copy built yara and volatility files +COPY --from=builder /tmp/root / + +# Create links and mount for symbols +RUN mkdir -p /symbols && \ + mkdir /symbols/mac && \ + mkdir /symbols/linux && \ + mkdir /symbols/windows && \ + ln -sf /symbols/mac \ + /usr/lib/python3.8/site-packages/volatility/symbols && \ + ln -sf /symbols/linux \ + /usr/lib/python3.8/site-packages/volatility/symbols && \ + ln -sf /symbols/windows \ + /usr/lib/python3.8/site-packages/volatility/symbols + +VOLUME [ "/symbols" ] + +WORKDIR / + +# +# Vol image +# +# To run as a standalone container: +# $ docker run -v /dir/to/symbols:/symbols -v /dir/to/image:/case:ro --rm --cap-drop ALL volatility/vol -f /case/data.lime windows.info +# +# One can also remove the ":ro" suffix (in the -v option) to allow writing to disk. +# +# See https://github.com/volatilityfoundation/volatility3 for details. +FROM volbase as vol + +LABEL name="vol" \ + version="0.1" \ + uri="https://github.com/volatilityfoundation/volatility3" \ + maintainer="Volatility Foundation "\ + status="beta" + +ENTRYPOINT [ "/usr/bin/env", "vol" ] + +CMD [ "--help" ] + +# +# Volshell image +# +# To run as a standalone container: +# $ docker run -v /dir/to/symbols:/symbols -v /dir/to/image:/case:ro --rm --cap-drop ALL volatility/volshell -f /case/data.lime -w +# +# One can also remove the ":ro" suffix (in the -v option) to allow writing to disk. +# +# See https://github.com/volatilityfoundation/volatility3 for details. + +FROM volbase as volshell + +LABEL name="volshell" \ + version="0.1" \ + uri="https://github.com/volatilityfoundation/volatility3" \ + maintainer="Volatility Foundation "\ + status="beta" + +ENTRYPOINT [ "/usr/bin/env", "volshell" ] + +CMD [ "--help" ] + +# +# Pdbconf image +# +# To run as a standalone container: +# $ docker run -v /dir/to/symbols:/symbols --rm --cap-drop ALL volatility/pdbconv -f /symbols/ntkrnlmp.pdb -o /symbols/ntkrnlmp.json +# +# See https://github.com/volatilityfoundation/volatility3 for details +FROM volbase as pdbconv +LABEL name="pdbconv" \ + version="0.1" \ + uri="https://github.com/volatilityfoundation/volatility3" \ + maintainer="Volatility Foundation "\ + status="beta" + +ENTRYPOINT [ "/usr/bin/env", "python3", "/usr/lib/python3.8/site-packages/volatility/framework/symbols/windows/pdbconv.py"] + +CMD [ "--help" ] \ No newline at end of file diff --git a/docker/Makefile b/docker/Makefile new file mode 100644 index 000000000..6a983a0cb --- /dev/null +++ b/docker/Makefile @@ -0,0 +1,33 @@ +DOCKER_BIN=docker +DOCKER_FLAGS+= +DOCKER_REPOSITORY?=volatility3 +DOCKER_TAG?=latest + +USERNAME ?= root +ALPINE_VERSION ?= 3.11 + +.PHONY: all pdbconv volshell vol + +all: volshell vol pdbconv + +pdbconv: + @$(DOCKER_BIN) build \ + $(DOCKER_FLAGS) \ + --rm \ + --tag $(DOCKER_REPOSITORY)/$@:$(DOCKER_TAG) \ + $@ + +volshell vol pdbconv: + @$(DOCKER_BIN) build \ + $(DOCKER_FLAGS) \ + --rm \ + --build-arg USERNAME=$(USERNAME) \ + --build-arg ALPINE_VERSION=$(ALPINE_VERSION) \ + --tag $(DOCKER_REPOSITORY)/$@:$(DOCKER_TAG) \ + --target $@ \ + . + +.PHONY: clean +clean: + docker rmi $(DOCKER_REPOSITORY)/pdbconv $(DOCKER_REPOSITORY)/volshell $(DOCKER_REPOSITORY)/vol + docker system prune \ No newline at end of file diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 000000000..e3c549be4 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,50 @@ +Dockerfile and makefile can be used to build several volatility docker images. +The images share a common builder image. A generic volatility image is +used for staging. The 3 docker images that are produced have the same +layers and only differ in `entrypoint` definition. The images are: + +* `volatility3/vol:latest` -- can be used to run plugins with vol.py +* `volatility3/volshell:latest` -- can be used to enter a volshell +* `volatility3/pdbconv:latest` -- can be used to convert pdb files to json files + +The symbols used for analysis need to be provided via a defined `/symbols` +volume. The image used for analysis also needs to be provided via a +user-defined volume. + +## volatility3/vol:latest + +To run as a standalone container and print a process list: + +``` +$ docker run -v /dir/to/symbols:/symbols -v /dir/to/image:/case:ro --rm --cap-drop ALL volatility/vol -f /case/data.lime windows.pslist.PsList +``` + +The first volume definition (with `-v`) provides a symbols location. The second volume definition is used to supply a memory sample for analysis. + +One can also remove the `":ro"` suffix (in the -v option) to allow writing to disk. + +## volatility3/volshell:latest + +To run as a standalone container and enter volshell for windows: + +``` +$ docker run -v /dir/to/symbols:/symbols -v /dir/to/image:/case:ro --rm --cap-drop ALL volatility/volshell -f /case/data.lime -w +``` + +The first volume definition (with `-v`) provides a symbols location. The second volume definition is used to supply a memory sample for analysis. + +One can also remove the `":ro"` suffix (in the -v option) to allow writing to disk. + +## volatility3/pdbconv:latest + +To run as a standalone container and convert a pdb file to json: + +``` +$ docker run -v /dir/to/symbols:/symbols --rm --cap-drop ALL volatility/pdbconv -f /symbols/ntkrnlmp.pdb -o /symbols/ntkrnlmp.json +``` + +The volume definition (with `-v`) provides a symbols location. + +## Acknowledgement + +Initial docker prototype was created by `sk4la `. \ No newline at end of file