Bump version to v1.3.2

Fix ConfigurationProfiles

AUTHORS

@@ -0,0 +1,7 @@
+MVT was originally authored by Claudio Guarnieri <nex@nex.sx>.
+
+For an up-to-date list of all contributors visit:
+    https://github.com/mvt-project/mvt/graphs/contributors
+
+Or run:
+    git shortlog -s -n

Dockerfile

@@ -2,48 +2,59 @@ FROM ubuntu:20.04
 
 # Ref. https://github.com/mvt-project/mvt
 
+LABEL url="https://mvt.re"
+LABEL vcs-url="https://github.com/mvt-project/mvt"
+LABEL description="MVT is a forensic tool to look for signs of infection in smartphone devices."
+
+ENV PIP_NO_CACHE_DIR=1
+
 # Fixing major OS dependencies
 # ----------------------------
 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 install -y wget unzip\ 
+  && 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 \
-	sqlite3 \
-    pkg-config
+  build-essential \
+  checkinstall \
+  git \
+  autoconf \
+  automake \
+  libtool-bin \
+  libplist-dev \
+  libusbmuxd-dev \
+  libssl-dev \
+  sqlite3 \
+  pkg-config \
 
 # Clean up
 # --------
-RUN apt-get clean \
-  && rm -rf /var/lib/apt/lists/*
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/* /var/cache/apt
 
 
 # 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 git clone https://github.com/libimobiledevice/libplist \
+  && git clone https://github.com/libimobiledevice/libimobiledevice-glue \
+  && git clone https://github.com/libimobiledevice/libusbmuxd \
+  && git clone https://github.com/libimobiledevice/libimobiledevice \
+  && git clone https://github.com/libimobiledevice/usbmuxd \
 
-RUN cd libplist && ./autogen.sh && make && make install && ldconfig
+  && cd libplist && ./autogen.sh && make && make install && ldconfig \
 
-RUN cd libusbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh && make && make install && ldconfig
+  && cd ../libimobiledevice-glue && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --prefix=/usr && make && make install && ldconfig \
 
-RUN cd libimobiledevice && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --enable-debug && make && make install && ldconfig
+  && cd ../libusbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh && 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
+  && cd ../libimobiledevice && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --enable-debug && make && make install && ldconfig \
+
+  && cd ../usbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --runstatedir=/run && make && make install \
+
+  # Clean up.
+  && cd .. && rm -rf libplist libimobiledevice-glue libusbmuxd libimobiledevice usbmuxd
 
 # Installing MVT
 # --------------
@@ -51,16 +62,29 @@ 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
+RUN mkdir /opt/abe \
+  && wget https://github.com/nelenkov/android-backup-extractor/releases/download/20210709062403-4c55371/abe.jar -O /opt/abe/abe.jar \
 # Create alias for abe
-RUN echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc
+  && echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc
+
+# Install Android Platform Tools 
+# ------------------------------ 
+
+RUN mkdir /opt/android \
+  && wget -q https://dl.google.com/android/repository/platform-tools-latest-linux.zip \
+  && unzip platform-tools-latest-linux.zip -d /opt/android \
+# Create alias for adb 
+  && echo 'alias adb="/opt/android/platform-tools/adb"' >> ~/.bashrc 
+
+# Generate adb key folder 
+# ------------------------------ 
+RUN mkdir /root/.android && /opt/android/platform-tools/adb keygen /root/.android/adbkey
 
 # Setup investigations environment
 # --------------------------------
 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
+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 \
+  && 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

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-     <img src="./docs/mvt.png" width="300" />
+     <img src="./docs/mvt.png" width="200" />
 </p>
 
 # Mobile Verification Toolkit
@@ -15,38 +15,20 @@ It has been developed and released by the [Amnesty International Security Lab](h
 
 ## Installation
 
-MVT can be installed from sources or conveniently using:
+MVT can be installed from sources or from [PyPi](https://pypi.org/project/mvt/) (you will need some dependencies, check the [documentation](https://docs.mvt.re/en/latest/install/)):
 
 ```
 pip3 install mvt
 ```
 
-You will need some dependencies, so please check the [documentation](https://docs.mvt.re/en/latest/install.html).
-
-Alternatively, you can decide to run MVT and all relevant tools through a [Docker container](https://docs.mvt.re/en/latest/docker.html).
+Alternatively, you can decide to run MVT and all relevant tools through a [Docker container](https://docs.mvt.re/en/latest/docker/).
 
+**Please note:** MVT is best run on Linux or Mac systems. [It does not currently support running natively on Windows.](https://docs.mvt.re/en/latest/install/#mvt-on-windows)
 
 ## Usage
 
-MVT provides two commands `mvt-ios` and `mvt-android` with the following subcommands available:
-
-* `mvt-ios`:
-    * `check-backup`: Extract artifacts from an iTunes backup
-    * `check-fs`: Extract artifacts from a full filesystem dump
-    * `check-iocs`: Compare stored JSON results to provided indicators
-    * `decrypt-backup`:  Decrypt an encrypted iTunes backup
-    * `extract-key`: Extract decryption key from an iTunes backup
-* `mvt-android`:
-    * `check-backup`: Check an Android Backup
-    * `download-apks`: Download all or non-safelisted installed APKs
-
-Check out [the documentation to see how to use them](https://docs.mvt.re/).
-
+MVT provides two commands `mvt-ios` and `mvt-android`. [Check out the documentation to learn how to use them!](https://docs.mvt.re/)
 
 ## 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*.
-
-In order to achieve this, MVT is released under an adaptation of [Mozilla Public License v2.0](https://www.mozilla.org/MPL). This modified license includes a new clause 3.0, "Consensual Use Restriction" which permits the use of the licensed software (and any *"Larger Work"* derived from it) exclusively with the explicit consent of the person/s whose data is being extracted and/or analysed (*"Data Owner"*).
-
-[Read the LICENSE](https://github.com/mvt-project/mvt/blob/main/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.  In order to achieve this, MVT is released under its own license. [Read more here.](https://docs.mvt.re/en/latest/license/)

dev/mvt-android

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import os
 import sys

dev/mvt-ios

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import os
 import sys

docs/android/adb.md

@@ -0,0 +1,42 @@
+# Check over ADB
+
+In order to check an Android device over the [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb) you will first need to install [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools). If you have installed [Android Studio](https://developer.android.com/studio/) you should already have access to `adb` and other utilities.
+
+While many Linux distributions already package Android Platform Tools (for example `android-platform-tools-base` on Debian), it is preferable to install the most recent version from the official website. Packaged versions might be outdated and incompatible with most recent Android handsets.
+
+Next you will need to enable debugging on the Android device you are testing. [Please follow the official instructions on how to do so.](https://developer.android.com/studio/command-line/adb)
+
+## Connecting over USB
+
+The easiest way to check the device is over a USB transport. You will need to have USB debugging enabled and the device plugged into your computer. If everything is configured appropriately you should see your device when launching the command `adb devices`.
+
+Now you can try launching MVT with:
+
+```bash
+mvt-android check-adb --output /path/to/results
+```
+
+If you have previously started an adb daemon MVT will alert you and require you to kill it with `adb kill-server` and relaunch the command.
+
+!!! warning
+    MVT relies on the Python library [adb-shell](https://pypi.org/project/adb-shell/) to connect to an Android device, which relies on libusb for the USB transport. Because of known driver issues, Windows users [are recommended](https://github.com/JeffLIrion/adb_shell/issues/118) to install appropriate drivers using [Zadig](https://zadig.akeo.ie/). Alternatively, an easier option might be to use the TCP transport and connect over Wi-Fi as describe next.
+
+## Connecting over Wi-FI
+
+When connecting to the device over USB is not possible or not working properly, an alternative option is to connect over the network. In order to do so, first launch an adb daemon at a fixed port number:
+
+```bash
+adb tcpip 5555
+```
+
+Then you can specify the IP address of the phone with the adb port number to MVT like so:
+
+```bash
+mvt-android check-adb --serial 192.168.1.20:5555 --output /path/to/results
+```
+
+Where `192.168.1.20` is the correct IP address of your device.
+
+## MVT modules requiring root privileges
+
+Of the currently available `mvt-android check-adb` modules a handful require root privileges to function correctly. This is because certain files, such as browser history and SMS messages databases are not accessible with user privileges through adb. These modules are to be considered OPTIONALLY available in case the device was already jailbroken. **Do NOT jailbreak your own device unless you are sure of what you are doing!** Jailbreaking your phone exposes it to considerable security risks!

docs/android/backup.md

@@ -1,38 +1,49 @@
-# Checking SMSs from Android backup
+# Check an Android Backup (SMS messages)
 
-Some attacks against Android phones are done by sending malicious links by SMS. The Android backup feature does not allow to gather much information that can be interesting for a forensic analysis, but it can be used to extract SMSs and check them with MVT.
+Android supports generating a backup archive of all the installed applications which supports it. However, over the years this functionality has been increasingly abandoned in favor of enabling users to remotely backup their personal data over the cloud. App developers can therefore decide to opt out from allowing the apps' data from being exported locally.
 
-To do so, you need to connect your Android device to your computer. You will then need to [enable USB debugging](https://developer.android.com/studio/debug/dev-options#enable>) on the Android device.
+At the time of writing, the Android Debug Bridge (adb) command to generate backups is still available but marked as deprecated.
 
-If this is the first time you connect to this device, you will need to approve the authentication keys through a prompt that will appear on your Android device.
+That said, most versions of Android should still allow to locally backup SMS messages, and since messages are still a prime vehicle for phishing and malware attacks, you might still want to take advantage of this functionality while it is supported.
 
-Then you can use adb to extract the backup for SMS only with the following command:
+## Generate a backup
+
+Because `mvt-android check-backup` currently only supports checking SMS messages, you can indicate to backup only those:
 
 ```bash
 adb backup com.android.providers.telephony
 ```
 
-You will need to approve the backup on the phone and potentially enter a password to encrypt the backup. The backup will then be stored in a file named `backup.ab`.
+In case you nonetheless wish to take a full backup, you can do so with
 
-You will need to use [Android Backup Extractor](https://github.com/nelenkov/android-backup-extractor) to convert it to a readable file format. Make sure that java is installed on your system and use the following command:
 ```bash
-java -jar ~/Download/abe.jar unpack backup.ab backup.tar
+adb backup -all
+```
+
+## Unpack the backup
+
+In order to unpack the backup, use [Android Backup Extractor (ABE)](https://github.com/nelenkov/android-backup-extractor) to convert it to a readable file format. Make sure that java is installed on your system and use the following command:
+
+```bash
+java -jar ~/path/to/abe.jar unpack backup.ab backup.tar
 tar xvf backup.tar
 ```
 
-(If the backup is encrypted, the password will be asked by Android Backup Extractor).
+If the backup is encrypted, ABE will prompt you to enter the password.
+
+Alternatively, [ab-decrypt](https://github.com/joernheissler/ab-decrypt) can be used for that purpose.
+
+## Check the backup
 
 You can then extract SMSs containing links with MVT:
 
 ```bash
-$ mvt-android check-backup --output . .
+$ mvt-android check-backup --output /path/to/results/ /path/to/backup/
 16:18:38 INFO     [mvt.android.cli] Checking ADB backup located at: .
          INFO     [mvt.android.modules.backup.sms] Running module SMS...
-         INFO     [mvt.android.modules.backup.sms] Processing SMS backup
-                  file at ./apps/com.android.providers.telephony/d_f/000
-                  000_sms_backup
+         INFO     [mvt.android.modules.backup.sms] Processing SMS backup file at /path/to/backup/apps/com.android.providers.telephony/d_f/000000_sms_backup
 16:18:39 INFO     [mvt.android.modules.backup.sms] Extracted a total of
                   64 SMS messages containing links
 ```
 
-Through the `--iocs` argument you can specify a [STIX2](https://oasis-open.github.io/cti-documentation/stix/intro) file defining a list of malicious indicators to check against the records extracted from the backup by mvt. Any matches will be highlighted in the terminal output.
+Through the `--iocs` argument you can specify a [STIX2](https://oasis-open.github.io/cti-documentation/stix/intro) file defining a list of malicious indicators to check against the records extracted from the backup by MVT. Any matches will be highlighted in the terminal output.

docs/android/download_apks.md

@@ -1,15 +1,18 @@
 # Downloading APKs from an Android phone
 
-In order to use `mvt-android` you need to connect your Android device to your computer. You will then need to [enable USB debugging](https://developer.android.com/studio/debug/dev-options#enable>) on the Android device.
+MVT allows to attempt to download all available installed packages (APKs) in order to further inspect them and potentially identify any which might be malicious in nature.
 
-If this is the first time you connect to this device, you will need to approve the authentication keys through a prompt that will appear on your Android device.
-
-Now you can launch `mvt-android` and specify the `download-apks` command and the path to the folder where you want to store the extracted data:
+You can do so by launching the following command:
 
 ```bash
 mvt-android download-apks --output /path/to/folder
 ```
 
+It might take several minutes to complete.
+
+!!! info
+    MVT will likely warn you it was unable to download certain installed packages. There is no reason to be alarmed: this is typically expected behavior when MVT attempts to download a system package it has no privileges to access.
+
 Optionally, you can decide to enable lookups of the SHA256 hash of all the extracted APKs on [VirusTotal](https://www.virustotal.com) and/or [Koodous](https://koodous.com). While these lookups do not provide any conclusive assessment on all of the extracted APKs, they might highlight any known malicious ones:
 
 ```bash
@@ -17,8 +20,15 @@ mvt-android download-apks --output /path/to/folder --virustotal
 mvt-android download-apks --output /path/to/folder --koodous
 ```
 
-Or, to launch all available lookups::
+Or, to launch all available lookups:
 
 ```bash
 mvt-android download-apks --output /path/to/folder --all-checks
 ```
+
+In case you have a previous extraction of APKs you want to later check against VirusTotal and Koodous, you can do so with the following arguments:
+
+```bash
+mvt-android download-apks --from-file /path/to/folder/apks.json --all-checks
+```
+

docs/android/methodology.md

@@ -1,8 +1,21 @@
 # Methodology for Android forensic
 
-For different technical reasons, it is more complex to do a forensic analysis of an Android phone.
+Unfortunately Android devices provide much less observability than their iOS cousins. Android stores very little diagnostic information useful to triage potential compromises, and because of this `mvt-android` capabilities are limited as well.
 
-Currently MVT allows to perform two different checks on an Android phone:
+However, not all is lost.
 
-* Download APKs installed in order to analyze them
-* Extract Android backup in order to look for suspicious SMS
+## Check installed Apps
+
+Because malware attacks over Android typically take the form of malicious or backdoored apps, the very first thing you might want to do is to extract and verify all installed Android packages and triage quickly if there are any which stand out as malicious or which might be atypical.
+
+While it is out of the scope of this documentation to dwell into details on how to analyze Android apps, MVT does allow to easily and automatically extract information about installed apps, download copies of them, and quickly lookup services such as [VirusTotal](https://www.virustotal.com) or [Koodous](https://koodous.com) which might quickly indicate known bad apps.
+
+
+## Check the device over Android Debug Bridge
+
+Some additional diagnostic information can be extracted from the phone using the [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb). `mvt-android` allows to automatically extract information including [dumpsys](https://developer.android.com/studio/command-line/dumpsys) results, details on installed packages (without download), running processes, presence of root binaries and packages, and more.
+
+
+## Check an Android Backup (SMS messages)
+
+Although Android backups are becoming deprecated, it is still possible to generate one. Unfortunately, because apps these days typically favor backup over the cloud, the amount of data available is limited. Currently, `mvt-android check-backup` only supports checking SMS messages containing links.

docs/index.md

@@ -10,4 +10,4 @@ In this documentation you will find instructions on how to install and run the `
 
 ## Resources
 
-[:fontawesome-brands-python: Python Package](https://pypi.org/project/mvt){: .md-button .md-button--primary } [:fontawesome-brands-github: GitHub](https://github.com/mvt-project/mvt){: .md-button }
+[:fontawesome-brands-github: GitHub](https://github.com/mvt-project/mvt){: .md-button .md-button--primary } [:fontawesome-brands-python: Python Package](https://pypi.org/project/mvt){: .md-button }

docs/install.md

@@ -1,6 +1,6 @@
 # Installation
 
-Before proceeding, please note that mvt requires Python 3.6+ to run. While it should be available on most operating systems, please make sure of that before proceeding.
+Before proceeding, please note that MVT requires Python 3.6+ to run. While it should be available on most operating systems, please make sure of that before proceeding.
 
 ## Dependencies on Linux
 
@@ -12,9 +12,11 @@ sudo apt install python3 python3-pip libusb-1.0-0 sqlite3
 
 *libusb-1.0-0* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
 
-## Dependencies on Mac
+When working with Android devices you should additionally install [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools). If you prefer to install a package made available by your distribution of choice, please make sure the version is recent to ensure compatibility with modern Android devices.
 
-Running MVT on Mac requires Xcode and [homebrew](https://brew.sh) to be installed.
+## Dependencies on macOS
+
+Running MVT on macOS requires Xcode and [homebrew](https://brew.sh) to be installed.
 
 In order to install dependencies use:
 
@@ -24,6 +26,20 @@ brew install python3 libusb sqlite3
 
 *libusb* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
 
+When working with Android devices you should additionally install [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools):
+
+```bash
+brew install --cask android-platform-tools
+```
+
+Or by downloading the [official binary releases](https://developer.android.com/studio/releases/platform-tools).
+
+## MVT on Windows
+
+MVT does not currently officially support running natively on Windows. While most functionality should work out of the box, there are known issues especially with `mvt-android`.
+
+It is recommended to try installing and running MVT from [Windows Subsystem Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about) and follow Linux installation instructions for your distribution of choice.
+
 ## Installing MVT
 
 If you haven't done so, you can add this to your `.bashrc` or `.zshrc` file in order to add locally installed Pypi binaries to your `$PATH`:

docs/introduction.md

@@ -10,6 +10,8 @@ Mobile Verification Toolkit (MVT) is a collection of utilities designed to facil
 - Generate JSON logs of extracted records, and separate JSON logs of all detected malicious traces.
 - Generate a unified chronological timeline of extracted records, along with a timeline all detected malicious traces.
 
+MVT is a forensic research tool intended for technologists and investigators. Using it requires understanding the basics of forensic analysis and using command-line tools. MVT is not intended for end-user self-assessment. If you are concerned with the security of your device please seek expert assistance.
+
 ## Consensual Forensics
 
 While MVT is capable of extracting and processing various types of very personal records typically found on a mobile phone (such as calls history, SMS and WhatsApp messages, etc.), this is intended to help identify potential attack vectors such as malicious SMS messages leading to exploitation.

docs/iocs.md

@@ -22,11 +22,23 @@ After extracting forensics data from a device, you are also able to compare it w
 mvt-ios check-iocs --iocs ~/iocs/malware.stix2 /path/to/iphone/output/
 ```
 
-If you're looking for indicators of compromise for a specific piece of malware or adversary, please ask investigators or anti-malware researchers who have the relevant expertise for a STIX file.
+The `--iocs` option can be invoked multiple times to let MVT import multiple STIX2 files at once. For example:
+
+```bash
+mvt-ios check-backup --iocs ~/iocs/malware1.stix --iocs ~/iocs/malware2.stix2 /path/to/backup
+```
+
+It is also possible to load STIX2 files automatically from the environment variable `MVT_STIX2`:
+
+```bash
+export MVT_STIX2="/home/user/IOC1.stix2:/home/user/IOC2.stix2"
+```
 
 ## Known repositories of STIX2 IOCs
 
 - The [Amnesty International investigations repository](https://github.com/AmnestyTech/investigations) contains STIX-formatted IOCs for:
     - [Pegasus](https://en.wikipedia.org/wiki/Pegasus_(spyware)) ([STIX2](https://raw.githubusercontent.com/AmnestyTech/investigations/master/2021-07-18_nso/pegasus.stix2))
+    - [Predator from Cytrox](https://citizenlab.ca/2021/12/pegasus-vs-predator-dissidents-doubly-infected-iphone-reveals-cytrox-mercenary-spyware/) ([STIX2](https://github.com/AmnestyTech/investigations/tree/master/2021-12-16_cytrox/cytrox.stix2))
+- [This repository](https://github.com/Te-k/stalkerware-indicators) contains IOCs for Android stalkerware including [a STIX MVT-compatible file](https://github.com/Te-k/stalkerware-indicators/blob/master/stalkerware.stix2).
 
 Please [open an issue](https://github.com/mvt-project/mvt/issues/) to suggest new sources of STIX-formatted IOCs.

docs/ios/backup/itunes.md

@@ -1,16 +1,16 @@
 # Backup with iTunes app
 
-It is possible to do an iPhone backup by using iTunes on Windows or Mac computers (in most recent versions of Mac OS, this feature is included in Finder).
+It is possible to do an iPhone backup by using iTunes on Windows or macOS computers (in most recent versions of macOS, this feature is included in Finder).
 
 To do that:
 
 * Make sure iTunes is installed.
 * Connect your iPhone to your computer using a Lightning/USB cable.
-* Open the device in iTunes (or Finder on Mac OS).
+* Open the device in iTunes (or Finder on macOS).
 * If you want to have a more accurate detection, ensure that the encrypted backup option is activated and choose a secure password for the backup.
 * Start the backup and wait for it to finish (this may take up to 30 minutes).
 
 ![](../../../img/macos-backup.jpg)
 _Source: [Apple Support](https://support.apple.com/en-us/HT211229)_
 
-* Once the backup is done, find its location and copy it to a place where it can be analyzed by `mvt`. On Windows, the backup can be stored either in `%USERPROFILE%\Apple\MobileSync\` or `%USERPROFILE%\AppData\Roaming\Apple Computer\MobileSync\`. On Mac OS, the backup is stored in `~/Library/Application Support/MobileSync/`.
+* Once the backup is done, find its location and copy it to a place where it can be analyzed by MVT. On Windows, the backup can be stored either in `%USERPROFILE%\Apple\MobileSync\` or `%USERPROFILE%\AppData\Roaming\Apple Computer\MobileSync\`. On macOS, the backup is stored in `~/Library/Application Support/MobileSync/`.

docs/ios/methodology.md

@@ -12,4 +12,4 @@ If you are not expected to return the phone, you might want to consider to attem
 
 #### iTunes Backup
 
-An alternative option is to generate an iTunes backup (in most recent version of mac OS, they are no longer launched from iTunes, but directly from Finder). While backups only provide a subset of the files stored on the device, in many cases it might be sufficient to at least detect some suspicious artifacts. Backups encrypted with a password will have some additional interesting records not available in unencrypted ones, such as Safari history, Safari state, etc.
+An alternative option is to generate an iTunes backup (in most recent version of macOS, they are no longer launched from iTunes, but directly from Finder). While backups only provide a subset of the files stored on the device, in many cases it might be sufficient to at least detect some suspicious artifacts. Backups encrypted with a password will have some additional interesting records not available in unencrypted ones, such as Safari history, Safari state, etc.

docs/requirements.txt

@@ -1,4 +1,4 @@
-mkdocs==1.2.1
+mkdocs==1.2.3
 mkdocs-autorefs
 mkdocs-material
 mkdocs-material-extensions

mkdocs.yml

@@ -42,7 +42,8 @@ nav:
         - Records extracted by mvt-ios: "ios/records.md"
     - MVT for Android:
         - Android Forensic Methodology: "android/methodology.md"
-        - Check APKs: "android/download_apks.md"
-        - Check an Android Backup: "android/backup.md"
+        - Check over ADB: "android/adb.md"
+        - Check an Android Backup (SMS messages): "android/backup.md"
+        - Download APKs: "android/download_apks.md"
     - Indicators of Compromise: "iocs.md"
     - License: "license.md"

mvt/__init__.py

@@ -1,4 +1,4 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/

mvt/android/__init__.py

@@ -1,6 +1,6 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 from .cli import cli

mvt/android/cli.py

@@ -1,17 +1,19 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
-import argparse
 import logging
 import os
-import sys
 
 import click
 from rich.logging import RichHandler
 
-from mvt.common.indicators import Indicators
+from mvt.common.help import HELP_MSG_MODULE, HELP_MSG_IOC
+from mvt.common.help import HELP_MSG_FAST, HELP_MSG_OUTPUT, HELP_MSG_LIST_MODULES
+from mvt.common.help import HELP_MSG_SERIAL
+from mvt.common.indicators import Indicators, IndicatorsFileBadFormat
+from mvt.common.logo import logo
 from mvt.common.module import run_module, save_timeline
 
 from .download_apks import DownloadAPKs
@@ -26,15 +28,20 @@ logging.basicConfig(level="INFO", format=LOG_FORMAT, handlers=[
     RichHandler(show_path=False, log_time_format="%X")])
 log = logging.getLogger(__name__)
 
-# Help messages of repeating options.
-OUTPUT_HELP_MESSAGE = "Specify a path to a folder where you want to store JSON results"
-
 
 #==============================================================================
 # Main
 #==============================================================================
 @click.group(invoke_without_command=False)
 def cli():
+    logo()
+
+
+#==============================================================================
+# Command: version
+#==============================================================================
+@cli.command("version", help="Show the currently installed version of MVT")
+def version():
     return
 
 
@@ -42,8 +49,9 @@ def cli():
 # Download APKs
 #==============================================================================
 @cli.command("download-apks", help="Download all or non-safelisted installed APKs installed on the device")
+@click.option("--serial", "-s", type=str, help=HELP_MSG_SERIAL)
 @click.option("--all-apks", "-a", is_flag=True,
-              help="Extract all packages installed on the phone, even those marked as safe")
+              help="Extract all packages installed on the phone, including system packages")
 @click.option("--virustotal", "-v", is_flag=True, help="Check packages on VirusTotal")
 @click.option("--koodous", "-k", is_flag=True, help="Check packages on Koodous")
 @click.option("--all-checks", "-A", is_flag=True, help="Run all available checks")
@@ -51,19 +59,28 @@ def cli():
               help="Specify a path to a folder where you want to store the APKs")
 @click.option("--from-file", "-f", type=click.Path(exists=True),
               help="Instead of acquiring from phone, load an existing packages.json file for lookups (mainly for debug purposes)")
-def download_apks(all_apks, virustotal, koodous, all_checks, output, from_file):
+@click.pass_context
+def download_apks(ctx, all_apks, virustotal, koodous, all_checks, output, from_file, serial):
     try:
         if from_file:
             download = DownloadAPKs.from_json(from_file)
         else:
-            if output and not os.path.exists(output):
+            # TODO: Do we actually want to be able to run without storing any file?
+            if not output:
+                log.critical("You need to specify an output folder with --output!")
+                ctx.exit(1)
+
+            if not os.path.exists(output):
                 try:
                     os.makedirs(output)
                 except Exception as e:
                     log.critical("Unable to create output folder %s: %s", output, e)
-                    sys.exit(-1)
+                    ctx.exit(1)
 
-            download = DownloadAPKs(output_folder=output, all_apks=all_apks)
+            download = DownloadAPKs(output_folder=output, all_apks=all_apks,
+                                    log=logging.getLogger(DownloadAPKs.__module__))
+            if serial:
+                download.serial = serial
             download.run()
 
         packages = download.packages
@@ -78,19 +95,23 @@ def download_apks(all_apks, virustotal, koodous, all_checks, output, from_file):
             koodous_lookup(packages)
     except KeyboardInterrupt:
         print("")
-        sys.exit(-1)
+        ctx.exit(1)
 
 
 #==============================================================================
 # Checks through ADB
 #==============================================================================
 @cli.command("check-adb", help="Check an Android device over adb")
-@click.option("--iocs", "-i", type=click.Path(exists=True), help="Path to indicators file")
+@click.option("--serial", "-s", type=str, help=HELP_MSG_SERIAL)
+@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
+              default=[], help=HELP_MSG_IOC)
 @click.option("--output", "-o", type=click.Path(exists=False),
-              help="Specify a path to a folder where you want to store JSON results")
-@click.option("--list-modules", "-l", is_flag=True, help="Print list of available modules and exit")
-@click.option("--module", "-m", help="Name of a single module you would like to run instead of all")
-def check_adb(iocs, output, list_modules, module):
+              help=HELP_MSG_OUTPUT)
+@click.option("--fast", "-f", is_flag=True, help=HELP_MSG_FAST)
+@click.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
+@click.option("--module", "-m", help=HELP_MSG_MODULE)
+@click.pass_context
+def check_adb(ctx, iocs, output, fast, list_modules, module, serial):
     if list_modules:
         log.info("Following is the list of available check-adb modules:")
         for adb_module in ADB_MODULES:
@@ -105,12 +126,16 @@ def check_adb(iocs, output, list_modules, module):
             os.makedirs(output)
         except Exception as e:
             log.critical("Unable to create output folder %s: %s", output, e)
-            sys.exit(-1)
+            ctx.exit(1)
 
-    if iocs:
-        # Pre-load indicators for performance reasons.
-        log.info("Loading indicators from provided file at %s", iocs)
-        indicators = Indicators(iocs)
+    indicators = Indicators(log=log)
+    for ioc_path in iocs:
+        try:
+            indicators.parse_stix2(ioc_path)
+        except IndicatorsFileBadFormat as e:
+            log.critical(e)
+            ctx.exit(1)
+    log.info("Loaded a total of %d indicators", indicators.ioc_count)
 
     timeline = []
     timeline_detected = []
@@ -118,7 +143,10 @@ def check_adb(iocs, output, list_modules, module):
         if module and adb_module.__name__ != module:
             continue
 
-        m = adb_module(output_folder=output, log=logging.getLogger(adb_module.__module__))
+        m = adb_module(output_folder=output, fast_mode=fast,
+                       log=logging.getLogger(adb_module.__module__))
+        if serial:
+            m.serial = serial
 
         if iocs:
             indicators.log = m.log
@@ -134,14 +162,18 @@ def check_adb(iocs, output, list_modules, module):
         if len(timeline_detected) > 0:
             save_timeline(timeline_detected, os.path.join(output, "timeline_detected.csv"))
 
+
 #==============================================================================
 # Check ADB backup
 #==============================================================================
 @cli.command("check-backup", help="Check an Android Backup")
-@click.option("--iocs", "-i", type=click.Path(exists=True), help="Path to indicators file")
-@click.option("--output", "-o", type=click.Path(exists=False), help=OUTPUT_HELP_MESSAGE)
+@click.option("--serial", "-s", type=str, help=HELP_MSG_SERIAL)
+@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
+              default=[], help=HELP_MSG_IOC)
+@click.option("--output", "-o", type=click.Path(exists=False), help=HELP_MSG_OUTPUT)
 @click.argument("BACKUP_PATH", type=click.Path(exists=True))
-def check_backup(iocs, output, backup_path):
+@click.pass_context
+def check_backup(ctx, iocs, output, backup_path, serial):
     log.info("Checking ADB backup located at: %s", backup_path)
 
     if output and not os.path.exists(output):
@@ -149,26 +181,33 @@ def check_backup(iocs, output, backup_path):
             os.makedirs(output)
         except Exception as e:
             log.critical("Unable to create output folder %s: %s", output, e)
-            sys.exit(-1)
+            ctx.exit(1)
 
-    if iocs:
-        # Pre-load indicators for performance reasons.
-        log.info("Loading indicators from provided file at %s", iocs)
-        indicators = Indicators(iocs)
+    indicators = Indicators(log=log)
+    for ioc_path in iocs:
+        try:
+            indicators.parse_stix2(ioc_path)
+        except IndicatorsFileBadFormat as e:
+            log.critical(e)
+            ctx.exit(1)
+    log.info("Loaded a total of %d indicators", indicators.ioc_count)
 
     if os.path.isfile(backup_path):
         log.critical("The path you specified is a not a folder!")
 
         if os.path.basename(backup_path) == "backup.ab":
-            log.info("You can use ABE (https://github.com/nelenkov/android-backup-extractor) " \
+            log.info("You can use ABE (https://github.com/nelenkov/android-backup-extractor) "
                      "to extract 'backup.ab' files!")
-        sys.exit(-1)
+        ctx.exit(1)
 
     for module in BACKUP_MODULES:
         m = module(base_folder=backup_path, output_folder=output,
                    log=logging.getLogger(module.__module__))
 
-        if iocs:
+        if serial:
+            m.serial = serial
+
+        if len(indicators.ioc_count) > 0:
             indicators.log = m.log
             m.indicators = indicators
 

mvt/android/data/safe_packages.txt

@@ -1,182 +0,0 @@
-android
-android.auto_generated_rro__
-android.autoinstalls.config.google.nexus
-com.android.backupconfirm
-com.android.bips
-com.android.bluetooth
-com.android.bluetoothmidiservice
-com.android.bookmarkprovider
-com.android.calllogbackup
-com.android.captiveportallogin
-com.android.carrierconfig
-com.android.carrierdefaultapp
-com.android.cellbroadcastreceiver
-com.android.certinstaller
-com.android.chrome
-com.android.companiondevicemanager
-com.android.connectivity.metrics
-com.android.cts.ctsshim
-com.android.cts.priv.ctsshim
-com.android.defcontainer
-com.android.documentsui
-com.android.dreams.basic
-com.android.egg
-com.android.emergency
-com.android.externalstorage
-com.android.facelock
-com.android.hotwordenrollment
-com.android.hotwordenrollment.okgoogle
-com.android.hotwordenrollment.tgoogle
-com.android.hotwordenrollment.xgoogle
-com.android.htmlviewer
-com.android.inputdevices
-com.android.keychain
-com.android.location.fused
-com.android.managedprovisioning
-com.android.mms.service
-com.android.mtp
-com.android.musicfx
-com.android.nfc
-com.android.omadm.service
-com.android.pacprocessor
-com.android.phone
-com.android.printspooler
-com.android.providers.blockednumber
-com.android.providers.calendar
-com.android.providers.contacts
-com.android.providers.downloads
-com.android.providers.downloads.ui
-com.android.providers.media
-com.android.providers.partnerbookmarks
-com.android.providers.settings
-com.android.providers.telephony
-com.android.providers.userdictionary
-com.android.proxyhandler
-com.android.retaildemo
-com.android.safetyregulatoryinfo
-com.android.sdm.plugins.connmo
-com.android.sdm.plugins.dcmo
-com.android.sdm.plugins.diagmon
-com.android.sdm.plugins.sprintdm
-com.android.server.telecom
-com.android.service.ims
-com.android.service.ims.presence
-com.android.settings
-com.android.sharedstoragebackup
-com.android.shell
-com.android.statementservice
-com.android.stk
-com.android.systemui
-com.android.systemui.theme.dark
-com.android.vending
-com.android.vpndialogs
-com.android.vzwomatrigger
-com.android.wallpaperbackup
-com.android.wallpaper.livepicker
-com.breel.wallpapers
-com.customermobile.preload.vzw
-com.google.android.apps.cloudprint
-com.google.android.apps.docs
-com.google.android.apps.docs.editors.docs
-com.google.android.apps.enterprise.dmagent
-com.google.android.apps.gcs
-com.google.android.apps.helprtc
-com.google.android.apps.inputmethod.hindi
-com.google.android.apps.maps
-com.google.android.apps.messaging
-com.google.android.apps.nexuslauncher
-com.google.android.apps.photos
-com.google.android.apps.pixelmigrate
-com.google.android.apps.tachyon
-com.google.android.apps.turbo
-com.google.android.apps.tycho
-com.google.android.apps.wallpaper
-com.google.android.apps.wallpaper.nexus
-com.google.android.apps.work.oobconfig
-com.google.android.apps.youtube.vr
-com.google.android.asdiv
-com.google.android.backuptransport
-com.google.android.calculator
-com.google.android.calendar
-com.google.android.carrier
-com.google.android.carrier.authdialog
-com.google.android.carrierentitlement
-com.google.android.carriersetup
-com.google.android.configupdater
-com.google.android.contacts
-com.google.android.deskclock
-com.google.android.dialer
-com.google.android.euicc
-com.google.android.ext.services
-com.google.android.ext.shared
-com.google.android.feedback
-com.google.android.gm
-com.google.android.gms
-com.google.android.gms.policy_auth
-com.google.android.gms.policy_sidecar_o
-com.google.android.gms.setup
-com.google.android.GoogleCamera
-com.google.android.googlequicksearchbox
-com.google.android.gsf
-com.google.android.gsf.login
-com.google.android.hardwareinfo
-com.google.android.hiddenmenu
-com.google.android.ims
-com.google.android.inputmethod.japanese
-com.google.android.inputmethod.korean
-com.google.android.inputmethod.latin
-com.google.android.inputmethod.pinyin
-com.google.android.instantapps.supervisor
-com.google.android.keep
-com.google.android.marvin.talkback
-com.google.android.music
-com.google.android.nexusicons
-com.google.android.onetimeinitializer
-com.google.android.packageinstaller
-com.google.android.partnersetup
-com.google.android.printservice.recommendation
-com.google.android.setupwizard
-com.google.android.soundpicker
-com.google.android.storagemanager
-com.google.android.syncadapters.contacts
-com.google.android.tag
-com.google.android.talk
-com.google.android.tetheringentitlement
-com.google.android.theme.pixel
-com.google.android.tts
-com.google.android.videos
-com.google.android.vr.home
-com.google.android.vr.inputmethod
-com.google.android.webview
-com.google.android.wfcactivation
-com.google.android.youtube
-com.google.ar.core
-com.google.intelligence.sense
-com.google.modemservice
-com.google.pixel.wahoo.gfxdrv
-com.google.SSRestartDetector
-com.google.tango
-com.google.vr.apps.ornament
-com.google.vr.vrcore
-com.htc.omadm.trigger
-com.qti.qualcomm.datastatusnotification
-com.qualcomm.atfwd
-com.qualcomm.embms
-com.qualcomm.fastdormancy
-com.qualcomm.ltebc_vzw
-com.qualcomm.qcrilmsgtunnel
-com.qualcomm.qti.ims
-com.qualcomm.qti.networksetting
-com.qualcomm.qti.telephonyservice
-com.qualcomm.qti.uceShimService
-com.qualcomm.shutdownlistner
-com.qualcomm.timeservice
-com.qualcomm.vzw_api
-com.quicinc.cne.CNEService
-com.verizon.llkagent
-com.verizon.mips.services
-com.verizon.obdm
-com.verizon.obdm_permissions
-com.verizon.services
-com.vzw.apnlib
-qualcomm.com.vzw_msdc_api

mvt/android/lookups/__init__.py

@@ -1,4 +1,4 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/

mvt/android/lookups/koodous.py

@@ -1,7 +1,7 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import logging
 
@@ -13,6 +13,7 @@ from rich.text import Text
 
 log = logging.getLogger(__name__)
 
+
 def koodous_lookup(packages):
     log.info("Looking up all extracted files on Koodous (www.koodous.com)")
     log.info("This might take a while...")
@@ -27,12 +28,12 @@ def koodous_lookup(packages):
     total_packages = len(packages)
     for i in track(range(total_packages), description=f"Looking up {total_packages} packages..."):
         package = packages[i]
-        for file in package.files:
+        for file in package.get("files", []):
             url = f"https://api.koodous.com/apks/{file['sha256']}"
             res = requests.get(url)
             report = res.json()
 
-            row = [package.name, file["local_name"]]
+            row = [package["package_name"], file["path"]]
 
             if "package_name" in report:
                 trusted = "no"

mvt/android/lookups/virustotal.py

@@ -1,7 +1,7 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import logging
 
@@ -13,6 +13,7 @@ from rich.text import Text
 
 log = logging.getLogger(__name__)
 
+
 def get_virustotal_report(hashes):
     apikey = "233f22e200ca5822bd91103043ccac138b910db79f29af5616a9afe8b6f215ad"
     url = f"https://www.virustotal.com/partners/sysinternals/file-reports?apikey={apikey}"
@@ -36,18 +37,20 @@ def get_virustotal_report(hashes):
         log.error("Unexpected response from VirusTotal: %s", res.status_code)
         return None
 
+
 def virustotal_lookup(packages):
     log.info("Looking up all extracted files on VirusTotal (www.virustotal.com)")
 
     unique_hashes = []
     for package in packages:
-        for file in package.files:
+        for file in package.get("files", []):
             if file["sha256"] not in unique_hashes:
                 unique_hashes.append(file["sha256"])
 
     total_unique_hashes = len(unique_hashes)
 
     detections = {}
+
     def virustotal_query(batch):
         report = get_virustotal_report(batch)
         if not report:
@@ -74,8 +77,8 @@ def virustotal_lookup(packages):
     table.add_column("Detections")
 
     for package in packages:
-        for file in package.files:
-            row = [package.name, file["local_name"]]
+        for file in package.get("files", []):
+            row = [package["package_name"], file["path"]]
 
             if file["sha256"] in detections:
                 detection = detections[file["sha256"]]

mvt/android/modules/__init__.py

@@ -1,4 +1,4 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/

mvt/android/modules/adb/__init__.py

@@ -1,12 +1,16 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 from .chrome_history import ChromeHistory
 from .dumpsys_batterystats import DumpsysBatterystats
+from .dumpsys_full import DumpsysFull
 from .dumpsys_packages import DumpsysPackages
 from .dumpsys_procstats import DumpsysProcstats
+from .dumpsys_receivers import DumpsysReceivers
+from .files import Files
+from .logcat import Logcat
 from .packages import Packages
 from .processes import Processes
 from .rootbinaries import RootBinaries
@@ -15,4 +19,5 @@ from .whatsapp import Whatsapp
 
 ADB_MODULES = [ChromeHistory, SMS, Whatsapp, Processes,
                DumpsysBatterystats, DumpsysProcstats,
-               DumpsysPackages, Packages, RootBinaries]
+               DumpsysPackages, DumpsysReceivers, DumpsysFull,
+               Packages, RootBinaries, Logcat, Files]

mvt/android/modules/adb/base.py

@@ -1,7 +1,7 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import logging
 import os
@@ -11,39 +11,39 @@ import sys
 import tempfile
 import time
 
-from adb_shell.adb_device import AdbDeviceUsb
+from adb_shell.adb_device import AdbDeviceTcp, AdbDeviceUsb
 from adb_shell.auth.keygen import keygen, write_public_keyfile
 from adb_shell.auth.sign_pythonrsa import PythonRSASigner
-from adb_shell.exceptions import AdbCommandFailureException, DeviceAuthError
+from adb_shell.exceptions import (AdbCommandFailureException, DeviceAuthError,
+                                  UsbReadFailedError)
 from usb1 import USBErrorAccess, USBErrorBusy
 
-from mvt.common.module import MVTModule
+from mvt.common.module import InsufficientPrivileges, MVTModule
 
 log = logging.getLogger(__name__)
 
 ADB_KEY_PATH = os.path.expanduser("~/.android/adbkey")
 ADB_PUB_KEY_PATH = os.path.expanduser("~/.android/adbkey.pub")
 
+
 class AndroidExtraction(MVTModule):
     """This class provides a base for all Android extraction modules."""
 
     def __init__(self, file_path=None, base_folder=None, output_folder=None,
                  fast_mode=False, log=None, results=[]):
-        """Initialize Android extraction module.
-        :param file_path: Path to the database file to parse
-        :param base_folder: Path to a base folder containing an Android dump
-        :param output_folder: Path to the folder where to store extraction
-                              results
-        """
         super().__init__(file_path=file_path, base_folder=base_folder,
                          output_folder=output_folder, fast_mode=fast_mode,
                          log=log, results=results)
 
         self.device = None
+        self.serial = None
+
+    @staticmethod
+    def _adb_check_keys():
+        """Make sure Android adb keys exist."""
+        if not os.path.isdir(os.path.dirname(ADB_KEY_PATH)):
+            os.makedirs(os.path.dirname(ADB_KEY_PATH))
 
-    def _adb_check_keys(self):
-        """Make sure Android adb keys exist.
-        """
         if not os.path.exists(ADB_KEY_PATH):
             keygen(ADB_KEY_PATH)
 
@@ -51,15 +51,29 @@ class AndroidExtraction(MVTModule):
             write_public_keyfile(ADB_KEY_PATH, ADB_PUB_KEY_PATH)
 
     def _adb_connect(self):
-        """Connect to the device over adb.
-        """
+        """Connect to the device over adb."""
         self._adb_check_keys()
 
         with open(ADB_KEY_PATH, "rb") as handle:
             priv_key = handle.read()
 
-        signer = PythonRSASigner("", priv_key)
-        self.device = AdbDeviceUsb()
+        with open(ADB_PUB_KEY_PATH, "rb") as handle:
+            pub_key = handle.read()
+
+        signer = PythonRSASigner(pub_key, priv_key)
+
+        # If no serial was specified or if the serial does not seem to be
+        # a HOST:PORT definition, we use the USB transport.
+        if not self.serial or ":" not in self.serial:
+            self.device = AdbDeviceUsb(serial=self.serial)
+        # Otherwise we try to use the TCP transport.
+        else:
+            addr = self.serial.split(":")
+            if len(addr) < 2:
+                raise ValueError("TCP serial number must follow the format: `address:port`")
+
+            self.device = AdbDeviceTcp(addr[0], int(addr[1]),
+                                       default_transport_timeout_s=30.)
 
         while True:
             try:
@@ -70,56 +84,69 @@ class AndroidExtraction(MVTModule):
             except DeviceAuthError:
                 log.error("You need to authorize this computer on the Android device. Retrying in 5 seconds...")
                 time.sleep(5)
-            except Exception as e:
-                log.critical(e)
+            except UsbReadFailedError:
+                log.error("Unable to connect to the device over USB. Try to unplug, plug the device and start again.")
                 sys.exit(-1)
+            except OSError as e:
+                if e.errno == 113 and self.serial:
+                    log.critical("Unable to connect to the device %s: did you specify the correct IP addres?",
+                                 self.serial)
+                    sys.exit(-1)
             else:
                 break
 
     def _adb_disconnect(self):
-        """Close adb connection to the device.
-        """
+        """Close adb connection to the device."""
         self.device.close()
 
     def _adb_reconnect(self):
-        """Reconnect to device using adb.
-        """
+        """Reconnect to device using adb."""
         log.info("Reconnecting ...")
         self._adb_disconnect()
         self._adb_connect()
 
     def _adb_command(self, command):
         """Execute an adb shell command.
+
         :param command: Shell command to execute
         :returns: Output of command
+
         """
         return self.device.shell(command)
 
     def _adb_check_if_root(self):
         """Check if we have a `su` binary on the Android device.
+
+
         :returns: Boolean indicating whether a `su` binary is present or not
+
         """
         return bool(self._adb_command("command -v su"))
 
     def _adb_root_or_die(self):
-        """Check if we have a `su` binary, otherwise raise an Exception.
-        """
+        """Check if we have a `su` binary, otherwise raise an Exception."""
         if not self._adb_check_if_root():
-            raise Exception("The Android device does not seem to have a `su` binary. Cannot run this module.")
+            raise InsufficientPrivileges("This module is optionally available in case the device is already rooted. Do NOT root your own device!")
 
     def _adb_command_as_root(self, command):
         """Execute an adb shell command.
+
         :param command: Shell command to execute as root
         :returns: Output of command
+
         """
         return self._adb_command(f"su -c {command}")
-    
+
     def _adb_check_file_exists(self, file):
         """Verify that a file exists.
+
         :param file: Path of the file
         :returns: Boolean indicating whether the file exists or not
+
         """
 
+        # TODO: Need to support checking files without root privileges as well.
+
         # Connect to the device over adb.
         self._adb_connect()
         # Check if we have root, if not raise an Exception.
@@ -129,9 +156,12 @@ class AndroidExtraction(MVTModule):
 
     def _adb_download(self, remote_path, local_path, progress_callback=None, retry_root=True):
         """Download a file form the device.
+
         :param remote_path: Path to download from the device
         :param local_path: Path to where to locally store the copy of the file
-        :param progress_callback: Callback for download progress bar
+        :param progress_callback: Callback for download progress bar (Default value = None)
+        :param retry_root: Default value = True)
+
         """
         try:
             self.device.pull(remote_path, local_path, progress_callback)
@@ -140,7 +170,7 @@ class AndroidExtraction(MVTModule):
                 self._adb_download_root(remote_path, local_path, progress_callback)
             else:
                 raise Exception(f"Unable to download file {remote_path}: {e}")
-    
+
     def _adb_download_root(self, remote_path, local_path, progress_callback=None):
         try:
             # Check if we have root, if not raise an Exception.
@@ -165,16 +195,18 @@ class AndroidExtraction(MVTModule):
 
             # Delete the copy on /sdcard/.
             self._adb_command(f"rm -rf {new_remote_path}")
-            
+
         except AdbCommandFailureException as e:
             raise Exception(f"Unable to download file {remote_path}: {e}")
 
     def _adb_process_file(self, remote_path, process_routine):
         """Download a local copy of a file which is only accessible as root.
         This is a wrapper around process_routine.
+
         :param remote_path: Path of the file on the device to process
         :param process_routine: Function to be called on the local copy of the
                                 downloaded file
+
         """
         # Connect to the device over adb.
         self._adb_connect()
@@ -208,6 +240,5 @@ class AndroidExtraction(MVTModule):
         self._adb_disconnect()
 
     def run(self):
-        """Run the main procedure.
-        """
+        """Run the main procedure."""
         raise NotImplementedError

mvt/android/modules/adb/chrome_history.py

@@ -1,7 +1,7 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import logging
 import os
@@ -16,11 +16,12 @@ log = logging.getLogger(__name__)
 
 CHROME_HISTORY_PATH = "data/data/com.android.chrome/app_chrome/Default/History"
 
+
 class ChromeHistory(AndroidExtraction):
     """This module extracts records from Android's Chrome browsing history."""
 
     def __init__(self, file_path=None, base_folder=None, output_folder=None,
-                 fast_mode=False, log=None, results=[]):
+                 serial=None, fast_mode=False, log=None, results=[]):
         super().__init__(file_path=file_path, base_folder=base_folder,
                          output_folder=output_folder, fast_mode=fast_mode,
                          log=log, results=results)
@@ -33,9 +34,19 @@ class ChromeHistory(AndroidExtraction):
             "data": f"{record['id']} - {record['url']} (visit ID: {record['visit_id']}, redirect source: {record['redirect_source']})"
         }
 
+    def check_indicators(self):
+        if not self.indicators:
+            return
+
+        for result in self.results:
+            if self.indicators.check_domain(result["url"]):
+                self.detected.append(result)
+
     def _parse_db(self, db_path):
         """Parse a Chrome History database file.
+
         :param db_path: Path to the History database to process.
+
         """
         conn = sqlite3.connect(db_path)
         cur = conn.cursor()
@@ -52,14 +63,14 @@ class ChromeHistory(AndroidExtraction):
         """)
 
         for item in cur:
-            self.results.append(dict(
-                id=item[0],
-                url=item[1],
-                visit_id=item[2],
-                timestamp=item[3],
-                isodate=convert_timestamp_to_iso(convert_chrometime_to_unix(item[3])),
-                redirect_source=item[4],
-            ))
+            self.results.append({
+                "id": item[0],
+                "url": item[1],
+                "visit_id": item[2],
+                "timestamp": item[3],
+                "isodate": convert_timestamp_to_iso(convert_chrometime_to_unix[item[3]]),
+                "redirect_source": item[4],
+            })
 
         cur.close()
         conn.close()

mvt/android/modules/adb/dumpsys_batterystats.py

@@ -1,7 +1,7 @@
 # Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021 MVT Project Developers.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
+# Copyright (c) 2021 The MVT Project Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
 
 import logging
 import os
@@ -10,11 +10,12 @@ from .base import AndroidExtraction
 
 log = logging.getLogger(__name__)
 
+
 class DumpsysBatterystats(AndroidExtraction):
     """This module extracts stats on battery consumption by processes."""
 
     def __init__(self, file_path=None, base_folder=None, output_folder=None,
-                 fast_mode=False, log=None, results=[]):
+                 serial=None, fast_mode=False, log=None, results=[]):
         super().__init__(file_path=file_path, base_folder=base_folder,
                          output_folder=output_folder, fast_mode=fast_mode,
                          log=log, results=results)
@@ -30,7 +31,7 @@ class DumpsysBatterystats(AndroidExtraction):
                 handle.write(stats)
 
             log.info("Records from dumpsys batterystats stored at %s",
-                      stats_path)
+                     stats_path)
 
         history = self._adb_command("dumpsys batterystats --history")
         if self.output_folder: