mirror of
https://github.com/mvt-project/mvt.git
synced 2026-09-03 00:21:07 +02:00
Donncha Ó Cearbhaill
a78894aaa5
* Add a platform-neutral mvt command 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. * Reduce indent for MVT CLI header * Move shell completion to the mvt command and generate one script for every MVT command Setting up shell completion had nothing to do with the acquisition of one platform, yet it was a command of mvt-ios and mvt-android, each generating the script of the program it ran under only. Completion now leaves the platform CLIs for mvt, which emits one script covering mvt, mvt-ios and mvt-android, installed as a single file loaded when the shell starts. Click names the completion function of each program after the program, so the three scripts concatenate without colliding, and fish takes the file in conf.d rather than one named after a single command. With one script there is nothing left for the platform commands to generate, so their completion command goes, and with it the banner suppression which was keyed on the command name: mvt-ios and mvt-android now print the banner for every command they have. The long help line says which commands the completion covers, so a short_help keeps "mvt --help" from truncating it. * Point the README and the command docs at plugin packages Loading a command by path is for local development; a package is how a command is distributed. The README's summary of what extends MVT now names plugin packages and nothing else, and the section on loading a command file says what it is for: keeping a command being written loadable without reinstalling its package after every change.
105 lines
3.7 KiB
Markdown
105 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
## Dependencies on Linux
|
|
|
|
First install some basic dependencies that will be necessary to build all required tools:
|
|
|
|
```bash
|
|
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
|
|
|
|
Running MVT on macOS requires Xcode and [homebrew](https://brew.sh) to be installed.
|
|
|
|
In order to install dependencies use:
|
|
|
|
```bash
|
|
brew install python3 pipx libusb sqlite3
|
|
```
|
|
|
|
*libusb* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
|
|
|
|
When working with Android devices you should additionally install [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools):
|
|
|
|
```bash
|
|
brew install --cask android-platform-tools
|
|
```
|
|
|
|
Or by downloading the [official binary releases](https://developer.android.com/studio/releases/platform-tools).
|
|
|
|
## MVT on Windows
|
|
|
|
MVT does not currently officially support running natively on Windows. While most functionality should work out of the box, there are known issues especially with `mvt-android`.
|
|
|
|
It is recommended to try installing and running MVT from [Windows Subsystem Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/about) and follow Linux installation instructions for your distribution of choice.
|
|
|
|
## Installing MVT
|
|
|
|
### 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
|
|
python3 -m venv env
|
|
```
|
|
|
|
2. Activate the virtual environment:
|
|
```bash
|
|
source env/bin/activate
|
|
```
|
|
|
|
3. Install `mvt` into the virtual environment:
|
|
```bash
|
|
pip install mvt
|
|
```
|
|
|
|
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)
|