From 8c855b645d9e71269f5b666272c17e5569dae43f Mon Sep 17 00:00:00 2001 From: febrezo Date: Tue, 20 Jul 2021 12:10:37 +0200 Subject: [PATCH 1/5] Add Dockerfile with Android dependencies solved --- Dockerfile | 29 +++++++++++++++++++++++++++++ README.md | 42 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 Dockerfile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..9547810 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,29 @@ +FROM ubuntu:20.04 + +# Fixing major OS dependencies +# ---------------------------- +RUN apt update \ + && apt install -y python3 python3-pip libusb-1.0-0 \ + && apt install -y wget \ + && apt install -y adb \ + && DEBIAN_FRONTEND=noninteractive apt-get -y install default-jre-headless \ + && apt-get clean \ + && rm -rf /var/lib/apt/lists/* + +# Installing MVT +# -------------- +RUN pip3 install mvt + +# Installing ABE +# -------------- +RUN mkdir /opt/abe +RUN wget https://github.com/nelenkov/android-backup-extractor/releases/download/20210709062403-4c55371/abe.jar -O /opt/abe/abe.jar +# Create shortcut for abe +RUN echo "java -jar /opt/abe/abe.jar" > /usr/local/bin/abe && chmod +x /usr/local/bin/abe + +# Setup investigations environment +# -------------------------------- +RUN mkdir /home/cases +WORKDIR /home/cases + +CMD /bin/bash diff --git a/README.md b/README.md index a9eb292..71754ae 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,46 @@ Mobile Verification Toolkit (MVT) is a collection of utilities to simplify and a [Please check out the documentation](https://mvt-docs.readthedocs.io/en/latest/).. -## Installation +### 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. + +Afterwards, you can build the Docker image once inside: + +``` +bash +git clone https://github.com/mvt-project/mvt.git +cd mvt +docker build -t mvt . +``` + +Once the image is built, can now be tested using, what will prompt a bash terminal: + +```bash +docker run -it mvt +``` + +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 `--pivileged` 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`. @@ -35,6 +74,7 @@ MVT provides two commands `mvt-ios` and `mvt-android` with the following subcomm Check out [the documentation to see how to use them.](https://mvt-docs.readthedocs.io/en/latest/). + ## License The purpose of MVT is to facilitate the ***consensual forensic analysis*** of devices of those who might be targets of sophisticated mobile spyware attacks, especially members of civil society and marginalized communities. We do not want MVT to enable privacy violations of non-consenting individuals. Therefore, the goal of this license is to prohibit the use of MVT (and any other software licensed the same) for the purpose of *adversarial forensics*. From f3afc871cd203d3efea0cf2f9274f176b7213290 Mon Sep 17 00:00:00 2001 From: febrezo Date: Tue, 20 Jul 2021 13:45:55 +0200 Subject: [PATCH 2/5] Create alias for abe instead of custom command --- Dockerfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 9547810..60805e6 100644 --- a/Dockerfile +++ b/Dockerfile @@ -18,8 +18,8 @@ RUN pip3 install mvt # -------------- RUN mkdir /opt/abe RUN wget https://github.com/nelenkov/android-backup-extractor/releases/download/20210709062403-4c55371/abe.jar -O /opt/abe/abe.jar -# Create shortcut for abe -RUN echo "java -jar /opt/abe/abe.jar" > /usr/local/bin/abe && chmod +x /usr/local/bin/abe +# Create alias for abe +RUN echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc # Setup investigations environment # -------------------------------- From 1adf3f430bfe3ad3f191a4bff48c618a864fa02c Mon Sep 17 00:00:00 2001 From: febrezo Date: Tue, 20 Jul 2021 14:02:29 +0200 Subject: [PATCH 3/5] Add welcome message when the terminal is launched --- Dockerfile | 2 ++ README.md | 3 +-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 60805e6..b49239f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -25,5 +25,7 @@ RUN echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc # -------------------------------- RUN mkdir /home/cases WORKDIR /home/cases +RUN echo 'echo "Mobile Verification Toolkit @ Docker\n------------------------------------\n\nYou can find information about how to use this image for Android (https://github.com/mvt-project/mvt/tree/master/docs/android) and iOS (https://github.com/mvt-project/mvt/tree/master/docs/ios) in the official docs of the project.\n"' >> ~/.bashrc +RUN echo 'echo "Note that to perform the debug via USB you might need to give the Docker image access to the USB using \"docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb mvt\" or, preferably, the \"--device=\" parameter.\n"' >> ~/.bashrc CMD /bin/bash diff --git a/README.md b/README.md index 71754ae..cf3145a 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,7 @@ Install Docker using the [official instructions](https://docs.docker.com/get-doc Afterwards, you can build the Docker image once inside: -``` -bash +```bash git clone https://github.com/mvt-project/mvt.git cd mvt docker build -t mvt . From 684aed8d1177d449af12aed7131dd9eb424c5385 Mon Sep 17 00:00:00 2001 From: febrezo Date: Thu, 22 Jul 2021 17:43:32 +0200 Subject: [PATCH 4/5] Add compilation of libimobiledevice for iOS compatibility Added considering the feedback reported in the #16 discussion. --- Dockerfile | 42 ++++++++++++++++++++++++++++++++++++++---- README.md | 2 +- 2 files changed, 39 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index b49239f..d7278a6 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,15 +1,49 @@ FROM ubuntu:20.04 +# Ref. https://github.com/mvt-project/mvt + # Fixing major OS dependencies # ---------------------------- -RUN apt update \ - && apt install -y python3 python3-pip libusb-1.0-0 \ +RUN apt update \ + && apt install -y python3 python3-pip libusb-1.0-0-dev \ && apt install -y wget \ && apt install -y adb \ - && DEBIAN_FRONTEND=noninteractive apt-get -y install default-jre-headless \ - && apt-get clean \ + && DEBIAN_FRONTEND=noninteractive apt-get -y install default-jre-headless + +# Install build tools for libimobiledevice +# ---------------------------------------- +RUN apt install -y build-essential \ + checkinstall \ + git \ + autoconf \ + automake \ + libtool-bin \ + libplist-dev \ + libusbmuxd-dev \ + libssl-dev \ + pkg-config + +# Clean up +# -------- +RUN apt-get clean \ && rm -rf /var/lib/apt/lists/* + +# Build libimobiledevice +# ---------------------- +RUN git clone https://github.com/libimobiledevice/libplist +RUN git clone https://github.com/libimobiledevice/libusbmuxd +RUN git clone https://github.com/libimobiledevice/libimobiledevice +RUN git clone https://github.com/libimobiledevice/usbmuxd + +RUN cd libplist && ./autogen.sh && make && make install && ldconfig + +RUN cd libusbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh && make && make install && ldconfig + +RUN cd libimobiledevice && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --enable-debug && make && make install && ldconfig + +RUN cd usbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --runstatedir=/run && make && make install + # Installing MVT # -------------- RUN pip3 install mvt diff --git a/README.md b/README.md index cf3145a..a93aa0f 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ This can be done using the `--privileged` parameter when launching Docker as fol docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb mvt ``` -Note that using the `--pivileged` 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. +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: From d6f49e76d6f6c25ca0fee68df107d64bdb57dc07 Mon Sep 17 00:00:00 2001 From: Nex Date: Sat, 24 Jul 2021 13:23:45 +0200 Subject: [PATCH 5/5] 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"