mirror of
https://github.com/mvt-project/mvt.git
synced 2026-09-03 08:30:51 +02:00
Donncha Ó Cearbhaill
c95e6659c6
Several MVT commands have nothing to do with the acquisition of one platform, yet they were reachable only through mvt-ios and mvt-android. Asking which version is installed or downloading the public indicators meant picking one of the two platform commands arbitrarily, and each of those tasks had to be written, documented and maintained twice. Add a third console script, mvt, hosting the commands which belong to no platform: version and download-iocs for now, with completion following in a later commit. Commands installed in the new mvt.cli_plugins entry-point group are registered on mvt, and on mvt only, so that a command package chooses the CLI each of its commands is added to: mvt.ios.cli_plugins for mvt-ios, mvt.android.cli_plugins for mvt-android and mvt.cli_plugins for mvt. A command wanted on both platform CLIs is registered in both platform groups; no group adds a command to every CLI. The MVT_CUSTOM_COMMANDS variable loads command files and folders into mvt the way the platform variables already do for mvt-ios and mvt-android. Run on its own, mvt prints the banner and its help instead of a usage error. The help text reminds that the forensic analysis of an acquisition runs through mvt-ios and mvt-android, so that the command which knows nothing about acquisitions says where they are analysed. version and download-iocs stay on mvt-ios and mvt-android for now, so that no documented invocation stops working. They are to be dropped from the platform CLIs in a later release, once mvt has been available long enough for the change to be announced. Unlike mvt-ios and mvt-android, which point at their subpackages, the console script points at mvt.cli:main and the mvt package re-exports nothing of it. Importing mvt has to stay cheap and free of side effects: it is the package plugins import from, and pulling in Click, the CLI and everything the commands import merely because something imported mvt would work against that. While here, give the version command of both platform CLIs the context settings every other command already has, so that "mvt-ios version -h" prints its help instead of failing on an unknown option.
94 lines
5.4 KiB
Markdown
94 lines
5.4 KiB
Markdown
<p align="center">
|
||
<img src="https://docs.mvt.re/en/latest/mvt.png" width="200" />
|
||
</p>
|
||
|
||
# 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://pypi.org/project/mvt/)
|
||
[](https://docs.mvt.re/en/latest/?badge=latest)
|
||
[](https://github.com/mvt-project/mvt/actions/workflows/tests.yml)
|
||
[](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://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.
|
||
|
||
> **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/)):
|
||
|
||
```
|
||
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 three commands: `mvt-ios` and `mvt-android` analyse acquisitions from devices of that platform, and `mvt` hosts what belongs to neither: `version` and `download-iocs` (both 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/)
|
||
|
||
### Shell completion
|
||
|
||
MVT can generate shell completion scripts for Bash, Zsh, and Fish:
|
||
|
||
```bash
|
||
mvt-ios completion
|
||
mvt-android completion
|
||
```
|
||
|
||
The commands print setup instructions by default. To generate a completion script directly, pass the shell name:
|
||
|
||
```bash
|
||
mvt-ios completion bash
|
||
mvt-android completion zsh
|
||
```
|
||
|
||
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.
|
||
Module-running `check-*` commands can load custom Python modules with
|
||
`--load-module PATH` or from a folder set in `MVT_CUSTOM_MODULES`. See the
|
||
[development documentation](https://docs.mvt.re/en/latest/development/) for
|
||
details.
|
||
|
||
Users can also add top-level commands to `mvt`, `mvt-ios` and `mvt-android`
|
||
from installed Python packages or local files and folders. See the
|
||
[custom CLI command documentation](https://docs.mvt.re/en/latest/development/custom_commands/)
|
||
for the plugin entry points and `--load-command` interface.
|
||
|
||
|
||
## License
|
||
|
||
The purpose of MVT is to facilitate the ***consensual forensic analysis*** of devices of those who might be targets of sophisticated mobile spyware attacks, especially members of civil society and marginalized communities. We do not want MVT to enable privacy violations of non-consenting individuals. In order to achieve this, MVT is released under its own license. [Read more here.](https://docs.mvt.re/en/latest/license/)
|