Merge pull request #964 from forest-savage1234/docs/python-minimum-q093-20260929

Correct the Python minimum in installation documentation

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "uv" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7

.github/workflows/add-issue-to-project.yml

@@ -0,0 +1,19 @@
+name: Add issue to project
+
+on:
+  issues:
+    types:
+      - opened
+      - reopened
+
+jobs:
+  add-to-project:
+    name: Add issue to project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v2
+        with:
+          # You can target a project in a different organization
+          # to the issue
+          project-url: https://github.com/orgs/mvt-project/projects/1
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}

.github/workflows/flake8.yml

@@ -1,26 +0,0 @@
-name: Flake8
-
-on:
-  push:
-    paths:
-      - '*.py'
-
-jobs:
-  flake8_py3:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Setup Python
-        uses: actions/setup-python@v1
-        with:
-          python-version: 3.9
-          architecture: x64
-      - name: Checkout
-        uses: actions/checkout@master
-      - name: Install flake8
-        run: pip install flake8
-      - name: Run flake8
-        uses: suo/flake8-github-action@releases/v1
-        with:
-          checkName: 'flake8_py3'   # NOTE: this needs to be the same as the job name
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/mypy.yml

@@ -0,0 +1,28 @@
+name: Mypy
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  mypy_py3:
+    name: Mypy check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Setup Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.0
+        with:
+          enable-cache: true
+      - name: Install Dependencies
+        run: |
+          uv sync --locked --group dev
+      - name: mypy
+        run: |
+          make mypy

.github/workflows/publish-release-docker.yml

@@ -0,0 +1,84 @@
+#
+name: Create and publish a Docker image
+
+# Configures this workflow to run every time a release is published.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+      #
+    strategy:
+      matrix:
+        platform:
+          - dockerfile: "Dockerfile"
+            tag-suffix: ""
+          - dockerfile: "Dockerfile.ios"
+            tag-suffix: "-ios"
+          - dockerfile: "Dockerfile.android"
+            tag-suffix: "-android"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # the package version comes from the git tags
+      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
+      - name: Log in to the Container registry
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          flavor: |
+            latest=false
+          tags: |
+            type=raw,value=latest,enable={{ is_default_branch }},suffix=${{ matrix.platform.tag-suffix }}
+            type=raw,enable=${{ github.event_name == 'release' || github.ref_type == 'tag' }},value=stable,suffix=${{ matrix.platform.tag-suffix }}
+            type=raw,enable=${{ github.event_name == 'release' }},value=${{ github.event.release.tag_name }},suffix=${{ matrix.platform.tag-suffix }}
+            type=raw,enable=${{ github.ref_type == 'tag' }},value=${{ github.ref_name }},suffix=${{ matrix.platform.tag-suffix }}
+            type=sha,suffix=${{ matrix.platform.tag-suffix }}
+            type=sha,format=long,suffix=${{ matrix.platform.tag-suffix }}
+      # Register emulators so Buildx can build the ARM64 images on the AMD64 runner.
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+      # This step sets up some additional capabilities to generate the provenance and sbom attestations
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
+      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v7
+        with:
+          file: ${{ matrix.platform.dockerfile }}
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          provenance: mode=max
+          sbom: true

.github/workflows/python-package.yml

@@ -1,44 +0,0 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        # python-version: [3.7, 3.8, 3.9]
-        python-version: [3.8, 3.9]
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade setuptools
-        python -m pip install --upgrade pip
-        python -m pip install flake8 pytest safety stix2 pytest-mock
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-        python -m pip install .
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Safety checks
-      run: safety check
-    - name: Test with pytest
-      run: pytest

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  schedule:
+    - cron: "0 9 * * 1" # Mondays, 09:00 UTC
+  workflow_dispatch:
+  push:
+    tags: ["v*"]
+
+jobs:
+  tag:
+    if: github.ref_type != 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - run: |
+          last=$(git describe --tags --abbrev=0 --match 'v*')
+          if [ "$(git rev-list "$last..HEAD" --count)" = 0 ]; then
+            echo "Nothing merged since $last"; exit 0
+          fi
+          tag=v$(date -u +%Y.%-m.%-d)
+          gh release create "$tag" --target "$GITHUB_SHA" --generate-notes
+          # Events made with GITHUB_TOKEN don't start other workflows; run them by hand.
+          gh workflow run release.yml --ref "$tag"
+          gh workflow run publish-release-docker.yml --ref "$tag"
+
+  publish:
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment: pypi # only tag refs may deploy; the PyPI trusted publisher requires it
+    permissions:
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.0.0
+      - run: uv build && uv publish

.github/workflows/ruff.yml

@@ -0,0 +1,29 @@
+name: Ruff
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  ruff_py3:
+    name: Ruff syntax check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Setup Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.0
+        with:
+          enable-cache: true
+      - name: Install Dependencies
+        run: |
+          uv sync --locked --group dev
+      - name: ruff
+        run: |
+          make ruff

.github/workflows/scripts/update-ios-releases.py

@@ -0,0 +1,96 @@
+"""
+Python script to download the Apple RSS feed and parse it.
+"""
+
+import json
+import os
+import urllib.request
+from xml.dom.minidom import parseString
+
+from packaging import version
+
+
+def download_apple_rss(feed_url):
+    with urllib.request.urlopen(feed_url) as f:
+        rss_feed = f.read().decode("utf-8")
+    print("Downloaded RSS feed from Apple.")
+    return rss_feed
+
+
+def parse_latest_ios_versions(rss_feed_text):
+    latest_ios_versions = []
+
+    parsed_feed = parseString(rss_feed_text)
+    for item in parsed_feed.getElementsByTagName("item"):
+        title = item.getElementsByTagName("title")[0].firstChild.data
+        if not title.startswith("iOS"):
+            continue
+
+        import re
+
+        build_match = re.match(
+            r"iOS (?P<version>[\d\.]+) (?P<beta>beta )?(\S*)?\((?P<build>.*)\)", title
+        )
+        if not build_match:
+            print("Could not parse iOS build:", title)
+            continue
+
+        # Handle iOS beta releases
+        release_info = build_match.groupdict()
+        release_beta = release_info.pop("beta")
+        if release_beta:
+            print("Skipping beta release:", title)
+            continue
+
+        # Some iOS releases have multiple build number for different hardware models.
+        # We will split these into separate entries and record each build number.
+        build_list = release_info.pop("build")
+        build_variants = build_list.split(" | ")
+        for build_number in build_variants:
+            release_info["build"] = build_number
+            latest_ios_versions.append(release_info)
+
+    return latest_ios_versions
+
+
+def update_mvt(mvt_checkout_path, latest_ios_versions):
+    version_path = os.path.join(mvt_checkout_path, "src/mvt/ios/data/ios_versions.json")
+    with open(version_path, "r") as version_file:
+        current_versions = json.load(version_file)
+
+    new_entry_count = 0
+    for new_version in latest_ios_versions:
+        for current_version in current_versions:
+            if new_version["build"] == current_version["build"]:
+                break
+        else:
+            # New version that does not exist in current data
+            current_versions.append(new_version)
+            new_entry_count += 1
+
+    if not new_entry_count:
+        print("No new iOS versions found.")
+    else:
+        print("Found {} new iOS versions.".format(new_entry_count))
+        new_version_list = sorted(
+            current_versions, key=lambda x: version.Version(x["version"])
+        )
+        with open(version_path, "w") as version_file:
+            json.dump(new_version_list, version_file, indent=4)
+
+
+def main():
+    print("Downloading RSS feed...")
+    mvt_checkout_path = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "../../../")
+    )
+
+    rss_feed = download_apple_rss(
+        "https://developer.apple.com/news/releases/rss/releases.rss"
+    )
+    latest_ios_version = parse_latest_ios_versions(rss_feed)
+    update_mvt(mvt_checkout_path, latest_ios_version)
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/tests.yml

@@ -0,0 +1,56 @@
+name: Tests
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pull-requests: write # coverage comment
+
+jobs:
+  build:
+    name: Run Python Tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    env:
+      # Takes precedence over .python-version, which otherwise makes `uv run`
+      # rebuild the venv with 3.10 and test every matrix entry on 3.10.
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.0
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Python dependencies
+        run: |
+          uv sync --locked --group dev
+      - name: Test with pytest
+        run: |
+          set -o pipefail
+          make test-ci | tee pytest-coverage.txt
+      - name: Coverage job summary
+        run: uv run coverage report --format=markdown --show-missing --skip-covered >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Pytest coverage comment
+        # One comment per PR, not one per matrix entry. PRs from forks get a
+        # read-only token and can't post; the job summary above still works.
+        if: github.event_name == 'pull_request' && matrix.python-version == '3.13'
+        continue-on-error: true
+        uses: MishaKav/pytest-coverage-comment@v1.12.2
+        with:
+          pytest-coverage-path: ./pytest-coverage.txt
+          junitxml-path: ./pytest.xml
+          # The full table with per-line links exceeds GitHub's 65536-char comment limit.
+          report-only-changed-files: true
+          remove-links-to-lines: true

.github/workflows/update-ios-data.yml

@@ -0,0 +1,32 @@
+name: Update iOS releases and version numbers
+run-name: ${{ github.actor }} is finding the latest iOS release version and build numbers
+on:
+  workflow_dispatch:
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    - cron:  '0 */6 * * *'
+
+
+jobs:
+  update-ios-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+      - name: Install script dependencies
+        run: python -m pip install "packaging==26.3"
+      - name: Run script to fetch latest iOS releases from Apple RSS feed.
+        run: python .github/workflows/scripts/update-ios-releases.py
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          title: '[auto] Update iOS releases and versions'
+          commit-message: Add new iOS versions and build numbers
+          branch: auto/add-new-ios-releases
+          draft: true
+          body: |
+            This is an automated pull request to update the iOS releases and version numbers.
+          add-paths: |
+            *.json
+          labels: |
+            automated pr

.gitignore

@@ -50,6 +50,8 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+pytest-coverage.txt
+pytest.xml
 
 # Translations
 *.mo
@@ -84,6 +86,9 @@ ipython_config.py
 # pyenv
 .python-version
 
+# uv project Python version
+!.python-version
+
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
 #   However, in case of collaboration, if having platform-specific dependencies or dependencies
@@ -136,4 +141,4 @@ dmypy.json
 .idea
 
 # Sublime Text project files
-*.sublime*
+*.sublime*

.python-version

@@ -0,0 +1 @@
+3.10

.readthedocs.yaml

@@ -5,11 +5,17 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3.11"
+
 mkdocs:
   configuration: mkdocs.yml
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
-   version: 3.7
-   install:
-   - requirements: docs/requirements.txt
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - docs

.safety-policy.yml

@@ -0,0 +1,11 @@
+# Safety Security and License Configuration file
+# We recommend checking this file into your source control in the root of your Python project
+# If this file is named .safety-policy.yml and is in the same directory where you run `safety check` it will be used by default.
+# Otherwise, you can use the flag `safety check --policy-file <path-to-this-file>` to specify a custom location and name for the file.
+# To validate and review your policy file, run the validate command: `safety validate policy_file --path <path-to-this-file>`
+security: # configuration for the `safety check` command
+    ignore-vulnerabilities: # Here you can list multiple specific vulnerabilities you want to ignore (optionally for a time period)
+        67599: # Example vulnerability ID
+            reason: disputed, inapplicable
+        70612:
+            reason: disputed, inapplicable

CONTRIBUTING.md

@@ -1,19 +1,65 @@
-# Contributing
+# Contributing to Mobile Verification Toolkit (MVT)
 
-Thank you for your interest in contributing to Mobile Verification Toolkit (MVT)! Your help is very much appreciated.
+We greatly appreciate contributions to MVT!
+
+Your involvement, whether through identifying issues, improving functionality, or enhancing documentation, is very much appreciated. To ensure smooth collaboration and a welcoming environment, we've outlined some key guidelines for contributing below.
+
+## Getting started
+
+Contributing to an open-source project like MVT might seem overwhelming at first, but we're here to support you!
+
+ Whether you're a technologist, a frontline human rights defender, a field researcher, or someone new to consensual spyware forensics, there are many ways to make meaningful contributions.
+
+ Here's how you can get started:
+
+1. **Explore the codebase:**
+    - Browse the repository to get familar with MVT. Many MVT modules are simple in functionality and easy to understand.
+    - Look for `TODO:` or `FIXME:` comments in the code for areas that need attention.
+
+2. **Check Github issues:**
+    - Look for issues tagged with ["help wanted"](https://github.com/mvt-project/mvt/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) or ["good first issue"](https://github.com/mvt-project/mvt/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to find tasks that are beginner-friendly or where input from the community would be helpful.
+
+3. **Ask for guidance:**
+
+    - If you're unsure where to start, feel free to open a [discussion](https://github.com/mvt-project/mvt/discussions) or comment on an issue.
+
+## How to contribute:
+
+1. **Report issues:**
+
+ - Found a bug? Please check existing issues to see if it's already reported. If not, open a new issue. Mobile operating systems and databases are constantly evolving, an new errors may appear spontaniously in new app versions.
+
+ **Please provide as much information as possible about the prodblem including: any error messages, steps to reproduce the problem, and any logs or screenshots that can help.**
 
 
-## Where to start
+2. **Suggest features:**
+    - If you have an idea for new functionality, create a feature request issue and describe your proposal.
 
-Starting to contribute to a somewhat complex project like MVT might seem intimidating. Unless you have specific ideas of new functionality you would like to submit, some good starting points are searching for `TODO:` and `FIXME:` comments throughout the code. Alternatively you can check if any GitHub issues existed marked with the ["help wanted"](https://github.com/mvt-project/mvt/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) tag.
+3. **Submit code:**
+    - Fork the repository and create a new branch for your changes.
+    - Ensure your changes align with the code style guidelines (see below).
+    - Open a pull request (PR) with a clear description of your changes and link it to any relevant issues.
 
+4. **Documentation contributions:**
+    - Improving documentation is just as valuable as contributing code! If you notice gaps or inaccuracies in the documentation, feel free to submit changes or suggest updates.
 
 ## Code style
+Please follow these code style guidelines for consistency and readability:
 
-When contributing code to 
+- **Indentation**: use 4 spaces per tab.
+- **Quotes**: Use double quotes (`"`) by default. Use single quotes (`'`) for nested strings instead of escaping (`\"`), or when using f-formatting.
+- **Maximum line length**:
+    - Aim for lines no longer than 80 characters.
+    - Exceptions are allowed for long log lines or strings, which may extend up to 100 characters.
+    - Wrap lines that exceed 100 characters.
 
-- **Indentation**: we use 4-spaces tabs.
+Follow [PEP 8 guidelines](https://peps.python.org/pep-0008/) for indentation and overall Python code style. All MVT code is automatically linted with [Ruff](https://github.com/astral-sh/ruff) before merging.
 
-- **Quotes**: we use double quotes (`"`) as a default. Single quotes (`'`) can be favored with nested strings instead of escaping (`\"`), or when using f-formatting.
+Please check your code before opening a pull request by running `make ruff`
 
-- **Maximum line length**: we strongly encourage to respect a 80 characters long lines and to follow [PEP8 indentation guidelines](https://peps.python.org/pep-0008/#indentation) when having to wrap. However, if breaking at 80 is not possible or is detrimental to the readability of the code, exceptions are tolerated. For example, long log lines, or long strings can be extended to 100 characters long. Please hard wrap anything beyond 100 characters.
+
+## Community and support
+
+We aim to create a supportive and collaborative environment for all contributors. If you run into any challenges, feel free to reach out through the discussions or issues section of the repository.
+
+Your contributions, big or small, help improve MVT and are always appreciated.

Dockerfile

@@ -1,79 +1,167 @@
-FROM ubuntu:22.04
+# Base image for building libraries
+# ---------------------------------
+FROM ubuntu:22.04 AS build-base
 
-# Ref. https://github.com/mvt-project/mvt
+ARG DEBIAN_FRONTEND=noninteractive
 
-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
-ENV DEBIAN_FRONTEND=noninteractive
-
-# Fixing major OS dependencies
-# ----------------------------
-RUN apt update \
-  && apt install -y python3 python3-pip libusb-1.0-0-dev wget unzip default-jre-headless adb \
-
-# Install build tools for libimobiledevice
-# ----------------------------------------
+# Install build tools and dependencies
+RUN apt-get update \
+  && apt-get install -y \
   build-essential \
-  checkinstall \
   git \
   autoconf \
   automake \
   libtool-bin \
-  libplist-dev \
-  libusbmuxd-dev \
-  libssl-dev \
-  sqlite3 \
   pkg-config \
+  libcurl4-openssl-dev \
+  libusb-1.0-0-dev \
+  libssl-dev \
+  udev \
+  && rm -rf /var/lib/apt/lists/*
 
-# Clean up
+
+# libplist
 # --------
-  && apt-get clean \
-  && rm -rf /var/lib/apt/lists/* /var/cache/apt
+FROM build-base AS build-libplist
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libplist && cd libplist \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libplist
 
 
-# Build libimobiledevice
-# ----------------------
-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 \
+# libimobiledevice-glue
+# ---------------------
+FROM build-base AS build-libimobiledevice-glue
 
-  && cd libplist && ./autogen.sh && make && make install && ldconfig \
+# Install dependencies
+COPY --from=build-libplist /build /
 
-  && cd ../libimobiledevice-glue && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --prefix=/usr && make && make install && ldconfig \
+# Build
+RUN git clone https://github.com/libimobiledevice/libimobiledevice-glue && cd libimobiledevice-glue \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libimobiledevice-glue
 
-  && cd ../libusbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh && make && make install && ldconfig \
 
-  && cd ../libimobiledevice && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --enable-debug && make && make install && ldconfig \
+# libtatsu
+# --------
+FROM build-base AS build-libtatsu
 
-  && cd ../usbmuxd && PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --runstatedir=/run && make && make install \
+# Install dependencies
+COPY --from=build-libplist /build /
 
-  # Clean up.
-  && cd .. && rm -rf libplist libimobiledevice-glue libusbmuxd libimobiledevice usbmuxd
+# Build
+RUN git clone https://github.com/libimobiledevice/libtatsu && cd libtatsu \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libtatsu
 
-# Installing MVT
-# --------------
-RUN pip3 install mvt
+
+# libusbmuxd
+# ----------
+FROM build-base AS build-libusbmuxd
+
+# Install dependencies
+COPY --from=build-libplist /build /
+COPY --from=build-libimobiledevice-glue /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libusbmuxd && cd libusbmuxd \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libusbmuxd
+
+
+# libimobiledevice
+# ----------------
+FROM build-base AS build-libimobiledevice
+
+# Install dependencies
+COPY --from=build-libplist /build /
+COPY --from=build-libtatsu /build /
+COPY --from=build-libimobiledevice-glue /build /
+COPY --from=build-libusbmuxd /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libimobiledevice && cd libimobiledevice \
+  && ./autogen.sh --enable-debug && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libimobiledevice
+
+
+# usbmuxd
+# -------
+FROM build-base AS build-usbmuxd
+
+# Install dependencies
+COPY --from=build-libplist /build /
+COPY --from=build-libimobiledevice-glue /build /
+COPY --from=build-libusbmuxd /build /
+COPY --from=build-libimobiledevice /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/usbmuxd && cd usbmuxd \
+  && ./autogen.sh --sysconfdir=/etc --localstatedir=/var --runstatedir=/run && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf usbmuxd && mv /build/lib /build/usr/lib
+
+
+# Create main image
+FROM ubuntu:24.04 AS main
+COPY --from=ghcr.io/astral-sh/uv:0.11.8 /uv /uvx /usr/local/bin/
+
+LABEL org.opencontainers.image.url="https://mvt.re"
+LABEL org.opencontainers.image.documentation="https://docs.mvt.re"
+LABEL org.opencontainers.image.source="https://github.com/mvt-project/mvt"
+LABEL org.opencontainers.image.title="Mobile Verification Toolkit"
+LABEL org.opencontainers.image.description="MVT is a forensic tool to look for signs of infection in smartphone devices."
+LABEL org.opencontainers.image.licenses="MVT License 1.1"
+LABEL org.opencontainers.image.base.name=docker.io/library/ubuntu:22.04
+
+# Install runtime dependencies
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update \
+  && apt-get install -y \
+  adb \
+  binutils \
+  default-jre-headless \
+  file \
+  git \
+  jq \
+  less \
+  libcurl4 \
+  libimage-exiftool-perl \
+  libssl3 \
+  libusb-1.0-0 \
+  moreutils \
+  p7zip-full \
+  python3 \
+  ripgrep \
+  sqlite3 \
+  tree \
+  unzip \
+  xxd
+COPY --from=build-libplist /build /
+COPY --from=build-libimobiledevice-glue /build /
+COPY --from=build-libtatsu /build /
+COPY --from=build-libusbmuxd /build /
+COPY --from=build-libimobiledevice /build /
+COPY --from=build-usbmuxd /build /
+
+# Install mvt using the locally checked out source
+COPY . mvt/
+RUN uv pip install --system --break-system-packages --no-cache ./mvt \
+  && rm -rf mvt
 
 # Installing ABE
-# --------------
-RUN mkdir /opt/abe \
-  && wget https://github.com/nelenkov/android-backup-extractor/releases/download/20210709062403-4c55371/abe.jar -O /opt/abe/abe.jar \
+ADD --checksum=sha256:a20e07f8b2ea47620aff0267f230c3f1f495f097081fd709eec51cf2a2e11632 \
+  https://github.com/nelenkov/android-backup-extractor/releases/download/master-20221109063121-8fdfc5e/abe.jar /opt/abe/abe.jar
 # Create alias for abe
-  && echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc
+RUN echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc
 
-# Generate adb key folder 
-# ------------------------------ 
-RUN mkdir /root/.android && adb keygen /root/.android/adbkey
+# Generate adb key folder
+RUN echo 'if [ ! -f /root/.android/adbkey ]; then adb keygen /root/.android/adbkey > /dev/null 2>&1; fi' >> ~/.bashrc
+RUN mkdir /root/.android
 
 # Setup investigations environment
-# --------------------------------
 RUN mkdir /home/cases
-WORKDIR /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 \
   && 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
 

Dockerfile.android

@@ -0,0 +1,37 @@
+# Create main image
+FROM python:3.10.14-alpine3.20 AS main
+COPY --from=ghcr.io/astral-sh/uv:0.11.8 /uv /uvx /usr/local/bin/
+
+LABEL org.opencontainers.image.url="https://mvt.re"
+LABEL org.opencontainers.image.documentation="https://docs.mvt.re"
+LABEL org.opencontainers.image.source="https://github.com/mvt-project/mvt"
+LABEL org.opencontainers.image.title="Mobile Verification Toolkit (Android)"
+LABEL org.opencontainers.image.description="MVT is a forensic tool to look for signs of infection in smartphone devices."
+LABEL org.opencontainers.image.licenses="MVT License 1.1"
+LABEL org.opencontainers.image.base.name=docker.io/library/python:3.10.14-alpine3.20
+
+# Install runtime dependencies
+RUN apk add --no-cache \
+  android-tools \
+  git \
+  libusb \
+  openjdk11-jre-headless \
+  sqlite
+
+# Install mvt
+COPY ./ mvt
+RUN apk add --no-cache --virtual .build-deps gcc musl-dev \
+  && uv pip install --system --no-cache ./mvt \
+  && apk del .build-deps gcc musl-dev && rm -rf ./mvt
+
+# Installing ABE
+ADD --checksum=sha256:a20e07f8b2ea47620aff0267f230c3f1f495f097081fd709eec51cf2a2e11632 \
+  https://github.com/nelenkov/android-backup-extractor/releases/download/master-20221109063121-8fdfc5e/abe.jar /opt/abe/abe.jar
+# Create alias for abe
+RUN echo 'alias abe="java -jar /opt/abe/abe.jar"' >> ~/.bashrc
+
+# Generate adb key folder
+RUN echo 'if [ ! -f /root/.android/adbkey ]; then adb keygen /root/.android/adbkey > /dev/null 2>&1; fi' >> ~/.bashrc
+RUN mkdir /root/.android
+
+ENTRYPOINT [ "/usr/local/bin/mvt-android" ]

Dockerfile.ios

@@ -0,0 +1,138 @@
+# Base image for building libraries
+# ---------------------------------
+FROM ubuntu:22.04 AS build-base
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+# Install build tools and dependencies
+RUN apt-get update \
+  && apt-get install -y \
+  build-essential \
+  git \
+  autoconf \
+  automake \
+  libtool-bin \
+  pkg-config \
+  libcurl4-openssl-dev \
+  libusb-1.0-0-dev \
+  libssl-dev \
+  udev \
+  && rm -rf /var/lib/apt/lists/*
+
+
+# libplist
+# --------
+FROM build-base AS build-libplist
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libplist && cd libplist \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libplist
+
+
+# libimobiledevice-glue
+# ---------------------
+FROM build-base AS build-libimobiledevice-glue
+
+# Install dependencies
+COPY --from=build-libplist /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libimobiledevice-glue && cd libimobiledevice-glue \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libimobiledevice-glue
+
+
+# libtatsu
+# --------
+FROM build-base AS build-libtatsu
+
+# Install dependencies
+COPY --from=build-libplist /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libtatsu && cd libtatsu \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libtatsu
+
+
+# libusbmuxd
+# ----------
+FROM build-base AS build-libusbmuxd
+
+# Install dependencies
+COPY --from=build-libplist /build /
+COPY --from=build-libimobiledevice-glue /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libusbmuxd && cd libusbmuxd \
+  && ./autogen.sh && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libusbmuxd
+
+
+# libimobiledevice
+# ----------------
+FROM build-base AS build-libimobiledevice
+
+# Install dependencies
+COPY --from=build-libplist /build /
+COPY --from=build-libtatsu /build /
+COPY --from=build-libimobiledevice-glue /build /
+COPY --from=build-libusbmuxd /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/libimobiledevice && cd libimobiledevice \
+  && ./autogen.sh --enable-debug && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf libimobiledevice
+
+
+# usbmuxd
+# -------
+FROM build-base AS build-usbmuxd
+
+# Install dependencies
+COPY --from=build-libplist /build /
+COPY --from=build-libimobiledevice-glue /build /
+COPY --from=build-libusbmuxd /build /
+COPY --from=build-libimobiledevice /build /
+
+# Build
+RUN git clone https://github.com/libimobiledevice/usbmuxd && cd usbmuxd \
+  && ./autogen.sh --sysconfdir=/etc --localstatedir=/var --runstatedir=/run && make -j "$(nproc)" && make install DESTDIR=/build \
+  && cd .. && rm -rf usbmuxd && mv /build/lib /build/usr/lib
+
+
+# Main image
+# ----------
+FROM python:3.10.14-alpine3.20 AS main
+COPY --from=ghcr.io/astral-sh/uv:0.11.8 /uv /uvx /usr/local/bin/
+
+LABEL org.opencontainers.image.url="https://mvt.re"
+LABEL org.opencontainers.image.documentation="https://docs.mvt.re"
+LABEL org.opencontainers.image.source="https://github.com/mvt-project/mvt"
+LABEL org.opencontainers.image.title="Mobile Verification Toolkit (iOS)"
+LABEL org.opencontainers.image.description="MVT is a forensic tool to look for signs of infection in smartphone devices."
+LABEL org.opencontainers.image.licenses="MVT License 1.1"
+LABEL org.opencontainers.image.base.name=docker.io/library/python:3.10.14-alpine3.20
+
+# Install runtime dependencies
+RUN apk add --no-cache \
+  gcompat \
+  libcurl \
+  libssl3 \
+  libusb \
+  sqlite
+COPY --from=build-libplist /build /
+COPY --from=build-libimobiledevice-glue /build /
+COPY --from=build-libtatsu /build /
+COPY --from=build-libusbmuxd /build /
+COPY --from=build-libimobiledevice /build /
+COPY --from=build-usbmuxd /build /
+
+# Install mvt using the locally checked out source
+COPY ./ mvt
+RUN apk add --no-cache --virtual .build-deps git gcc musl-dev \
+  && uv pip install --system --no-cache ./mvt \
+  && apk del .build-deps git gcc musl-dev && rm -rf ./mvt
+
+ENTRYPOINT [ "/usr/local/bin/mvt-ios" ]

MANIFEST.in

@@ -0,0 +1,4 @@
+prune tests
+prune docs
+prune .github
+exclude uv.lock Dockerfile* mkdocs.yml .readthedocs.yaml .safety-policy.yml .python-version .gitignore Makefile

Makefile

@@ -1,16 +1,34 @@
 PWD = $(shell pwd)
+UV ?= uv
+
+check: ruff mypy
+
+ruff:
+	$(UV) run ruff check .
+
+mypy:
+	$(UV) run mypy
+
+test:
+	$(UV) run pytest
+
+test-ci:
+	$(UV) run pytest -v
+
+install:
+	$(UV) sync
+
+test-requirements:
+	$(UV) sync --group dev
+
+generate-proto-parsers:
+	# Generate python parsers for protobuf files
+	PROTO_FILES=$$(find src/mvt/android/parsers/proto/ -iname "*.proto"); \
+	$(UV) run protoc -Isrc/mvt/android/parsers/proto/ --python_betterproto2_out=src/mvt/android/parsers/proto/ $$PROTO_FILES
 
 clean:
-	rm -rf $(PWD)/build $(PWD)/dist $(PWD)/mvt.egg-info
+	rm -rf $(PWD)/build $(PWD)/dist $(PWD)/src/mvt.egg-info
 
 dist:
-	python3 setup.py sdist bdist_wheel
+	$(UV) build
 
-upload:
-	python3 -m twine upload dist/*
-
-test-upload:
-	python3 -m twine upload --repository testpypi dist/*
-
-pylint:
-	pylint --rcfile=setup.cfg mvt

README.md

@@ -4,32 +4,87 @@
 
 # Mobile Verification Toolkit
 
+> [!IMPORTANT]
+> We recently merged the "v3" branch. This introduced breaking changes. If you relied on mvt output in other scripts They might have broken. More details: https://github.com/mvt-project/mvt/issues/757
+
 [![](https://img.shields.io/pypi/v/mvt)](https://pypi.org/project/mvt/)
 [![Documentation Status](https://readthedocs.org/projects/mvt/badge/?version=latest)](https://docs.mvt.re/en/latest/?badge=latest)
-[![CI](https://github.com/mvt-project/mvt/actions/workflows/python-package.yml/badge.svg)](https://github.com/mvt-project/mvt/actions/workflows/python-package.yml)
+[![CI](https://github.com/mvt-project/mvt/actions/workflows/tests.yml/badge.svg)](https://github.com/mvt-project/mvt/actions/workflows/tests.yml)
 [![Downloads](https://pepy.tech/badge/mvt)](https://pepy.tech/project/mvt)
 
 Mobile Verification Toolkit (MVT) is a collection of utilities to simplify and automate the process of gathering forensic traces helpful to identify a potential compromise of Android and iOS devices.
 
-It has been developed and released by the [Amnesty International Security Lab](https://www.amnesty.org/en/tech/) in July 2021 in the context of the [Pegasus project](https://forbiddenstories.org/about-the-pegasus-project/) along with [a technical forensic methodology and forensic evidence](https://www.amnesty.org/en/latest/research/2021/07/forensic-methodology-report-how-to-catch-nso-groups-pegasus/).
+It has been developed and released by the [Amnesty International Security Lab](https://securitylab.amnesty.org) in July 2021 in the context of the [Pegasus Project](https://forbiddenstories.org/about-the-pegasus-project/) along with [a technical forensic methodology](https://www.amnesty.org/en/latest/research/2021/07/forensic-methodology-report-how-to-catch-nso-groups-pegasus/). It continues to be maintained by Amnesty International and other contributors.
 
-*Warning*: 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. This is not intended for end-user self-assessment. If you are concerned with the security of your device please seek expert assistance.
+> **Note**
+> MVT is a forensic research tool intended for technologists and investigators. It requires understanding digital forensics and using command-line tools. This is not intended for end-user self-assessment. If you are concerned with the security of your device please seek reputable expert assistance.
+>
 
+### Indicators of Compromise
+
+MVT supports using public [indicators of compromise (IOCs)](https://github.com/mvt-project/mvt-indicators) to scan mobile devices for potential traces of targeting or infection by known spyware campaigns. This includes IOCs published by [Amnesty International](https://github.com/AmnestyTech/investigations/) and other  research groups.
+
+> **Warning**
+> Public indicators of compromise are insufficient to determine that a device is "clean", and not targeted with a particular spyware tool. Reliance on public indicators alone can miss recent forensic traces and give a false sense of security.
+>
+> Reliable and comprehensive digital forensic support and triage requires access to non-public indicators, research and threat intelligence.
+>
+>Such support is available to civil society through [Amnesty International's Security Lab](https://securitylab.amnesty.org/get-help/?c=mvt_docs) or through our forensic partnership with [Access Now’s Digital Security Helpline](https://www.accessnow.org/help/).
+
+More information about using indicators of compromise with MVT is available in the [documentation](https://docs.mvt.re/en/latest/iocs/).
 
 ## Installation
 
-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/)):
+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 can also install MVT from PyPI with [uv](https://docs.astral.sh/uv/). First, install uv:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then install MVT as a command-line tool:
+
+```bash
+uv tool install mvt
+```
+
 For alternative installation options and known issues, please refer to the [documentation](https://docs.mvt.re/en/latest/install/) as well as [GitHub Issues](https://github.com/mvt-project/mvt/issues).
 
 
 ## Usage
 
-MVT provides two commands `mvt-ios` and `mvt-android`. [Check out the documentation to learn how to use them!](https://docs.mvt.re/)
+MVT provides three commands: `mvt-ios` and `mvt-android` analyse acquisitions from devices of that platform, and `mvt` hosts what belongs to neither: `version`, `completion`, `plugins` and `download-iocs` (`version` and `download-iocs` remain available on the platform commands for now). Running `mvt` on its own shows the installed version, update notices and the available commands. [Check out the documentation to learn how to use them!](https://docs.mvt.re/)
+
+Pass `--verbose` to any of the three commands, before the command name (`mvt-ios --verbose check-backup ...`), for debug output. The `--verbose` option the `check-*` commands accept after their name still works but is kept for compatibility only and will be removed in a future release.
+
+### Shell completion
+
+MVT can generate a shell completion script for Bash, Zsh, and Fish which covers `mvt`, `mvt-ios` and `mvt-android`:
+
+```bash
+mvt completion
+```
+
+The command prints setup instructions by default. To generate the completion script directly, pass the shell name:
+
+```bash
+mvt completion bash
+```
+
+MVT only writes completion files or shell configuration when `--install` is passed. See the [command completion documentation](https://docs.mvt.re/en/latest/command_completion/) for details.
+
+Plugin packages extend MVT with additional forensic modules, which run inside
+the `check-*` commands, and with top-level commands on `mvt`, `mvt-ios` and
+`mvt-android`. See the
+[development documentation](https://docs.mvt.re/en/latest/development/) for
+writing and installing them, and the
+[custom CLI command documentation](https://docs.mvt.re/en/latest/development/custom_commands/)
+for the entry points a package registers commands in.
 
 
 ## License

SECURITY.md

@@ -2,4 +2,61 @@
 
 Thank you for your interest in reporting security issues and vulnerabilities! Security research is of utmost importance and we take all reports seriously. If you discover an issue please report it to us right away!
 
-Please DO NOT file a public issue, instead send your report privately to *nex [at] nex [dot] sx*. You can also write PGP-encrypted emails to [this key](https://keybase.io/nex/pgp_keys.asc?fingerprint=05216f3b86848a303c2fe37dd166f1667359d880).
+Please DO NOT file a public issue, instead send your report privately to the MVT maintainers at Amnesty International via `security [at] amnesty [dot] tech`.
+
+You can also write PGP-encrypted emails to key `CFBF9698DCA8EB2A80F48ADEA035A030FA04ED13`. The corresponding PGP public key is lited below.
+
+```
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQINBGlFPwsBEADQ+d7SeHrFPYv3wPOjWs2oMpp0DPdfIyGbg+iYWOC36FegZhKY
++WeK96GqJWt8wD6kwFUVwQI795WZrjSd1q4a7wR+kj/h7xlRB6ZfVICA6O5DOOm6
+GNMvqy7ESm8g1XZDpb2u1BXmSS9X8f6rjB0e86kYsF1mB5/2USTM63jgDs0GGTkZ
+Q1z4Mq4gYyqH32b3gvXkbb68LeQmONUIM3cgmec9q8/pNc1l7fcoLWhOVADRj17Q
+plisa/EUf/SYqdtk9w7EHGggNenKNwVM235mkPcMqmE72bTpjT6XCxvZY3ByG5yi
+7L+tHJU45ZuXtt62EvX03azxThVfSmH/WbRk8lH8+CW8XMmiWZphG4ydPWqgVKCB
+2UOXm+6CQnKA+7Dt1AeK2t5ciATrv9LvwgSxk5WKc3288XFLA6eGMrTdQygYlLjJ
++42RSdK/7fCt/qk4q13oUw8ZTVcCia98uZFi704XuuYTH6NrntIB7j/0oucIS4Y9
+cTWNO5LBerez4v8VI4YHcYESPeIWGFkXhvJzo0VMg1zidBLtiPoGF2JKZGwaK7/p
+yY1xALskLp4H+5OY4eB1kf8kl4vGsEK8xA/NNzOiapVmwBXpvVvmXIQJE2k+olNf
+sAuyB8+aO1Ws7tFYt3D+olC7iaprOdK7uA4GCgmYYhq6QQPg+cxfczgHfwARAQAB
+tD1TZWN1cml0eSBMYWIgYXQgQW1uZXN0eSBJbnRlcm5hdGlvbmFsIDxzZWN1cml0
+eUBhbW5lc3R5LnRlY2g+iQJRBBMBCAA7FiEEz7+WmNyo6yqA9IreoDWgMPoE7RMF
+AmlFPwsCGwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AACgkQoDWgMPoE7RNr
+2w//a88uP90uSN6lgeIwKsHr1ri27QIBbzCV6hLN/gZBFR2uaiOn/xfFDbnR0Cjo
+5nMCJCT1k4nrPbMTlfmWLCD+YKELBzVqWlw4J2SOg3nznPl2JrL8QBKjwts0sF+h
+QbRWDsT54wBZnl6ZJJ79eLShNTokBbKnQ7071dMrENr5e2P2sClQXyiIc51ga4FM
+fHyhsx+GsrdiZNd2AH8912ljW1GuEi3epTO7KMZprmr37mjpZSUToiV59Yhl1Gbo
+2pixkYJqi62DG02/gTpCjq9NH3cEMxcxjh4E7yCA8ggLG6+IN6woIvPIdOsnQ+Yj
+d3H4rMNBjPSKoL+bdHILkCnp5HokcbVjNY3QAyOAF4qWhk4GtgpTshwxUmb4Tbay
+tWLJC2bzjuUBxLkGzMVFfU3B96sVS4Fi0sBaEMBtHskl2f45X8LJhSq//Lw/2L/8
+34uP/RxDSn+DPvj/yqMpekdCcmeFSTX1A19xkPcc0rVhMRde4VL338R86vzh0gMI
+1LySDAhXZyVWzrQ5s3n6N3EvCaHCn3qu7ieyFJifCSR7gZqevCEznMQRVpkMTzUt
+rk13Z6NOOb4IlTW7HFoY3omJG8Z5jV4kMIE7n6nb0qpNYQiG+YvjenQ3VrMoISyh
+lpS2De8+oOtwrxBVX3+qKWvQqzufeE3416kw2Z+5mxH7bx25Ag0EaUU/CwEQALyZ
+b+kwLN1yHObTm2yDBEn5HbCT3H1GremvPNmbAaTnfrjUngoKa8MuWWzbX5ptgmZR
+UpYY/ylOYcgGydz58vUNrPlhIZT9UhmiifPgZLEXyd0uFpr/NsbRajHMkK10iEZf
+h5bHNobiB7pGCu4Uj9e1cMiIZ4yEaYeyXYUoNHf6ISP39mJhHy6ov5yIpm9q0wzm
+tGUQPupxGXmEZlOPr3lxqXQ3Ekdv6cWDY5r/oOq71QJ/HUQ13QUuGFIbhnMbT8zd
+zaS6f/v772YKsWPc4NNUhtlf25VnQ4FuUtjCe3p6iYP4OVD8gJm0GvXyvyTuiQbL
+CSk/378JiNT7nZzYXxrWchMwvEoMIU55+/UaBc50HI5xvDQ858CX7PYGiimcdsO1
+EkQzhVxRfjlILfWrC2lgt+H5qhTn4Fah250Xe1PnLjXGHVUQnY/f3MFeiWQgf92b
+02+MfvOeC5OKttP1z5lcx6RFWCIa1E/u8Nj7YrH9hk0ZBRAnBaeAncDFY8dfX2zX
+VMoc0dV16gM7RrZ6i7D3CG3eLLkQlX0jbW9dzTuG/3f098EWB1p8vOfS/RbNCBRX
+jqGiqacL/aFF3Ci3nQ4O5tSv1XipbgrUhvXnwm9pxrLPS/45iaO59WN4RRGWLLQ7
+LHmeBxoa9avv0SdBYUL+eBxY46GXb/j5VLzHYhSnABEBAAGJAjYEGAEIACAWIQTP
+v5aY3KjrKoD0it6gNaAw+gTtEwUCaUU/CwIbDAAKCRCgNaAw+gTtEyvsEACnyFFD
+alOZTrrJTXNnUejuiExLh+qTO3T91p5bte597jpwCZnYGwkxEfffsqqhlY6ftEOf
+d5tNWE5isai4v8XCbplWomz4KBpepxcn2b+9o5dSyr1vohEFuCJziZDsta1J2DX5
+IE9U48kTgLDfdIBhuOyHNRkvXRHP2OVLCaiw4d9q+hlrraR8pehHt2BJSxh+QZoe
+n0iHvIZCBIUA45zLEGmXFpNTGeEf2dKPp3xOkAXOhAMPptE0V1itkF3R7kEW4aFO
+SZo8L3C1aWSz/gQ4/vvW5t1IJxirNMUgTMQFvqEkAwX3fm6GCxlgRSvTTRXdcrS8
+6qyFdH1nkCNsavPahN3N2RGGIlWtODEMTO1Hjy0kZtTYdW+JH9sendliCoJES+yN
+DjM125SgdAgrqlSYm/g8n9knWpxZv1QM6jU/sVz1J+l6/ixugL2i+CAL2d6uv4tT
+QmXnu7Ei4/2kHBUu3Lf59MNgmLHm6F7AhOWErszSeoJKsp+3yA1oTT/npz67sRzY
+VVyxz4NBIollna59a1lz0RhlWzNKqNB27jhylyM4ltdzHB7r4VMAVJyttozmIIOC
+35ucYxl5BHLuapaRSaYHdUId1LOccYyaOOFF/PSyCu9dKzXk7zEz2HNcIboWSkAE
+8ZDExMYM4WVpVCOj+frdsaBvzItHacRWuijtkw==
+=JAXX
+-----END PGP PUBLIC KEY BLOCK-----
+```

dev/mvt-android

@@ -1,14 +0,0 @@
-#!/usr/bin/env python3
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2022 Claudio Guarnieri.
-# 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
-
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-
-from mvt import android
-
-android.cli()

dev/mvt-ios

@@ -1,14 +0,0 @@
-#!/usr/bin/env python3
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2022 Claudio Guarnieri.
-# 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
-
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-
-from mvt import ios
-
-ios.cli()

docs/android/adb.md

@@ -1,42 +1,29 @@
-# Check over ADB
+# ADB Analysis Removed
 
-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.
+The ability to analyze Android devices directly over the [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb) has been removed from MVT.
 
-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:
+Use [AndroidQF](https://github.com/mvt-project/androidqf) to collect forensic artifacts from an Android device, then analyze the collected output with:
 
 ```bash
-mvt-android check-adb --output /path/to/results
+mvt-android check-androidqf /path/to/androidqf-output
 ```
 
-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:
+For a standalone Android bug report, use:
 
 ```bash
-adb tcpip 5555
+mvt-android check-bugreport /path/to/bugreport.zip
 ```
 
-Then you can specify the IP address of the phone with the adb port number to MVT like so:
+## Reasons for Removal
 
-```bash
-mvt-android check-adb --serial 192.168.1.20:5555 --output /path/to/results
-```
+1. **Inconsistent Data Collection Across Devices**
+   Android devices vary significantly in system architecture, security policy, and diagnostic log availability. This made it difficult to collect reliable forensic data across devices.
 
-Where `192.168.1.20` is the correct IP address of your device.
+2. **Incomplete Forensic Data Acquisition**
+   Direct ADB analysis did not retrieve a complete forensic snapshot. Critical artifacts such as full bug reports could be missing.
 
-## MVT modules requiring root privileges
+3. **Duplicated Analysis Paths**
+   Similar artifacts were parsed through separate ADB, AndroidQF, and bugreport modules, which made behavior harder to keep consistent.
 
-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!
+4. **Workflow Consistency**
+   MVT now focuses on analyzing acquired artifacts rather than interacting with live devices directly.

docs/android/backup.md

@@ -24,7 +24,7 @@ Some recent phones will enforce the utilisation of a password to encrypt the bac
 
 ## Unpack and check the backup
 
-MVT includes a partial implementation of the Android Backup parsing, because of the implementation difference in the compression algorithm between Java and Python. The `-nocompress` option passed to adb in the section above allows to avoid this issue. You can analyse and extract SMSs containing links from the backup directly with MVT:
+MVT includes a partial implementation of the Android Backup parsing, because of the implementation difference in the compression algorithm between Java and Python. The `-nocompress` option passed to adb in the section above allows to avoid this issue. You can analyse and extract SMSs from the backup directly with MVT:
 
 ```bash
 $ mvt-android check-backup --output /path/to/results/ /path/to/backup.ab
@@ -32,10 +32,14 @@ $ mvt-android check-backup --output /path/to/results/ /path/to/backup.ab
          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/000000_sms_backup
-         INFO     [mvt.android.modules.backup.sms] Extracted a total of 64 SMS messages containing links
+         INFO     [mvt.android.modules.backup.sms] Extracted a total of 64 SMS messages
 ```
 
-If the backup is encrypted, MVT will prompt you to enter the password.
+If the backup is encrypted, MVT will prompt you to enter the password. A backup password can also be provided with the `--backup-password` command line option or through the `MVT_ANDROID_BACKUP_PASSWORD` environment variable. The same options can also be used to when analysing an encrypted backup collected through AndroidQF in the `mvt-android check-androidqf` command:
+
+```bash
+$ mvt-android check-backup --backup-password "password123" --output /path/to/results/ /path/to/backup.ab
+```
 
 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.
 
@@ -52,4 +56,10 @@ 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.
 
-You can then extract SMSs containing links with MVT by passing the folder path as parameter instead of the `.ab` file: `mvt-android check-backup --output /path/to/results/ /path/to/backup/` (the path to backup given should be the folder containing the `apps` folder).
+You can then extract SMSs with MVT by passing the folder path as parameter instead of the `.ab` file: `mvt-android check-backup --output /path/to/results/ /path/to/backup/` (the path to backup given should be the folder containing the `apps` folder).
+
+When an output folder is specified, URLs extracted from SMS and MMS messages
+are also written to `urls.json`. Each entry contains the URL, its expanded
+destination when MVT resolved a shortened URL during indicator checking, the
+message timestamp, and the `sms` source. The same file is created by
+`check-androidqf` when its nested Android backup contains messages with URLs.

docs/android/download_apks.md

@@ -1,28 +0,0 @@
-# Downloading APKs from an Android phone
-
-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.
-
-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). While these lookups do not provide any conclusive assessment on all of the extracted APKs, they might highlight any known malicious ones:
-
-```bash
-MVT_VT_API_KEY=<key> mvt-android download-apks --output /path/to/folder --virustotal
-```
-
-Please note that in order to use VirusTotal lookups you are required to provide your own API key through the `MVT_VT_API_KEY` environment variable. You should also note that VirusTotal enforces strict API usage. Be mindful that MVT might consume your hourly search quota.
-
-In case you have a previous extraction of APKs you want to later check against VirusTotal, you can do so with the following arguments:
-
-```bash
-MVT_VT_API_KEY=<key> mvt-android download-apks --from-file /path/to/folder/apks.json --virustotal
-```

docs/android/intrusion_logs.md

@@ -0,0 +1,82 @@
+# Check Android Intrusion Logs
+
+Recent versions of Android can produce structured *Intrusion Logs* — newline-delimited JSON records derived from the platform's [SecurityLog API](https://developer.android.com/reference/android/app/admin/SecurityLog). Intrusion Logging is offered as a new option under Android's **Advanced Protection Mode**, which users can opt into on their device; no MDM or device-policy configuration is required. When enabled, these logs provide a high-fidelity record of process starts, DNS queries, outbound network connections, ADB activity, keyguard events, and other security-relevant operations. The initial Intrusion Logging feature was released for Android 16 in May 2026. The feature and supported events is likely to be expanded over time.
+
+For background on how this data source was introduced and why it is forensically valuable, see the Amnesty International Security Lab announcement: [Android Intrusion Logging as a new source of data for consensual forensic analysis](https://securitylab.amnesty.org/latest/2026/05/android-intrusion-logging-as-a-new-source-of-data-for-consensual-forensic-analysis/).
+
+## Recommended workflow: collect with AndroidQF
+
+[AndroidQF](https://github.com/mvt-project/androidqf) is the recommended way to acquire data from an Android device for analysis with MVT. During acquisition AndroidQF will prompt the user to also collect intrusion logs from the device, and writes them into an `intrusion-logs/` subdirectory of the acquisition output.
+
+When you analyse such an acquisition with `mvt-android check-androidqf`, MVT automatically detects the `intrusion-logs/` directory and runs the same intrusion-log checks described below — there is no need to invoke a separate command:
+
+```bash
+mvt-android check-androidqf --output /path/to/results/ /path/to/androidqf-output/
+```
+
+The device timezone is read from the AndroidQF acquisition (`getprop.txt`) and applied to event timestamps automatically.
+
+## Standalone command: `check-intrusion-logs`
+
+The `mvt-android check-intrusion-logs` command runs the intrusion-log analysis directly against a set of log files. Prefer the AndroidQF workflow above; use the standalone command when the intrusion logs were collected outside of an AndroidQF acquisition, or when re-analysing only a set of intrusion logs.
+
+## Expected input
+
+`check-intrusion-logs` accepts either:
+
+- a **directory** containing one or more `.txt` files (recursively), or
+- a **`.zip` archive** containing such `.txt` files (nested `.zip` archives are also walked).
+
+Each `.txt` file is expected to contain newline-delimited JSON, with one JSON object per line. Each object wraps a single event under a top-level key indicating its type, for example:
+
+```json
+{"dns_event": {"event_time": 1746979200000, "hostname": "example.com", "ip_addresses": ["93.184.216.34"], "package_name": "com.example.app"}}
+{"connect_event": {"event_time": 1746979201000, "ip_address": "93.184.216.34", "port": 443, "package_name": "com.example.app"}}
+{"security_event": {"event_time": 1746979202000, "tag": 210005, "data": ["..."]}}
+```
+
+Identical events that appear across multiple overlapping log files (e.g. daily rotations) are de-duplicated on a first-seen basis.
+
+## Running the analysis
+
+```bash
+mvt-android check-intrusion-logs --output /path/to/results/ /path/to/intrusion-logs/
+```
+
+A `.zip` archive can be passed directly in place of the directory:
+
+```bash
+mvt-android check-intrusion-logs --output /path/to/results/ /path/to/intrusion-logs.zip
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `-i, --iocs PATH` | Path to a STIX2 indicator file. May be passed multiple times. |
+| `-o, --output PATH` | Directory where JSON results and the timeline CSV will be written. |
+| `-l, --list-modules` | List the available intrusion-log modules and exit. |
+| `-m, --module NAME` | Run a single module (e.g. `DnsEvent`) instead of all of them. |
+| `-t, --timezone TZ` | IANA timezone name for the device (e.g. `Europe/Paris`). When set, event timestamps are converted to the device's local time instead of UTC. |
+| `-v, --verbose` | Verbose logging. Kept for compatibility and to be removed in a future release: pass `--verbose` to `mvt-android` itself instead. |
+
+## Modules
+
+The command runs the following modules over the parsed events:
+
+- **`DnsEvent`** — DNS resolution events. Hostnames and resolved IP addresses are checked against domain indicators, and the requesting `package_name` is checked against app-identifier indicators.
+- **`ConnectEvent`** — Outbound network connection events. Destination IPs (with localhost addresses skipped) are checked against domain indicators, and `package_name` is checked against app-identifier indicators.
+- **`SecurityEvent`** — Security log events keyed by Android `SecurityLog` tag IDs (e.g. `app_process_start`, `adb_shell_cmd`, `keyguard_dismissed`, `os_startup`, `cert_*` events). These are surfaced in the timeline to help reconstruct device activity around suspected events.
+
+All three modules share a single pre-parsing pass over the input, so adding more modules in the future does not multiply I/O cost. Additional modules will be added in the future to support new event types which are generated by the Intrusion Logging feature.
+
+## Interpreting results
+
+A successful IOC match raises a `CRITICAL` alert that includes the matched indicator, the offending event, and the event timestamp. Alerts are summarised at the end of the run and persisted alongside the per-module JSON results.
+
+When `--timezone` is provided, timestamps in the timeline and JSON output reflect the device's local wall-clock time. Otherwise timestamps are in UTC, consistent with the rest of MVT.
+
+## Limitations
+
+- This page assumes the intrusion logs have already been collected from the device. The recommended collection path is via AndroidQF (see above); intrusion logging itself must have been enabled on the device beforehand by opting into Android's Advanced Protection mode and also enabling the optional Intrusion Logging feature (see the [Amnesty blog post](https://securitylab.amnesty.org/latest/2026/05/android-intrusion-logging-as-a-new-source-of-data-for-consensual-forensic-analysis/) for details).
+- As with all IOC-based analysis, public indicators alone are not sufficient to conclude that a device is uncompromised. See the [Indicators of Compromise](../iocs.md) page for context.

docs/android/methodology.md

@@ -1,23 +1,75 @@
 # Methodology for Android forensic
 
-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.
+Unfortunately Android devices provide fewer complete forensically useful datasources than their iOS cousins. Unlike iOS, the Android backup feature only provides a limited about of relevant data.
+
+Android diagnostic logs such as *bugreport files* can be inconsistent in format and structure across different Android versions and device  vendors. The limited diagnostic information available makes it difficult to triage potential compromises, and because of this `mvt-android` capabilities are limited as well.
 
 However, not all is lost.
 
-## Check installed Apps
+## Check Android devices with AndroidQF and MVT
 
-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.
+The [AndroidQF](https://github.com/mvt-project/androidqf) tool can be used to collect a wide range of forensic artifacts from an Android device including an Android backup, a bugreport file, and a range of system logs. MVT natively supports analyzing the generated AndroidQF output for signs of device compromise.
 
-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 look them up on services such as [VirusTotal](https://www.virustotal.com).
+### Why Use AndroidQF?
 
-!!! info "Using VirusTotal"
-	Please note that in order to use VirusTotal lookups you are required to provide your own API key through the `MVT_VT_API_KEY` environment variable. You should also note that VirusTotal enforces strict API usage. Be mindful that MVT might consume your hourly search quota.
+- **Complete and raw data extraction**
+  AndroidQF collects full forensic artifacts using an on-device forensic collection agent, ensuring that no crucial data is overlooked. The data collection does not depended on the shell environment or utilities available on the device.
 
-## Check the device over Android Debug Bridge
+- **Consistent and standardized output**
+  By collecting a predefined and complete set of forensic files, AndroidQF ensures consistency in data acquisition across different Android devices.
 
-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.
+- **Future-proof analysis**
+  Since the full forensic artifacts are preserved, analysts can extract new evidence or apply updated analysis techniques without requiring access to the original device.
 
+- **Cross-platform tool without dependencies**
+  AndroidQF is a standalone Go binary which can be used to remotely collect data from an Android device without the device owner needing to install MVT or a Python environment.
+
+### Workflow for Android Forensic Analysis with AndroidQF
+
+With AndroidQF the analysis process is split into a separate data collection and data analysis stages.
+
+1. **Extract Data Using AndroidQF**
+  Deploy the AndroidQF forensic collector to acquire all relevant forensic artifacts from the Android device.
+
+2. **Analyze Extracted Data with MVT**
+  Use the `mvt-android check-androidqf` command to perform forensic analysis on the extracted artifacts.
+
+By separating artifact collection from forensic analysis, this approach ensures a more reliable and scalable methodology for Android forensic investigations.
+
+For more information, refer to the [AndroidQF project documentation](https://github.com/mvt-project/androidqf).
+
+### VirusTotal package lookups
+
+AndroidQF records APK file hashes in `packages.json`. MVT can optionally look up non-system APK hashes on VirusTotal while checking an AndroidQF acquisition:
+
+```bash
+MVT_VT_API_KEY=<key> mvt-android check-androidqf --virustotal /path/to/androidqf-output
+```
+
+The `--virustotal` option is disabled by default because it sends APK hashes to VirusTotal and requires network access. It uses the `VT_API_KEY` MVT configuration value, which can also be provided through the `MVT_VT_API_KEY` environment variable.
+
+To avoid exhausting free VirusTotal API quotas, MVT waits 16 seconds between package hash requests by default. Use `--delay` to change the delay, or `--delay 0` to disable throttling:
+
+```bash
+mvt-android check-androidqf --virustotal --delay 30 /path/to/androidqf-output
+```
+
+## Android Intrusion Logs
+
+On devices where the user has opted into Android's [**Advanced Protection Mode**](https://support.google.com/android/answer/16339980) and turned on the optional Intrusion Logging featrue, Android can create and archive structured *Intrusion Logs* in an encrypted format. These logs record DNS queries, outbound network connections, process starts, ADB activity and other security-relevant events, and are a high-fidelity complement to the rest of an AndroidQF acquisition. The logs are generated on-device and encrypted before being stored in the Google account associated with the device. The encryption key is protected by the user device PIN. The intrusion log data is not accessible to Google.
+
+AndroidQF will prompt the user to download, decrypt and collect device intrusion logs as part of an acquisition. When they are present, `mvt-android check-androidqf` will automatically run the intrusion-log checks alongside the other AndroidQF modules — no extra command is required. This is the recommended workflow for Android forensic analysis with MVT.
+
+For cases where intrusion logs were collected outside of an AndroidQF acquisition, the standalone `mvt-android check-intrusion-logs` command can analyse them directly. See [Check Android Intrusion Logs](intrusion_logs.md) for details, and the [feature announcment from Amnesty International's Security Lab](https://securitylab.amnesty.org/latest/2026/05/android-intrusion-logging-as-a-new-source-of-data-for-consensual-forensic-analysis/) for background on the data source.
+
+## Android Debug Bridge analysis removed
+
+The ability to analyze Android devices directly over ADB has been removed from MVT. Direct extraction of data from ADB was error-prone and frequently resulted in inconsistent data collection between ADB and AndroidQF acquisitions. Use AndroidQF for device acquisition and `mvt-android check-androidqf` for analysis.
 
 ## 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.
+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.
+
+The `mvt-android check-androidqf` command will automatically check an Android backup and SMS messages if an SMS backup is included in the AndroidQF extraction.
+
+The  `mvt-android check-backup` command can also be used directly with an Android backup file.

docs/command_completion.md

@@ -0,0 +1,66 @@
+# Command Completion
+
+MVT utilizes the [Click](https://click.palletsprojects.com/en/stable/) library for creating its command line interface.
+
+Click provides tab completion support for Bash (version 4.4 and up), Zsh, and Fish.
+
+To enable it, you need to register a completion script with your shell, which varies depending on the shell you are using.
+
+`mvt completion` generates one script which covers `mvt`, `mvt-ios` and `mvt-android`. The following describes how to generate that script and add it to your shell configuration.
+
+> **Note: You will need to start a new shell for the changes to take effect.**
+
+### For Bash
+
+```bash
+# Generate the bash completion script
+mvt completion bash > ~/.mvt-complete.bash
+```
+
+Add the following to `~/.bashrc`:
+```bash
+# source the mvt completion script
+[ -f ~/.mvt-complete.bash ] && . ~/.mvt-complete.bash
+```
+
+### For Zsh
+
+```bash
+# Generate the zsh completion script
+mvt completion zsh > ~/.mvt-complete.zsh
+```
+
+Add the following to `~/.zshrc`:
+```bash
+# source the mvt completion script
+[ -f ~/.mvt-complete.zsh ] && . ~/.mvt-complete.zsh
+```
+
+### For Fish
+
+```bash
+# Generate the fish completion script
+mkdir -p ~/.config/fish/conf.d
+mvt completion fish > ~/.config/fish/conf.d/mvt-completion.fish
+```
+
+Fish loads the files in `~/.config/fish/conf.d` automatically.
+
+### Automatic Installation
+
+MVT can write the completion file and update the relevant shell configuration for Bash and Zsh when you pass `--install`:
+
+```bash
+mvt completion bash --install
+```
+
+Replace `bash` with `zsh` or `fish` as needed. For Fish, `--install` writes the completion file into `~/.config/fish/conf.d` and changes no shell configuration.
+
+!!! note
+
+    Earlier versions generated one script per command, with `mvt-ios completion`
+    and `mvt-android completion`. Files written by them keep working. When you
+    switch to the single script, remove the old files and the lines which load
+    them from your shell configuration.
+
+For more information, visit the official [Click Docs](https://click.palletsprojects.com/en/stable/shell-completion/#enabling-completion).

docs/development/custom_commands.md

@@ -0,0 +1,202 @@
+# Custom CLI Commands
+
+MVT can load additional top-level commands into `mvt`, `mvt-ios` and
+`mvt-android`. A command package chooses which of the three each of its
+commands is added to.
+Custom commands are different from [custom forensic modules](index.md#custom-modules):
+commands add new CLI operations, while modules add analysis steps to existing
+`check-*` commands.
+
+!!! warning
+
+    Custom commands run as trusted Python code inside the MVT process. Install
+    or load commands only from sources you trust. MVT does not sandbox
+    third-party commands, and the MVT maintainers do not maintain them.
+
+## Install a Command Package
+
+Python packages can register a Click command or group on one or more of the MVT CLIs.
+A minimal package can expose this command from `my_mvt_plugin.py`:
+
+```python
+import click
+
+
+@click.command()
+@click.argument("path", type=click.Path(exists=True))
+def summarize(path):
+    """Summarize an acquisition."""
+    click.echo(f"Summarizing {path}")
+```
+
+Log through `get_plugin_logger(__name__)` from `mvt.plugin`. Records logged
+through `logging.getLogger(__name__)` do not reach `command.log`, and MVT's
+console handler does not show them.
+
+Register the object in the package's `pyproject.toml`. The entry-point name is
+the command users invoke:
+
+```toml
+[project.entry-points."mvt.ios.cli_plugins"]
+summarize = "my_mvt_plugin:summarize"
+
+[project.entry-points."mvt.android.cli_plugins"]
+summarize = "my_mvt_plugin:summarize"
+```
+
+Each entry-point group adds the command to one CLI: `mvt.ios.cli_plugins` to
+`mvt-ios`, `mvt.android.cli_plugins` to `mvt-android` and `mvt.cli_plugins` to
+`mvt`. Register the command in the group of every CLI which should offer it: a
+platform-specific command belongs in one platform group, and a command which
+handles acquisitions of both platforms, as above, in both. After installing the
+package in the same environment as MVT, the command appears directly in those
+CLIs:
+
+```bash
+mvt-ios summarize ./ios-backup
+mvt-android summarize ./androidqf-output
+```
+
+For a `pipx` installation of MVT, inject the plugin into MVT's environment:
+
+```bash
+pipx inject mvt my-mvt-plugin
+```
+
+When MVT is installed in an active virtual environment, install the plugin with
+`pip` in that environment. `mvt plugins list` shows the installed packages and
+the commands they add, see [Managing Plugins](plugins.md).
+
+Command packages that need their own settings, such as an API key, should store
+them in a namespaced [plugin configuration file](plugin_configuration.md)
+rather than in MVT's own `config.yaml`.
+
+### Commands on `mvt`
+
+A MVT plugin command can also add sub-commands to the base `mvt` command. This can be used for commands which are not tied to a particular forensic platform:
+
+```toml
+[project.entry-points."mvt.cli_plugins"]
+my-plugin = "my_mvt_plugin:my_plugin"
+```
+
+Commands in this group are added to `mvt` only, so this one is invoked as
+`mvt my-plugin`. A command on `mvt` has nothing but its name to say which
+plugin it belongs to, so name it after the plugin, and make it a Click group
+when the plugin has several operations to offer, such as
+`mvt my-plugin configure`.
+
+## Developing a Command Locally
+
+A package is how a command is distributed. While a command is being written,
+MVT can load it straight from its file instead, so the package need not be
+reinstalled after every change; an editable install of the package does the
+same through its entry points. Create a Python file that exports one Click
+command or group named `cli`:
+
+```python
+import click
+
+
+@click.command("case-summary")
+@click.argument("path", type=click.Path(exists=True))
+def cli(path):
+    """Summarize a case directory."""
+    click.echo(f"Summarizing {path}")
+```
+
+Pass the file before the custom command name:
+
+```bash
+mvt-ios --load-command ./case_summary.py case-summary ./ios-backup
+```
+
+`--load-command` can be repeated and also accepts a folder. MVT loads
+non-hidden top-level `*.py` files in sorted order and skips `__init__.py`.
+Every loaded file must export one `cli` object.
+
+To load a file or folder on every invocation, set the environment variable of
+the CLI the commands belong on. Like the entry-point groups, each variable adds
+its commands to one CLI only:
+
+```bash
+export MVT_CUSTOM_COMMANDS=./commands
+export MVT_IOS_CUSTOM_COMMANDS=./ios_commands
+export MVT_ANDROID_CUSTOM_COMMANDS=./android_commands
+```
+
+## Building a Module-Running Command
+
+A command which runs forensic modules over an acquisition subclasses `Command`.
+`Command` creates the output folder and writes `command.log`. It orders the
+modules, resolves their dependencies and runs them. It writes the result files,
+`alerts.json` and `info.json`. The subclass sets `platform`, `name` and
+`modules`:
+
+```python
+from mvt.plugin import Command, MVTModule, convert_unix_to_iso, get_plugin_logger
+
+log = get_plugin_logger(__name__)
+
+
+class APKManifest(MVTModule):
+    supported_commands = (("android", "check-apks"),)
+
+    def run(self):
+        self.results = [{"checked_at": convert_unix_to_iso(0)}]
+
+
+class CmdCheckAPKs(Command):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.platform = "android"
+        self.name = "check-apks"
+        self.modules = [APKManifest]
+```
+
+`platform` and `name` are the pair the modules declare in
+`supported_commands`. `modules` lists the module classes the command runs,
+imported directly. A command which runs modules of another plugin depends on
+that package in `pyproject.toml` and imports them the same way. `init()`,
+`module_init(module)` and `finish()` are optional hooks. `run()` calls them
+before the run, before each module and after the run.
+
+Wrap the command in a Click command with an `--output` option. Run it, then
+print the alert summary:
+
+```python
+import click
+
+
+@click.command("check-apks")
+@click.option("--output", "-o", type=click.Path(exists=False))
+@click.argument("TARGET_PATH", type=click.Path(exists=True))
+def cli(output, target_path):
+    cmd = CmdCheckAPKs(target_path=target_path, results_path=output)
+    log.info("Checking APK files at path: %s", target_path)
+    cmd.run()
+    cmd.show_alerts_brief()
+```
+
+The `--verbose` option of `mvt`, `mvt-ios` and `mvt-android` applies to the
+command. The command defines no `--verbose` option of its own. The pair a
+plugin command adds is not listed anywhere in MVT. Name it in the plugin's
+README.
+
+## Naming and Errors
+
+Built-in MVT commands cannot be replaced. External command names must also be
+unique on each CLI; when installed packages or environment paths collide, MVT
+keeps the first command and logs a warning. The environment path of a CLI is
+registered before its installed packages, so a command loaded from there wins a
+collision with a package. A collision from an explicit `--load-command` is a
+usage error.
+
+A package entry point or environment command that cannot be imported appears
+as a marked broken command without preventing other MVT commands from working.
+Invoke that command to see its package or file source and the underlying error.
+An invalid command supplied explicitly with `--load-command` fails immediately
+with a usage error.
+
+Installed command packages use the entry-point name as the CLI command name.
+The entry point must resolve to a `click.Command` or `click.Group`.

docs/development/index.md

@@ -0,0 +1,391 @@
+# Development
+
+The Mobile Verification Toolkit team welcomes contributions of new forensic modules or other contributions which help improve the software.
+
+## Local environment
+
+MVT uses `uv` for dependency management. To install the project and development dependencies from the locked environment, run:
+
+```bash
+make install
+```
+
+## Testing
+
+MVT uses `pytest` for unit and integration tests. Code style consistency is maintained with `ruff` and `mypy`. All can
+be run automatically with:
+
+```bash
+make check
+```
+
+Run these tests before making new commits or opening pull requests.
+
+## Module dependencies
+
+Modules can require other modules to run first by declaring their classes in
+`dependencies`. The command runner uses a stable topological ordering, so the
+existing module list order is preserved wherever dependency constraints allow.
+
+```python
+class DependentModule(MVTModule):
+    dependencies = (PrerequisiteModule,)
+
+    def run(self):
+        prerequisite_results = self.get_dependency_results(PrerequisiteModule)
+```
+
+Selecting a single module also runs its transitive dependencies.
+
+A module can only depend on modules the command it runs in also has. When a
+declared dependency is not among them, the command logs a warning naming the
+module and the missing dependency, skips that module and everything depending
+on it, and runs the rest of the analysis. Selecting such a module with
+`--module` therefore leaves nothing to run, which the warning explains.
+
+A cycle in the dependency graph is a programming error rather than a
+configuration problem: the command logs a warning and runs no modules at all.
+
+## Custom modules
+
+MVT's module-running `check-*` commands can run forensic modules which are not
+part of MVT. Custom modules are distributed as plugin packages. A Python
+package installed next to MVT registers its modules through an entry point.
+The modules then load automatically in every command they support, see
+[Installed module packages](#installed-module-packages). `mvt plugins list`
+shows the installed packages and where each one was installed from.
+
+MVT can also load module files by path, with `--load-module` and
+`MVT_CUSTOM_MODULES`, see
+[Developing modules locally](#developing-modules-locally). This can be used
+while writing a module. Use a Python package to distribute one.
+
+A custom module declares in `supported_commands` the platform and command
+pairs it runs in. A module with empty `supported_commands` does not run and
+MVT logs a warning. The nine pairs are:
+
+```python
+("ios", "check-backup")
+("ios", "check-fs")
+("ios", "check-iocs")
+("ios", "check-sysdiagnose")
+("android", "check-backup")
+("android", "check-bugreport")
+("android", "check-androidqf")
+("android", "check-intrusion-logs")
+("android", "check-iocs")
+```
+
+`check-iocs` re-checks stored results rather than an acquisition. It matches
+every `<slug>.json` file in the results folder to the module with that slug.
+It then runs that module's `check_indicators()` again. A module which
+implements `check_indicators()` is included in `check-iocs` for its platform.
+It does not need to declare the `check-iocs` pair.
+
+### Writing a module
+
+A module subclasses `MVTModule` or one of the base classes below and
+implements `run()`. `check_indicators()` and `serialize()` are optional. The
+first matches results against IOCs or detections. The second returns timeline
+records.
+
+```python
+from mvt.plugin import IOSExtraction, convert_unix_to_iso
+
+
+class ExampleCustomModule(IOSExtraction):
+    supported_commands = (
+        ("ios", "check-backup"),
+        ("ios", "check-fs"),
+    )
+    slug = "example_custom_module"
+
+    def run(self):
+        self.results = [{"checked_at": convert_unix_to_iso(0)}]
+
+    def check_indicators(self):
+        pass
+
+    def serialize(self, result):
+        return None
+```
+
+The base classes are:
+
+- `MVTModule`: the base of every module. It provides `self.results`,
+  `self.alertstore`, `self.log`, `self.indicators` and
+  `get_dependency_results()`. Subclass it directly for a module which reads
+  only the results of other modules.
+- `IOSExtraction`: `("ios", "check-backup")` and `("ios", "check-fs")`. Adds
+  `_find_ios_database()`, which locates a module's database in a backup or in
+  a filesystem dump and repairs it if it is malformed. Adds
+  `_get_backup_files_from_manifest()`, `_get_backup_file_from_id()` and
+  `_get_fs_files_from_patterns()`. Adds `_open_sqlite_db()`, which opens a
+  database read-only.
+- `SysdiagnoseExtraction`: `("ios", "check-sysdiagnose")`. MVT extracts the
+  archive and calls `from_sysdiagnose_folder()` before `run()`. The module
+  reads files with `_get_files_by_pattern()` and `_get_file_content()`.
+  `ips_files` lists the crash reports. See
+  [Check an iOS Sysdiagnose](../ios/sysdiagnose.md).
+- `AndroidQFModule`: `("android", "check-androidqf")`. MVT calls `from_dir()`
+  or `from_zip()` with the file list of the acquisition. The module reads
+  files with `_get_files_by_pattern()` and `_get_file_content()`.
+  `_get_device_timezone()` returns the device timezone.
+- `AndroidBackupModule`: `("android", "check-backup")`. MVT calls `from_dir()`
+  or `from_ab()`. The module reads files with `_get_files_by_pattern()` and
+  `_get_file_content()`.
+- `BugReportModule`: `("android", "check-bugreport")`. MVT calls `from_dir()`
+  or `from_zip()`. The module reads files with `_get_files_by_pattern()`,
+  `_get_files_by_patterns()` and `_get_file_content()`.
+  `_get_dumpstate_file()` returns the dumpstate file, and
+  `_get_file_modification_time()` the modification time of a file.
+
+The underscore-named helpers are internal to the base classes. Plugin modules
+can call them. Their names and signatures can change between releases. Read
+the base class in `src/mvt/ios/modules` or `src/mvt/android/modules` before
+relying on one.
+
+### Depending on a built-in module
+
+A module which post-processes records generated by one or more built-in MVT
+modules must declare the source modules in `dependencies`. It reads their
+results with `get_dependency_results()`. Import the class from its family
+package: `mvt.ios.modules.backup`, `mvt.ios.modules.fs`,
+`mvt.ios.modules.mixed`, `mvt.android.modules.androidqf`,
+`mvt.android.modules.backup`, `mvt.android.modules.bugreport` or
+`mvt.android.modules.intrusion_logs`.
+
+```python
+from mvt.ios.modules.backup import Manifest
+from mvt.plugin import MVTModule
+
+
+class DependentCustomModule(MVTModule):
+    supported_commands = (("ios", "check-backup"),)
+    dependencies = (Manifest,)
+
+    def run(self):
+        manifest_results = self.get_dependency_results(Manifest)
+        self.results = [{"manifest_entries": len(manifest_results)}]
+```
+
+Dependencies are ordered as for the built-in modules, with custom modules
+appended after the built-ins, see [Module dependencies](#module-dependencies).
+A dependency has to run in every command the module supports. Where it does
+not, MVT skips the module with a warning.
+
+`get_dependency_results()` returns the plain dictionaries the module produced.
+They are the same records it writes to `<slug>.json`. Typed results per module
+are planned.
+
+### Replacing a built-in module
+
+A custom module which extends a built-in one runs alongside it, and when the
+two share a slug they write to the same results file. MVT warns about that
+collision, naming both modules, where each came from and the file the later one
+overwrites, but it runs them both. Set `replaces` to the class the module
+supersedes to take that module's place instead: when both are available to a
+command, the named module is dropped from the run.
+
+```python
+from mvt.ios.modules.backup import Manifest as BuiltinManifest
+
+
+class Manifest(BuiltinManifest):
+    supported_commands = (("ios", "check-backup"),)
+    replaces = BuiltinManifest
+```
+
+Keeping the class name of the replaced module, as above, keeps the name
+`--module` selects the module by and the slug its results file is named after.
+A replacement with a different class name writes to a file named after its own
+slug, unless it sets `slug` to the slug of the module it replaces, and
+`--module` still selects it by the name of the replaced module, which MVT logs.
+Taking over the slug of a replaced module is not a collision and is not warned
+about, because that module is no longer part of the run.
+
+Modules which depend on the replaced module receive the replacement instead, so
+`get_dependency_results(BuiltinManifest)` returns the replacement's results. A
+module must not depend on the module it replaces: that module does not run, so
+the replacement has to produce the data itself, and MVT logs a warning when a
+module declares both.
+
+A replacement takes on the obligations of the module it replaces. If it
+declares a dependency the command does not provide, it is skipped like any
+other module with an unavailable dependency, and the module it replaced stays
+out of the run: neither of them produces results, and the modules depending on
+the replaced module are skipped as well.
+
+Subclassing the replaced module is not required, but a replacement which is not
+a subclass is logged with a warning, because its results may not be what the
+modules depending on the replaced module expect. Naming a module the command
+does not run has no effect, and modules which replace each other in a cycle all
+keep running and replace nothing. Every applied substitution is logged, so it
+is recorded in `command.log` when the command runs with an `--output` folder.
+
+Every command resolves replacements on its own. `check-iocs` matches stored
+results files against the slugs of the modules available for that command. A
+replacement which subclasses the module it replaces inherits its
+`check_indicators()`. It is then part of `check-iocs` for its platform and
+re-checks the results file named after its slug. A replacement with no
+`check_indicators()` is not part of `check-iocs`. The built-in module it
+replaced re-checks the file. `check-iocs` matches `--module` on the class name
+only. Pass a differently named replacement's own name there, not the name of
+the module it replaces.
+
+### Importing from MVT
+
+Import from `mvt.plugin` if it has what you need. The names it exports are
+kept working on a best-effort basis. A change to one of them is announced in
+the release notes. Anything else in `mvt` can be imported too, but may change
+between releases without notice. The plugin interface is best effort.
+
+`mvt.plugin` exports the base classes above and `Command`, `Alert` and
+`AlertLevel`, the result types, `DatabaseNotFoundError` and
+`DatabaseCorruptedError`, the timestamp converters, the settings API of
+[Plugin Configuration](plugin_configuration.md), MVT's own `settings`,
+`get_plugin_logger()` and `MVT_VERSION`. `src/mvt/plugin.py` holds the list.
+Read MVT's `settings` for values such as `NETWORK_ACCESS_ALLOWED` and
+`NETWORK_TIMEOUT`. Plugin values go in the plugin's own settings file.
+
+## Installed module packages
+
+Python packages can register modules so they load automatically in every
+module-running `check-*` command, without `--load-module` or
+`MVT_CUSTOM_MODULES`. Register an entry point in the `mvt.modules` group in
+the package's `pyproject.toml`:
+
+```toml
+[project.entry-points."mvt.modules"]
+mvt-plugin-example-org = "mvt_plugin_example_org:get_modules"
+```
+
+The entry point must resolve to an iterable of `MVTModule` subclasses, or to
+a callable returning one:
+
+```python
+from mvt.plugin import MVTModule
+
+
+class PackagedModule(MVTModule):
+    supported_commands = (("ios", "check-backup"),)
+
+    def run(self):
+        self.results = [{"message": "packaged module ran"}]
+
+
+def get_modules() -> list[type[MVTModule]]:
+    return [PackagedModule]
+```
+
+`get_modules()` is the package's module list, written by hand. A package which
+keeps its modules in separate files imports each class there and lists it. A
+module missing from the list does not load.
+
+Installed modules follow the same rules as other custom modules: each module
+must declare `supported_commands`, and dependencies are resolved with the
+standard ordering logic. A broken entry point is skipped with a warning and
+does not prevent MVT from running. As with custom commands, installed module
+packages run as trusted code inside the MVT process, so install only packages
+from sources you trust.
+
+For a `pipx` installation of MVT, inject the package into MVT's environment:
+
+```bash
+pipx inject mvt mvt-plugin-example-org
+```
+
+Module packages that need their own settings, such as an API key, should store
+them in a namespaced [plugin configuration file](plugin_configuration.md)
+rather than in MVT's own `config.yaml`.
+
+### Naming module packages
+
+Name module packages `mvt-plugin-<name>` (import package `mvt_plugin_<name>`),
+and include the name of the publishing organization or author so packages from
+different groups do not collide: for example, an organisation's custom modules
+would be distributed as `mvt-plugin-example-org` with the import package
+`mvt_plugin_example_org`.
+
+The prefix makes module packages easy to find on PyPI and keeps their import
+names from clashing with unrelated Python packages. It is a convention, not a
+technical requirement: modules load through the `mvt.modules` entry point
+regardless of what the package is called, and existing packages with other
+names keep working. Note that the prefix is also not a mark of authenticity —
+anyone can publish a package with any available name, so vet a module package
+and its publisher before installing it, whatever it is called.
+
+### Module logging
+
+Modules log through `self.log`, and MVT names the logger for where the module
+came from. MVT's own modules log under their dotted path (for example
+`mvt.ios.modules.mixed.whatsapp`). Everything external is namespaced under
+`mvt.ext` to keep it visually distinct from built-in modules and isolated from
+MVT's internal logger tree:
+
+- Installed packages log under `mvt.ext.<package>`, with the `mvt_plugin_`
+  prefix stripped: modules in `mvt_plugin_example_org` log as
+  `mvt.ext.example_org.*`.
+- Files loaded with `--load-module` or `MVT_CUSTOM_MODULES` log as
+  `mvt.ext.<file name>`.
+
+Outside a module class, for example in a custom command line handler, log
+through `get_plugin_logger(__name__)`. It returns a logger in the same
+namespace.
+
+## Developing modules locally
+
+While a module is being written, load it from its file. `--load-module` takes a
+Python file, or a folder of them, on every module-running command, and can be
+repeated:
+
+```bash
+mvt-ios check-backup --load-module ./example_module.py --output ./out ./backup
+```
+
+For a folder, MVT loads its non-hidden top-level `*.py` files in sorted order
+and skips `__init__.py`. `MVT_CUSTOM_MODULES` names a folder to load on every
+module-running command, before any `--load-module` path:
+
+```bash
+MVT_CUSTOM_MODULES=./custom_modules mvt-android check-bugreport ./bugreport.zip
+```
+
+Files loaded this way follow the same rules as packaged modules.
+`--list-modules` reports them with the SHA-256 hash of the file in place of a
+version. An editable install of the package (`pip install -e .`) also works:
+the modules load through the entry point, and `mvt plugins list` shows the
+package with the `local` origin.
+
+Loading by path is for development. Move a module into a package once it
+works.
+
+## Auditing loaded modules
+
+Because installed module packages load automatically, MVT records where every
+module came from:
+
+- `--list-modules` groups the available modules by source: MVT itself
+  (with its version), each installed package (with its version and, when
+  installed directly from a repository, the commit), and each file loaded
+  with `--load-module` or `MVT_CUSTOM_MODULES` (with the SHA-256 hash of the
+  file).
+- When a command runs with an `--output` folder, the `command.log` file
+  records one line per module source with the source's version or hash and
+  the list of modules loaded from it.
+- `mvt plugins list` lists the installed packages, where each of them
+  was installed from and how many modules it contributes, see
+  [Managing Plugins](plugins.md).
+
+## Profiling
+
+Some MVT modules extract and process significant amounts of data during the analysis process or while checking results against known indicators. Care must be
+take to avoid inefficient code paths as we add new modules.
+
+MVT modules can be profiled with Python built-in `cProfile` by setting the `MVT_PROFILE` environment variable.
+
+```bash
+MVT_PROFILE=1 dev/mvt-ios check-backup test_backup
+```
+
+Open an issue or PR if you are encountering significant performance issues when analyzing a device with MVT.

docs/development/plugin_configuration.md

@@ -0,0 +1,157 @@
+# Plugin Configuration
+
+Plugin packages that add [custom CLI commands](custom_commands.md) or
+[modules](index.md#installed-module-packages) often need to store their
+own settings, such as an API key, a server URL or the timestamp of the last
+synchronization. MVT provides a namespaced settings base class so each plugin
+keeps its configuration in its own file, and a data folder for anything else a
+plugin needs to keep on disk.
+
+!!! warning
+
+    Do not write plugin settings to MVT's own `config.yaml`. MVT rewrites that
+    file with the settings it knows about every time it starts, so any other
+    section is deleted.
+
+## Where Settings Are Stored
+
+Each plugin gets one YAML file in a `plugins` folder next to MVT's own
+configuration:
+
+```
+~/.config/mvt/plugins/<plugin name>.yaml
+```
+
+The exact parent folder follows the platform convention used for MVT's
+`config.yaml` (for example `~/Library/Application Support/mvt` on macOS). Use
+`plugin_config_path()` from `mvt.plugin` instead of building the path by hand.
+
+Plugin names must be lowercase and may only contain letters, digits and dashes,
+matching the `mvt-plugin-<name>` package naming convention. MVT creates the
+`plugins` folder with `0700` permissions and writes the settings files with
+`0600` permissions, because they commonly hold credentials. Files are written
+through a temporary file and moved into place, so an interrupted save never
+leaves a partially written settings file behind.
+
+## Plugin Data Folder
+
+Everything else a plugin keeps on disk, such as a cache, a downloaded artifact
+or synchronization state, belongs in the folder returned by the `data_folder()`
+class method of the plugin's settings class, or by `plugin_data_folder()` from
+`mvt.plugin`, called with the plugin name if the plugin has no settings class:
+
+```
+~/.local/share/mvt/plugin-data/<plugin name>/                # Linux
+~/Library/Application Support/mvt/plugin-data/<plugin name>/ # macOS
+```
+
+The folder sits beside MVT's own data, such as the downloaded indicators. It is
+created if it is missing, with `0700` permissions. Asking for it again returns
+the same path and leaves the contents alone, so a plugin can ask for it every
+time it needs the folder. `ExamplePluginSettings` below is the settings class
+defined in the next section:
+
+```python
+import os
+
+
+def cache_path() -> str:
+    folder = ExamplePluginSettings.data_folder()
+    return os.path.join(folder, "virustotal_lookups_cache.json")
+```
+
+A plugin which has no settings class calls
+`plugin_data_folder("example-plugin")` instead.
+
+Do not fall back on a path of your own such as `~/.cache/example-plugin`: it
+is a Linux-only convention, and MVT will not create it for you.
+
+## Defining Plugin Settings
+
+Subclass `MVTPluginSettings`, set `plugin_name` and declare typed fields with
+defaults:
+
+```python
+from typing import Optional
+
+from mvt.plugin import MVTPluginSettings
+
+
+class ExamplePluginSettings(MVTPluginSettings):
+    plugin_name = "example-plugin"
+
+    API_KEY: Optional[str] = None
+    MAX_RESULTS: int = 25
+    LAST_SYNC: Optional[str] = None
+```
+
+`load()` returns the current settings and `save()` writes them back:
+
+```python
+from datetime import datetime, timezone
+
+import click
+
+from mvt.plugin import plugin_env_prefix
+
+
+def sync():
+    settings = ExamplePluginSettings.load()
+    if not settings.API_KEY:
+        prefix = plugin_env_prefix(settings.plugin_name)
+        raise click.ClickException(
+            f"No API key configured. Set {prefix}API_KEY or "
+            "run 'example-plugin configure'."
+        )
+
+    settings.LAST_SYNC = datetime.now(timezone.utc).isoformat()
+    settings.save()
+```
+
+The message builds the variable name with `plugin_env_prefix()`, see
+[Environment Variables](#environment-variables).
+
+A missing settings file is not an error: the plugin then runs on the field
+defaults and on whatever the environment provides. `save()` only persists the
+values that differ from the defaults, and it never touches MVT's `config.yaml`.
+A settings file that cannot be parsed, or that does not hold a mapping of
+setting names to values, raises a `PluginConfigLoadError` naming the file.
+
+Every subclass that sets its own `plugin_name` gets its own file and its own
+environment namespace. A subclass that does not redefine `plugin_name` inherits
+it, and therefore shares the file and the environment variables of its parent
+class.
+
+## Environment Variables
+
+Every field can also be set with an environment variable. The prefix is
+`MVT_PLUGIN_`, followed by the plugin name upper-cased with dashes replaced by
+underscores, followed by the field name. For the example above:
+
+```bash
+export MVT_PLUGIN_EXAMPLE_PLUGIN_API_KEY=...
+export MVT_PLUGIN_EXAMPLE_PLUGIN_MAX_RESULTS=50
+```
+
+Do not repeat the plugin name in a field name: a plugin named `example-scanner`
+with a `SCANNER_API_KEY` field asks the user for
+`MVT_PLUGIN_EXAMPLE_SCANNER_SCANNER_API_KEY`. Name the field `API_KEY`.
+
+Settings resolve in this order, from highest to lowest priority:
+
+1. Arguments passed to the settings class directly, such as
+   `ExamplePluginSettings(API_KEY="...")`
+2. Environment variables
+3. The plugin's YAML file
+4. The field defaults declared on the settings class
+
+!!! tip
+
+    On shared or multi-user machines, prefer passing API keys through
+    environment variables rather than saving them to the plugin file. `save()`
+    skips every value that the environment currently supplies, so a credential
+    provided that way is not copied into the settings file when a plugin saves
+    an unrelated setting.
+
+Unknown keys in a plugin's YAML file are ignored, so a settings file written by
+a newer version of a plugin does not break an older one.

docs/development/plugins.md

@@ -0,0 +1,116 @@
+# Managing Plugins
+
+Plugin packages extend MVT with additional
+[forensic modules](index.md#custom-modules) and
+[CLI commands](custom_commands.md). Because installed packages load
+automatically, `mvt plugins` audits what is installed and checks whether
+updates are available. The command lives on `mvt` only, although the packages
+it lists extend `mvt-ios` and `mvt-android` too.
+
+## List Installed Plugins
+
+```bash
+mvt plugins list
+```
+
+```
+                        Installed MVT plugins
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┓
+┃ Name                ┃ Version ┃ Origin       ┃ Modules ┃ Commands  ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━┩
+│ mvt-plugin-example  │ 1.2.0   │ pypi         │       4 │ summarize │
+│ mvt-plugin-research │ 0.1.0   │ git+3f9a1c7d │       2 │ -         │
+│ mvt-plugin-local    │ 0.0.1   │ local        │       1 │ triage    │
+└─────────────────────┴─────────┴──────────────┴─────────┴───────────┘
+```
+
+The origin records where each package was installed from: `pypi` for a package
+installed from a package index, `git+<commit>` for a package installed directly
+from a repository, and `local` for a package installed from a local folder or
+archive rather than from an index, including an editable development install.
+The last two columns show how many forensic modules the package contributes and
+which CLI commands it adds.
+
+A plugin whose modules cannot be imported is listed with `error` in the
+`Modules` column rather than breaking the listing.
+
+## Check for Updates
+
+```bash
+mvt plugins check-updates
+```
+
+```
+Plugin updates available:
+  mvt-plugin-example  1.2.0 → 1.3.0
+    Upgrade with: pip install -U mvt-plugin-example
+
+MVT does not install plugin updates. Run the command above when you decide to
+upgrade.
+```
+
+Packages installed from a package index are compared against the latest release
+published for them. A package which was never published, for example a plugin
+distributed only within an organization, is skipped silently.
+
+!!! note
+
+    Packages shown with the `pypi` origin are compared against
+    [PyPI](https://pypi.org), whichever index they were installed from. A
+    plugin installed from a private index under a name which also exists on
+    PyPI is therefore compared against the unrelated public package of that
+    name. Give plugins published to a private index a name which is not taken
+    on PyPI, and treat an unexpected update suggestion as a reason to check
+    where the package would come from.
+
+!!! warning
+
+    MVT never installs or upgrades a plugin itself, it only prints the command
+    which does. Upgrading a plugin in the middle of an investigation changes
+    the modules producing the results, and a plugin runs as trusted code inside
+    the MVT process, so pulling in a new version is a decision for the analyst
+    to make deliberately and not a side effect of running a check.
+
+## Automatic Update Checks
+
+MVT also reports available plugin updates in the banner printed when a command
+starts:
+
+```
+        MVT - Mobile Verification Toolkit
+
+        https://mvt.re
+        Version: 2026.7.29
+
+        Plugin updates available:
+          mvt-plugin-example  1.2.0 → 1.3.0   (pip install -U mvt-plugin-example)
+```
+
+This check runs at most once every 12 hours. In between checks MVT prints the
+findings of the latest check without contacting anything, so a plugin update
+stays visible without a lookup on every command. The
+`mvt plugins check-updates` command checks immediately, regardless of when the
+last check happened.
+
+The automatic check is skipped when the `--disable-update-check` option is
+used, when `NETWORK_ACCESS_ALLOWED` is disabled in the MVT configuration, and
+when no plugins are installed.
+
+## Plugins Installed From a Repository
+
+A plugin installed with `pip install "mvt-plugin-example @ git+<url>"` is
+checked by asking the remote repository which commit the installed revision
+points at now. MVT runs git and ssh in batch mode, so a repository which needs
+credentials MVT does not already have fails the check instead of prompting for
+them. The check is skipped silently when git is not available, when the
+repository cannot be reached, and when access to it is denied.
+
+How the plugin was installed decides what an update means:
+
+- A plugin installed from a branch is reported as outdated when the branch has
+  moved past the installed commit.
+- A plugin installed from a specific commit or a tag is pinned. It is never
+  reported as outdated, however far the branch it came from moves on.
+
+Pinning a plugin to a commit or a tag is therefore the way to keep the modules
+used across an investigation stable.

docs/docker.md

@@ -2,7 +2,22 @@ Using Docker simplifies having all the required dependencies and tools (includin
 
 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:
+Once Docker is installed, you can run MVT by downloading a prebuilt MVT Docker image, or by building a Docker image yourself from the MVT source repo.
+
+### Using the prebuilt Docker image
+
+```bash
+docker pull ghcr.io/mvt-project/mvt
+```
+
+You can then run the Docker container with:
+
+```
+docker run -it ghcr.io/mvt-project/mvt
+```
+
+
+### Build and run Docker image from source
 
 ```bash
 git clone https://github.com/mvt-project/mvt.git
@@ -18,16 +33,16 @@ 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:
+## Access an iOS device from Docker
+
+On the Linux host, install and start [usbmuxd](https://github.com/libimobiledevice/usbmuxd), then connect and unlock the iOS device. The daemon exposes the device through the `/var/run/usbmuxd` socket.
+
+Bind that socket into the container to let MVT communicate with the device:
 
 ```bash
-docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb mvt
+docker run -it \
+    --mount type=bind,source=/var/run/usbmuxd,target=/var/run/usbmuxd \
+    ghcr.io/mvt-project/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/<your_usb_port> mvt
-```
+If you built the image from source, replace `ghcr.io/mvt-project/mvt` with `mvt`. 

docs/index.md

@@ -6,7 +6,10 @@
 
 Mobile Verification Toolkit (MVT) is a tool to facilitate the [consensual forensic analysis](introduction.md#consensual-forensics) of Android and iOS devices, for the purpose of identifying traces of compromise.
 
-In this documentation you will find instructions on how to install and run the `mvt-ios` and `mvt-android` commands, and guidance on how to interpret the extracted results.
+It has been developed and released by the [Amnesty International Security Lab](https://securitylab.amnesty.org) in July 2021 in the context of the [Pegasus Project](https://forbiddenstories.org/about-the-pegasus-project/) along with [a technical forensic methodology](https://www.amnesty.org/en/latest/research/2021/07/forensic-methodology-report-how-to-catch-nso-groups-pegasus/). It continues to be maintained by Amnesty International and other contributors.
+
+
+In this documentation you will find instructions on how to install and run the `mvt-ios`, `mvt-android` and `mvt` commands, and guidance on how to interpret the extracted results.
 
 ## Resources
 

docs/install.md

@@ -1,17 +1,33 @@
 # 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.10 or newer to run. While it should be available on most operating systems, please make sure of that before proceeding.
 
 ## Dependencies on Linux
 
 First install some basic dependencies that will be necessary to build all required tools:
 
 ```bash
-sudo apt install python3 python3-pip libusb-1.0-0 sqlite3
+sudo apt install python3 python3-venv python3-pip sqlite3 libusb-1.0-0
 ```
 
 *libusb-1.0-0* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
 
+(Recommended) Set up `pipx`
+
+For Ubuntu 23.04 or above:
+```bash
+sudo apt install pipx
+pipx ensurepath
+```
+
+For Ubuntu 22.04 or below:
+```
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+Other distributions: check for a `pipx` or `python-pipx` via your package manager.
+
 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.
 
 ## Dependencies on macOS
@@ -21,7 +37,7 @@ Running MVT on macOS requires Xcode and [homebrew](https://brew.sh) to be instal
 In order to install dependencies use:
 
 ```bash
-brew install python3 libusb sqlite3
+brew install python3 pipx libusb sqlite3
 ```
 
 *libusb* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
@@ -42,24 +58,47 @@ It is recommended to try installing and running MVT from [Windows Subsystem Linu
 
 ## 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`:
+### Installing from PyPI with pipx (recommended)
+1. Install `pipx` following the instructions above for your OS/distribution. Make sure to run `pipx ensurepath` and open a new terminal window.
+2. ```bash
+   pipx install mvt
+   ```
 
+You now should have the `mvt`, `mvt-ios` and `mvt-android` utilities installed. If you run into problems with these commands not being found, ensure you have run `pipx ensurepath` and opened a new terminal window.
+
+### Installing from PyPI directly into a virtual environment
+You can use `pipenv`, `poetry` etc. for your virtual environment, but the provided example is with the built-in `venv` tool:
+
+1. Create the virtual environment in a folder in the current directory named `env`:
 ```bash
-export PATH=$PATH:~/.local/bin
+python3 -m venv env
 ```
 
-Then you can install MVT directly from [pypi](https://pypi.org/project/mvt/)
-
+2. Activate the virtual environment:
 ```bash
-pip3 install mvt
+source env/bin/activate
 ```
 
-Or from the source code:
-
+3. Install `mvt` into the virtual environment:
 ```bash
-git clone https://github.com/mvt-project/mvt.git
-cd mvt
-pip3 install .
+pip install mvt
 ```
 
-You now should have the `mvt-ios` and `mvt-android` utilities installed.
+The `mvt`, `mvt-ios` and `mvt-android` utilities should now be available as commands whenever the virtual environment is active.
+
+### Installing from git source with pipx
+If you want to have the latest features in development, you can install MVT directly from the source code in git.
+
+```bash
+pipx install --force git+https://github.com/mvt-project/mvt.git
+```
+
+You now should have the `mvt`, `mvt-ios` and `mvt-android` utilities installed.
+
+**Notes:**
+1. The `--force` flag is necessary to force the reinstallation of the package.
+2. To revert to using a PyPI version, it will be necessary to `pipx uninstall mvt` first.
+
+## Setting up command completions
+
+See ["Command completions"](command_completion.md)

docs/introduction.md

@@ -12,6 +12,20 @@ Mobile Verification Toolkit (MVT) is a collection of utilities designed to facil
 
 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.
 
+## Indicators of Compromise
+
+MVT supports using [indicators of compromise (IOCs)](https://github.com/mvt-project/mvt-indicators) to scan mobile devices for potential traces of targeting or infection by known spyware campaigns. This includes IOCs published by [Amnesty International](https://github.com/AmnestyTech/investigations/) and other research groups.
+
+!!! warning
+    Public indicators of compromise are insufficient to determine that a device is "clean", and not targeted with a particular spyware tool. Reliance on public indicators alone can miss recent forensic traces and give a false sense of security.
+
+    Reliable and comprehensive digital forensic support and triage requires access to non-public indicators, research and threat intelligence.
+
+    Such support is available to civil society through [Amnesty International's Security Lab](https://securitylab.amnesty.org/get-help/?c=mvt_docs) or [Access Now’s Digital Security Helpline](https://www.accessnow.org/help/).
+
+More information about using indicators of compromise with MVT is available in the [documentation](iocs.md).
+
+
 ## 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

@@ -34,13 +34,44 @@ It is also possible to load STIX2 files automatically from the environment varia
 export MVT_STIX2="/home/user/IOC1.stix2:/home/user/IOC2.stix2"
 ```
 
+## Network Access
+
+When checking URL indicators, MVT follows recognized shortened URLs with an
+HTTP `HEAD` request. URL checks are deduplicated and run concurrently, with at
+most 20 requests in progress at a time. Redirects within an individual URL
+chain are still followed sequentially. The following environment variables
+control these requests:
+
+- `MVT_NETWORK_ACCESS_ALLOWED` enables or disables network requests. It defaults
+  to `true`. Set it to `false` to prevent MVT from attempting to resolve
+  shortened URLs.
+- `MVT_NETWORK_TIMEOUT` sets the request timeout in seconds. It defaults to
+  `15`.
+
+For example, to run IOC checks without resolving shortened URLs:
+
+```bash
+MVT_NETWORK_ACCESS_ALLOWED=false mvt-ios check-iocs \
+    --iocs ~/iocs/malware.stix2 /path/to/iphone/output/
+```
+
+## STIX2 Support
+
+So far MVT implements only a subset of [STIX2 specifications](https://docs.oasis-open.org/cti/stix/v2.1/csprd01/stix-v2.1-csprd01.html):
+
+* It only supports checks for one value (such as `[domain-name:value='DOMAIN']`) and not boolean expressions over multiple comparisons
+* It only supports the following types: `domain-name:value`, `process:name`, `email-addr:value`, `file:name`, `file:path`, `file:hashes.md5`, `file:hashes.sha1`, `file:hashes.sha256`, `app:id`, `configuration-profile:id`, `android-property:name`, `url:value` (but each type will only be checked by a module if it is relevant to the type of data obtained)
+
 ## 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://raw.githubusercontent.com/AmnestyTech/investigations/master/2021-12-16_cytrox/cytrox.stix2))
+    - [An Android Spyware Campaign Linked to a Mercenary Company](https://github.com/AmnestyTech/investigations/tree/master/2023-03-29_android_campaign) ([STIX2](https://github.com/AmnestyTech/investigations/blob/master/2023-03-29_android_campaign/malware.stix2))
 - [This repository](https://github.com/Te-k/stalkerware-indicators) contains IOCs for Android stalkerware including [a STIX MVT-compatible file](https://raw.githubusercontent.com/Te-k/stalkerware-indicators/master/generated/stalkerware.stix2).
+- We are also maintaining [a list of IOCs](https://github.com/mvt-project/mvt-indicators) in STIX format from public spyware campaigns.
 
-You can automaticallly download the latest public indicator files with the command `mvt-ios download-iocs` or `mvt-android download-iocs`. These commands download the list of indicators listed [here](https://github.com/mvt-project/mvt/blob/main/public_indicators.json) and store them in the [appdir](https://pypi.org/project/appdirs/) folder. They are then loaded automatically by MVT.
+You can automatically download the latest public indicator files with the command `mvt download-iocs`. The per-platform forms `mvt-ios download-iocs` and `mvt-android download-iocs` do the same thing. These commands download the list of indicators from the [mvt-indicators](https://github.com/mvt-project/mvt-indicators/blob/main/indicators.yaml) repository and store them in the [appdir](https://pypi.org/project/appdirs/) folder. They are then loaded automatically by MVT.
 
 Please [open an issue](https://github.com/mvt-project/mvt/issues/) to suggest new sources of STIX-formatted IOCs.
+

docs/ios/backup/itunes.md

@@ -10,7 +10,7 @@ To do that:
 4. 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.
 5. Start the backup and wait for it to finish (this may take up to 30 minutes).
 
-![](../../../img/macos-backup.jpg)
+![](../../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 macOS, the backup is stored in `~/Library/Application Support/MobileSync/`.
@@ -25,13 +25,13 @@ On more recent MacOS versions, this feature is included in Finder. To do a backu
 4. In the General tab, select `Back up all the data on your iPhone to this Mac` from the options under the Backups section.
 5. Check the box that says `Encrypt local backup`. If it is your first time selecting this option, you may need to enter a password to encrypt the backup.
 
-![](../../../img/macos-backup2.png)
+![](../../img/macos-backup2.png)
 _Source: [Apple Support](https://support.apple.com/en-us/HT211229)_
 
 6. Click `Back Up Now` to start the back-up process.
 7. The encrypted backup for your iPhone should now start. Once the process finishes, you can check the backup by opening `Finder`, clicking on the `General` tab, then click on `Manage Backups`. Now you should see a list of your backups like the image below:
 
-![](../../../img/macos-backups.png)
+![](../../img/macos-backups.png)
 _Source: [Apple Support](https://support.apple.com/en-us/HT211229)_
 
 If your backup has a lock next to it like in the image above, then the backup is encrypted. You should also see the date and time when the encrypted backup was created. The backup files are stored in `~/Library/Application Support/MobileSync/`.

docs/ios/install.md

@@ -45,10 +45,10 @@ Once the idevice tools are available you can check if everything works fine by c
 ideviceinfo
 ```
 
-This should some many details on the connected iOS device. If you are connecting the device to your laptop for the first time, it will require to unlock and enter the PIN code on the mobile device. If it complains that no device is connected and the mobile device is indeed plugged in through the USB cable, you might need to do this first, although typically the pairing is automatically done when connecting the device:
+This should show many details on the connected iOS device. If you are connecting the device to your laptop for the first time, it will require to unlock and enter the PIN code on the mobile device. If it complains that no device is connected and the mobile device is indeed plugged in through the USB cable, you might need to do this first, although typically the pairing is automatically done when connecting the device:
 
 ```bash
-sudo usbmuxd -f -d
+sudo usbmuxd -f -v
 idevicepair pair
 ```
 

docs/ios/records.md

@@ -7,7 +7,7 @@ In this page you can find a (reasonably) up-to-date breakdown of the files creat
 ### `analytics.json`
 
 !!! info "Availability"
-    Backup (if encrypted): :material-close:  
+    Backup (if encrypted): :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `Analytics` module. The module extracts records from the plists inside the SQLite databases located at *private/var/Keychains/Analytics/\*.db*, which contain various analytics information regarding networking, certificate-pinning, TLS, etc. failures.
@@ -16,10 +16,22 @@ If indicators are provided through the command-line, processes and domains are c
 
 ---
 
+### `applications.json`
+
+!!! info "Availability"
+    Backup: :material-check:
+    Full filesystem dump: :material-check:
+
+This JSON file is created by mvt-ios' `Applications` module. The module extracts the list of applications installed on the device from the `Info.plist` file in backup, or from the `iTunesMetadata.plist` files in a file system dump. These records contains detailed information on the source and installation of the app.
+
+If indicators are provided through the command-line, processes and application ids are checked against the app name of each application. It also flags any applications not installed from the AppStore. Any matches are stored in *applications_detected.json*.
+
+---
+
 ### `backup_info.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-close:
 
 This JSON file is created by mvt-ios' `BackupInfo` module. The module extracts some details about the backup and the device, such as name, phone number, IMEI, product type and version.
@@ -29,7 +41,7 @@ This JSON file is created by mvt-ios' `BackupInfo` module. The module extracts s
 ### `cache_files.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `CacheFiles` module. The module extracts records from all SQLite database files stored on disk with the name *Cache.db*. These databases typically contain data from iOS' [internal URL caching](https://developer.apple.com/documentation/foundation/nsurlcache). Through this module you might be able to recover records of HTTP requests and responses performed my applications as well as system services, that would otherwise be unavailable. For example, you might see HTTP requests part of an exploitation chain performed by an iOS service attempting to download a first stage malicious payload.
@@ -38,10 +50,22 @@ If indicators are provided through the command-line, they are checked against th
 
 ---
 
+### `calendar.json`
+
+!!! info "Availability"
+    Backup: :material-check:
+    Full filesystem dump: :material-check:
+
+This JSON file is created by mvt-ios' `Calendar` module. This module extracts all CalendarItems from the `Calendar.sqlitedb` database. This database contains all calendar entries from the different calendars installed on the phone.
+
+If indicators are provided through the command-line, email addresses are checked against the inviter's email of the different events. Any matches are stored in *calendar_detected.json*.
+
+---
+
 ### `calls.json`
 
 !!! info "Availability"
-    Backup (if encrypted): :material-check:  
+    Backup (if encrypted): :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `Calls` module. The module extracts records from a SQLite database located at */private/var/mobile/Library/CallHistoryDB/CallHistory.storedata*, which contains records of incoming and outgoing calls, including from messaging apps such as WhatsApp or Skype.
@@ -51,7 +75,7 @@ This JSON file is created by mvt-ios' `Calls` module. The module extracts record
 ### `chrome_favicon.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `ChromeFavicon` module. The module extracts records from a SQLite database located at */private/var/mobile/Containers/Data/Application/\*/Library/Application Support/Google/Chrome/Default/Favicons*, which contains a mapping of favicons' URLs and the visited URLs which loaded them.
@@ -63,7 +87,7 @@ If indicators are provided through the command-line, they are checked against bo
 ### `chrome_history.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `ChromeHistory` module. The module extracts records from a SQLite database located at */private/var/mobile/Containers/Data/Application/\*/Library/Application Support/Google/Chrome/Default/History*, which contains a history of URL visits.
@@ -75,7 +99,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `configuration_profiles.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-close:
 
 This JSON file is created by mvt-ios' `ConfigurationProfiles` module. The module extracts details about iOS configuration profiles that have been installed on the device. These should include both default iOS as well as third-party profiles.
@@ -87,7 +111,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `contacts.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `Contacts` module. The module extracts records from a SQLite database located at */private/var/mobile/Library/AddressBook/AddressBook.sqlitedb*, which contains records from the phone's address book. While this database obviously would not contain any malicious indicators per se, you might want to use it to compare records from other apps (such as iMessage, SMS, etc.) to filter those originating from unknown origins.
@@ -97,7 +121,7 @@ This JSON file is created by mvt-ios' `Contacts` module. The module extracts rec
 ### `firefox_favicon.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `FirefoxFavicon` module. The module extracts records from a SQLite database located at */private/var/mobile/profile.profile/browser.db*, which contains a mapping of favicons' URLs and the visited URLs which loaded them.
@@ -109,7 +133,7 @@ If indicators are provided through the command-line, they are checked against bo
 ### `firefox_history.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `FirefoxHistory` module. The module extracts records from a SQLite database located at */private/var/mobile/profile.profile/browser.db*, which contains a history of URL visits.
@@ -118,10 +142,20 @@ If indicators are provided through the command-line, they are checked against th
 
 ---
 
+### `global_preferences.json`
+
+!!! info "Availability"
+    Backup: :material-check:
+    Full filesystem dump: :material-check:
+
+This JSON file is created by mvt-ios' `GlobalPreferences` module. The module extracts records from a Plist file located at */private/var/mobile/Library/Preferences/.GlobalPreferences.plist*, which contains a system preferences including if Lockdown Mode is enabled.
+
+---
+
 ### `id_status_cache.json`
 
 !!! info "Availability"
-    Backup (before iOS 14.7): :material-check:  
+    Backup (before iOS 14.7): :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `IDStatusCache` module. The module extracts records from a plist file located at */private/var/mobile/Library/Preferences/com.apple.identityservices.idstatuscache.plist*, which contains a cache of Apple user ID authentication. This chance will indicate when apps like Facetime and iMessage first established contacts with other registered Apple IDs. This is significant because it might contain traces of malicious accounts involved in exploitation of those apps.
@@ -133,7 +167,7 @@ Starting from iOS 14.7.0, this file is empty or absent.
 ### `shortcuts.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `Shortcuts` module. The module extracts records from an SQLite database located at */private/var/mobile/Library/Shortcuts/Shortcuts.sqlite*, which contains records about the Shortcuts application. Shortcuts are a built-in iOS feature which allows users to automation certain actions on their device. In some cases the legitimate Shortcuts app may be abused by spyware to maintain persistence on an infected devices.
@@ -143,7 +177,7 @@ This JSON file is created by mvt-ios' `Shortcuts` module. The module extracts re
 ### `interaction_c.json`
 
 !!! info "Availability"
-    Backup (if encrypted): :material-check:  
+    Backup (if encrypted): :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `InteractionC` module. The module extracts records from a SQLite database located at */private/var/mobile/Library/CoreDuet/People/interactionC.db*, which contains details about user interactions with installed apps.
@@ -153,7 +187,7 @@ This JSON file is created by mvt-ios' `InteractionC` module. The module extracts
 ### `locationd_clients.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `LocationdClients` module. The module extracts records from a plist file located at */private/var/mobile/Library/Caches/locationd/clients.plist*, which contains a cache of apps which requested access to location services.
@@ -163,19 +197,23 @@ This JSON file is created by mvt-ios' `LocationdClients` module. The module extr
 ### `manifest.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-close:
 
 This JSON file is created by mvt-ios' `Manifest` module. The module extracts records from the SQLite database *Manifest.db* contained in iTunes backups, and which indexes the locally backed-up files to the original paths on the iOS device.
 
 If indicators are provided through the command-line, they are checked against the original relative path in case. In some cases, there might be records of files created containing a domain name in their name, for example in the case of browser cache folders. Any matches are stored in *manifest_detected.json*.
 
+An incomplete backup still lists in its manifest the files it failed to acquire. Those records carry a `"missing": true` field, and the module reports how many of them it found. Use it to tell a module which returned nothing because the artifact was not acquired apart from one which found nothing on a device that never had it.
+
+Files must be stored at their expected paths inside the backup folder. If the module cannot finish listing the backup files, it logs a warning and skips the missing-file check; the manifest metadata is still extracted.
+
 ---
 
 ### `os_analytics_ad_daily.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `OSAnalyticsADDaily` module. The module extracts records from a plist located *private/var/mobile/Library/Preferences/com.apple.osanalytics.addaily.plist*, which contains a history of data usage by processes running on the system. Besides the network statistics, these records are particularly important because they might show traces of malicious process executions and the relevant timeframe.
@@ -187,7 +225,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `datausage.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `Datausage` module. The module extracts records from a SQLite database located */private/var/wireless/Library/Databases/DataUsage.sqlite*, which contains a history of network data usage by processes running on the system. It does not log network traffic through WiFi (the fields `WIFI_IN` and `WIFI_OUT` are always empty), and the `WWAN_IN` and `WWAN_OUT` fields are stored in bytes. Besides the network statistics, these records are particularly important because they might show traces of malicious process executions and the relevant timeframe. In particular, processes which do not have a valid bundle ID might require particular attention.
@@ -199,7 +237,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `netusage.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `Netusage` module. The module extracts records from a SQLite database located */private/var/networkd/netusage.sqlite*, which contains a history of data usage by processes running on the system. Besides the network statistics, these records are particularly important because they might show traces of malicious process executions and the relevant timeframe. In particular, processes which do not have a valid bundle ID might require particular attention.
@@ -211,7 +249,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `profile_events.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-close:
 
 This JSON file is created by mvt-ios' `ProfileEvents` module. The module extracts a timeline of configuration profile operations. For example, it should indicate when a new profile was installed from the Settings app, or when one was removed.
@@ -221,7 +259,7 @@ This JSON file is created by mvt-ios' `ProfileEvents` module. The module extract
 ### `safari_browser_state.json`
 
 !!! info "Availability"
-    Backup (if encrypted): :material-check:  
+    Backup (if encrypted): :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `SafariBrowserState` module. The module extracts records from the SQLite databases located at */private/var/mobile/Library/Safari/BrowserState.db* or */private/var/mobile/Containers/Data/Application/\*/Library/Safari/BrowserState.db*, which contain records of opened tabs.
@@ -233,7 +271,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `safari_favicon.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `SafariFavicon` module. The module extracts records from the SQLite databases located at */private/var/mobile/Library/Image Cache/Favicons/Favicons.db* or */private/var/mobile/Containers/Data/Application/\*/Library/Image Cache/Favicons/Favicons.db*, which contain mappings of favicons' URLs and the visited URLs which loaded them.
@@ -245,7 +283,7 @@ If indicators are provided through the command-line, they are checked against bo
 ### `safari_history.json`
 
 !!! info "Availability"
-    Backup (if encrypted): :material-check:  
+    Backup (if encrypted): :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `SafariHistory` module. The module extracts records from the SQLite databases located at */private/var/mobile/Library/Safari/History.db* or */private/var/mobile/Containers/Data/Application/\*/Library/Safari/History.db*, which contain a history of URL visits.
@@ -257,7 +295,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `shutdown_log.json`
 
 !!! info "Availability"
-    Backup (if encrypted): :material-close:  
+    Backup (if encrypted): :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `ShutdownLog` module. The module extracts records from the shutdown log located at *private/var/db/diagnostics/shutdown.log*. When shutting down an iPhone, a SIGTERM will be sent to all processes runnning. The `shutdown.log` file will log any process (with its pid and path) that did not shut down after the SIGTERM was sent.
@@ -269,19 +307,28 @@ If indicators are provided through the command-line, they are checked against th
 ### `sms.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
-This JSON file is created by mvt-ios' `SMS` module. The module extracts a list of SMS messages containing HTTP links from the SQLite database located at */private/var/mobile/Library/SMS/sms.db*.
+This JSON file is created by mvt-ios' `SMS` module. The module extracts a list of SMS messages from the SQLite database located at */private/var/mobile/Library/SMS/sms.db*.
 
 If indicators are provided through the command-line, they are checked against the extracted HTTP links. Any matches are stored in *sms_detected.json*.
 
 ---
 
+### `urls.json`
+
+This JSON file collects URLs extracted from SMS, iMessage, and WhatsApp
+messages. Each entry contains the original URL, its expanded destination when
+MVT resolved a shortened URL during indicator checking, the message timestamp,
+and its `sms` or `whatsapp` source.
+
+---
+
 ### `sms_attachments.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `SMSAttachments` module. The module extracts details about attachments sent via SMS or iMessage from the same database used by the `SMS` module. These records might be useful to indicate unique patterns that might be indicative of exploitation attempts leveraging potential vulnerabilities in file format parsers or other forms of file handling by the Messages app.
@@ -291,7 +338,7 @@ This JSON file is created by mvt-ios' `SMSAttachments` module. The module extrac
 ### `tcc.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `TCC` module. The module extracts records from a SQLite database located at */private/var/mobile/Library/TCC/TCC.db*, which contains a list of which services such as microphone, camera, or location, apps have been granted or denied access to.
@@ -301,7 +348,7 @@ This JSON file is created by mvt-ios' `TCC` module. The module extracts records
 ### `version_history.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `IOSVersionHistory` module. The module extracts records of iOS software updates from analytics plist files located at */private/var/db/analyticsd/Analytics-Journal-\*.ips*.
@@ -311,7 +358,7 @@ This JSON file is created by mvt-ios' `IOSVersionHistory` module. The module ext
 ### `webkit_indexeddb.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `WebkitIndexedDB` module. The module extracts a list of file and folder names located at the following path */private/var/mobile/Containers/Data/Application/\*/Library/WebKit/WebsiteData/IndexedDB*, which contains IndexedDB files created by any app installed on the device.
@@ -323,7 +370,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `webkit_local_storage.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `WebkitLocalStorage` module. The module extracts a list of file and folder names located at the following path */private/var/mobile/Containers/Data/Application/\*/Library/WebKit/WebsiteData/LocalStorage/*, which contains local storage files created by any app installed on the device.
@@ -335,7 +382,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `webkit_resource_load_statistics.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios `WebkitResourceLoadStatistics` module. The module extracts records from available WebKit ResourceLoadStatistics *observations.db* SQLite3 databases. These records should indicate domain names contacted by apps, including a timestamp.
@@ -347,7 +394,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `webkit_safari_view_service.json`
 
 !!! info "Availability"
-    Backup: :material-close:  
+    Backup: :material-close:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `WebkitSafariViewService` module. The module extracts a list of file and folder names located at the following path */private/var/mobile/Containers/Data/Application/\*/SystemData/com.apple.SafariViewService/Library/WebKit/WebsiteData/*, which contains files cached by SafariVewService.
@@ -359,7 +406,7 @@ If indicators are provided through the command-line, they are checked against th
 ### `webkit_session_resource_log.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
 This JSON file is created by mvt-ios' `WebkitSessionResourceLog` module. The module extracts records from plist files with the name *full_browsing_session_resourceLog.plist*, which contain records of resources loaded by different domains visited.
@@ -371,10 +418,32 @@ If indicators are provided through the command-line, they are checked against th
 ### `whatsapp.json`
 
 !!! info "Availability"
-    Backup: :material-check:  
+    Backup: :material-check:
     Full filesystem dump: :material-check:
 
-This JSON file is created by mvt-ios' `WhatsApp` module. The module extracts a list of WhatsApp messages containing HTTP links from the SQLite database located at *private/var/mobile/Containers/Shared/AppGroup/\*/ChatStorage.sqlite*.
+This JSON file is created by mvt-ios' `WhatsApp` module. The module extracts a list of WhatsApp messages from the SQLite database located at *private/var/mobile/Containers/Shared/AppGroup/\*/ChatStorage.sqlite*, along with one record per chat session (marked with `"record_type": "chat_session"`) containing the first and last interaction dates of each conversation. Chat sessions produce `chat_first_message` and `chat_last_message` timeline events, and group chats additionally produce a `group_created` event. A chat session's last-message date can postdate its newest stored message when the most recent messages in the chat were deleted.
+
+Recent WhatsApp versions key 1:1 chat sessions by an opaque LID identifier rather than the contact's phone number. The module resolves these using the `ZWAPHONENUMBERLIDPAIR` table from the *LID.sqlite* database in the same app group (or from *ChatStorage.sqlite* itself in versions that store it there), populating `partner_resolved_phone_number` on chat session records and using the phone number in timeline events. Each LID-phone number pair is also extracted as a record (`"record_type": "lid_phone_number_pair"`) and produces a `lid_pair_recorded` timeline event marking when WhatsApp learned the association.
 
 If indicators are provided through the command-line, they are checked against the extracted HTTP links. Any matches are stored in *whatsapp_detected.json*.
 
+---
+
+### `whatsapp_contacts.json`
+
+!!! info "Availability"
+    Backup: :material-check:
+    Full filesystem dump: :material-check:
+
+This JSON file is created by mvt-ios' `WhatsappContacts` module. The module extracts WhatsApp contact records from the SQLite database located at *private/var/mobile/Containers/Shared/AppGroup/\*/ContactsV2.sqlite*, including each contact's phone number, WhatsApp and LID identifiers, and the per-contact disappearing messages timer, which is not recorded in *ChatStorage.sqlite*. Each timestamp stored on a contact record produces a timeline event: `disappearing_mode_set` (when the disappearing messages timer was last changed), `about_changed` (when the contact last changed their "about" text), `about_expiration` (when a timed "about" is scheduled to expire) and `contact_last_updated` (when the contact record was last updated).
+
+This database is often missing from incremental backups. When it cannot be found, the module logs a warning and produces no results, in which case the disappearing messages state of chats cannot be determined from the backup.
+
+
+---
+
+## Records extracted by `check-sysdiagnose`
+
+### `sysdiagnose_info.json`
+
+This JSON file is created by mvt-ios' `SysdiagnoseInfo` module. The module extracts details about the device and the sysdiagnose itself: the product type and model, iOS version and build, serial number, IMEI, MEID and UDID from the remotectl dump state and the mobile activation request, the Apple account name and email from the App Store daemon database (no longer part of a sysdiagnose on newer iOS versions, still read from older archives), and the original file name and creation time of the archive from *sysdiagnose.log*.

docs/ios/sysdiagnose.md

@@ -0,0 +1,57 @@
+# Check an iOS Sysdiagnose
+
+`mvt-ios check-sysdiagnose` analyzes an iOS sysdiagnose archive. MVT's own
+`SysdiagnoseInfo` module extracts details about the device and the archive
+(see [`sysdiagnose_info.json`](records.md#sysdiagnose_infojson)); the checks
+come from the modules of the installed
+[plugin packages](../development/index.md#installed-module-packages) which
+declare support for the command. Without any such module the command still
+records the device details, and warns that no forensic sysdiagnose modules
+have been loaded so that the run cannot pass for a clean analysis.
+
+The command accepts either an extracted sysdiagnose directory or the original
+gzip-compressed tar archive.
+
+```bash
+mvt-ios check-sysdiagnose --output ./results \
+    ./sysdiagnose_2024.01.02_03-04-05+0200.tar.gz
+```
+
+Use `--hashes` to include hashes for analyzed files in `info.json`, and
+`--list-modules` to display the eligible modules without running them.
+
+## Writing a custom module
+
+Extend `SysdiagnoseExtraction` from `mvt.plugin`, see
+[Writing a module](../development/index.md#writing-a-module). The module reads
+the archive the same way whether MVT was given a folder or a tar archive. It
+declares the command in `supported_commands`. While writing one,
+[load it from its file](../development/index.md#developing-modules-locally).
+
+```python
+from mvt.plugin import SysdiagnoseExtraction
+
+
+class ExampleSysdiagnoseModule(SysdiagnoseExtraction):
+    supported_commands = (("ios", "check-sysdiagnose"),)
+    slug = "example_sysdiagnose"
+
+    def run(self):
+        paths = self._get_files_by_pattern("*/example.log")
+        if paths:
+            content = self._get_file_content(paths[0]).decode("utf-8", "replace")
+            self.results = [{"content": content}]
+
+    def check_indicators(self):
+        pass
+
+    def serialize(self, result):
+        return None
+```
+
+MVT extracts a tar archive first. It calls `from_sysdiagnose_folder()` on each
+module before `run()`. `ips_files` lists the IPS crash reports.
+
+`_get_files_by_pattern()` and `_get_file_content()` are internal helpers of the
+base class. Use them to read the archive. Their names and signatures can change
+between releases. See `src/mvt/ios/modules/sysdiagnose/base.py`.

docs/requirements.txt

@@ -1,5 +0,0 @@
-mkdocs==1.2.3
-mkdocs-autorefs
-mkdocs-material
-mkdocs-material-extensions
-mkdocstrings

mkdocs.yml

@@ -1,14 +1,16 @@
 site_name: Mobile Verification Toolkit
 repo_url: https://github.com/mvt-project/mvt
 edit_uri: edit/main/docs/
-copyright: Copyright © 2021-2022 MVT Project Developers
+copyright: Copyright © 2021-2023 MVT Project Developers
 site_description: Mobile Verification Toolkit Documentation
+not_in_nav: |
+    android/adb.md
 markdown_extensions:
     - attr_list
     - admonition
     - pymdownx.emoji:
-        emoji_index: !!python/name:materialx.emoji.twemoji
-        emoji_generator: !!python/name:materialx.emoji.to_svg
+        emoji_index: !!python/name:material.extensions.emoji.twemoji
+        emoji_generator: !!python/name:material.extensions.emoji.to_svg
     - pymdownx.superfences
     - pymdownx.inlinehilite
     - pymdownx.highlight:
@@ -28,6 +30,7 @@ nav:
     - Welcome: "index.md"
     - Introduction: "introduction.md"
     - Installation: "install.md"
+    - Command Completion: "command_completion.md"
     - Using Docker: "docker.md"
     - MVT for iOS:
         - iOS Forensic Methodology: "ios/methodology.md"
@@ -39,11 +42,16 @@ nav:
         - Check a Filesystem Dump:
             - Dumping the filesystem: "ios/filesystem/dump.md"
             - Check a Filesystem Dump with mvt-ios: "ios/filesystem/check.md"
+        - Check a Sysdiagnose: "ios/sysdiagnose.md"
         - Records extracted by mvt-ios: "ios/records.md"
     - MVT for Android:
         - Android Forensic Methodology: "android/methodology.md"
-        - Check over ADB: "android/adb.md"
         - Check an Android Backup (SMS messages): "android/backup.md"
-        - Download APKs: "android/download_apks.md"
+        - Check Android Intrusion Logs: "android/intrusion_logs.md"
     - Indicators of Compromise: "iocs.md"
+    - Development:
+        - Development Instructions: "development/index.md"
+        - Custom CLI Commands: "development/custom_commands.md"
+        - Plugin Configuration: "development/plugin_configuration.md"
+        - Managing Plugins: "development/plugins.md"
     - License: "license.md"

mvt/android/cli.py

@@ -1,257 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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 click
-from rich.logging import RichHandler
-
-from mvt.common.cmd_check_iocs import CmdCheckIOCS
-from mvt.common.help import (HELP_MSG_FAST, HELP_MSG_IOC,
-                             HELP_MSG_LIST_MODULES, HELP_MSG_MODULE,
-                             HELP_MSG_OUTPUT, HELP_MSG_SERIAL,
-                             HELP_MSG_HASHES)
-from mvt.common.logo import logo
-from mvt.common.updates import IndicatorsUpdates
-
-from .cmd_check_adb import CmdAndroidCheckADB
-from .cmd_check_androidqf import CmdAndroidCheckAndroidQF
-from .cmd_check_backup import CmdAndroidCheckBackup
-from .cmd_check_bugreport import CmdAndroidCheckBugreport
-from .cmd_download_apks import DownloadAPKs
-from .modules.adb import ADB_MODULES
-from .modules.adb.packages import Packages
-from .modules.backup import BACKUP_MODULES
-from .modules.bugreport import BUGREPORT_MODULES
-
-# Setup logging using Rich.
-LOG_FORMAT = "[%(name)s] %(message)s"
-logging.basicConfig(level="INFO", format=LOG_FORMAT, handlers=[
-    RichHandler(show_path=False, log_time_format="%X")])
-log = logging.getLogger(__name__)
-CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
-
-
-#==============================================================================
-# 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
-
-
-#==============================================================================
-# Command: download-apks
-#==============================================================================
-@cli.command("download-apks", help="Download all or only non-system installed APKs",
-             context_settings=CONTEXT_SETTINGS)
-@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, including system packages")
-@click.option("--virustotal", "-v", is_flag=True, help="Check packages on VirusTotal")
-@click.option("--output", "-o", type=click.Path(exists=False),
-              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)")
-@click.pass_context
-def download_apks(ctx, all_apks, virustotal, output, from_file, serial):
-    try:
-        if from_file:
-            download = DownloadAPKs.from_json(from_file)
-        else:
-            # 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)
-
-            download = DownloadAPKs(results_path=output, all_apks=all_apks)
-            if serial:
-                download.serial = serial
-            download.run()
-
-        packages_to_lookup = []
-        if all_apks:
-            packages_to_lookup = download.packages
-        else:
-            for package in download.packages:
-                if not package.get("system", False):
-                    packages_to_lookup.append(package)
-
-            if len(packages_to_lookup) == 0:
-                return
-
-        if virustotal:
-            m = Packages()
-            m.check_virustotal(packages_to_lookup)
-    except KeyboardInterrupt:
-        print("")
-        ctx.exit(1)
-
-
-#==============================================================================
-# Command: check-adb
-#==============================================================================
-@cli.command("check-adb", help="Check an Android device over adb",
-             context_settings=CONTEXT_SETTINGS)
-@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.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, serial, iocs, output, fast, list_modules, module):
-    cmd = CmdAndroidCheckADB(results_path=output, ioc_files=iocs,
-                             module_name=module, serial=serial, fast_mode=fast)
-
-    if list_modules:
-        cmd.list_modules()
-        return
-
-    log.info("Checking Android device over debug bridge")
-
-    cmd.run()
-
-    if cmd.detected_count > 0:
-        log.warning("The analysis of the Android device produced %d detections!",
-                    cmd.detected_count)
-
-
-#==============================================================================
-# Command: check-bugreport
-#==============================================================================
-@cli.command("check-bugreport", help="Check an Android Bug Report",
-             context_settings=CONTEXT_SETTINGS)
-@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.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
-@click.option("--module", "-m", help=HELP_MSG_MODULE)
-@click.argument("BUGREPORT_PATH", type=click.Path(exists=True))
-@click.pass_context
-def check_bugreport(ctx, iocs, output, list_modules, module, bugreport_path):
-    # Always generate hashes as bug reports are small.
-    cmd = CmdAndroidCheckBugreport(target_path=bugreport_path,
-                                   results_path=output, ioc_files=iocs,
-                                   module_name=module, hashes=True)
-
-    if list_modules:
-        cmd.list_modules()
-        return
-
-    log.info("Checking Android bug report at path: %s", bugreport_path)
-
-    cmd.run()
-
-    if cmd.detected_count > 0:
-        log.warning("The analysis of the Android bug report produced %d detections!",
-                    cmd.detected_count)
-
-
-#==============================================================================
-# Command: check-backup
-#==============================================================================
-@cli.command("check-backup", help="Check an Android Backup",
-             context_settings=CONTEXT_SETTINGS)
-@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.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
-@click.argument("BACKUP_PATH", type=click.Path(exists=True))
-@click.pass_context
-def check_backup(ctx, iocs, output, list_modules, backup_path):
-    # Always generate hashes as backups are generally small.
-    cmd = CmdAndroidCheckBackup(target_path=backup_path, results_path=output,
-                                ioc_files=iocs, hashes=True)
-
-    if list_modules:
-        cmd.list_modules()
-        return
-
-    log.info("Checking Android backup at path: %s", backup_path)
-
-    cmd.run()
-
-    if cmd.detected_count > 0:
-        log.warning("The analysis of the Android backup produced %d detections!",
-                    cmd.detected_count)
-
-
-#==============================================================================
-# Command: check-androidqf
-#==============================================================================
-@cli.command("check-androidqf", help="Check data collected with AndroidQF",
-             context_settings=CONTEXT_SETTINGS)
-@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.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
-@click.option("--module", "-m", help=HELP_MSG_MODULE)
-@click.option("--hashes", "-H", is_flag=True, help=HELP_MSG_HASHES)
-@click.argument("ANDROIDQF_PATH", type=click.Path(exists=True))
-@click.pass_context
-def check_androidqf(ctx, iocs, output, list_modules, module, hashes, androidqf_path):
-    cmd = CmdAndroidCheckAndroidQF(target_path=androidqf_path,
-                                   results_path=output, ioc_files=iocs,
-                                   module_name=module, hashes=hashes)
-
-    if list_modules:
-        cmd.list_modules()
-        return
-
-    log.info("Checking AndroidQF acquisition at path: %s", androidqf_path)
-
-    cmd.run()
-
-    if cmd.detected_count > 0:
-        log.warning("The analysis of the AndroidQF acquisition produced %d detections!",
-                    cmd.detected_count)
-
-
-#==============================================================================
-# Command: check-iocs
-#==============================================================================
-@cli.command("check-iocs", help="Compare stored JSON results to provided indicators",
-             context_settings=CONTEXT_SETTINGS)
-@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
-              default=[], help=HELP_MSG_IOC)
-@click.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
-@click.option("--module", "-m", help=HELP_MSG_MODULE)
-@click.argument("FOLDER", type=click.Path(exists=True))
-@click.pass_context
-def check_iocs(ctx, iocs, list_modules, module, folder):
-    cmd = CmdCheckIOCS(target_path=folder, ioc_files=iocs, module_name=module)
-    cmd.modules = BACKUP_MODULES + ADB_MODULES + BUGREPORT_MODULES
-
-    if list_modules:
-        cmd.list_modules()
-        return
-
-    cmd.run()
-
-
-#==============================================================================
-# Command: download-iocs
-#==============================================================================
-@cli.command("download-iocs", help="Download public STIX2 indicators",
-             context_settings=CONTEXT_SETTINGS)
-def download_indicators():
-    ioc_updates = IndicatorsUpdates()
-    ioc_updates.update()

mvt/android/cmd_check_adb.py

@@ -1,32 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.common.command import Command
-
-from .modules.adb import ADB_MODULES
-
-log = logging.getLogger(__name__)
-
-
-class CmdAndroidCheckADB(Command):
-
-    def __init__(
-        self,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        ioc_files: Optional[list] = None,
-        module_name: Optional[str] = None,
-        serial: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-    ) -> None:
-        super().__init__(target_path=target_path, results_path=results_path,
-                         ioc_files=ioc_files, module_name=module_name,
-                         serial=serial, fast_mode=fast_mode, log=log)
-
-        self.name = "check-adb"
-        self.modules = ADB_MODULES

mvt/android/cmd_check_androidqf.py

@@ -1,34 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.common.command import Command
-
-from .modules.androidqf import ANDROIDQF_MODULES
-
-log = logging.getLogger(__name__)
-
-
-class CmdAndroidCheckAndroidQF(Command):
-
-    def __init__(
-        self,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        ioc_files: Optional[list] = None,
-        module_name: Optional[str] = None,
-        serial: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        hashes: Optional[bool] = False,
-    ) -> None:
-        super().__init__(target_path=target_path, results_path=results_path,
-                         ioc_files=ioc_files, module_name=module_name,
-                         serial=serial, fast_mode=fast_mode, hashes=hashes,
-                         log=log)
-
-        self.name = "check-androidqf"
-        self.modules = ANDROIDQF_MODULES

mvt/android/cmd_check_backup.py

@@ -1,100 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import io
-import logging
-import os
-import sys
-import tarfile
-from pathlib import Path
-from typing import Callable, Optional, List
-
-from rich.prompt import Prompt
-
-from mvt.android.parsers.backup import (AndroidBackupParsingError,
-                                        InvalidBackupPassword, parse_ab_header,
-                                        parse_backup_file)
-from mvt.common.command import Command
-from mvt.android.modules.backup.base import BackupExtraction
-
-from .modules.backup import BACKUP_MODULES
-
-log = logging.getLogger(__name__)
-
-
-class CmdAndroidCheckBackup(Command):
-
-    def __init__(
-        self,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        ioc_files: Optional[list] = None,
-        module_name: Optional[str] = None,
-        serial: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        hashes: Optional[bool] = False,
-    ) -> None:
-        super().__init__(target_path=target_path, results_path=results_path,
-                         ioc_files=ioc_files, module_name=module_name,
-                         serial=serial, fast_mode=fast_mode, hashes=hashes,
-                         log=log)
-
-        self.name = "check-backup"
-        self.modules = BACKUP_MODULES
-
-        self.backup_type: str = ""
-        self.backup_archive: Optional[tarfile.TarFile] = None
-        self.backup_files: List[str] = []
-
-    def init(self) -> None:
-        if not self.target_path:
-            return
-
-        if os.path.isfile(self.target_path):
-            self.backup_type = "ab"
-            with open(self.target_path, "rb") as handle:
-                data = handle.read()
-
-            header = parse_ab_header(data)
-            if not header["backup"]:
-                log.critical("Invalid backup format, file should be in .ab format")
-                sys.exit(1)
-
-            password = None
-            if header["encryption"] != "none":
-                password = Prompt.ask("Enter backup password", password=True)
-            try:
-                tardata = parse_backup_file(data, password=password)
-            except InvalidBackupPassword:
-                log.critical("Invalid backup password")
-                sys.exit(1)
-            except AndroidBackupParsingError as exc:
-                log.critical("Impossible to parse this backup file: %s", exc)
-                log.critical("Please use Android Backup Extractor (ABE) instead")
-                sys.exit(1)
-
-            dbytes = io.BytesIO(tardata)
-            self.backup_archive = tarfile.open(fileobj=dbytes)
-            for member in self.backup_archive:
-                self.backup_files.append(member.name)
-
-        elif os.path.isdir(self.target_path):
-            self.backup_type = "folder"
-            self.target_path = Path(self.target_path).absolute().as_posix()
-            for root, subdirs, subfiles in os.walk(os.path.abspath(self.target_path)):
-                for fname in subfiles:
-                    self.backup_files.append(os.path.relpath(os.path.join(root, fname),
-                                                             self.target_path))
-        else:
-            log.critical("Invalid backup path, path should be a folder or an "
-                         "Android Backup (.ab) file")
-            sys.exit(1)
-
-    def module_init(self, module: BackupExtraction) -> None:  # type: ignore[override]
-        if self.backup_type == "folder":
-            module.from_folder(self.target_path, self.backup_files)
-        else:
-            module.from_ab(self.target_path, self.backup_archive,
-                           self.backup_files)

mvt/android/cmd_check_bugreport.py

@@ -1,70 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from pathlib import Path
-from typing import Callable, Optional, List
-from zipfile import ZipFile
-
-from mvt.common.command import Command
-from mvt.android.modules.bugreport.base import BugReportModule
-
-from .modules.bugreport import BUGREPORT_MODULES
-
-log = logging.getLogger(__name__)
-
-
-class CmdAndroidCheckBugreport(Command):
-
-    def __init__(
-        self,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        ioc_files: Optional[list] = None,
-        module_name: Optional[str] = None,
-        serial: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        hashes: Optional[bool] = False,
-    ) -> None:
-        super().__init__(target_path=target_path, results_path=results_path,
-                         ioc_files=ioc_files, module_name=module_name,
-                         serial=serial, fast_mode=fast_mode, hashes=hashes,
-                         log=log)
-
-        self.name = "check-bugreport"
-        self.modules = BUGREPORT_MODULES
-
-        self.bugreport_format: str = ""
-        self.bugreport_archive: Optional[ZipFile] = None
-        self.bugreport_files: List[str] = []
-
-    def init(self) -> None:
-        if not self.target_path:
-            return
-
-        if os.path.isfile(self.target_path):
-            self.bugreport_format = "zip"
-            self.bugreport_archive = ZipFile(self.target_path)
-            for file_name in self.bugreport_archive.namelist():
-                self.bugreport_files.append(file_name)
-        elif os.path.isdir(self.target_path):
-            self.bugreport_format = "dir"
-            parent_path = Path(self.target_path).absolute().as_posix()
-            for root, _, subfiles in os.walk(os.path.abspath(self.target_path)):
-                for file_name in subfiles:
-                    file_path = os.path.relpath(os.path.join(root, file_name),
-                                                parent_path)
-                    self.bugreport_files.append(file_path)
-
-    def module_init(self, module: BugReportModule) -> None:  # type: ignore[override]
-        if self.bugreport_format == "zip":
-            module.from_zip(self.bugreport_archive, self.bugreport_files)
-        else:
-            module.from_folder(self.target_path, self.bugreport_files)
-
-    def finish(self) -> None:
-        if self.bugreport_archive:
-            self.bugreport_archive.close()

mvt/android/cmd_download_apks.py

@@ -1,171 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import json
-import logging
-import os
-from typing import Callable, Optional
-
-from rich.progress import track
-
-from mvt.common.module import InsufficientPrivileges
-
-from .modules.adb.base import AndroidExtraction
-from .modules.adb.packages import Packages
-
-log = logging.getLogger(__name__)
-
-
-class DownloadAPKs(AndroidExtraction):
-    """DownloadAPKs is the main class operating the download of APKs
-    from the device.
-
-
-    """
-
-    def __init__(
-        self,
-        results_path: Optional[str] = None,
-        all_apks: Optional[bool] = False,
-        packages: Optional[list] = None
-    ) -> None:
-        """Initialize module.
-        :param results_path: Path to the folder where data should be stored
-        :param all_apks: Boolean indicating whether to download all packages
-                         or filter known-goods
-        :param packages: Provided list of packages, typically for JSON checks
-        """
-        super().__init__(results_path=results_path, log=log)
-
-        self.packages = packages
-        self.all_apks = all_apks
-        self.results_path_apks = None
-
-    @classmethod
-    def from_json(cls, json_path: str) -> Callable:
-        """Initialize this class from an existing apks.json file.
-
-        :param json_path: Path to the apks.json file to parse.
-
-        """
-        with open(json_path, "r", encoding="utf-8") as handle:
-            packages = json.load(handle)
-            return cls(packages=packages)
-
-    def pull_package_file(self, package_name: str, remote_path: str) -> None:
-        """Pull files related to specific package from the device.
-
-        :param package_name: Name of the package to download
-        :param remote_path: Path to the file to download
-        :returns: Path to the local copy
-
-        """
-        log.info("Downloading %s ...", remote_path)
-
-        file_name = ""
-        if "==/" in remote_path:
-            file_name = "_" + remote_path.split("==/")[1].replace(".apk", "")
-
-        local_path = os.path.join(self.results_path_apks,
-                                  f"{package_name}{file_name}.apk")
-        name_counter = 0
-        while True:
-            if not os.path.exists(local_path):
-                break
-
-            name_counter += 1
-            local_path = os.path.join(self.results_path_apks,
-                                      f"{package_name}{file_name}_{name_counter}.apk")
-
-        try:
-            self._adb_download(remote_path, local_path)
-        except InsufficientPrivileges:
-            log.error("Unable to pull package file from %s: insufficient privileges, "
-                      "it might be a system app", remote_path)
-            self._adb_reconnect()
-            return None
-        except Exception as exc:
-            log.exception("Failed to pull package file from %s: %s",
-                          remote_path, exc)
-            self._adb_reconnect()
-            return None
-
-        return local_path
-
-    def get_packages(self) -> None:
-        """Use the Packages adb module to retrieve the list of packages.
-        We reuse the same extraction logic to then download the APKs.
-        """
-        self.log.info("Retrieving list of installed packages...")
-
-        m = Packages()
-        m.log = self.log
-        m.serial = self.serial
-        m.run()
-
-        self.packages = m.results
-
-    def pull_packages(self) -> None:
-        """Download all files of all selected packages from the device.
-        """
-        log.info("Starting extraction of installed APKs at folder %s",
-                 self.results_path)
-
-        # If the user provided the flag --all-apks we select all packages.
-        packages_selection = []
-        if self.all_apks:
-            log.info("Selected all %d available packages", len(self.packages))
-            packages_selection = self.packages
-        else:
-            # Otherwise we loop through the packages and get only those that
-            # are not marked as system.
-            for package in self.packages:
-                if not package.get("system", False):
-                    packages_selection.append(package)
-
-            log.info("Selected only %d packages which are not marked as \"system\"",
-                     len(packages_selection))
-
-        if len(packages_selection) == 0:
-            log.info("No packages were selected for download")
-            return
-
-        log.info("Downloading packages from device. This might take some time ...")
-
-        self.results_path_apks = os.path.join(self.results_path, "apks")
-        if not os.path.exists(self.results_path_apks):
-            os.makedirs(self.results_path_apks, exist_ok=True)
-
-        for i in track(range(len(packages_selection)),
-                       description=f"Downloading {len(packages_selection)} packages..."):
-            package = packages_selection[i]
-
-            log.info("[%d/%d] Package: %s", i, len(packages_selection),
-                     package["package_name"])
-
-            # Sometimes the package path contains multiple lines for multiple
-            # apks. We loop through each line and download each file.
-            for package_file in package["files"]:
-                device_path = package_file["path"]
-                local_path = self.pull_package_file(package["package_name"],
-                                                    device_path)
-                if not local_path:
-                    continue
-
-                package_file["local_path"] = local_path
-
-        log.info("Download of selected packages completed")
-
-    def save_json(self) -> None:
-        json_path = os.path.join(self.results_path, "apks.json")
-        with open(json_path, "w", encoding="utf-8") as handle:
-            json.dump(self.packages, handle, indent=4)
-
-    def run(self) -> None:
-        self.get_packages()
-        self._adb_connect()
-        self.pull_packages()
-        self.save_json()
-        self._adb_disconnect()

mvt/android/modules/adb/__init__.py

@@ -1,30 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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_accessibility import DumpsysAccessibility
-from .dumpsys_activities import DumpsysActivities
-from .dumpsys_appops import DumpsysAppOps
-from .dumpsys_battery_daily import DumpsysBatteryDaily
-from .dumpsys_battery_history import DumpsysBatteryHistory
-from .dumpsys_dbinfo import DumpsysDBInfo
-from .dumpsys_full import DumpsysFull
-from .dumpsys_receivers import DumpsysReceivers
-from .files import Files
-from .getprop import Getprop
-from .logcat import Logcat
-from .packages import Packages
-from .processes import Processes
-from .root_binaries import RootBinaries
-from .selinux_status import SELinuxStatus
-from .settings import Settings
-from .sms import SMS
-from .whatsapp import Whatsapp
-
-ADB_MODULES = [ChromeHistory, SMS, Whatsapp, Processes, Getprop, Settings,
-               SELinuxStatus, DumpsysBatteryHistory, DumpsysBatteryDaily,
-               DumpsysReceivers, DumpsysActivities, DumpsysAccessibility,
-               DumpsysDBInfo, DumpsysFull, DumpsysAppOps, Packages, Logcat,
-               RootBinaries, Files]

mvt/android/modules/adb/base.py

@@ -1,310 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import base64
-import logging
-import os
-import random
-import string
-import sys
-import tempfile
-import time
-from typing import Callable, Optional
-
-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,
-                                  UsbDeviceNotFoundError, UsbReadFailedError)
-from rich.prompt import Prompt
-from usb1 import USBErrorAccess, USBErrorBusy
-
-from mvt.android.parsers.backup import (InvalidBackupPassword, parse_ab_header,
-                                        parse_backup_file)
-from mvt.common.module import InsufficientPrivileges, MVTModule
-
-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: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.device = None
-        self.serial = None
-
-    @staticmethod
-    def _adb_check_keys() -> None:
-        """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))
-
-        if not os.path.exists(ADB_KEY_PATH):
-            keygen(ADB_KEY_PATH)
-
-        if not os.path.exists(ADB_PUB_KEY_PATH):
-            write_public_keyfile(ADB_KEY_PATH, ADB_PUB_KEY_PATH)
-
-    def _adb_connect(self) -> None:
-        """Connect to the device over adb."""
-        self._adb_check_keys()
-
-        with open(ADB_KEY_PATH, "rb") as handle:
-            priv_key = handle.read()
-
-        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:
-            try:
-                self.device = AdbDeviceUsb(serial=self.serial)
-            except UsbDeviceNotFoundError:
-                self.log.critical("No device found. Make sure it is connected and unlocked.")
-                sys.exit(-1)
-        # 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:
-                self.device.connect(rsa_keys=[signer], auth_timeout_s=5)
-            except (USBErrorBusy, USBErrorAccess):
-                self.log.critical("Device is busy, maybe run `adb kill-server` and try again.")
-                sys.exit(-1)
-            except DeviceAuthError:
-                self.log.error("You need to authorize this computer on the Android device. "
-                               "Retrying in 5 seconds...")
-                time.sleep(5)
-            except UsbReadFailedError:
-                self.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 exc:
-                if exc.errno == 113 and self.serial:
-                    self.log.critical("Unable to connect to the device %s: "
-                                      "did you specify the correct IP address?",
-                                      self.serial)
-                    sys.exit(-1)
-            else:
-                break
-
-    def _adb_disconnect(self) -> None:
-        """Close adb connection to the device."""
-        self.device.close()
-
-    def _adb_reconnect(self) -> None:
-        """Reconnect to device using adb."""
-        self.log.info("Reconnecting ...")
-        self._adb_disconnect()
-        self._adb_connect()
-
-    def _adb_command(self, command: str) -> str:
-        """Execute an adb shell command.
-
-        :param command: Shell command to execute
-        :returns: Output of command
-
-        """
-        return self.device.shell(command, read_timeout_s=200.0)
-
-    def _adb_check_if_root(self) -> bool:
-        """Check if we have a `su` binary on the Android device.
-
-
-        :returns: Boolean indicating whether a `su` binary is present or not
-
-        """
-        result = self._adb_command("command -v su && su -c true")
-        return bool(result) and "Permission denied" not in result
-
-    def _adb_root_or_die(self) -> None:
-        """Check if we have a `su` binary, otherwise raise an Exception."""
-        if not self._adb_check_if_root():
-            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: str) -> bool:
-        """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.
-
-        # Check if we have root, if not raise an Exception.
-        self._adb_root_or_die()
-
-        return bool(self._adb_command_as_root(f"[ ! -f {file} ] || echo 1"))
-
-    def _adb_download(
-        self,
-        remote_path: str,
-        local_path: str,
-        progress_callback: Optional[Callable] = None,
-        retry_root: Optional[bool] = True
-    ) -> None:
-        """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
-                                  (Default value = None)
-        :param retry_root: Default value = True)
-
-        """
-        try:
-            self.device.pull(remote_path, local_path, progress_callback)
-        except AdbCommandFailureException as exc:
-            if retry_root:
-                self._adb_download_root(remote_path, local_path,
-                                        progress_callback)
-            else:
-                raise Exception(f"Unable to download file {remote_path}: {exc}") from exc
-
-    def _adb_download_root(
-        self,
-        remote_path: str,
-        local_path: str,
-        progress_callback: Optional[Callable] = None
-    ) -> None:
-        try:
-            # Check if we have root, if not raise an Exception.
-            self._adb_root_or_die()
-
-            # We generate a random temporary filename.
-            allowed_chars = (string.ascii_uppercase
-                             + string.ascii_lowercase
-                             + string.digits)
-            tmp_filename = "tmp_" + ''.join(random.choices(allowed_chars, k=10))
-
-            # We create a temporary local file.
-            new_remote_path = f"/sdcard/{tmp_filename}"
-
-            # We copy the file from the data folder to /sdcard/.
-            cp_output = self._adb_command_as_root(f"cp {remote_path} {new_remote_path}")
-            if cp_output.startswith("cp: ") and "No such file or directory" in cp_output:
-                raise Exception(f"Unable to process file {remote_path}: File not found")
-            if cp_output.startswith("cp: ") and "Permission denied" in cp_output:
-                raise Exception(f"Unable to process file {remote_path}: Permission denied")
-
-            # We download from /sdcard/ to the local temporary file.
-            # If it doesn't work now, don't try again (retry_root=False)
-            self._adb_download(new_remote_path, local_path, progress_callback,
-                               retry_root=False)
-
-            # Delete the copy on /sdcard/.
-            self._adb_command(f"rm -rf {new_remote_path}")
-
-        except AdbCommandFailureException as exc:
-            raise Exception(f"Unable to download file {remote_path}: {exc}") from exc
-
-    def _adb_process_file(self, remote_path: str,
-                          process_routine: Callable) -> None:
-        """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.
-        # Check if we have root, if not raise an Exception.
-        self._adb_root_or_die()
-
-        # We create a temporary local file.
-        tmp = tempfile.NamedTemporaryFile()
-        local_path = tmp.name
-        local_name = os.path.basename(tmp.name)
-        new_remote_path = f"/sdcard/Download/{local_name}"
-
-        # We copy the file from the data folder to /sdcard/.
-        cp_output = self._adb_command_as_root(f"cp {remote_path} {new_remote_path}")
-        if cp_output.startswith("cp: ") and "No such file or directory" in cp_output:
-            raise Exception(f"Unable to process file {remote_path}: File not found")
-        if cp_output.startswith("cp: ") and "Permission denied" in cp_output:
-            raise Exception(f"Unable to process file {remote_path}: Permission denied")
-
-        # We download from /sdcard/ to the local temporary file.
-        self._adb_download(new_remote_path, local_path)
-
-        # Launch the provided process routine!
-        process_routine(local_path)
-
-        # Delete the local copy.
-        tmp.close()
-        # Delete the copy on /sdcard/.
-        self._adb_command(f"rm -f {new_remote_path}")
-
-    def _generate_backup(self, package_name: str) -> bytes:
-        self.log.info("Please check phone and accept Android backup prompt. "
-                      "You may need to set a backup password. \a")
-
-        # TODO: Base64 encoding as temporary fix to avoid byte-mangling over
-        #       the shell transport...
-        cmd = f"/system/bin/bu backup -nocompress '{package_name}' | base64"
-        backup_output_b64 = self._adb_command(cmd)
-        backup_output = base64.b64decode(backup_output_b64)
-        header = parse_ab_header(backup_output)
-
-        if not header["backup"]:
-            self.log.error("Extracting SMS via Android backup failed. "
-                           "No valid backup data found.")
-            return None
-
-        if header["encryption"] == "none":
-            return parse_backup_file(backup_output, password=None)
-
-        for _ in range(0, 3):
-            backup_password = Prompt.ask("Enter backup password",
-                                         password=True)
-            try:
-                decrypted_backup_tar = parse_backup_file(backup_output,
-                                                         backup_password)
-                return decrypted_backup_tar
-            except InvalidBackupPassword:
-                self.log.error("You provided the wrong password! Please try again...")
-
-        self.log.error("All attempts to decrypt backup with password failed!")
-
-        return None
-
-    def run(self) -> None:
-        """Run the main procedure."""
-        raise NotImplementedError

mvt/android/modules/adb/chrome_history.py

@@ -1,98 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-import sqlite3
-from typing import Optional, Union
-
-from mvt.common.utils import (convert_chrometime_to_datetime,
-                              convert_datetime_to_iso)
-
-from .base import AndroidExtraction
-
-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: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        return {
-            "timestamp": record["isodate"],
-            "module": self.__class__.__name__,
-            "event": "visit",
-            "data": f"{record['id']} - {record['url']} (visit ID: {record['visit_id']}, "
-                    f"redirect source: {record['redirect_source']})"
-        }
-
-    def check_indicators(self) -> None:
-        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: str) -> None:
-        """Parse a Chrome History database file.
-
-        :param db_path: Path to the History database to process.
-
-        """
-        conn = sqlite3.connect(db_path)
-        cur = conn.cursor()
-        cur.execute("""
-            SELECT
-                urls.id,
-                urls.url,
-                visits.id,
-                visits.visit_time,
-                visits.from_visit
-            FROM urls
-            JOIN visits ON visits.url = urls.id
-            ORDER BY visits.visit_time;
-        """)
-
-        for item in cur:
-            self.results.append({
-                "id": item[0],
-                "url": item[1],
-                "visit_id": item[2],
-                "timestamp": item[3],
-                "isodate": convert_datetime_to_iso(
-                    convert_chrometime_to_datetime(item[3])),
-                "redirect_source": item[4],
-            })
-
-        cur.close()
-        conn.close()
-
-        self.log.info("Extracted a total of %d history items",
-                      len(self.results))
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        try:
-            self._adb_process_file(os.path.join("/", CHROME_HISTORY_PATH),
-                                   self._parse_db)
-        except Exception as exc:
-            self.log.error(exc)
-
-        self._adb_disconnect()

mvt/android/modules/adb/dumpsys_accessibility.py

@@ -1,53 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_accessibility
-
-from .base import AndroidExtraction
-
-
-class DumpsysAccessibility(AndroidExtraction):
-    """This module extracts stats on accessibility."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("dumpsys accessibility")
-        self._adb_disconnect()
-
-        self.results = parse_dumpsys_accessibility(output)
-
-        for result in self.results:
-            self.log.info("Found installed accessibility service \"%s\"",
-                          result.get("service"))
-
-        self.log.info("Identified a total of %d accessibility services",
-                      len(self.results))

mvt/android/modules/adb/dumpsys_activities.py

@@ -1,51 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_activity_resolver_table
-
-from .base import AndroidExtraction
-
-
-class DumpsysActivities(AndroidExtraction):
-    """This module extracts details on receivers for risky activities."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = results if results else {}
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for intent, activities in self.results.items():
-            for activity in activities:
-                ioc = self.indicators.check_app_id(activity["package_name"])
-                if ioc:
-                    activity["matched_indicator"] = ioc
-                    self.detected.append({intent: activity})
-                    continue
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("dumpsys package")
-        self._adb_disconnect()
-
-        self.results = parse_dumpsys_activity_resolver_table(output)
-
-        self.log.info("Extracted activities for %d intents", len(self.results))

mvt/android/modules/adb/dumpsys_appops.py

@@ -1,73 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union
-
-from mvt.android.parsers.dumpsys import parse_dumpsys_appops
-
-from .base import AndroidExtraction
-
-
-class DumpsysAppOps(AndroidExtraction):
-    """This module extracts records from App-op Manager."""
-
-    slug = "dumpsys_appops"
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        records = []
-        for perm in record["permissions"]:
-            if "entries" not in perm:
-                continue
-
-            for entry in perm["entries"]:
-                if "timestamp" in entry:
-                    records.append({
-                        "timestamp": entry["timestamp"],
-                        "module": self.__class__.__name__,
-                        "event": entry["access"],
-                        "data": f"{record['package_name']} access to "
-                                f"{perm['name']}: {entry['access']}",
-                    })
-
-        return records
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if self.indicators:
-                ioc = self.indicators.check_app_id(result.get("package_name"))
-                if ioc:
-                    result["matched_indicator"] = ioc
-                    self.detected.append(result)
-                    continue
-
-            for perm in result["permissions"]:
-                if (perm["name"] == "REQUEST_INSTALL_PACKAGES"
-                        and perm["access"] == "allow"):
-                    self.log.info("Package %s with REQUEST_INSTALL_PACKAGES "
-                                  "permission", result["package_name"])
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("dumpsys appops")
-        self._adb_disconnect()
-
-        self.results = parse_dumpsys_appops(output)
-
-        self.log.info("Extracted a total of %d records from app-ops manager",
-                      len(self.results))

mvt/android/modules/adb/dumpsys_battery_daily.py

@@ -1,58 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union
-
-from mvt.android.parsers import parse_dumpsys_battery_daily
-
-from .base import AndroidExtraction
-
-
-class DumpsysBatteryDaily(AndroidExtraction):
-    """This module extracts records from battery daily updates."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        return {
-            "timestamp": record["from"],
-            "module": self.__class__.__name__,
-            "event": "battery_daily",
-            "data": f"Recorded update of package {record['package_name']} "
-                    f"with vers {record['vers']}"
-        }
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("dumpsys batterystats --daily")
-        self._adb_disconnect()
-
-        self.results = parse_dumpsys_battery_daily(output)
-
-        self.log.info("Extracted %d records from battery daily stats",
-                      len(self.results))

mvt/android/modules/adb/dumpsys_battery_history.py

@@ -1,49 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_battery_history
-
-from .base import AndroidExtraction
-
-
-class DumpsysBatteryHistory(AndroidExtraction):
-    """This module extracts records from battery history events."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("dumpsys batterystats --history")
-        self._adb_disconnect()
-
-        self.results = parse_dumpsys_battery_history(output)
-
-        self.log.info("Extracted %d records from battery history",
-                      len(self.results))

mvt/android/modules/adb/dumpsys_dbinfo.py

@@ -1,53 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_dbinfo
-
-from .base import AndroidExtraction
-
-
-class DumpsysDBInfo(AndroidExtraction):
-    """This module extracts records from battery daily updates."""
-
-    slug = "dumpsys_dbinfo"
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            path = result.get("path", "")
-            for part in path.split("/"):
-                ioc = self.indicators.check_app_id(part)
-                if ioc:
-                    result["matched_indicator"] = ioc
-                    self.detected.append(result)
-                    continue
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("dumpsys dbinfo")
-        self._adb_disconnect()
-
-        self.results = parse_dumpsys_dbinfo(output)
-
-        self.log.info("Extracted a total of %d records from database information",
-                      len(self.results))

mvt/android/modules/adb/dumpsys_full.py

@@ -1,40 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidExtraction
-
-
-class DumpsysFull(AndroidExtraction):
-    """This module extracts stats on battery consumption by processes."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        output = self._adb_command("dumpsys")
-        if self.results_path:
-            output_path = os.path.join(self.results_path, "dumpsys.txt")
-            with open(output_path, "w", encoding="utf-8") as handle:
-                handle.write(output)
-
-            self.log.info("Full dumpsys output stored at %s", output_path)
-
-        self._adb_disconnect()

mvt/android/modules/adb/dumpsys_receivers.py

@@ -1,73 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_receiver_resolver_table
-
-from .base import AndroidExtraction
-
-INTENT_NEW_OUTGOING_SMS = "android.provider.Telephony.NEW_OUTGOING_SMS"
-INTENT_SMS_RECEIVED = "android.provider.Telephony.SMS_RECEIVED"
-INTENT_DATA_SMS_RECEIVED = "android.intent.action.DATA_SMS_RECEIVED"
-INTENT_PHONE_STATE = "android.intent.action.PHONE_STATE"
-INTENT_NEW_OUTGOING_CALL = "android.intent.action.NEW_OUTGOING_CALL"
-
-
-class DumpsysReceivers(AndroidExtraction):
-    """This module extracts details on receivers for risky activities."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = results if results else {}
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for intent, receivers in self.results.items():
-            for receiver in receivers:
-                if intent == INTENT_NEW_OUTGOING_SMS:
-                    self.log.info("Found a receiver to intercept outgoing SMS messages: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_SMS_RECEIVED:
-                    self.log.info("Found a receiver to intercept incoming SMS messages: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_DATA_SMS_RECEIVED:
-                    self.log.info("Found a receiver to intercept incoming data SMS message: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_PHONE_STATE:
-                    self.log.info("Found a receiver monitoring "
-                                  "telephony state/incoming calls: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_NEW_OUTGOING_CALL:
-                    self.log.info("Found a receiver monitoring outgoing calls: \"%s\"",
-                                  receiver["receiver"])
-
-                ioc = self.indicators.check_app_id(receiver["package_name"])
-                if ioc:
-                    receiver["matched_indicator"] = ioc
-                    self.detected.append({intent: receiver})
-                    continue
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        output = self._adb_command("dumpsys package")
-        self.results = parse_dumpsys_receiver_resolver_table(output)
-
-        self._adb_disconnect()

mvt/android/modules/adb/files.py

@@ -1,141 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-import stat
-from typing import Optional, Union
-
-from mvt.common.utils import convert_unix_to_iso
-
-from .base import AndroidExtraction
-
-ANDROID_TMP_FOLDERS = [
-    "/tmp/",
-    "/data/local/tmp/",
-]
-ANDROID_MEDIA_FOLDERS = [
-    "/data/media/0",
-    "/sdcard/",
-]
-
-
-class Files(AndroidExtraction):
-    """This module extracts the list of files on the device."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-        self.full_find = False
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        if "modified_time" in record:
-            return {
-                "timestamp": record["modified_time"],
-                "module": self.__class__.__name__,
-                "event": "file_modified",
-                "data": record["path"],
-            }
-
-        return None
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if result.get("is_suid"):
-                self.log.warning("Found an SUID file in a non-standard directory \"%s\".",
-                                 result["path"])
-
-            if self.indicators and self.indicators.check_file_path(result["path"]):
-                self.log.warning("Found a known suspicous file at path: \"%s\"",
-                                 result["path"])
-                self.detected.append(result)
-
-    def backup_file(self, file_path: str) -> None:
-        local_file_name = file_path.replace("/", "_").replace(" ", "-")
-        local_files_folder = os.path.join(self.results_path, "files")
-        if not os.path.exists(local_files_folder):
-            os.mkdir(local_files_folder)
-
-        local_file_path = os.path.join(local_files_folder, local_file_name)
-
-        try:
-            self._adb_download(remote_path=file_path,
-                               local_path=local_file_path)
-        except Exception:
-            pass
-        else:
-            self.log.info("Downloaded file %s to local copy at %s",
-                          file_path, local_file_path)
-
-    def find_files(self, folder: str) -> None:
-        if self.full_find:
-            cmd = f"find '{folder}' -type f -printf '%T@ %m %s %u %g %p\n' 2> /dev/null"
-            output = self._adb_command(cmd)
-
-            for file_line in output.splitlines():
-                file_info = file_line.rstrip().split(" ", 5)
-                if len(file_line) < 6:
-                    self.log.info("Skipping invalid file info - %s", file_line.rstrip())
-                    continue
-                [unix_timestamp, mode, size,
-                 owner, group, full_path] = file_info
-                mod_time = convert_unix_to_iso(unix_timestamp)
-
-                self.results.append({
-                    "path": full_path,
-                    "modified_time": mod_time,
-                    "mode": mode,
-                    "is_suid": (int(mode, 8) & stat.S_ISUID) == 2048,
-                    "is_sgid": (int(mode, 8) & stat.S_ISGID) == 1024,
-                    "size": size,
-                    "owner": owner,
-                    "group": group,
-                })
-        else:
-            output = self._adb_command(f"find '{folder}' -type f 2> /dev/null")
-            for file_line in output.splitlines():
-                self.results.append({"path": file_line.rstrip()})
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        cmd = "find '/' -maxdepth 1 -printf '%T@ %m %s %u %g %p\n' 2> /dev/null"
-        output = self._adb_command(cmd)
-        if output or output.strip().splitlines():
-            self.full_find = True
-
-        for tmp_folder in ANDROID_TMP_FOLDERS:
-            self.find_files(tmp_folder)
-
-        for entry in self.results:
-            self.log.info("Found file in tmp folder at path %s",
-                          entry.get("path"))
-            if self.results_path:
-                self.backup_file(entry.get("path"))
-
-        for media_folder in ANDROID_MEDIA_FOLDERS:
-            self.find_files(media_folder)
-
-        self.log.info("Found %s files in primary Android tmp and media folders",
-                      len(self.results))
-
-        if self.fast_mode:
-            self.log.info("Flag --fast was enabled: skipping full file listing")
-        else:
-            self.log.info("Processing full file listing. This may take a while...")
-            self.find_files("/")
-
-            self.log.info("Found %s total files", len(self.results))
-
-        self._adb_disconnect()

mvt/android/modules/adb/getprop.py

@@ -1,50 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from datetime import datetime, timedelta
-from typing import Optional
-
-from mvt.android.parsers import parse_getprop
-
-from .base import AndroidExtraction
-
-
-class Getprop(AndroidExtraction):
-    """This module extracts device properties from getprop command."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = {} if not results else results
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("getprop")
-        self._adb_disconnect()
-
-        self.results = parse_getprop(output)
-
-        # Alert if phone is outdated.
-        security_patch = self.results.get("ro.build.version.security_patch", "")
-        if security_patch:
-            patch_date = datetime.strptime(security_patch, "%Y-%m-%d")
-            if (datetime.now() - patch_date) > timedelta(days=6*30):
-                self.log.warning("This phone has not received security updates "
-                                 "for more than six months (last update: %s)",
-                                 security_patch)
-
-        self.log.info("Extracted %d Android system properties",
-                      len(self.results))

mvt/android/modules/adb/logcat.py

@@ -1,54 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidExtraction
-
-
-class Logcat(AndroidExtraction):
-    """This module extracts details on installed packages."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        # Get the current logcat.
-        output = self._adb_command("logcat -d")
-        # Get the locat prior to last reboot.
-        last_output = self._adb_command("logcat -L")
-
-        if self.results_path:
-            logcat_path = os.path.join(self.results_path,
-                                       "logcat.txt")
-            with open(logcat_path, "w", encoding="utf-8") as handle:
-                handle.write(output)
-
-            self.log.info("Current logcat logs stored at %s",
-                          logcat_path)
-
-            logcat_last_path = os.path.join(self.results_path,
-                                            "logcat_last.txt")
-            with open(logcat_last_path, "w", encoding="utf-8") as handle:
-                handle.write(last_output)
-
-            self.log.info("Logcat logs prior to last reboot stored at %s",
-                          logcat_last_path)
-
-        self._adb_disconnect()

mvt/android/modules/adb/packages.py

@@ -1,348 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union, List
-
-from rich.console import Console
-from rich.progress import track
-from rich.table import Table
-from rich.text import Text
-
-from mvt.android.parsers.dumpsys import parse_dumpsys_package_for_details
-from mvt.common.virustotal import VTNoKey, VTQuotaExceeded, virustotal_lookup
-
-from .base import AndroidExtraction
-
-DANGEROUS_PERMISSIONS_THRESHOLD = 10
-DANGEROUS_PERMISSIONS = [
-    "android.permission.ACCESS_COARSE_LOCATION",
-    "android.permission.ACCESS_FINE_LOCATION",
-    "android.permission.AUTHENTICATE_ACCOUNTS",
-    "android.permission.CAMERA",
-    "android.permission.DISABLE_KEYGUARD",
-    "android.permission.PROCESS_OUTGOING_CALLS",
-    "android.permission.READ_CALENDAR",
-    "android.permission.READ_CALL_LOG",
-    "android.permission.READ_CONTACTS",
-    "android.permission.READ_PHONE_STATE",
-    "android.permission.READ_SMS",
-    "android.permission.RECEIVE_MMS",
-    "android.permission.RECEIVE_SMS",
-    "android.permission.RECEIVE_WAP_PUSH",
-    "android.permission.RECORD_AUDIO",
-    "android.permission.SEND_SMS",
-    "android.permission.SYSTEM_ALERT_WINDOW",
-    "android.permission.USE_CREDENTIALS",
-    "android.permission.USE_SIP",
-    "com.android.browser.permission.READ_HISTORY_BOOKMARKS",
-]
-ROOT_PACKAGES: List[str] = [
-    "com.noshufou.android.su",
-    "com.noshufou.android.su.elite",
-    "eu.chainfire.supersu",
-    "com.koushikdutta.superuser",
-    "com.thirdparty.superuser",
-    "com.yellowes.su",
-    "com.koushikdutta.rommanager",
-    "com.koushikdutta.rommanager.license",
-    "com.dimonvideo.luckypatcher",
-    "com.chelpus.lackypatch",
-    "com.ramdroid.appquarantine",
-    "com.ramdroid.appquarantinepro",
-    "com.devadvance.rootcloak",
-    "com.devadvance.rootcloakplus",
-    "de.robv.android.xposed.installer",
-    "com.saurik.substrate",
-    "com.zachspong.temprootremovejb",
-    "com.amphoras.hidemyroot",
-    "com.amphoras.hidemyrootadfree",
-    "com.formyhm.hiderootPremium",
-    "com.formyhm.hideroot",
-    "me.phh.superuser",
-    "eu.chainfire.supersu.pro",
-    "com.kingouser.com",
-    "com.topjohnwu.magisk",
-]
-SECURITY_PACKAGES = [
-    "com.policydm",
-    "com.samsung.android.app.omcagent",
-    "com.samsung.android.securitylogagent",
-    "com.sec.android.soagent",
-]
-SYSTEM_UPDATE_PACKAGES = [
-    "com.android.updater",
-    "com.google.android.gms",
-    "com.huawei.android.hwouc",
-    "com.lge.lgdmsclient",
-    "com.motorola.ccc.ota",
-    "com.oneplus.opbackup",
-    "com.oppo.ota",
-    "com.transsion.systemupdate",
-    "com.wssyncmldm",
-]
-
-
-class Packages(AndroidExtraction):
-    """This module extracts the list of installed packages."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        records = []
-
-        timestamps = [
-            {
-                "event": "package_install",
-                "timestamp": record["timestamp"]
-            },
-            {
-                "event": "package_first_install",
-                "timestamp": record["first_install_time"]
-            },
-            {
-                "event": "package_last_update",
-                "timestamp": record["last_update_time"]
-            },
-        ]
-
-        for timestamp in timestamps:
-            records.append({
-                "timestamp": timestamp["timestamp"],
-                "module": self.__class__.__name__,
-                "event": timestamp["event"],
-                "data": f"{record['package_name']} (system: {record['system']},"
-                        f" third party: {record['third_party']})",
-            })
-
-        return records
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if result["package_name"] in ROOT_PACKAGES:
-                self.log.warning("Found an installed package related to "
-                                 "rooting/jailbreaking: \"%s\"",
-                                 result["package_name"])
-                self.detected.append(result)
-                continue
-
-            if result["package_name"] in SECURITY_PACKAGES and result["disabled"]:
-                self.log.warning("Found a security package disabled: \"%s\"",
-                                 result["package_name"])
-
-            if result["package_name"] in SYSTEM_UPDATE_PACKAGES and result["disabled"]:
-                self.log.warning("System OTA update package \"%s\" disabled on the phone",
-                                 result["package_name"])
-
-            if not self.indicators:
-                continue
-
-            ioc = self.indicators.check_app_id(result.get("package_name"))
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-            for package_file in result.get("files", []):
-                ioc = self.indicators.check_file_hash(package_file["sha256"])
-                if ioc:
-                    result["matched_indicator"] = ioc
-                    self.detected.append(result)
-
-    @staticmethod
-    def check_virustotal(packages: list) -> None:
-        hashes = []
-        for package in packages:
-            for file in package.get("files", []):
-                if file["sha256"] not in hashes:
-                    hashes.append(file["sha256"])
-
-        total_hashes = len(hashes)
-        detections = {}
-
-        progress_desc = f"Looking up {total_hashes} files..."
-        for i in track(range(total_hashes), description=progress_desc):
-            try:
-                results = virustotal_lookup(hashes[i])
-            except VTNoKey:
-                return
-            except VTQuotaExceeded as exc:
-                print("Unable to continue: %s", exc)
-                break
-
-            if not results:
-                continue
-
-            positives = results["attributes"]["last_analysis_stats"]["malicious"]
-            total = len(results["attributes"]["last_analysis_results"])
-
-            detections[hashes[i]] = f"{positives}/{total}"
-
-        table = Table(title="VirusTotal Packages Detections")
-        table.add_column("Package name")
-        table.add_column("File path")
-        table.add_column("Detections")
-
-        for package in packages:
-            for file in package.get("files", []):
-                row = [package["package_name"], file["path"]]
-
-                if file["sha256"] in detections:
-                    detection = detections[file["sha256"]]
-                    positives = detection.split("/")[0]
-                    if int(positives) > 0:
-                        row.append(Text(detection, "red bold"))
-                    else:
-                        row.append(detection)
-                else:
-                    row.append("not found")
-
-                table.add_row(*row)
-
-        console = Console()
-        console.print(table)
-
-    @staticmethod
-    def parse_package_for_details(output: str) -> dict:
-        lines = []
-        in_packages = False
-        for line in output.splitlines():
-            if in_packages:
-                if line.strip() == "":
-                    break
-                lines.append(line)
-            if line.strip() == "Packages:":
-                in_packages = True
-
-        return parse_dumpsys_package_for_details("\n".join(lines))
-
-    def _get_files_for_package(self, package_name: str) -> list:
-        output = self._adb_command(f"pm path {package_name}")
-        output = output.strip().replace("package:", "")
-        if not output:
-            return []
-
-        package_files = []
-        for file_path in output.splitlines():
-            file_path = file_path.strip()
-
-            md5 = self._adb_command(
-                f"md5sum {file_path}").split(" ", maxsplit=1)[0]
-            sha1 = self._adb_command(
-                f"sha1sum {file_path}").split(" ", maxsplit=1)[0]
-            sha256 = self._adb_command(
-                f"sha256sum {file_path}").split(" ", maxsplit=1)[0]
-            sha512 = self._adb_command(
-                f"sha512sum {file_path}").split(" ", maxsplit=1)[0]
-
-            package_files.append({
-                "path": file_path,
-                "md5": md5,
-                "sha1": sha1,
-                "sha256": sha256,
-                "sha512": sha512,
-            })
-
-        return package_files
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        packages = self._adb_command("pm list packages -u -i -f")
-
-        for line in packages.splitlines():
-            line = line.strip()
-            if not line.startswith("package:"):
-                continue
-
-            fields = line.split()
-            file_name, package_name = fields[0].split(":")[1].rsplit("=", 1)
-
-            try:
-                installer = fields[1].split("=")[1].strip()
-            except IndexError:
-                installer = None
-            else:
-                if installer == "null":
-                    installer = None
-
-            package_files = self._get_files_for_package(package_name)
-            new_package = {
-                "package_name": package_name,
-                "file_name": file_name,
-                "installer": installer,
-                "disabled": False,
-                "system": False,
-                "third_party": False,
-                "files": package_files,
-            }
-
-            dumpsys_package = self._adb_command(
-                f"dumpsys package {package_name}")
-            package_details = self.parse_package_for_details(dumpsys_package)
-            new_package.update(package_details)
-
-            self.results.append(new_package)
-
-        cmds = [
-            {"field": "disabled", "arg": "-d"},
-            {"field": "system", "arg": "-s"},
-            {"field": "third_party", "arg": "-3"},
-        ]
-        for cmd in cmds:
-            output = self._adb_command(f"pm list packages {cmd['arg']}")
-            for line in output.splitlines():
-                line = line.strip()
-                if not line.startswith("package:"):
-                    continue
-
-                package_name = line.split(":", 1)[1]
-                for i, result in enumerate(self.results):
-                    if result["package_name"] == package_name:
-                        self.results[i][cmd["field"]] = True
-
-        for result in self.results:
-            if not result["third_party"]:
-                continue
-
-            dangerous_permissions_count = 0
-            for perm in result["requested_permissions"]:
-                if perm in DANGEROUS_PERMISSIONS:
-                    dangerous_permissions_count += 1
-
-            if dangerous_permissions_count >= DANGEROUS_PERMISSIONS_THRESHOLD:
-                self.log.info("Third-party package \"%s\" requested %d "
-                              "potentially dangerous permissions",
-                              result["package_name"],
-                              dangerous_permissions_count)
-
-        packages_to_lookup = []
-        for result in self.results:
-            if result["system"]:
-                continue
-
-            packages_to_lookup.append(result)
-            self.log.info("Found non-system package with name \"%s\" installed by \"%s\" on %s",
-                          result["package_name"], result["installer"],
-                          result["timestamp"])
-
-        if not self.fast_mode:
-            self.check_virustotal(packages_to_lookup)
-
-        self.log.info("Extracted at total of %d installed package names",
-                      len(self.results))
-
-        self._adb_disconnect()

mvt/android/modules/adb/processes.py

@@ -1,86 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidExtraction
-
-
-class Processes(AndroidExtraction):
-    """This module extracts details on running processes."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            proc_name = result.get("proc_name", "")
-            if not proc_name:
-                continue
-
-            # Skipping this process because of false positives.
-            if result["proc_name"] == "gatekeeperd":
-                continue
-
-            ioc = self.indicators.check_app_id(proc_name)
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-            ioc = self.indicators.check_process(proc_name)
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        output = self._adb_command("ps -A")
-
-        for line in output.splitlines()[1:]:
-            line = line.strip()
-            if line == "":
-                continue
-
-            fields = line.split()
-            proc = {
-                "user": fields[0],
-                "pid": fields[1],
-                "parent_pid": fields[2],
-                "vsize": fields[3],
-                "rss": fields[4],
-            }
-
-            # Sometimes WCHAN is empty, so we need to re-align output fields.
-            if len(fields) == 8:
-                proc["wchan"] = ""
-                proc["pc"] = fields[5]
-                proc["name"] = fields[7]
-            elif len(fields) == 9:
-                proc["wchan"] = fields[5]
-                proc["pc"] = fields[6]
-                proc["name"] = fields[8]
-
-            self.results.append(proc)
-
-        self._adb_disconnect()
-
-        self.log.info("Extracted records on a total of %d processes",
-                      len(self.results))

mvt/android/modules/adb/root_binaries.py

@@ -1,61 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidExtraction
-
-
-class RootBinaries(AndroidExtraction):
-    """This module extracts the list of installed packages."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def run(self) -> None:
-        root_binaries = [
-            "su",
-            "busybox",
-            "supersu",
-            "Superuser.apk",
-            "KingoUser.apk",
-            "SuperSu.apk",
-            "magisk",
-            "magiskhide",
-            "magiskinit",
-            "magiskpolicy",
-        ]
-
-        self._adb_connect()
-
-        for root_binary in root_binaries:
-            root_binary = root_binary.strip()
-            if not root_binary:
-                continue
-
-            output = self._adb_command(f"which -a {root_binary}")
-            output = output.strip()
-
-            if not output:
-                continue
-
-            if "which: not found" in output:
-                continue
-
-            self.detected.append(root_binary)
-            self.log.warning("Found root binary \"%s\"", root_binary)
-
-        self._adb_disconnect()

mvt/android/modules/adb/selinux_status.py

@@ -1,43 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidExtraction
-
-
-class SELinuxStatus(AndroidExtraction):
-    """This module checks if SELinux is being enforced."""
-
-    slug = "selinux_status"
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = {} if not results else results
-
-    def run(self) -> None:
-        self._adb_connect()
-        output = self._adb_command("getenforce")
-        self._adb_disconnect()
-
-        status = output.lower().strip()
-        self.results["status"] = status
-
-        if status == "enforcing":
-            self.log.info("SELinux is being regularly enforced")
-        else:
-            self.log.warning("SELinux status is \"%s\"!", status)

mvt/android/modules/adb/settings.py

@@ -1,110 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidExtraction
-
-ANDROID_DANGEROUS_SETTINGS = [
-    {
-        "description": "disabled Google Play Services apps verification",
-        "key": "verifier_verify_adb_installs",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled Google Play Protect",
-        "key": "package_verifier_enable",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled Google Play Protect",
-        "key": "package_verifier_user_consent",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled Google Play Protect",
-        "key": "upload_apk_enable",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled confirmation of adb apps installation",
-        "key": "adb_install_need_confirm",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled sharing of security reports",
-        "key": "send_security_reports",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled sharing of crash logs with manufacturer",
-        "key": "samsung_errorlog_agree",
-        "safe_value": "1",
-    },
-    {
-        "description": "disabled applications errors reports",
-        "key": "send_action_app_error",
-        "safe_value": "1",
-    },
-    {
-        "description": "enabled installation of non Google Play apps",
-        "key": "install_non_market_apps",
-        "safe_value": "0",
-    }
-]
-
-
-class Settings(AndroidExtraction):
-    """This module extracts Android system settings."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = {} if not results else results
-
-    def check_indicators(self) -> None:
-        for _, settings in self.results.items():
-            for key, value in settings.items():
-                for danger in ANDROID_DANGEROUS_SETTINGS:
-                    # Check if one of the dangerous settings is using an unsafe
-                    # value (different than the one specified).
-                    if danger["key"] == key and danger["safe_value"] != value:
-                        self.log.warning("Found suspicious setting \"%s = %s\" (%s)",
-                                         key, value, danger["description"])
-                        break
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        for namespace in ["system", "secure", "global"]:
-            out = self._adb_command(f"cmd settings list {namespace}")
-            if not out:
-                continue
-
-            self.results[namespace] = {}
-
-            for line in out.splitlines():
-                line = line.strip()
-                if line == "":
-                    continue
-
-                fields = line.split("=", 1)
-                try:
-                    self.results[namespace][fields[0]] = fields[1]
-                except IndexError:
-                    continue
-
-        self._adb_disconnect()

mvt/android/modules/adb/sms.py

@@ -1,165 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-import sqlite3
-from typing import Optional, Union
-
-from mvt.android.parsers.backup import (AndroidBackupParsingError,
-                                        parse_tar_for_sms)
-from mvt.common.module import InsufficientPrivileges
-from mvt.common.utils import check_for_links, convert_unix_to_iso
-
-from .base import AndroidExtraction
-
-SMS_BUGLE_PATH = "data/data/com.google.android.apps.messaging/databases/bugle_db"
-SMS_BUGLE_QUERY = """
-SELECT
-    ppl.normalized_destination AS address,
-    p.timestamp AS timestamp,
-CASE WHEN m.sender_id IN
-(SELECT _id FROM participants WHERE contact_id=-1)
-THEN 2 ELSE 1 END incoming, p.text AS body
-FROM messages m, conversations c, parts p,
-        participants ppl, conversation_participants cp
-WHERE (m.conversation_id = c._id)
-    AND (m._id = p.message_id)
-    AND (cp.conversation_id = c._id)
-    AND (cp.participant_id = ppl._id);
-"""
-
-SMS_MMSSMS_PATH = "data/data/com.android.providers.telephony/databases/mmssms.db"
-SMS_MMSMS_QUERY = """
-SELECT
-    address AS address,
-    date_sent AS timestamp,
-    type as incoming,
-    body AS body
-FROM sms;
-"""
-
-
-class SMS(AndroidExtraction):
-    """This module extracts all SMS messages containing links."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.sms_db_type = 0
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        body = record["body"].replace("\n", "\\n")
-        return {
-            "timestamp": record["isodate"],
-            "module": self.__class__.__name__,
-            "event": f"sms_{record['direction']}",
-            "data": f"{record.get('address', 'unknown source')}: \"{body}\""
-        }
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for message in self.results:
-            if "body" not in message:
-                continue
-
-            # TODO: check links exported from the body previously.
-            message_links = check_for_links(message["body"])
-            if self.indicators.check_domains(message_links):
-                self.detected.append(message)
-
-    def _parse_db(self, db_path: str) -> None:
-        """Parse an Android bugle_db SMS database file.
-
-        :param db_path: Path to the Android SMS database file to process
-
-        """
-        conn = sqlite3.connect(db_path)
-        cur = conn.cursor()
-
-        if self.sms_db_type == 1:
-            cur.execute(SMS_BUGLE_QUERY)
-        elif self.sms_db_type == 2:
-            cur.execute(SMS_MMSMS_QUERY)
-
-        names = [description[0] for description in cur.description]
-
-        for item in cur:
-            message = {}
-            for index, value in enumerate(item):
-                message[names[index]] = value
-
-            message["direction"] = ("received" if message["incoming"] == 1 else "sent")
-            message["isodate"] = convert_unix_to_iso(message["timestamp"])
-
-            # If we find links in the messages or if they are empty we add
-            # them to the list of results.
-            if check_for_links(message["body"]) or message["body"].strip() == "":
-                self.results.append(message)
-
-        cur.close()
-        conn.close()
-
-        self.log.info("Extracted a total of %d SMS messages containing links",
-                      len(self.results))
-
-    def _extract_sms_adb(self) -> None:
-        """Use the Android backup command to extract SMS data from the native
-        SMS app.
-
-        It is crucial to use the under-documented "-nocompress" flag to disable
-        the non-standard Java compression algorithm. This module only supports
-        an unencrypted ADB backup.
-        """
-        backup_tar = self._generate_backup("com.android.providers.telephony")
-        if not backup_tar:
-            return
-
-        try:
-            self.results = parse_tar_for_sms(backup_tar)
-        except AndroidBackupParsingError:
-            self.log.info("Impossible to read SMS from the Android Backup, "
-                          "please extract the SMS and try extracting it with "
-                          "Android Backup Extractor")
-            return
-
-        self.log.info("Extracted a total of %d SMS messages containing links",
-                      len(self.results))
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        try:
-            if self._adb_check_file_exists(os.path.join("/", SMS_BUGLE_PATH)):
-                self.sms_db_type = 1
-                self._adb_process_file(os.path.join("/", SMS_BUGLE_PATH),
-                                       self._parse_db)
-            elif self._adb_check_file_exists(os.path.join("/", SMS_MMSSMS_PATH)):
-                self.sms_db_type = 2
-                self._adb_process_file(os.path.join("/", SMS_MMSSMS_PATH),
-                                       self._parse_db)
-
-            self._adb_disconnect()
-            return
-        except InsufficientPrivileges:
-            pass
-
-        self.log.info("No SMS database found. Trying extraction of SMS data "
-                      "using Android backup feature.")
-        self._extract_sms_adb()
-
-        self._adb_disconnect()

mvt/android/modules/adb/whatsapp.py

@@ -1,107 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import base64
-import logging
-import os
-import sqlite3
-from typing import Optional, Union
-
-from mvt.common.utils import check_for_links, convert_unix_to_iso
-
-from .base import AndroidExtraction
-
-WHATSAPP_PATH = "data/data/com.whatsapp/databases/msgstore.db"
-
-
-class Whatsapp(AndroidExtraction):
-    """This module extracts all WhatsApp messages containing links."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        text = record["data"].replace("\n", "\\n")
-        return {
-            "timestamp": record["isodate"],
-            "module": self.__class__.__name__,
-            "event": f"whatsapp_msg_{record['direction']}",
-            "data": f"\"{text}\""
-        }
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for message in self.results:
-            if "data" not in message:
-                continue
-
-            message_links = check_for_links(message["data"])
-            if self.indicators.check_domains(message_links):
-                self.detected.append(message)
-
-    def _parse_db(self, db_path: str) -> None:
-        """Parse an Android msgstore.db WhatsApp database file.
-
-        :param db_path: Path to the Android WhatsApp database file to process
-
-        """
-        conn = sqlite3.connect(db_path)
-        cur = conn.cursor()
-        cur.execute("""
-            SELECT * FROM messages;
-        """)
-        names = [description[0] for description in cur.description]
-
-        messages = []
-        for item in cur:
-            message = {}
-            for index, value in enumerate(item):
-                message[names[index]] = value
-
-            if not message["data"]:
-                continue
-
-            message["direction"] = ("send" if message["key_from_me"] == 1 else "received")
-            message["isodate"] = convert_unix_to_iso(message["timestamp"])
-
-            # If we find links in the messages or if they are empty we add them
-            # to the list.
-            if (check_for_links(message["data"])
-                    or message["data"].strip() == ""):
-                if message.get("thumb_image"):
-                    message["thumb_image"] = base64.b64encode(
-                        message["thumb_image"])
-
-                messages.append(message)
-
-        cur.close()
-        conn.close()
-
-        self.log.info("Extracted a total of %d WhatsApp messages containing links",
-                      len(messages))
-        self.results = messages
-
-    def run(self) -> None:
-        self._adb_connect()
-
-        try:
-            self._adb_process_file(os.path.join("/", WHATSAPP_PATH),
-                                                self._parse_db)
-        except Exception as exc:
-            self.log.error(exc)
-
-        self._adb_disconnect()

mvt/android/modules/androidqf/__init__.py

@@ -1,18 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-from .dumpsys_accessibility import DumpsysAccessibility
-from .dumpsys_activities import DumpsysActivities
-from .dumpsys_appops import DumpsysAppops
-from .dumpsys_packages import DumpsysPackages
-from .dumpsys_receivers import DumpsysReceivers
-from .getprop import Getprop
-from .processes import Processes
-from .settings import Settings
-from .sms import SMS
-
-ANDROIDQF_MODULES = [DumpsysActivities, DumpsysReceivers, DumpsysAccessibility,
-                     DumpsysAppops, Processes, Getprop, Settings, SMS,
-                     DumpsysPackages]

mvt/android/modules/androidqf/base.py

@@ -1,38 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import fnmatch
-import logging
-import os
-from typing import Union, List, Dict, Any, Optional
-
-from mvt.common.module import MVTModule
-
-
-class AndroidQFModule(MVTModule):
-    """This class provides a base for all Android Data analysis modules."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Union[List[Dict[str, Any]], Dict[str, Any], None] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self._path = target_path
-        self._files = []
-
-        for root, dirs, files in os.walk(target_path):
-            for name in files:
-                self._files.append(os.path.join(root, name))
-
-    def _get_files_by_pattern(self, pattern):
-        return fnmatch.filter(self._files, pattern)

mvt/android/modules/androidqf/dumpsys_accessibility.py

@@ -1,68 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_accessibility
-
-from .base import AndroidQFModule
-
-
-class DumpsysAccessibility(AndroidQFModule):
-    """This module analyse dumpsys accessbility"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-
-    def run(self) -> None:
-        dumpsys_file = self._get_files_by_pattern("*/dumpsys.txt")
-        if not dumpsys_file:
-            return
-
-        lines = []
-        in_accessibility = False
-        with open(dumpsys_file[0]) as handle:
-            for line in handle:
-                if line.strip().startswith("DUMP OF SERVICE accessibility:"):
-                    in_accessibility = True
-                    continue
-
-                if not in_accessibility:
-                    continue
-
-                if line.strip().startswith("-------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                    break
-
-                lines.append(line.rstrip())
-
-        self.results = parse_dumpsys_accessibility("\n".join(lines))
-
-        for result in self.results:
-            self.log.info("Found installed accessibility service \"%s\"",
-                          result.get("service"))
-
-        self.log.info("Identified a total of %d accessibility services",
-                      len(self.results))

mvt/android/modules/androidqf/dumpsys_activities.py

@@ -1,66 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_activity_resolver_table
-
-from .base import AndroidQFModule
-
-
-class DumpsysActivities(AndroidQFModule):
-    """This module extracts details on receivers for risky activities."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = results if results else {}
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for intent, activities in self.results.items():
-            for activity in activities:
-                ioc = self.indicators.check_app_id(activity["package_name"])
-                if ioc:
-                    activity["matched_indicator"] = ioc
-                    self.detected.append({intent: activity})
-
-    def run(self) -> None:
-        dumpsys_file = self._get_files_by_pattern("*/dumpsys.txt")
-        if not dumpsys_file:
-            return
-
-        lines = []
-        in_package = False
-        with open(dumpsys_file[0]) as handle:
-            for line in handle:
-                if line.strip() == "DUMP OF SERVICE package:":
-                    in_package = True
-                    continue
-
-                if not in_package:
-                    continue
-
-                if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                    break
-
-                lines.append(line.rstrip())
-
-        self.results = parse_dumpsys_activity_resolver_table("\n".join(lines))
-
-        self.log.info("Extracted activities for %d intents", len(self.results))

mvt/android/modules/androidqf/dumpsys_appops.py

@@ -1,83 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union
-
-from mvt.android.parsers import parse_dumpsys_appops
-
-from .base import AndroidQFModule
-
-
-class DumpsysAppops(AndroidQFModule):
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        records = []
-        for perm in record["permissions"]:
-            if "entries" not in perm:
-                continue
-
-            for entry in perm["entries"]:
-                if "timestamp" in entry:
-                    records.append({
-                        "timestamp": entry["timestamp"],
-                        "module": self.__class__.__name__,
-                        "event": entry["access"],
-                        "data": f"{record['package_name']} access to "
-                                f"{perm['name']} : {entry['access']}",
-                    })
-
-        return records
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if self.indicators:
-                ioc = self.indicators.check_app_id(result.get("package_name"))
-                if ioc:
-                    result["matched_indicator"] = ioc
-                    self.detected.append(result)
-                    continue
-
-            for perm in result["permissions"]:
-                if (perm["name"] == "REQUEST_INSTALL_PACKAGES"
-                        and perm["access"] == "allow"):
-                    self.log.info("Package %s with REQUEST_INSTALL_PACKAGES permission",
-                                  result["package_name"])
-
-    def run(self) -> None:
-        dumpsys_file = self._get_files_by_pattern("*/dumpsys.txt")
-        if not dumpsys_file:
-            return
-
-        lines = []
-        in_package = False
-        with open(dumpsys_file[0]) as handle:
-            for line in handle:
-                if line.startswith("DUMP OF SERVICE appops:"):
-                    in_package = True
-                    continue
-
-                if in_package:
-                    if line.startswith("-------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                        break
-
-                    lines.append(line.rstrip())
-
-        self.results = parse_dumpsys_appops("\n".join(lines))
-        self.log.info("Identified %d applications in AppOps Manager",
-                      len(self.results))

mvt/android/modules/androidqf/dumpsys_packages.py

@@ -1,108 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from datetime import datetime
-from typing import Optional, Union, List, Any, Dict
-
-from mvt.android.modules.adb.packages import (DANGEROUS_PERMISSIONS,
-                                              DANGEROUS_PERMISSIONS_THRESHOLD,
-                                              ROOT_PACKAGES)
-from mvt.android.parsers.dumpsys import parse_dumpsys_packages
-from mvt.common.utils import convert_datetime_to_iso
-
-from .base import AndroidQFModule
-
-
-class DumpsysPackages(AndroidQFModule):
-    """This module analyse dumpsys packages"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[List[Dict[str, Any]]] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        entries = []
-        for entry in ["timestamp", "first_install_time", "last_update_time"]:
-            if entry in record:
-                entries.append({
-                    "timestamp": record[entry],
-                    "module": self.__class__.__name__,
-                    "event": entry,
-                    "data": f"Package {record['package_name']} "
-                            f"({record['uid']})",
-                })
-
-        return entries
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if result["package_name"] in ROOT_PACKAGES:
-                self.log.warning("Found an installed package related to "
-                                 "rooting/jailbreaking: \"%s\"",
-                                 result["package_name"])
-                self.detected.append(result)
-                continue
-
-            if not self.indicators:
-                continue
-
-            ioc = self.indicators.check_app_id(result.get("package_name", ""))
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-
-    def run(self) -> None:
-        dumpsys_file = self._get_files_by_pattern("*/dumpsys.txt")
-        if len(dumpsys_file) != 1:
-            self.log.info("Dumpsys file not found")
-            return
-
-        with open(dumpsys_file[0]) as handle:
-            data = handle.read().split("\n")
-
-        package = []
-        in_service = False
-        in_package_list = False
-        for line in data:
-            if line.strip().startswith("DUMP OF SERVICE package:"):
-                in_service = True
-                continue
-
-            if in_service and line.startswith("Packages:"):
-                in_package_list = True
-                continue
-
-            if not in_service or not in_package_list:
-                continue
-
-            if line.strip() == "":
-                break
-
-            package.append(line)
-
-        self.results = parse_dumpsys_packages("\n".join(package))
-
-        for result in self.results:
-            dangerous_permissions_count = 0
-            for perm in result["permissions"]:
-                if perm["name"] in DANGEROUS_PERMISSIONS:
-                    dangerous_permissions_count += 1
-
-            if dangerous_permissions_count >= DANGEROUS_PERMISSIONS_THRESHOLD:
-                self.log.info("Found package \"%s\" requested %d potentially dangerous permissions",
-                              result["package_name"],
-                              dangerous_permissions_count)
-
-        self.log.info("Extracted details on %d packages", len(self.results))

mvt/android/modules/androidqf/dumpsys_receivers.py

@@ -1,86 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, List, Dict, Union, Any
-
-from mvt.android.modules.adb.dumpsys_receivers import (
-    INTENT_DATA_SMS_RECEIVED, INTENT_NEW_OUTGOING_CALL,
-    INTENT_NEW_OUTGOING_SMS, INTENT_PHONE_STATE, INTENT_SMS_RECEIVED)
-from mvt.android.parsers import parse_dumpsys_receiver_resolver_table
-
-from .base import AndroidQFModule
-
-
-class DumpsysReceivers(AndroidQFModule):
-    """This module analyse dumpsys receivers"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Union[List[Any], Dict[str, Any], None] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = results if results else {}
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for intent, receivers in self.results.items():
-            for receiver in receivers:
-                if intent == INTENT_NEW_OUTGOING_SMS:
-                    self.log.info("Found a receiver to intercept outgoing SMS messages: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_SMS_RECEIVED:
-                    self.log.info("Found a receiver to intercept incoming SMS messages: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_DATA_SMS_RECEIVED:
-                    self.log.info("Found a receiver to intercept incoming data SMS message: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_PHONE_STATE:
-                    self.log.info("Found a receiver monitoring "
-                                  "telephony state/incoming calls: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_NEW_OUTGOING_CALL:
-                    self.log.info("Found a receiver monitoring outgoing calls: \"%s\"",
-                                  receiver["receiver"])
-
-                ioc = self.indicators.check_app_id(receiver["package_name"])
-                if ioc:
-                    receiver["matched_indicator"] = ioc
-                    self.detected.append({intent: receiver})
-
-    def run(self) -> None:
-        dumpsys_file = self._get_files_by_pattern("*/dumpsys.txt")
-        if not dumpsys_file:
-            return
-
-        in_receivers = False
-        lines = []
-        with open(dumpsys_file[0]) as handle:
-            for line in handle:
-                if line.strip() == "DUMP OF SERVICE package:":
-                    in_receivers = True
-                    continue
-
-                if not in_receivers:
-                    continue
-
-                if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                    break
-
-                lines.append(line.rstrip())
-
-        self.results = parse_dumpsys_receiver_resolver_table("\n".join(lines))
-
-        self.log.info("Extracted receivers for %d intents", len(self.results))

mvt/android/modules/androidqf/getprop.py

@@ -1,66 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from datetime import datetime, timedelta
-from typing import Optional
-
-from mvt.android.parsers import getprop
-
-from .base import AndroidQFModule
-
-INTERESTING_PROPERTIES = [
-    "gsm.sim.operator.alpha",
-    "gsm.sim.operator.iso-country",
-    "persist.sys.timezone",
-    "ro.boot.serialno",
-    "ro.build.version.sdk",
-    "ro.build.version.security_patch",
-    "ro.product.cpu.abi",
-    "ro.product.locale",
-    "ro.product.vendor.manufacturer",
-    "ro.product.vendor.model",
-    "ro.product.vendor.name"
-]
-
-
-class Getprop(AndroidQFModule):
-    """This module extracts data from get properties."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-        self.results = {}
-
-    def run(self) -> None:
-        getprop_files = self._get_files_by_pattern("*/getprop.txt")
-        if not getprop_files:
-            self.log.info("getprop.txt file not found")
-            return
-
-        with open(getprop_files[0]) as f:
-            data = f.read()
-
-        self.results = getprop.parse_getprop(data)
-        for entry in self.results:
-            if entry in INTERESTING_PROPERTIES:
-                self.log.info("%s: %s", entry, self.results[entry])
-            if entry == "ro.build.version.security_patch":
-                last_patch = datetime.strptime(self.results[entry], "%Y-%m-%d")
-                if (datetime.now() - last_patch) > timedelta(days=6*31):
-                    self.log.warning("This phone has not received security "
-                                     "updates for more than six months "
-                                     "(last update: %s)", self.results[entry])
-
-        self.log.info("Extracted a total of %d properties", len(self.results))

mvt/android/modules/androidqf/processes.py

@@ -1,92 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from .base import AndroidQFModule
-
-
-class Processes(AndroidQFModule):
-    """This module analyse running processes"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            proc_name = result.get("proc_name", "")
-            if not proc_name:
-                continue
-
-            # Skipping this process because of false positives.
-            if result["proc_name"] == "gatekeeperd":
-                continue
-
-            ioc = self.indicators.check_app_id(proc_name)
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-            ioc = self.indicators.check_process(proc_name)
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-
-    def _parse_ps(self, data):
-        for line in data.split("\n")[1:]:
-            proc = line.split()
-
-            # Sometimes WCHAN is empty.
-            if len(proc) == 8:
-                proc = proc[:5] + [''] + proc[5:]
-
-            # Sometimes there is the security label.
-            if proc[0].startswith("u:r"):
-                label = proc[0]
-                proc = proc[1:]
-            else:
-                label = ""
-
-            # Sometimes there is no WCHAN.
-            if len(proc) < 9:
-                proc = proc[:5] + [""] + proc[5:]
-
-            self.results.append({
-                "user": proc[0],
-                "pid": int(proc[1]),
-                "ppid": int(proc[2]),
-                "virtual_memory_size": int(proc[3]),
-                "resident_set_size": int(proc[4]),
-                "wchan": proc[5],
-                "aprocress": proc[6],
-                "stat": proc[7],
-                "proc_name": proc[8].strip("[]"),
-                "label": label,
-            })
-
-    def run(self) -> None:
-        ps_files = self._get_files_by_pattern("*/ps.txt")
-        if not ps_files:
-            return
-
-        with open(ps_files[0]) as handle:
-            self._parse_ps(handle.read())
-
-        self.log.info("Identified %d running processes", len(self.results))

mvt/android/modules/androidqf/settings.py

@@ -1,58 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.modules.adb.settings import ANDROID_DANGEROUS_SETTINGS
-
-from .base import AndroidQFModule
-
-
-class Settings(AndroidQFModule):
-    """This module analyse setting files"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-        self.results = {}
-
-    def run(self) -> None:
-        for setting_file in self._get_files_by_pattern("*/settings_*.txt"):
-            namespace = setting_file[setting_file.rfind("_")+1:-4]
-
-            self.results[namespace] = {}
-
-            with open(setting_file) as handle:
-                for line in handle:
-                    line = line.strip()
-                    try:
-                        key, value = line.split("=", 1)
-                    except ValueError:
-                        continue
-
-                    try:
-                        self.results[namespace][key] = value
-                    except IndexError:
-                        continue
-
-                    for danger in ANDROID_DANGEROUS_SETTINGS:
-                        if (danger["key"] == key
-                                and danger["safe_value"] != value):
-                            self.log.warning("Found suspicious setting \"%s = %s\" (%s)",
-                                             key, value, danger["description"])
-                            break
-
-        self.log.info("Identified %d settings",
-                      sum([len(val) for val in self.results.values()]))

mvt/android/modules/androidqf/sms.py

@@ -1,85 +0,0 @@
-# Mobile Verification Toolkit (MVT) - Private
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# This file is part of MVT Private and its content is confidential.
-# Please refer to the project maintainers before sharing with others.
-
-import getpass
-import logging
-from typing import Optional
-
-from mvt.android.parsers.backup import (AndroidBackupParsingError,
-                                        InvalidBackupPassword, parse_ab_header,
-                                        parse_backup_file, parse_tar_for_sms)
-
-from .base import AndroidQFModule
-
-
-class SMS(AndroidQFModule):
-    """This module analyse SMS file in backup"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for message in self.results:
-            if "body" not in message:
-                continue
-
-            if self.indicators.check_domains(message["links"]):
-                self.detected.append(message)
-
-    def parse_backup(self, data):
-        header = parse_ab_header(data)
-        if not header["backup"]:
-            self.log.critical("Invalid backup format, backup.ab was not analysed")
-            return
-
-        password = None
-        if header["encryption"] != "none":
-            password = getpass.getpass(prompt="Backup Password: ", stream=None)
-        try:
-            tardata = parse_backup_file(data, password=password)
-        except InvalidBackupPassword:
-            self.log.critical("Invalid backup password")
-            return
-        except AndroidBackupParsingError:
-            self.log.critical("Impossible to parse this backup file, please use"
-                              " Android Backup Extractor instead")
-            return
-
-        if not tardata:
-            return
-
-        try:
-            self.results = parse_tar_for_sms(tardata)
-        except AndroidBackupParsingError:
-            self.log.info("Impossible to read SMS from the Android Backup, "
-                          "please extract the SMS and try extracting it with "
-                          "Android Backup Extractor")
-            return
-
-    def run(self) -> None:
-        files = self._get_files_by_pattern("*/backup.ab")
-        if not files:
-            self.log.info("No backup data found")
-            return
-
-        with open(files[0], "rb") as handle:
-            data = handle.read()
-
-        self.parse_backup(data)
-        self.log.info("Identified %d SMS in backup data",
-                      len(self.results))

mvt/android/modules/backup/base.py

@@ -1,66 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import fnmatch
-import logging
-import os
-from tarfile import TarFile
-from typing import Optional, List
-
-from mvt.common.module import MVTModule
-
-
-class BackupExtraction(MVTModule):
-    """This class provides a base for all backup extractios modules"""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-        self.ab = None
-        self.backup_path = None
-        self.tar = None
-        self.files = []
-
-    def from_folder(self, backup_path: Optional[str], files: List[str]) -> None:
-        """
-        Get all the files and list them
-        """
-        self.backup_path = backup_path
-        self.files = files
-
-    def from_ab(self, file_path: Optional[str], tar: Optional[TarFile], files: List[str]) -> None:
-        """
-        Extract the files
-        """
-        self.ab = file_path
-        self.tar = tar
-        self.files = files
-
-    def _get_files_by_pattern(self, pattern: str) -> list:
-        return fnmatch.filter(self.files, pattern)
-
-    def _get_file_content(self, file_path: str) -> bytes:
-        if self.ab:
-            try:
-                member = self.tar.getmember(file_path)
-            except KeyError:
-                return None
-            handle = self.tar.extractfile(member)
-        else:
-            handle = open(os.path.join(self.backup_path, file_path), "rb")
-
-        data = handle.read()
-        handle.close()
-
-        return data

mvt/android/modules/backup/sms.py

@@ -1,54 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.modules.backup.base import BackupExtraction
-from mvt.android.parsers.backup import parse_sms_file
-
-
-class SMS(BackupExtraction):
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-        self.results = []
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for message in self.results:
-            if "body" not in message:
-                continue
-
-            if self.indicators.check_domains(message["links"]):
-                self.detected.append(message)
-
-    def run(self) -> None:
-        sms_path = "apps/com.android.providers.telephony/d_f/*_sms_backup"
-        for file in self._get_files_by_pattern(sms_path):
-            self.log.info("Processing SMS backup file at %s", file)
-            data = self._get_file_content(file)
-            self.results.extend(parse_sms_file(data))
-
-        mms_path = "apps/com.android.providers.telephony/d_f/*_mms_backup"
-        for file in self._get_files_by_pattern(mms_path):
-            self.log.info("Processing MMS backup file at %s", file)
-            data = self._get_file_content(file)
-            self.results.extend(parse_sms_file(data))
-
-        self.log.info("Extracted a total of %d SMS & MMS messages containing links",
-                      len(self.results))

mvt/android/modules/bugreport/__init__.py

@@ -1,17 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-from .accessibility import Accessibility
-from .activities import Activities
-from .appops import Appops
-from .battery_daily import BatteryDaily
-from .battery_history import BatteryHistory
-from .dbinfo import DBInfo
-from .getprop import Getprop
-from .packages import Packages
-from .receivers import Receivers
-
-BUGREPORT_MODULES = [Accessibility, Activities, Appops, BatteryDaily,
-                     BatteryHistory, DBInfo, Getprop, Packages, Receivers]

mvt/android/modules/bugreport/accessibility.py

@@ -1,69 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_accessibility
-
-from .base import BugReportModule
-
-
-class Accessibility(BugReportModule):
-    """This module extracts stats on accessibility."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        lines = []
-        in_accessibility = False
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE accessibility:":
-                in_accessibility = True
-                continue
-
-            if not in_accessibility:
-                continue
-
-            if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_accessibility("\n".join(lines))
-        for result in self.results:
-            self.log.info("Found installed accessibility service \"%s\"",
-                          result.get("service"))
-
-        self.log.info("Identified a total of %d accessibility services",
-                      len(self.results))

mvt/android/modules/bugreport/activities.py

@@ -1,68 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_activity_resolver_table
-
-from .base import BugReportModule
-
-
-class Activities(BugReportModule):
-    """This module extracts details on receivers for risky activities."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = results if results else {}
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for intent, activities in self.results.items():
-            for activity in activities:
-                ioc = self.indicators.check_app_id(activity["package_name"])
-                if ioc:
-                    activity["matched_indicator"] = ioc
-                    self.detected.append({intent: activity})
-                    continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        lines = []
-        in_package = False
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE package:":
-                in_package = True
-                continue
-
-            if not in_package:
-                continue
-
-            if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_activity_resolver_table("\n".join(lines))
-
-        self.log.info("Extracted activities for %d intents", len(self.results))

mvt/android/modules/bugreport/appops.py

@@ -1,88 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union
-
-from mvt.android.parsers import parse_dumpsys_appops
-
-from .base import BugReportModule
-
-
-class Appops(BugReportModule):
-    """This module extracts information on package from App-Ops Manager."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        records = []
-        for perm in record["permissions"]:
-            if "entries" not in perm:
-                continue
-
-            for entry in perm["entries"]:
-                if "timestamp" in entry:
-                    records.append({
-                        "timestamp": entry["timestamp"],
-                        "module": self.__class__.__name__,
-                        "event": entry["access"],
-                        "data": f"{record['package_name']} access to "
-                                f"{perm['name']}: {entry['access']}",
-                    })
-
-        return records
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if self.indicators:
-                ioc = self.indicators.check_app_id(result.get("package_name"))
-                if ioc:
-                    result["matched_indicator"] = ioc
-                    self.detected.append(result)
-                    continue
-
-            for perm in result["permissions"]:
-                if (perm["name"] == "REQUEST_INSTALL_PACKAGES"
-                        and perm["access"] == "allow"):
-                    self.log.info("Package %s with REQUEST_INSTALL_PACKAGES permission",
-                                  result["package_name"])
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        lines = []
-        in_appops = False
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE appops:":
-                in_appops = True
-                continue
-
-            if not in_appops:
-                continue
-
-            if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_appops("\n".join(lines))
-
-        self.log.info("Identified a total of %d packages in App-Ops Manager",
-                      len(self.results))

mvt/android/modules/bugreport/base.py

@@ -1,88 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# See the file 'LICENSE' for usage and copying permissions, or find a copy at
-#   https://github.com/mvt-project/mvt/blob/main/LICENSE
-
-import fnmatch
-import logging
-import os
-from typing import Optional, List
-from zipfile import ZipFile
-
-from mvt.common.module import MVTModule
-
-
-class BugReportModule(MVTModule):
-    """This class provides a base for all Android Bug Report modules."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.zip_archive: Optional[ZipFile] = None
-        self.extract_path: Optional[str] = None
-        self.extract_files: List[str] = []
-        self.zip_files: List[str] = []
-
-    def from_folder(self, extract_path: Optional[str], extract_files: List[str]) -> None:
-        self.extract_path = extract_path
-        self.extract_files = extract_files
-
-    def from_zip(self, zip_archive: Optional[ZipFile], zip_files: List[str]) -> None:
-        self.zip_archive = zip_archive
-        self.zip_files = zip_files
-
-    def _get_files_by_pattern(self, pattern: str) -> list:
-        file_names = []
-        if self.zip_archive:
-            for zip_file in self.zip_files:
-                file_names.append(zip_file)
-        else:
-            file_names = self.extract_files
-
-        return fnmatch.filter(file_names, pattern)
-
-    def _get_files_by_patterns(self, patterns: list) -> list:
-        for pattern in patterns:
-            matches = self._get_files_by_pattern(pattern)
-            if matches:
-                return matches
-
-        return []
-
-    def _get_file_content(self, file_path: str) -> bytes:
-        if self.zip_archive:
-            handle = self.zip_archive.open(file_path)
-        else:
-            handle = open(os.path.join(self.extract_path, file_path), "rb")
-
-        data = handle.read()
-        handle.close()
-
-        return data
-
-    def _get_dumpstate_file(self) -> bytes:
-        main = self._get_files_by_pattern("main_entry.txt")
-        if main:
-            main_content = self._get_file_content(main[0])
-            try:
-                return self._get_file_content(main_content.decode().strip())
-            except KeyError:
-                return None
-        else:
-            dumpstate_logs = self._get_files_by_pattern("dumpState_*.log")
-            if not dumpstate_logs:
-                return None
-
-            return self._get_file_content(dumpstate_logs[0])
-
-        return None

mvt/android/modules/bugreport/battery_daily.py

@@ -1,84 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union
-
-from mvt.android.parsers import parse_dumpsys_battery_daily
-
-from .base import BugReportModule
-
-
-class BatteryDaily(BugReportModule):
-    """This module extracts records from battery daily updates."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        return {
-            "timestamp": record["from"],
-            "module": self.__class__.__name__,
-            "event": "battery_daily",
-            "data": f"Recorded update of package {record['package_name']} "
-                    f"with vers {record['vers']}"
-        }
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        lines = []
-        in_batterystats = False
-        in_daily = False
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE batterystats:":
-                in_batterystats = True
-                continue
-
-            if not in_batterystats:
-                continue
-
-            if line.strip() == "Daily stats:":
-                lines.append(line)
-                in_daily = True
-                continue
-
-            if not in_daily:
-                continue
-
-            if line.strip() == "":
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_battery_daily("\n".join(lines))
-
-        self.log.info("Extracted a total of %d battery daily stats",
-                      len(self.results))

mvt/android/modules/bugreport/battery_history.py

@@ -1,67 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_battery_history
-
-from .base import BugReportModule
-
-
-class BatteryHistory(BugReportModule):
-    """This module extracts records from battery daily updates."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            ioc = self.indicators.check_app_id(result["package_name"])
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        lines = []
-        in_history = False
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip().startswith("Battery History "):
-                lines.append(line)
-                in_history = True
-                continue
-
-            if not in_history:
-                continue
-
-            if line.strip() == "":
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_battery_history("\n".join(lines))
-
-        self.log.info("Extracted a total of %d battery history records",
-                      len(self.results))

mvt/android/modules/bugreport/dbinfo.py

@@ -1,70 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_dbinfo
-
-from .base import BugReportModule
-
-
-class DBInfo(BugReportModule):
-    """This module extracts records from battery daily updates."""
-
-    slug = "dbinfo"
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for result in self.results:
-            path = result.get("path", "")
-            for part in path.split("/"):
-                ioc = self.indicators.check_app_id(part)
-                if ioc:
-                    result["matched_indicator"] = ioc
-                    self.detected.append(result)
-                    continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        in_dbinfo = False
-        lines = []
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE dbinfo:":
-                in_dbinfo = True
-                continue
-
-            if not in_dbinfo:
-                continue
-
-            if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_dbinfo("\n".join(lines))
-
-        self.log.info("Extracted a total of %d database connection pool records",
-                      len(self.results))

mvt/android/modules/bugreport/getprop.py

@@ -1,67 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from datetime import datetime, timedelta
-from typing import Optional
-
-from mvt.android.parsers import parse_getprop
-
-from .base import BugReportModule
-
-
-class Getprop(BugReportModule):
-    """This module extracts device properties from getprop command."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = {} if not results else results
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        lines = []
-        in_getprop = False
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "------ SYSTEM PROPERTIES (getprop) ------":
-                in_getprop = True
-                continue
-
-            if not in_getprop:
-                continue
-
-            if line.strip() == "------":
-                break
-
-            lines.append(line)
-
-        self.results = parse_getprop("\n".join(lines))
-
-        # Alert if phone is outdated.
-        security_patch = self.results.get("ro.build.version.security_patch", "")
-        if security_patch:
-            patch_date = datetime.strptime(security_patch, "%Y-%m-%d")
-            if (datetime.now() - patch_date) > timedelta(days=6*30):
-                self.log.warning("This phone has not received security updates "
-                                 "for more than six months (last update: %s)",
-                                 security_patch)
-
-        self.log.info("Extracted %d Android system properties",
-                      len(self.results))

mvt/android/modules/bugreport/packages.py

@@ -1,122 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional, Union
-
-from mvt.android.modules.adb.packages import (DANGEROUS_PERMISSIONS,
-                                              DANGEROUS_PERMISSIONS_THRESHOLD,
-                                              ROOT_PACKAGES)
-from mvt.android.parsers.dumpsys import parse_dumpsys_packages
-
-from .base import BugReportModule
-
-
-class Packages(BugReportModule):
-    """This module extracts details on receivers for risky activities."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-    def serialize(self, record: dict) -> Union[dict, list]:
-        records = []
-
-        timestamps = [
-            {
-                "event": "package_install",
-                "timestamp": record["timestamp"]
-            },
-            {
-                "event": "package_first_install",
-                "timestamp": record["first_install_time"]
-            },
-            {
-                "event": "package_last_update",
-                "timestamp": record["last_update_time"]
-            },
-        ]
-
-        for timestamp in timestamps:
-            records.append({
-                "timestamp": timestamp["timestamp"],
-                "module": self.__class__.__name__,
-                "event": timestamp["event"],
-                "data": f"Install or update of package {record['package_name']}",
-            })
-
-        return records
-
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if result["package_name"] in ROOT_PACKAGES:
-                self.log.warning("Found an installed package related to "
-                                 "rooting/jailbreaking: \"%s\"",
-                                 result["package_name"])
-                self.detected.append(result)
-                continue
-
-            if not self.indicators:
-                continue
-
-            ioc = self.indicators.check_app_id(result.get("package_name"))
-            if ioc:
-                result["matched_indicator"] = ioc
-                self.detected.append(result)
-                continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        in_package = False
-        in_packages_list = False
-        lines = []
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE package:":
-                in_package = True
-                continue
-
-            if not in_package:
-                continue
-
-            if line.strip() == "Packages:":
-                in_packages_list = True
-                continue
-
-            if not in_packages_list:
-                continue
-
-            if line.strip() == "":
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_packages("\n".join(lines))
-
-        for result in self.results:
-            dangerous_permissions_count = 0
-            for perm in result["permissions"]:
-                if perm["name"] in DANGEROUS_PERMISSIONS:
-                    dangerous_permissions_count += 1
-
-            if dangerous_permissions_count >= DANGEROUS_PERMISSIONS_THRESHOLD:
-                self.log.info("Found package \"%s\" requested %d potentially dangerous permissions",
-                              result["package_name"],
-                              dangerous_permissions_count)
-
-        self.log.info("Extracted details on %d packages", len(self.results))

mvt/android/modules/bugreport/receivers.py

@@ -1,91 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# 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
-from typing import Optional
-
-from mvt.android.parsers import parse_dumpsys_receiver_resolver_table
-
-from .base import BugReportModule
-
-INTENT_NEW_OUTGOING_SMS = "android.provider.Telephony.NEW_OUTGOING_SMS"
-INTENT_SMS_RECEIVED = "android.provider.Telephony.SMS_RECEIVED"
-INTENT_DATA_SMS_RECEIVED = "android.intent.action.DATA_SMS_RECEIVED"
-INTENT_PHONE_STATE = "android.intent.action.PHONE_STATE"
-INTENT_NEW_OUTGOING_CALL = "android.intent.action.NEW_OUTGOING_CALL"
-
-
-class Receivers(BugReportModule):
-    """This module extracts details on receivers for risky activities."""
-
-    def __init__(
-        self,
-        file_path: Optional[str] = None,
-        target_path: Optional[str] = None,
-        results_path: Optional[str] = None,
-        fast_mode: Optional[bool] = False,
-        log: logging.Logger = logging.getLogger(__name__),
-        results: Optional[list] = None
-    ) -> None:
-        super().__init__(file_path=file_path, target_path=target_path,
-                         results_path=results_path, fast_mode=fast_mode,
-                         log=log, results=results)
-
-        self.results = results if results else {}
-
-    def check_indicators(self) -> None:
-        if not self.indicators:
-            return
-
-        for intent, receivers in self.results.items():
-            for receiver in receivers:
-                if intent == INTENT_NEW_OUTGOING_SMS:
-                    self.log.info("Found a receiver to intercept outgoing SMS messages: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_SMS_RECEIVED:
-                    self.log.info("Found a receiver to intercept incoming SMS messages: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_DATA_SMS_RECEIVED:
-                    self.log.info("Found a receiver to intercept incoming data SMS message: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_PHONE_STATE:
-                    self.log.info("Found a receiver monitoring "
-                                  "telephony state/incoming calls: \"%s\"",
-                                  receiver["receiver"])
-                elif intent == INTENT_NEW_OUTGOING_CALL:
-                    self.log.info("Found a receiver monitoring outgoing calls: \"%s\"",
-                                  receiver["receiver"])
-
-                ioc = self.indicators.check_app_id(receiver["package_name"])
-                if ioc:
-                    receiver["matched_indicator"] = ioc
-                    self.detected.append({intent: receiver})
-                    continue
-
-    def run(self) -> None:
-        content = self._get_dumpstate_file()
-        if not content:
-            self.log.error("Unable to find dumpstate file. "
-                           "Did you provide a valid bug report archive?")
-            return
-
-        in_receivers = False
-        lines = []
-        for line in content.decode(errors="ignore").splitlines():
-            if line.strip() == "DUMP OF SERVICE package:":
-                in_receivers = True
-                continue
-
-            if not in_receivers:
-                continue
-
-            if line.strip().startswith("------------------------------------------------------------------------------"):  # pylint: disable=line-too-long
-                break
-
-            lines.append(line)
-
-        self.results = parse_dumpsys_receiver_resolver_table("\n".join(lines))
-
-        self.log.info("Extracted receivers for %d intents", len(self.results))

mvt/android/parsers/__init__.py

@@ -1,11 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-from .dumpsys import (parse_dumpsys_accessibility,
-                      parse_dumpsys_activity_resolver_table,
-                      parse_dumpsys_appops, parse_dumpsys_battery_daily,
-                      parse_dumpsys_battery_history, parse_dumpsys_dbinfo,
-                      parse_dumpsys_receiver_resolver_table)
-from .getprop import parse_getprop

mvt/android/parsers/dumpsys.py

@@ -1,521 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import re
-from typing import List, Dict, Any
-from datetime import datetime
-
-from mvt.common.utils import convert_datetime_to_iso
-
-
-def parse_dumpsys_accessibility(output: str) -> List[Dict[str, str]]:
-    results = []
-
-    in_services = False
-    for line in output.splitlines():
-        if line.strip().startswith("installed services:"):
-            in_services = True
-            continue
-
-        if not in_services:
-            continue
-
-        if line.strip() == "}":
-            break
-
-        service = line.split(":")[1].strip()
-
-        results.append({
-            "package_name": service.split("/")[0],
-            "service": service,
-        })
-
-    return results
-
-
-def parse_dumpsys_activity_resolver_table(output: str) -> Dict[str, Any]:
-    results = {}
-
-    in_activity_resolver_table = False
-    in_non_data_actions = False
-    intent = None
-    for line in output.splitlines():
-        if line.startswith("Activity Resolver Table:"):
-            in_activity_resolver_table = True
-            continue
-
-        if not in_activity_resolver_table:
-            continue
-
-        if line.startswith("  Non-Data Actions:"):
-            in_non_data_actions = True
-            continue
-
-        if not in_non_data_actions:
-            continue
-
-        # If we hit an empty line, the Non-Data Actions section should be
-        # finished.
-        if line.strip() == "":
-            break
-
-        # We detect the action name.
-        if (line.startswith(" " * 6) and not line.startswith(" " * 8)
-                and ":" in line):
-            intent = line.strip().replace(":", "")
-            results[intent] = []
-            continue
-
-        # If we are not in an intent block yet, skip.
-        if not intent:
-            continue
-
-        # If we are in a block but the line does not start with 8 spaces
-        # it means the block ended a new one started, so we reset and
-        # continue.
-        if not line.startswith(" " * 8):
-            intent = None
-            continue
-
-        # If we got this far, we are processing receivers for the
-        # activities we are interested in.
-        activity = line.strip().split(" ")[1]
-        package_name = activity.split("/")[0]
-
-        results[intent].append({
-            "package_name": package_name,
-            "activity": activity,
-        })
-
-    return results
-
-
-def parse_dumpsys_battery_daily(output: str) -> list:
-    results = []
-    daily = None
-    daily_updates = []
-    for line in output.splitlines():
-        if line.startswith("  Daily from "):
-            if len(daily_updates) > 0:
-                results.extend(daily_updates)
-                daily_updates = []
-
-            timeframe = line[13:].strip()
-            date_from, date_to = timeframe.strip(":").split(" to ", 1)
-            daily = {"from": date_from[0:10], "to": date_to[0:10]}
-            continue
-
-        if not daily:
-            continue
-
-        if not line.strip().startswith("Update "):
-            continue
-
-        line = line.strip().replace("Update ", "")
-        package_name, vers = line.split(" ", 1)
-        vers_nr = vers.split("=", 1)[1]
-
-        already_seen = False
-        for update in daily_updates:
-            if (package_name == update["package_name"]
-                    and vers_nr == update["vers"]):
-                already_seen = True
-                break
-
-        if not already_seen:
-            daily_updates.append({
-                "action": "update",
-                "from": daily["from"],
-                "to": daily["to"],
-                "package_name": package_name,
-                "vers": vers_nr,
-            })
-
-    if len(daily_updates) > 0:
-        results.extend(daily_updates)
-
-    return results
-
-
-def parse_dumpsys_battery_history(output: str) -> List[Dict[str, Any]]:
-    results = []
-
-    for line in output.splitlines():
-        if line.startswith("Battery History "):
-            continue
-
-        if line.strip() == "":
-            break
-
-        time_elapsed = line.strip().split(" ", 1)[0]
-
-        event = ""
-        if line.find("+job") > 0:
-            event = "start_job"
-            uid = line[line.find("+job")+5:line.find(":")]
-            service = line[line.find(":")+1:].strip('"')
-            package_name = service.split("/")[0]
-        elif line.find("-job") > 0:
-            event = "end_job"
-            uid = line[line.find("-job")+5:line.find(":")]
-            service = line[line.find(":")+1:].strip('"')
-            package_name = service.split("/")[0]
-        elif line.find("+running +wake_lock=") > 0:
-            uid = line[line.find("+running +wake_lock=")+21:line.find(":")]
-            event = "wake"
-            service = line[line.find("*walarm*:")+9:].split(" ")[0].strip('"').strip()
-            if service == "" or "/" not in service:
-                continue
-
-            package_name = service.split("/")[0]
-        elif (line.find("+top=") > 0) or (line.find("-top") > 0):
-            if line.find("+top=") > 0:
-                event = "start_top"
-                top_pos = line.find("+top=")
-            else:
-                event = "end_top"
-                top_pos = line.find("-top=")
-            colon_pos = top_pos+line[top_pos:].find(":")
-            uid = line[top_pos+5:colon_pos]
-            service = ""
-            package_name = line[colon_pos+1:].strip('"')
-        else:
-            continue
-
-        results.append({
-            "time_elapsed": time_elapsed,
-            "event": event,
-            "uid": uid,
-            "package_name": package_name,
-            "service": service,
-        })
-
-    return results
-
-
-def parse_dumpsys_dbinfo(output: str) -> List[Dict[str, Any]]:
-    results = []
-
-    rxp = re.compile(r'.*\[([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3})\].*\[Pid:\((\d+)\)\](\w+).*sql\=\"(.+?)\"')  # pylint: disable=line-too-long
-    rxp_no_pid = re.compile(r'.*\[([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3})\][ ]{1}(\w+).*sql\=\"(.+?)\"')  # pylint: disable=line-too-long
-
-    pool = None
-    in_operations = False
-    for line in output.splitlines():
-        if line.startswith("Connection pool for "):
-            pool = line.replace("Connection pool for ", "").rstrip(":")
-
-        if not pool:
-            continue
-
-        if line.strip() == "Most recently executed operations:":
-            in_operations = True
-            continue
-
-        if not in_operations:
-            continue
-
-        if not line.startswith("        "):
-            in_operations = False
-            pool = None
-            continue
-
-        matches = rxp.findall(line)
-        if not matches:
-            matches = rxp_no_pid.findall(line)
-            if not matches:
-                continue
-
-            match = matches[0]
-            results.append({
-                "isodate": match[0],
-                "action": match[1],
-                "sql": match[2],
-                "path": pool,
-            })
-        else:
-            match = matches[0]
-            results.append({
-                "isodate": match[0],
-                "pid": match[1],
-                "action": match[2],
-                "sql": match[3],
-                "path": pool,
-            })
-
-    return results
-
-
-def parse_dumpsys_receiver_resolver_table(output: str) -> Dict[str, Any]:
-    results = {}
-
-    in_receiver_resolver_table = False
-    in_non_data_actions = False
-    intent = None
-    for line in output.splitlines():
-        if line.startswith("Receiver Resolver Table:"):
-            in_receiver_resolver_table = True
-            continue
-
-        if not in_receiver_resolver_table:
-            continue
-
-        if line.startswith("  Non-Data Actions:"):
-            in_non_data_actions = True
-            continue
-
-        if not in_non_data_actions:
-            continue
-
-        # If we hit an empty line, the Non-Data Actions section should be
-        # finished.
-        if line.strip() == "":
-            break
-
-        # We detect the action name.
-        if (line.startswith(" " * 6) and not line.startswith(" " * 8)
-                and ":" in line):
-            intent = line.strip().replace(":", "")
-            results[intent] = []
-            continue
-
-        # If we are not in an intent block yet, skip.
-        if not intent:
-            continue
-
-        # If we are in a block but the line does not start with 8 spaces
-        # it means the block ended a new one started, so we reset and
-        # continue.
-        if not line.startswith(" " * 8):
-            intent = None
-            continue
-
-        # If we got this far, we are processing receivers for the
-        # activities we are interested in.
-        receiver = line.strip().split(" ")[1]
-        package_name = receiver.split("/")[0]
-
-        results[intent].append({
-            "package_name": package_name,
-            "receiver": receiver,
-        })
-
-    return results
-
-
-def parse_dumpsys_appops(output: str) -> List[Dict[str, Any]]:
-    results = []
-    perm = {}
-    package = {}
-    entry = {}
-    uid = None
-    in_packages = False
-
-    for line in output.splitlines():
-        if line.startswith("  Uid 0:"):
-            in_packages = True
-
-        if not in_packages:
-            continue
-
-        if line.startswith("  Uid "):
-            uid = line[6:-1]
-            continue
-
-        if line.startswith("    Package "):
-            if entry:
-                perm["entries"].append(entry)
-                entry = {}
-
-            if package:
-                if perm:
-                    package["permissions"].append(perm)
-
-                perm = {}
-                results.append(package)
-
-            package = {
-                "package_name": line[12:-1],
-                "permissions": [],
-                "uid": uid,
-            }
-            continue
-
-        if line.startswith("      ") and line[6] != " ":
-            if entry:
-                perm["entries"].append(entry)
-                entry = {}
-            if perm:
-                package["permissions"].append(perm)
-                perm = {}
-
-            perm["name"] = line.split()[0]
-            perm["entries"] = []
-            if len(line.split()) > 1:
-                perm["access"] = line.split()[1][1:-2]
-
-            continue
-
-        if line.startswith("          "):
-            # Permission entry like:
-            # Reject: [fg-s]2021-05-19 22:02:52.054 (-314d1h25m2s33ms)
-            if entry:
-                perm["entries"].append(entry)
-                entry = {}
-
-            entry["access"] = line.split(":")[0].strip()
-            entry["type"] = line[line.find("[")+1:line.find("]")]
-
-            try:
-                entry["timestamp"] = convert_datetime_to_iso(
-                    datetime.strptime(
-                        line[line.find("]")+1:line.find("(")].strip(),
-                        "%Y-%m-%d %H:%M:%S.%f"))
-            except ValueError:
-                # Invalid date format
-                pass
-
-        if line.strip() == "":
-            break
-
-    if entry:
-        perm["entries"].append(entry)
-    if perm:
-        package["permissions"].append(perm)
-    if package:
-        results.append(package)
-
-    return results
-
-
-def parse_dumpsys_package_for_details(output: str) -> Dict[str, Any]:
-    """
-    Parse one entry of a dumpsys package information
-    """
-    details = {
-        "uid": "",
-        "version_name": "",
-        "version_code": "",
-        "timestamp": "",
-        "first_install_time": "",
-        "last_update_time": "",
-        "permissions": [],
-        "requested_permissions": [],
-    }
-
-    in_install_permissions = False
-    in_runtime_permissions = False
-    in_declared_permissions = False
-    in_requested_permissions = True
-    for line in output.splitlines():
-        if in_install_permissions:
-            if line.startswith(" " * 4) and not line.startswith(" " * 6):
-                in_install_permissions = False
-            else:
-                lineinfo = line.strip().split(":")
-                permission = lineinfo[0]
-                granted = None
-                if "granted=" in lineinfo[1]:
-                    granted = ("granted=true" in lineinfo[1])
-
-                details["permissions"].append({
-                    "name": permission,
-                    "granted": granted,
-                    "type": "install"
-                })
-
-        if in_runtime_permissions:
-            if not line.startswith(" " * 8):
-                in_runtime_permissions = False
-            else:
-                lineinfo = line.strip().split(":")
-                permission = lineinfo[0]
-                granted = None
-                if "granted=" in lineinfo[1]:
-                    granted = ("granted=true" in lineinfo[1])
-
-                details["permissions"].append({
-                    "name": permission,
-                    "granted": granted,
-                    "type": "runtime"
-                })
-
-        if in_declared_permissions:
-            if not line.startswith(" " * 6):
-                in_declared_permissions = False
-            else:
-                permission = line.strip().split(":")[0]
-                details["permissions"].append({
-                    "name": permission,
-                    "type": "declared"
-                })
-        if in_requested_permissions:
-            if not line.startswith(" " * 6):
-                in_requested_permissions = False
-            else:
-                details["requested_permissions"].append(line.strip())
-
-        if line.strip().startswith("userId="):
-            details["uid"] = line.split("=")[1].strip()
-        elif line.strip().startswith("versionName="):
-            details["version_name"] = line.split("=")[1].strip()
-        elif line.strip().startswith("versionCode="):
-            details["version_code"] = line.split("=", 1)[1].strip()
-        elif line.strip().startswith("timeStamp="):
-            details["timestamp"] = line.split("=")[1].strip()
-        elif line.strip().startswith("firstInstallTime="):
-            details["first_install_time"] = line.split("=")[1].strip()
-        elif line.strip().startswith("lastUpdateTime="):
-            details["last_update_time"] = line.split("=")[1].strip()
-        elif line.strip() == "install permissions:":
-            in_install_permissions = True
-        elif line.strip() == "runtime permissions:":
-            in_runtime_permissions = True
-        elif line.strip() == "declared permissions:":
-            in_declared_permissions = True
-        elif line.strip() == "requested permissions:":
-            in_requested_permissions = True
-
-    return details
-
-
-def parse_dumpsys_packages(output: str) -> List[Dict[str, Any]]:
-    """
-    Parse the dumpsys package service data
-    """
-    pkg_rxp = re.compile(r"  Package \[(.+?)\].*")
-
-    results = []
-    package_name = None
-    package = {}
-    lines = []
-    for line in output.splitlines():
-        if line.startswith("  Package ["):
-            if len(lines) > 0:
-                details = parse_dumpsys_package_for_details("\n".join(lines))
-                package.update(details)
-                results.append(package)
-                lines = []
-                package = {}
-
-            matches = pkg_rxp.findall(line)
-            if not matches:
-                continue
-
-            package_name = matches[0]
-            package["package_name"] = package_name
-            continue
-
-        if not package_name:
-            continue
-
-        lines.append(line)
-
-    if len(lines) > 0:
-        details = parse_dumpsys_package_for_details("\n".join(lines))
-        package.update(details)
-        results.append(package)
-
-    return results

mvt/android/parsers/getprop.py

@@ -1,26 +0,0 @@
-# Mobile Verification Toolkit (MVT)
-# Copyright (c) 2021-2023 Claudio Guarnieri.
-# Use of this software is governed by the MVT License 1.1 that can be found at
-#   https://license.mvt.re/1.1/
-
-import re
-
-
-def parse_getprop(output: str) -> dict:
-    results = {}
-    rxp = re.compile(r"\[(.+?)\]: \[(.+?)\]")
-
-    for line in output.splitlines():
-        line = line.strip()
-        if line == "":
-            continue
-
-        matches = re.findall(rxp, line)
-        if not matches or len(matches[0]) != 2:
-            continue
-
-        key = matches[0][0]
-        value = matches[0][1]
-        results[key] = value
-
-    return results