mirror of
https://github.com/mvt-project/mvt.git
synced 2026-08-16 16:10:25 +02:00
108 lines
3.2 KiB
Markdown
108 lines
3.2 KiB
Markdown
# Custom CLI Commands
|
|
|
|
MVT can load additional top-level commands into `mvt-ios` and `mvt-android`.
|
|
Custom commands are different from [custom forensic modules](development.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 for either MVT CLI. 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}")
|
|
```
|
|
|
|
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"
|
|
```
|
|
|
|
Use only the iOS or Android group if the command is platform-specific. After
|
|
installing the package in the same environment as MVT, it appears directly in
|
|
the appropriate CLI:
|
|
|
|
```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.
|
|
|
|
## Load a Command File
|
|
|
|
For local commands that are not packaged, 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 platform-specific
|
|
environment variable:
|
|
|
|
```bash
|
|
export MVT_IOS_CUSTOM_COMMANDS=./ios_commands
|
|
export MVT_ANDROID_CUSTOM_COMMANDS=./android_commands
|
|
```
|
|
|
|
## Naming and Errors
|
|
|
|
Built-in MVT commands cannot be replaced. External command names must also be
|
|
unique; when installed packages or environment paths collide, MVT keeps the
|
|
first command and logs a warning. 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`.
|