Donncha Ó CearbhaillandDonncha Ó Cearbhaill
097766a63b
* Add namespaced plugin configuration support Plugin packages need somewhere to keep their own settings, but MVT rewrites its config.yaml with only the fields it knows about, so any foreign section is dropped. Add MVTPluginSettings, a pydantic-settings base class that gives each plugin its own file under the MVT config folder and its own MVT_PLUGIN_<NAME>_ environment variable namespace. Settings resolve from constructor arguments, then the environment, then the plugin file, then the field defaults. Saving skips the values the environment currently supplies, so credentials passed as environment variables are not copied to disk, and writes through a private temporary file so a settings file is never partially written or briefly readable by other users. * Add per-plugin data folders Plugins had no sanctioned place to keep the data they persist, so the plugin configuration documentation suggested a CACHE_FOLDER setting defaulting to ~/.cache/example-plugin. That is a Linux convention which is wrong on macOS, nothing expands or creates it, and it turns a path into a setting a user can be asked to configure. Add plugin_data_folder(), which returns the folder a plugin should use for caches, downloaded artifacts, synchronization state or anything else it writes to disk, and creates it if it is missing. The plugin name is validated before anything is created, so a name holding a path separator raises an error and leaves no folder behind, and calling the function again returns the same folder with its contents untouched. The folder sits under plugin-data rather than under the plugins folder which holds the settings files. On macOS the configuration folder and the data folder are the same directory, so reusing the plugins name would leave each plugin's data folder in among the settings files. Both the plugin-data folder and the folder of each plugin are created with 0700 permissions. MVT is a forensic tool, and what a plugin keeps there, such as API responses or sample metadata, is private by default. The path is resolved on every call, as the configuration folder already is, so it follows the current environment rather than whatever it was when MVT was imported. The documentation now points plugins at the helper, and the example settings class carries a plain integer setting in place of its cache folder. * Derive the data folder of a plugin from its settings class A plugin with a settings class already names itself in `plugin_name`; passing the name again to plugin_data_folder() repeats it and can drift. Add a `data_folder()` class method on MVTPluginSettings which returns plugin_data_folder() for the class's validated plugin name (works on the class and on an instance); plugin_data_folder(name) stays as the function underneath for plugins without a settings class. --------- Co-authored-by: Donncha Ó Cearbhaill <google@donncha.is>
3.4 KiB
Custom CLI Commands
MVT can load additional top-level commands into mvt-ios and mvt-android.
Custom commands are different from custom forensic 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:
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:
[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:
mvt-ios summarize ./ios-backup
mvt-android summarize ./androidqf-output
For a pipx installation of MVT, inject the plugin into MVT's environment:
pipx inject mvt my-mvt-plugin
When MVT is installed in an active virtual environment, install the plugin with
pip in that environment.
Command packages that need their own settings, such as an API key, should store
them in a namespaced plugin configuration file
rather than in MVT's own config.yaml.
Load a Command File
For local commands that are not packaged, create a Python file that exports one
Click command or group named cli:
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:
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:
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.