From d6f49e76d6f6c25ca0fee68df107d64bdb57dc07 Mon Sep 17 00:00:00 2001 From: Nex Date: Sat, 24 Jul 2021 13:23:45 +0200 Subject: [PATCH] Included Docker details in the documentation --- README.md | 47 +++++------------------------------------------ docs/docker.md | 35 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 41 insertions(+), 42 deletions(-) create mode 100644 docs/docker.md diff --git a/README.md b/README.md index 1b556bc..d96cc3d 100644 --- a/README.md +++ b/README.md @@ -14,54 +14,17 @@ It has been developed and released by the [Amnesty International Security Lab](h [Please check out the documentation.](https://mvt.readthedocs.io/en/latest/) -### Installation using the Docker image -Using Docker is the easiest way of having all the dependencies fixed with a couple of commands. -Install Docker using the [official instructions](https://docs.docker.com/get-docker/) provided in the Website page. +## Installation -Afterwards, you can build the Docker image once inside: +MVT can be installed from sources or conveniently using: -```bash -git clone https://github.com/mvt-project/mvt.git -cd mvt -docker build -t mvt . -``` +`pip3 install mvt`. -Once the image is built, can now be tested using, what will prompt a bash terminal: +You will need some dependencies, so please check the [documentation](https://mvt.readthedocs.io/en/latest/install.html). -```bash -docker run -it mvt -``` +Alternatively, you can decide to run MVT and all relevant tools through a [Docker container](https://mvt.readthedocs.io/en/latest/docker.html) -If this is correct, close the container (`exit`) and it is time to connect the Android device to analyse to the USB port using the development mode as explained in the official docs [here](https://developer.android.com/studio/debug/dev-options). -To have visibility of the USB, the container WILL need to have access to the USB which is not activated in Docker by default. -This can be done using the `--privileged` parameter when launching Docker as follows and mounting the USB as a volume. - -```bash -docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb mvt -``` - -Note that using the `--privileged` parameter is insecure for a number of reasons explained in detail [here](https://blog.trailofbits.com/2019/07/19/understanding-docker-container-escapes/) as it gives access to the whole system. -As a brief explanation, the `-v :` syntax maps the host path to the dockerized path to allow the connection. -Modern versions of Docker have a `--device` option where you can specify the exact USB to mount without the `--privileged` option: - -```bash -docker run -it --device=/dev/ mvt -``` - -The Docker image contains the dependencies fixed to perform a forensic analysis on an Android device using MVT, including ADB (reachable using `adb` as expected) and ABE (installed under `/opt/abe` and reachable using `abe` from the command line) which is ready to be launched using the installed version of Java. -Thus, the forensic analyst can proceed as expected to grab the evidences needed and performs the required tests. - -## Manual Installation - -First you need to install dependencies, on Linux `sudo apt install python3 python3-pip libusb-1.0-0` or on MacOS `brew install python3 libusb`. - -Then you can install mvt from pypi with `pip3 install mvt`, or directly from sources: -```bash -git clone https://github.com/mvt-project/mvt.git -cd mvt -pip3 install . -``` ## Usage diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 0000000..2596fa1 --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,35 @@ +## Using Docker + +Using Docker simplifies having all the required dependencies and tools (including most recent versions of [libimobiledevice](https://libimobiledevice.org)) readily installed. + +Install Docker following the [official documentation](https://docs.docker.com/get-docker/). + +Once installed, you can clone MVT's repository and build its Docker image: + +```bash +git clone https://github.com/mvt-project/mvt.git +cd mvt +docker build -t mvt . +``` + +Test if the image was created successfully: + +```bash +docker run -it mvt +``` + +If a prompt is spawned successfully, you can close it with `exit`. + +If you wish to use MVT to test an Android device you will need to enable the container's access to the host's USB devices. You can do so by enabling the `--privileged` flag and mounting the USB bus device as a volume: + +```bash +docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb mvt +``` + +**Please note:** the `--privileged` parameter is generally regarded as a security risk. If you want to learn more about this check out [this explainer on container escapes](https://blog.trailofbits.com/2019/07/19/understanding-docker-container-escapes/) as it gives access to the whole system. + +Recent versions of Docker provide a `--device` parameter allowing to specify a precise USB device without enabling `--privileged`: + +```bash +docker run -it --device=/dev/ mvt +``` diff --git a/mkdocs.yml b/mkdocs.yml index 448b1f6..1837158 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,7 @@ nav: - Welcome: "index.md" - Introduction: "introduction.md" - Installation: "install.md" + - Using Docker: "docker.md" - MVT for iOS: - iOS Forensic Methodology: "ios/methodology.md" - Install libimobiledevice: "ios/install.md"