Match receiver indicators by package ID

* Validate iOS backup path before checks

* Fix iOS backup path mypy typing

* Fix custom module test backup fixture

README.md

@@ -60,6 +60,23 @@ For alternative installation options and known issues, please refer to the [docu
 
 MVT provides two commands `mvt-ios` and `mvt-android`. [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

docs/android/methodology.md

@@ -38,6 +38,22 @@ By separating artifact collection from forensic analysis, this approach ensures
 
 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.

docs/command_completion.md

@@ -1,43 +1,66 @@
-# Command Completion 
+# Command Completion
 
-MVT utilizes the [Click](https://click.palletsprojects.com/en/stable/) library for creating its command line interface. 
+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 manually register a special function with your shell, which varies depending on the shell you are using.
+To enable it, you need to register a completion script with your shell, which varies depending on the shell you are using.
 
-The following describes how to generate the command completion scripts and add them to your shell configuration. 
+The following describes how to generate the command completion scripts and add them to your shell configuration.
 
 > **Note: You will need to start a new shell for the changes to take effect.**
 
 ### For Bash
 
 ```bash
-# Generates bash completion scripts
-echo "$(_MVT_IOS_COMPLETE=bash_source mvt-ios)" > ~/.mvt-ios-complete.bash &&
-echo "$(_MVT_ANDROID_COMPLETE=bash_source mvt-android)" > ~/.mvt-android-complete.bash
+# Generate bash completion scripts
+mvt-ios completion bash > ~/.mvt-ios-complete.bash
+mvt-android completion bash > ~/.mvt-android-complete.bash
 ```
 
 Add the following to `~/.bashrc`:
 ```bash
 # source mvt completion scripts
-. ~/.mvt-ios-complete.bash && .  ~/.mvt-android-complete.bash
+[ -f ~/.mvt-ios-complete.bash ] && . ~/.mvt-ios-complete.bash
+[ -f ~/.mvt-android-complete.bash ] && . ~/.mvt-android-complete.bash
 ```
 
 ### For Zsh
 
 ```bash
-# Generates zsh completion scripts
-echo "$(_MVT_IOS_COMPLETE=zsh_source mvt-ios)" >  ~/.mvt-ios-complete.zsh &&
-echo "$(_MVT_ANDROID_COMPLETE=zsh_source mvt-android)" > ~/.mvt-android-complete.zsh
+# Generate zsh completion scripts
+mvt-ios completion zsh > ~/.mvt-ios-complete.zsh
+mvt-android completion zsh > ~/.mvt-android-complete.zsh
 ```
 
 Add the following to `~/.zshrc`:
 ```bash
 # source mvt completion scripts
-.  ~/.mvt-ios-complete.zsh  && .  ~/.mvt-android-complete.zsh
+[ -f ~/.mvt-ios-complete.zsh ] && . ~/.mvt-ios-complete.zsh
+[ -f ~/.mvt-android-complete.zsh ] && . ~/.mvt-android-complete.zsh
 ```
 
+### For Fish
+
+```bash
+# Generate fish completion scripts
+mkdir -p ~/.config/fish/completions
+mvt-ios completion fish > ~/.config/fish/completions/mvt-ios.fish
+mvt-android completion fish > ~/.config/fish/completions/mvt-android.fish
+```
+
+Fish loads completion files from `~/.config/fish/completions` 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-ios completion bash --install
+mvt-android completion bash --install
+```
+
+Replace `bash` with `zsh` or `fish` as needed. For Fish, `--install` writes the completion file into `~/.config/fish/completions`.
+
 For more information, visit the official [Click Docs](https://click.palletsprojects.com/en/stable/shell-completion/#enabling-completion).
 
-

src/mvt/android/cli.py

@@ -8,6 +8,12 @@ import logging
 import click
 
 from mvt.common.cmd_check_iocs import CmdCheckIOCS
+from mvt.common.completion import (
+    SUPPORTED_SHELLS,
+    completion_instructions,
+    generate_completion_script,
+    install_completion_script,
+)
 from mvt.common.help import (
     HELP_MSG_ANDROID_BACKUP_PASSWORD,
     HELP_MSG_CHECK_ADB_REMOVED,
@@ -17,6 +23,8 @@ from mvt.common.help import (
     HELP_MSG_CHECK_BUGREPORT,
     HELP_MSG_CHECK_IOCS,
     HELP_MSG_CHECK_INTRUSION_LOGS,
+    HELP_MSG_DELAY_CHECKS,
+    HELP_MSG_COMPLETION,
     HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK,
     HELP_MSG_DISABLE_UPDATE_CHECK,
     HELP_MSG_HASHES,
@@ -29,6 +37,7 @@ from mvt.common.help import (
     HELP_MSG_STIX2,
     HELP_MSG_VERBOSE,
     HELP_MSG_VERSION,
+    HELP_MSG_VIRUS_TOTAL,
 )
 from mvt.common.logo import logo
 from mvt.common.module_loader import CustomModuleLoadError, load_custom_modules
@@ -85,10 +94,11 @@ def cli(ctx, disable_update_check, disable_indicator_update_check):
     ctx.ensure_object(dict)
     ctx.obj["disable_version_check"] = disable_update_check
     ctx.obj["disable_indicator_check"] = disable_indicator_update_check
-    logo(
-        disable_version_check=disable_update_check,
-        disable_indicator_check=disable_indicator_update_check,
-    )
+    if ctx.invoked_subcommand != "completion":
+        logo(
+            disable_version_check=disable_update_check,
+            disable_indicator_check=disable_indicator_update_check,
+        )
 
 
 # ==============================================================================
@@ -99,6 +109,40 @@ def version():
     return
 
 
+# ==============================================================================
+# Command: completion
+# ==============================================================================
+@cli.command("completion", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_COMPLETION)
+@click.argument("shell", required=False, type=click.Choice(SUPPORTED_SHELLS))
+@click.option(
+    "--install",
+    is_flag=True,
+    help="Write completion files and update shell configuration.",
+)
+@click.pass_context
+def completion(ctx, shell, install):
+    program_name = "mvt-android"
+
+    if shell is None:
+        if install:
+            raise click.UsageError("A shell is required when using --install.")
+        click.echo(completion_instructions(program_name))
+        return
+
+    root_cli = ctx.find_root().command
+
+    if install:
+        script_path = install_completion_script(root_cli, program_name, shell)
+        click.echo(f"Installed {shell} completion to {script_path}")
+        if shell in ("bash", "zsh"):
+            click.echo(f"Updated ~/.{shell}rc")
+        else:
+            click.echo("Fish loads completion files automatically.")
+        return
+
+    click.echo(generate_completion_script(root_cli, program_name, shell))
+
+
 # ==============================================================================
 # Command: check-adb (removed)
 # ==============================================================================
@@ -268,6 +312,10 @@ def check_backup(
     help=HELP_MSG_LOAD_MODULE,
 )
 @click.option("--hashes", "-H", is_flag=True, help=HELP_MSG_HASHES)
+@click.option("--virustotal", "-V", is_flag=True, help=HELP_MSG_VIRUS_TOTAL)
+@click.option(
+    "--delay", "-d", type=click.IntRange(min=0), default=16, help=HELP_MSG_DELAY_CHECKS
+)
 @click.option("--non-interactive", "-n", is_flag=True, help=HELP_MSG_NONINTERACTIVE)
 @click.option("--backup-password", "-p", help=HELP_MSG_ANDROID_BACKUP_PASSWORD)
 @click.option("--verbose", "-v", is_flag=True, help=HELP_MSG_VERBOSE)
@@ -281,6 +329,8 @@ def check_androidqf(
     module,
     load_module,
     hashes,
+    virustotal,
+    delay,
     non_interactive,
     backup_password,
     verbose,
@@ -298,6 +348,8 @@ def check_androidqf(
         module_options={
             "interactive": not non_interactive,
             "backup_password": cli_load_android_backup_password(log, backup_password),
+            "virustotal": virustotal,
+            "virustotal_delay": delay,
         },
         disable_version_check=_get_disable_flags(ctx)[0],
         disable_indicator_check=_get_disable_flags(ctx)[1],

src/mvt/android/modules/androidqf/aqf_packages.py

@@ -5,8 +5,11 @@
 
 import json
 import logging
+import time
 from typing import Optional
 
+from rich.progress import track
+
 from mvt.android.utils import (
     BROWSER_INSTALLERS,
     PLAY_STORE_INSTALLERS,
@@ -15,7 +18,8 @@ from mvt.android.utils import (
     SYSTEM_UPDATE_PACKAGES,
     THIRD_PARTY_STORE_INSTALLERS,
 )
-from mvt.common.module_types import ModuleResults
+from mvt.common.module_types import ModuleAtomicResult, ModuleResults
+from mvt.common.virustotal import VTNoKey, VTQuotaExceeded, virustotal_lookup
 
 from .base import AndroidQFModule
 
@@ -125,6 +129,65 @@ class AQFPackages(AndroidQFModule):
                         )
                         break
 
+        if self.module_options.get("virustotal", False):
+            self.check_virustotal(
+                delay=self.module_options.get("virustotal_delay", 0)
+            )
+
+    def check_virustotal(self, delay: int = 0) -> None:
+        files_by_hash: dict[
+            str, list[tuple[ModuleAtomicResult, ModuleAtomicResult]]
+        ] = {}
+        for package in self.results:
+            if package.get("system", False):
+                continue
+
+            for package_file in package.get("files", []):
+                file_hash = package_file.get("sha256")
+                if not file_hash:
+                    continue
+
+                files_by_hash.setdefault(file_hash, []).append((package, package_file))
+
+        total_hashes = len(files_by_hash)
+        if total_hashes == 0:
+            return
+
+        progress_desc = f"Looking up {total_hashes} package files on VirusTotal..."
+        for index, file_hash in enumerate(
+            track(files_by_hash, description=progress_desc)
+        ):
+            try:
+                results = virustotal_lookup(file_hash)
+            except VTNoKey as exc:
+                self.log.warning("%s", exc)
+                return
+            except VTQuotaExceeded as exc:
+                self.log.warning("Unable to continue VirusTotal lookups: %s", exc)
+                break
+
+            if index < total_hashes - 1 and delay > 0:
+                time.sleep(delay)
+
+            if not results:
+                continue
+
+            attributes = results.get("attributes", {})
+            stats = attributes.get("last_analysis_stats", {})
+            positives = stats.get("malicious", 0)
+            total = len(attributes.get("last_analysis_results", {}))
+            detection = f"{positives}/{total}"
+
+            for package, package_file in files_by_hash[file_hash]:
+                package_file["virustotal"] = detection
+                if positives > 0:
+                    self.alertstore.high(
+                        f'VirusTotal flagged package "{package["name"]}" file '
+                        f'"{package_file["path"]}" with {detection} detections',
+                        "",
+                        package,
+                    )
+
     def run(self) -> None:
         packages = self._get_files_by_pattern("*/packages.json")
         if not packages:

src/mvt/android/modules/bugreport/dumpsys_receivers.py

@@ -35,24 +35,6 @@ class DumpsysReceivers(DumpsysReceiversArtifact, BugReportModule):
 
         self.results = results if results else {}
 
-    def check_indicators(self) -> None:
-        for result in self.results:
-            if self.indicators:
-                receiver_name = self.results[result][0]["receiver"]
-
-                # return IoC if the stix2 process name a substring of the receiver name
-                ioc_match = self.indicators.check_receiver_prefix(receiver_name)
-                if ioc_match:
-                    self.alertstore.critical(
-                        ioc_match.message,
-                        "",
-                        self.results[result][0],
-                        matched_indicator=ioc_match.ioc,
-                    )
-                    continue
-
-
-
     def run(self) -> None:
         content = self._get_dumpstate_file()
         if not content:

src/mvt/android/modules/intrusion_logs/security_event.py

@@ -270,6 +270,11 @@ SECURITY_EVENT_METADATA_KEYS = {
     "timestamp",
 }
 
+# Known platform failures that remain in the timeline but do not need a warning.
+KNOWN_BENIGN_KEY_GENERATION_FAILURES = {
+    ("PinStorage_crossReboot_key", 1001),
+}
+
 
 class SecurityEvent(IntrusionLogsModule):
     """This module analyzes security events from intrusion logs."""
@@ -400,10 +405,17 @@ class SecurityEvent(IntrusionLogsModule):
         independent of any loaded indicators."""
         # Flag failed cryptographic operations as potentially suspicious
         if "key_generated" in result:
-            if not result["key_generated"].get("success", True):
+            key_info = result["key_generated"]
+            key_id = key_info.get("key_id", "unknown")
+            uid = key_info.get("uid")
+            is_known_benign_failure = (
+                key_id,
+                uid,
+            ) in KNOWN_BENIGN_KEY_GENERATION_FAILURES
+            if not key_info.get("success", True) and not is_known_benign_failure:
                 self.log.warning(
                     "Failed key generation detected for key_id: %s",
-                    result["key_generated"].get("key_id", "unknown"),
+                    key_id,
                 )
 
         # Flag certificate validation failures

src/mvt/common/completion.py

@@ -0,0 +1,94 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2023 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+from pathlib import Path
+import shlex
+
+import click
+from click.shell_completion import get_completion_class
+
+
+SUPPORTED_SHELLS = ("bash", "zsh", "fish")
+
+
+def completion_instructions(program_name: str) -> str:
+    return f"""Shell completion for {program_name}
+
+Print a completion script:
+  {program_name} completion bash > ~/.{program_name}-complete.bash
+  {program_name} completion zsh > ~/.{program_name}-complete.zsh
+  mkdir -p ~/.config/fish/completions
+  {program_name} completion fish > ~/.config/fish/completions/{program_name}.fish
+
+Load the generated Bash script from ~/.bashrc:
+  [ -f ~/.{program_name}-complete.bash ] && . ~/.{program_name}-complete.bash
+
+Load the generated Zsh script from ~/.zshrc:
+  [ -f ~/.{program_name}-complete.zsh ] && . ~/.{program_name}-complete.zsh
+
+Fish loads completion files from ~/.config/fish/completions automatically.
+
+To write these files and update Bash/Zsh shell configuration automatically:
+  {program_name} completion bash --install
+  {program_name} completion zsh --install
+  {program_name} completion fish --install
+"""
+
+
+def generate_completion_script(cli: click.Command, program_name: str, shell: str) -> str:
+    completion_class = get_completion_class(shell)
+    if completion_class is None:
+        raise click.ClickException(f"Unsupported shell: {shell}")
+
+    complete_var = f"_{program_name.upper().replace('-', '_')}_COMPLETE"
+    return completion_class(cli, {}, program_name, complete_var).source()
+
+
+def install_completion_script(
+    cli: click.Command,
+    program_name: str,
+    shell: str,
+) -> Path:
+    script = generate_completion_script(cli, program_name, shell)
+    script_path = _completion_script_path(program_name, shell)
+    script_path.parent.mkdir(parents=True, exist_ok=True)
+    script_path.write_text(script, encoding="utf-8")
+
+    if shell in ("bash", "zsh"):
+        _install_shell_source_line(program_name, shell, script_path)
+
+    return script_path
+
+
+def _completion_script_path(program_name: str, shell: str) -> Path:
+    home = Path.home()
+
+    if shell == "fish":
+        return home / ".config" / "fish" / "completions" / f"{program_name}.fish"
+
+    return home / f".{program_name}-complete.{shell}"
+
+
+def _install_shell_source_line(program_name: str, shell: str, script_path: Path) -> None:
+    shell_config_path = Path.home() / f".{shell}rc"
+    source_line = (
+        f"[ -f {shlex.quote(str(script_path))} ] && "
+        f". {shlex.quote(str(script_path))}"
+    )
+    block = (
+        f"# MVT shell completion for {program_name}\n"
+        f"{source_line}\n"
+    )
+
+    if shell_config_path.exists():
+        shell_config = shell_config_path.read_text(encoding="utf-8")
+        if source_line in shell_config:
+            return
+    else:
+        shell_config = ""
+
+    separator = "" if not shell_config or shell_config.endswith("\n") else "\n"
+    with shell_config_path.open("a", encoding="utf-8") as handle:
+        handle.write(f"{separator}{block}")

src/mvt/common/help.py

@@ -21,6 +21,7 @@ HELP_MSG_CHECK_IOCS = "Compare stored JSON results to provided indicators"
 HELP_MSG_STIX2 = "Download public STIX2 indicators"
 HELP_MSG_DISABLE_UPDATE_CHECK = "Disable MVT version update check"
 HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK = "Disable indicators update check"
+HELP_MSG_COMPLETION = "Generate or install shell completion"
 
 # IOS Specific
 HELP_MSG_DECRYPT_BACKUP = "Decrypt an encrypted iTunes backup"
@@ -52,3 +53,5 @@ HELP_MSG_CHECK_BUGREPORT = "Check an Android Bug Report"
 HELP_MSG_CHECK_ANDROID_BACKUP = "Check an Android Backup"
 HELP_MSG_CHECK_ANDROIDQF = "Check data collected with AndroidQF"
 HELP_MSG_CHECK_INTRUSION_LOGS = "Check Android Intrusion Logging files"
+HELP_MSG_VIRUS_TOTAL = "Check package APK hashes on VirusTotal"
+HELP_MSG_DELAY_CHECKS = "Delay in seconds between VirusTotal requests"

src/mvt/common/indicators.py

@@ -727,29 +727,6 @@ class Indicators:
 
         return None
 
-    def check_receiver_prefix(
-        self, receiver_name: str
-    ) -> Optional[IndicatorMatch]:
-        """Check the provided receiver name against the list of indicators.
-        An IoC match is detected when a substring of the receiver matches the indicator.
-
-        :param receiver_name: Receiver name to check against app ID indicators
-        :type receiver_name: str
-        :returns: IndicatorMatch if matched, otherwise None
-
-        """
-        if not receiver_name:
-            return None
-
-        for ioc in self.get_iocs("app_ids"):
-            if ioc.value.lower() in receiver_name.lower():
-                return IndicatorMatch(
-                    ioc=ioc,
-                    message=f'Found a known suspicious receiver with name "{receiver_name}" matching indicators from "{ioc.name}"',
-                )
-
-        return None
-
     def check_android_property_name(
         self, property_name: str
     ) -> Optional[IndicatorMatch]:

src/mvt/common/virustotal.py

@@ -0,0 +1,53 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2023 The MVT Authors.
+# 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 Any, Optional
+
+import requests
+
+from .config import settings
+
+log = logging.getLogger(__name__)
+
+
+class VTNoKey(Exception):
+    pass
+
+
+class VTQuotaExceeded(Exception):
+    pass
+
+
+def virustotal_lookup(file_hash: str) -> Optional[dict[str, Any]]:
+    if not settings.VT_API_KEY:
+        raise VTNoKey(
+            "No VirusTotal API key provided: to use VirusTotal lookups please set "
+            "MVT_VT_API_KEY or VT_API_KEY in the MVT configuration file"
+        )
+
+    headers = {
+        "User-Agent": "VirusTotal",
+        "Content-Type": "application/json",
+        "x-apikey": settings.VT_API_KEY,
+    }
+    res = requests.get(
+        f"https://www.virustotal.com/api/v3/files/{file_hash}",
+        headers=headers,
+        timeout=settings.NETWORK_TIMEOUT,
+    )
+
+    if res.status_code == 200:
+        report = res.json()
+        return report["data"]
+
+    if res.status_code == 404:
+        log.info("Could not find results for file with hash %s", file_hash)
+    elif res.status_code == 429:
+        raise VTQuotaExceeded("You have exceeded the quota for your VirusTotal API key")
+    else:
+        raise RuntimeError(f"Unexpected response from VirusTotal: {res.status_code}")
+
+    return None

src/mvt/ios/cli.py

@@ -11,6 +11,12 @@ import click
 from rich.prompt import Prompt
 
 from mvt.common.cmd_check_iocs import CmdCheckIOCS
+from mvt.common.completion import (
+    SUPPORTED_SHELLS,
+    completion_instructions,
+    generate_completion_script,
+    install_completion_script,
+)
 from mvt.common.logo import logo
 from mvt.common.options import MutuallyExclusiveOption
 from mvt.common.updates import IndicatorsUpdates
@@ -40,6 +46,7 @@ from mvt.common.help import (
     HELP_MSG_CHECK_IOS_BACKUP,
     HELP_MSG_DISABLE_UPDATE_CHECK,
     HELP_MSG_DISABLE_INDICATOR_UPDATE_CHECK,
+    HELP_MSG_COMPLETION,
 )
 from mvt.common.module_loader import CustomModuleLoadError, load_custom_modules
 from .cmd_check_backup import CmdIOSCheckBackup
@@ -91,10 +98,11 @@ def cli(ctx, disable_update_check, disable_indicator_update_check):
     ctx.ensure_object(dict)
     ctx.obj["disable_version_check"] = disable_update_check
     ctx.obj["disable_indicator_check"] = disable_indicator_update_check
-    logo(
-        disable_version_check=disable_update_check,
-        disable_indicator_check=disable_indicator_update_check,
-    )
+    if ctx.invoked_subcommand != "completion":
+        logo(
+            disable_version_check=disable_update_check,
+            disable_indicator_check=disable_indicator_update_check,
+        )
 
 
 # ==============================================================================
@@ -105,6 +113,40 @@ def version():
     return
 
 
+# ==============================================================================
+# Command: completion
+# ==============================================================================
+@cli.command("completion", context_settings=CONTEXT_SETTINGS, help=HELP_MSG_COMPLETION)
+@click.argument("shell", required=False, type=click.Choice(SUPPORTED_SHELLS))
+@click.option(
+    "--install",
+    is_flag=True,
+    help="Write completion files and update shell configuration.",
+)
+@click.pass_context
+def completion(ctx, shell, install):
+    program_name = "mvt-ios"
+
+    if shell is None:
+        if install:
+            raise click.UsageError("A shell is required when using --install.")
+        click.echo(completion_instructions(program_name))
+        return
+
+    root_cli = ctx.find_root().command
+
+    if install:
+        script_path = install_completion_script(root_cli, program_name, shell)
+        click.echo(f"Installed {shell} completion to {script_path}")
+        if shell in ("bash", "zsh"):
+            click.echo(f"Updated ~/.{shell}rc")
+        else:
+            click.echo("Fish loads completion files automatically.")
+        return
+
+    click.echo(generate_completion_script(root_cli, program_name, shell))
+
+
 # ==============================================================================
 # Command: decrypt-backup
 # ==============================================================================
@@ -281,7 +323,10 @@ def check_backup(
         cmd.list_modules()
         return
 
-    log.info("Checking iTunes backup located at: %s", backup_path)
+    if not cmd.resolve_backup_path():
+        ctx.exit(1)
+
+    log.info("Checking iTunes backup located at: %s", cmd.target_path)
 
     cmd.run()
     cmd.show_alerts_brief()

src/mvt/ios/cmd_check_backup.py

@@ -4,6 +4,7 @@
 #   https://license.mvt.re/1.1/
 
 import logging
+import os
 from typing import Optional
 
 from mvt.common.command import Command
@@ -16,6 +17,12 @@ from .modules.mixed import MIXED_MODULES
 log = logging.getLogger(__name__)
 
 
+def is_ios_backup_folder(path: str) -> bool:
+    return os.path.isfile(os.path.join(path, "Manifest.db")) and os.path.isfile(
+        os.path.join(path, "Info.plist")
+    )
+
+
 class CmdIOSCheckBackup(Command):
     def __init__(
         self,
@@ -52,5 +59,46 @@ class CmdIOSCheckBackup(Command):
         self.name = "check-backup"
         self.modules = BACKUP_MODULES + MIXED_MODULES
 
+    def resolve_backup_path(self) -> bool:
+        target_path = getattr(self, "target_path", None)
+        if not isinstance(target_path, str) or not target_path:
+            return False
+
+        if is_ios_backup_folder(target_path):
+            return True
+
+        if not os.path.isdir(target_path):
+            self.log.critical(
+                "%s does not appear to be an iTunes backup folder. "
+                "Expected Manifest.db and Info.plist.",
+                target_path,
+            )
+            return False
+
+        candidates = []
+        for entry_name in sorted(os.listdir(target_path)):
+            entry_path = os.path.join(target_path, entry_name)
+            if os.path.isdir(entry_path) and is_ios_backup_folder(entry_path):
+                candidates.append(entry_path)
+
+        if len(candidates) == 1:
+            self.log.info("Found iTunes backup in subfolder: %s", candidates[0])
+            self.target_path = candidates[0]
+            return True
+
+        if candidates:
+            self.log.critical(
+                "Found multiple iTunes backups in %s. Please specify one backup folder.",
+                target_path,
+            )
+            return False
+
+        self.log.critical(
+            "%s does not appear to be an iTunes backup folder. "
+            "Expected Manifest.db and Info.plist.",
+            target_path,
+        )
+        return False
+
     def module_init(self, module):
         module.is_backup = True

src/mvt/ios/modules/fs/shutdownlog.py

@@ -6,6 +6,7 @@
 import logging
 from typing import Optional
 
+from mvt.common.module import DatabaseNotFoundError
 from mvt.common.module_types import (
     ModuleAtomicResult,
     ModuleResults,
@@ -17,6 +18,7 @@ from ..base import IOSExtraction
 
 SHUTDOWN_LOG_PATH = [
     "private/var/db/diagnostics/shutdown.log",
+    "private/var/db/diagnostics/shutdown.*.log",
 ]
 
 
@@ -132,10 +134,17 @@ class ShutdownLog(IOSExtraction):
         self.results = sorted(self.results, key=lambda entry: entry["isodate"])
 
     def run(self) -> None:
-        self._find_ios_database(root_paths=SHUTDOWN_LOG_PATH)
-        self.log.info("Found shutdown log at path: %s", self.file_path)
+        if self.file_path:
+            shutdown_log_paths = [self.file_path]
+        else:
+            shutdown_log_paths = sorted(
+                self._get_fs_files_from_patterns(SHUTDOWN_LOG_PATH)
+            )
 
-        if not self.file_path:
-            return
-        with open(self.file_path, "r", encoding="utf-8") as handle:
-            self.process_shutdownlog(handle.read())
+        if not shutdown_log_paths:
+            raise DatabaseNotFoundError("unable to find any shutdown log files")
+
+        for shutdown_log_path in shutdown_log_paths:
+            self.log.info("Found shutdown log at path: %s", shutdown_log_path)
+            with open(shutdown_log_path, "r", encoding="utf-8") as handle:
+                self.process_shutdownlog(handle.read())

tests/android/test_intrusion_logs.py

@@ -215,6 +215,52 @@ def _run_security_heuristics(results):
     return module.alertstore.alerts
 
 
+@pytest.mark.parametrize("success", [False, 0])
+def test_known_pinstorage_key_generation_failure_does_not_warn(success, caplog):
+    record = {
+        "timestamp": "2026-06-17 15:31:02.014",
+        "key_generated": {
+            "success": success,
+            "key_id": "PinStorage_crossReboot_key",
+            "uid": 1001,
+        },
+    }
+
+    with caplog.at_level(logging.WARNING):
+        _run_security_heuristics([record])
+
+    assert "Failed key generation detected" not in caplog.text
+
+    timeline_event = SecurityEvent().serialize(record)
+    assert timeline_event["event"] == "key_generated"
+    assert "Key generation failed: PinStorage_crossReboot_key" in timeline_event["data"]
+
+
+@pytest.mark.parametrize(
+    ("key_id", "uid"),
+    [
+        ("PinStorage_crossReboot_key", 10_000),
+        ("another_key", 1001),
+    ],
+)
+def test_other_key_generation_failures_still_warn(key_id, uid, caplog):
+    with caplog.at_level(logging.WARNING):
+        _run_security_heuristics(
+            [
+                {
+                    "timestamp": "2026-06-17 15:31:02.014",
+                    "key_generated": {
+                        "success": False,
+                        "key_id": key_id,
+                        "uid": uid,
+                    },
+                }
+            ]
+        )
+
+    assert f"Failed key generation detected for key_id: {key_id}" in caplog.text
+
+
 def test_cert_authority_installed_raises_medium_alert_without_indicators():
     alerts = _run_security_heuristics(
         [

tests/android_androidqf/test_packages.py

@@ -7,8 +7,11 @@ import logging
 from pathlib import Path
 
 import pytest
+from click.testing import CliRunner
 
+from mvt.android.cli import check_androidqf
 from mvt.android.modules.androidqf.aqf_packages import AQFPackages
+from mvt.android.modules.androidqf import aqf_packages as aqf_packages_module
 from mvt.common.module import run_module
 
 from ..utils import get_android_androidqf, list_files
@@ -132,3 +135,55 @@ class TestAndroidqfPackages:
             possible_detected_app[0].matched_indicator.value
             == "c7e56178748be1441370416d4c10e34817ea0c961eb636c8e9d98e0fd79bf730"
         )
+
+    def test_virustotal_delays_after_missing_result(self, monkeypatch):
+        lookups = []
+        sleeps = []
+
+        def fake_virustotal_lookup(file_hash):
+            lookups.append(file_hash)
+            if file_hash == "missing_hash":
+                return None
+            return {
+                "attributes": {
+                    "last_analysis_stats": {"malicious": 1},
+                    "last_analysis_results": {"engine": {}},
+                }
+            }
+
+        monkeypatch.setattr(
+            aqf_packages_module, "virustotal_lookup", fake_virustotal_lookup
+        )
+        monkeypatch.setattr(aqf_packages_module.time, "sleep", sleeps.append)
+
+        module = AQFPackages(
+            module_options={"virustotal": True, "virustotal_delay": 16},
+            results=[
+                {
+                    "name": "org.example",
+                    "installer": "com.android.vending",
+                    "disabled": False,
+                    "system": False,
+                    "files": [
+                        {"path": "/data/app/missing.apk", "sha256": "missing_hash"},
+                        {"path": "/data/app/found.apk", "sha256": "found_hash"},
+                    ],
+                }
+            ],
+        )
+
+        module.check_indicators()
+
+        assert lookups == ["missing_hash", "found_hash"]
+        assert sleeps == [16]
+        assert module.results[0]["files"][1]["virustotal"] == "1/1"
+        assert len(module.alertstore.alerts) == 1
+
+
+def test_check_androidqf_rejects_negative_virustotal_delay(data_path):
+    runner = CliRunner()
+
+    result = runner.invoke(check_androidqf, ["--delay", "-1", data_path])
+
+    assert result.exit_code == 2
+    assert "Invalid value for '--delay'" in result.output

tests/android_bugreport/test_bugreport.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from mvt.android.modules.bugreport.dumpsys_appops import DumpsysAppops
 from mvt.android.modules.bugreport.dumpsys_getprop import DumpsysGetProp
 from mvt.android.modules.bugreport.dumpsys_packages import DumpsysPackages
+from mvt.android.modules.bugreport.dumpsys_receivers import DumpsysReceivers
 from mvt.android.modules.bugreport.tombstones import Tombstones
 from mvt.common.module import run_module
 
@@ -60,6 +61,31 @@ class TestBugreportAnalysis:
         m = self.launch_bug_report_module(DumpsysGetProp)
         assert len(m.results) == 0
 
+    def test_receivers_match_exact_package_name(self, indicators_factory):
+        intent = "android.intent.action.PHONE_STATE"
+        false_positive = {
+            "package_name": "com.android.phone",
+            "receiver": (
+                "com.android.phone/"
+                "com.android.services.telephony.sip.SipIncomingCallReceiver"
+            ),
+        }
+        malicious_receiver = {
+            "package_name": "com.android.services",
+            "receiver": "com.android.services/com.example.SomeReceiver",
+        }
+        module = DumpsysReceivers(
+            results={intent: [false_positive, malicious_receiver]}
+        )
+        module.indicators = indicators_factory(app_ids=["com.android.services"])
+
+        module.check_indicators()
+
+        assert len(module.alertstore.alerts) == 1
+        alert = module.alertstore.alerts[0]
+        assert alert.event == {intent: malicious_receiver}
+        assert alert.matched_indicator.value == "com.android.services"
+
     def test_tombstones_modules(self):
         m = self.launch_bug_report_module(Tombstones)
         assert len(m.results) == 2

tests/conftest.py

@@ -35,6 +35,7 @@ def indicators_factory(indicator_file):
         domains=[],
         emails=[],
         file_names=[],
+        file_paths=[],
         processes=[],
         app_ids=[],
         app_cert_hashes=[],
@@ -47,6 +48,7 @@ def indicators_factory(indicator_file):
         ind.ioc_collections[0]["domains"].extend(domains)
         ind.ioc_collections[0]["emails"].extend(emails)
         ind.ioc_collections[0]["file_names"].extend(file_names)
+        ind.ioc_collections[0]["file_paths"].extend(file_paths)
         ind.ioc_collections[0]["processes"].extend(processes)
         ind.ioc_collections[0]["app_ids"].extend(app_ids)
         ind.ioc_collections[0]["android_property_names"].extend(android_property_names)

tests/ios_fs/test_shutdownlog.py

@@ -0,0 +1,59 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2023 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+# https://license.mvt.re/1.1/
+
+from mvt.common.module import run_module
+from mvt.ios.modules.fs.shutdownlog import ShutdownLog
+
+
+def _shutdown_log_entry(pid: int, client: str, timestamp: int) -> str:
+    return (
+        f"remaining client pid: {pid} ({client})\n"
+        f"SIGTERM: [{timestamp}]\n"
+    )
+
+
+class TestShutdownLog:
+    def test_discovers_rotated_shutdown_logs(self, tmp_path):
+        diagnostics_path = tmp_path / "private/var/db/diagnostics"
+        diagnostics_path.mkdir(parents=True)
+        (diagnostics_path / "shutdown.log").write_text(
+            _shutdown_log_entry(100, "/usr/libexec/first", 1_700_000_000),
+            encoding="utf-8",
+        )
+        (diagnostics_path / "shutdown.0.log").write_text(
+            _shutdown_log_entry(200, "/usr/libexec/second", 1_700_000_001),
+            encoding="utf-8",
+        )
+
+        module = ShutdownLog(target_path=str(tmp_path))
+        run_module(module)
+
+        assert {result["client"] for result in module.results} == {
+            "/usr/libexec/first",
+            "/usr/libexec/second",
+        }
+
+    def test_file_path_indicator_matches_client_with_trailing_uuid(
+        self, indicators_factory
+    ):
+        executable_path = "/usr/sbin/filecoordinationd"
+        client = f"{executable_path}/123e4567-e89b-12d3-a456-426614174000"
+        module = ShutdownLog(
+            results=[
+                {
+                    "isodate": "2023-11-14 22:13:20.000000",
+                    "pid": "100",
+                    "client": client,
+                    "delay": 0.0,
+                    "times_delayed": 0,
+                }
+            ]
+        )
+        module.indicators = indicators_factory(file_paths=[executable_path])
+
+        module.check_indicators()
+
+        assert len(module.alertstore.alerts) == 1
+        assert module.alertstore.alerts[0].matched_indicator.value == executable_path

tests/test_check_ios_backup.py

@@ -3,6 +3,8 @@
 # Use of this software is governed by the MVT License 1.1 that can be found at
 #   https://license.mvt.re/1.1/
 
+import shutil
+
 from click.testing import CliRunner
 
 from mvt.ios.cli import check_backup
@@ -16,3 +18,18 @@ class TestCheckBackupCommand:
         path = get_ios_backup_folder()
         result = runner.invoke(check_backup, [path])
         assert result.exit_code == 0
+
+    def test_check_finds_backup_in_subfolder(self, tmp_path, caplog):
+        runner = CliRunner()
+        backup_path = tmp_path / "MobileSync" / "Backup" / "device-id"
+        shutil.copytree(get_ios_backup_folder(), backup_path)
+
+        result = runner.invoke(check_backup, [str(backup_path.parent)])
+        assert result.exit_code == 0
+        assert f"Found iTunes backup in subfolder: {backup_path}" in caplog.text
+
+    def test_check_rejects_non_backup_folder(self, tmp_path, caplog):
+        runner = CliRunner()
+        result = runner.invoke(check_backup, [str(tmp_path)])
+        assert result.exit_code == 1
+        assert "does not appear to be an iTunes backup folder" in caplog.text

tests/test_completion.py

@@ -0,0 +1,78 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2023 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+from click.testing import CliRunner
+
+from mvt.android.cli import cli as android_cli
+from mvt.ios.cli import cli as ios_cli
+
+
+class TestCompletionCommand:
+    def test_completion_prints_instructions_by_default(self):
+        runner = CliRunner()
+        result = runner.invoke(ios_cli, ["completion"])
+
+        assert result.exit_code == 0
+        assert "Shell completion for mvt-ios" in result.output
+        assert "mvt-ios completion bash > ~/.mvt-ios-complete.bash" in result.output
+        assert "Mobile Verification Toolkit" not in result.output
+
+    def test_completion_prints_bash_script(self):
+        runner = CliRunner()
+        result = runner.invoke(ios_cli, ["completion", "bash"])
+
+        assert result.exit_code == 0
+        assert "_MVT_IOS_COMPLETE=bash_complete" in result.output
+        assert "complete -o nosort" in result.output
+        assert "mvt-ios" in result.output
+        assert "Mobile Verification Toolkit" not in result.output
+
+    def test_completion_prints_fish_script(self):
+        runner = CliRunner()
+        result = runner.invoke(android_cli, ["completion", "fish"])
+
+        assert result.exit_code == 0
+        assert "_MVT_ANDROID_COMPLETE=fish_complete" in result.output
+        assert "complete --no-files --command mvt-android" in result.output
+        assert "Mobile Verification Toolkit" not in result.output
+
+    def test_completion_install_updates_bashrc_once(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        runner = CliRunner()
+
+        result = runner.invoke(ios_cli, ["completion", "bash", "--install"])
+        assert result.exit_code == 0
+
+        script_path = tmp_path / ".mvt-ios-complete.bash"
+        bashrc_path = tmp_path / ".bashrc"
+        assert script_path.exists()
+        assert "_MVT_IOS_COMPLETE=bash_complete" in script_path.read_text(
+            encoding="utf-8"
+        )
+        bashrc = bashrc_path.read_text(encoding="utf-8")
+        assert "[ -f" in bashrc
+        assert ".mvt-ios-complete.bash" in bashrc
+
+        result = runner.invoke(ios_cli, ["completion", "bash", "--install"])
+        assert result.exit_code == 0
+        assert bashrc_path.read_text(encoding="utf-8") == bashrc
+
+    def test_completion_install_fish_does_not_update_shell_rc(
+        self, tmp_path, monkeypatch
+    ):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        runner = CliRunner()
+
+        result = runner.invoke(android_cli, ["completion", "fish", "--install"])
+
+        assert result.exit_code == 0
+        script_path = (
+            tmp_path / ".config" / "fish" / "completions" / "mvt-android.fish"
+        )
+        assert script_path.exists()
+        assert "_MVT_ANDROID_COMPLETE=fish_complete" in script_path.read_text(
+            encoding="utf-8"
+        )
+        assert not (tmp_path / ".fishrc").exists()

tests/test_custom_modules.py

@@ -63,6 +63,8 @@ def test_load_module_appears_only_for_supported_cli_command(tmp_path):
 
 
 def test_module_option_runs_supported_custom_module(tmp_path):
+    (tmp_path / "Manifest.db").touch()
+    (tmp_path / "Info.plist").touch()
     module_path = _write_custom_module(
         tmp_path / "custom.py",
         "CustomRunModule",