2021-07-16 06:05:01 +00:00
|
|
|
# Mobile Verification Toolkit (MVT)
|
2022-01-30 19:15:01 +00:00
|
|
|
# Copyright (c) 2021-2022 The MVT Project Authors.
|
2021-08-01 19:11:08 +00:00
|
|
|
# Use of this software is governed by the MVT License 1.1 that can be found at
|
|
|
|
# https://license.mvt.re/1.1/
|
2021-07-16 06:05:01 +00:00
|
|
|
|
2021-07-30 09:40:09 +00:00
|
|
|
import logging
|
2021-07-16 06:05:01 +00:00
|
|
|
import os
|
2022-02-02 15:10:12 +00:00
|
|
|
from pathlib import Path
|
2022-02-02 15:10:24 +00:00
|
|
|
from zipfile import ZipFile
|
2021-07-30 09:40:09 +00:00
|
|
|
|
2021-07-16 06:05:01 +00:00
|
|
|
import click
|
|
|
|
from rich.logging import RichHandler
|
|
|
|
|
2022-01-11 15:02:44 +00:00
|
|
|
from mvt.common.help import (HELP_MSG_FAST, HELP_MSG_IOC,
|
|
|
|
HELP_MSG_LIST_MODULES, HELP_MSG_MODULE,
|
|
|
|
HELP_MSG_OUTPUT, HELP_MSG_SERIAL)
|
|
|
|
from mvt.common.indicators import Indicators, download_indicators_files
|
2021-08-26 10:36:37 +00:00
|
|
|
from mvt.common.logo import logo
|
2021-07-30 09:40:09 +00:00
|
|
|
from mvt.common.module import run_module, save_timeline
|
|
|
|
|
2021-07-16 06:05:01 +00:00
|
|
|
from .download_apks import DownloadAPKs
|
|
|
|
from .lookups.koodous import koodous_lookup
|
|
|
|
from .lookups.virustotal import virustotal_lookup
|
|
|
|
from .modules.adb import ADB_MODULES
|
|
|
|
from .modules.backup import BACKUP_MODULES
|
2022-02-01 23:09:53 +00:00
|
|
|
from .modules.bugreport import BUGREPORT_MODULES
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
# Setup logging using Rich.
|
|
|
|
LOG_FORMAT = "[%(name)s] %(message)s"
|
|
|
|
logging.basicConfig(level="INFO", format=LOG_FORMAT, handlers=[
|
|
|
|
RichHandler(show_path=False, log_time_format="%X")])
|
|
|
|
log = logging.getLogger(__name__)
|
|
|
|
|
2021-11-19 14:27:51 +00:00
|
|
|
|
2021-07-16 06:05:01 +00:00
|
|
|
#==============================================================================
|
|
|
|
# Main
|
|
|
|
#==============================================================================
|
|
|
|
@click.group(invoke_without_command=False)
|
|
|
|
def cli():
|
2021-08-26 10:36:37 +00:00
|
|
|
logo()
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
|
2021-09-17 12:19:03 +00:00
|
|
|
#==============================================================================
|
|
|
|
# Command: version
|
|
|
|
#==============================================================================
|
|
|
|
@cli.command("version", help="Show the currently installed version of MVT")
|
|
|
|
def version():
|
|
|
|
return
|
|
|
|
|
|
|
|
|
2021-07-16 06:05:01 +00:00
|
|
|
#==============================================================================
|
2022-02-01 23:09:53 +00:00
|
|
|
# Command: download-apks
|
2021-07-16 06:05:01 +00:00
|
|
|
#==============================================================================
|
|
|
|
@cli.command("download-apks", help="Download all or non-safelisted installed APKs installed on the device")
|
2021-08-21 13:48:52 +00:00
|
|
|
@click.option("--serial", "-s", type=str, help=HELP_MSG_SERIAL)
|
2021-07-16 06:05:01 +00:00
|
|
|
@click.option("--all-apks", "-a", is_flag=True,
|
2021-08-25 11:35:21 +00:00
|
|
|
help="Extract all packages installed on the phone, including system packages")
|
2021-07-16 06:05:01 +00:00
|
|
|
@click.option("--virustotal", "-v", is_flag=True, help="Check packages on VirusTotal")
|
|
|
|
@click.option("--koodous", "-k", is_flag=True, help="Check packages on Koodous")
|
|
|
|
@click.option("--all-checks", "-A", is_flag=True, help="Run all available checks")
|
2021-07-20 01:09:53 +00:00
|
|
|
@click.option("--output", "-o", type=click.Path(exists=False),
|
2021-07-30 09:08:32 +00:00
|
|
|
help="Specify a path to a folder where you want to store the APKs")
|
2021-07-16 06:05:01 +00:00
|
|
|
@click.option("--from-file", "-f", type=click.Path(exists=True),
|
|
|
|
help="Instead of acquiring from phone, load an existing packages.json file for lookups (mainly for debug purposes)")
|
2021-08-17 11:06:31 +00:00
|
|
|
@click.pass_context
|
|
|
|
def download_apks(ctx, all_apks, virustotal, koodous, all_checks, output, from_file, serial):
|
2021-07-16 06:05:01 +00:00
|
|
|
try:
|
|
|
|
if from_file:
|
|
|
|
download = DownloadAPKs.from_json(from_file)
|
|
|
|
else:
|
2021-08-17 11:06:31 +00:00
|
|
|
# TODO: Do we actually want to be able to run without storing any file?
|
|
|
|
if not output:
|
|
|
|
log.critical("You need to specify an output folder with --output!")
|
|
|
|
ctx.exit(1)
|
|
|
|
|
|
|
|
if not os.path.exists(output):
|
2021-07-30 09:08:32 +00:00
|
|
|
try:
|
|
|
|
os.makedirs(output)
|
|
|
|
except Exception as e:
|
|
|
|
log.critical("Unable to create output folder %s: %s", output, e)
|
2021-08-17 11:06:31 +00:00
|
|
|
ctx.exit(1)
|
2021-07-16 06:05:01 +00:00
|
|
|
|
2021-08-25 11:35:21 +00:00
|
|
|
download = DownloadAPKs(output_folder=output, all_apks=all_apks,
|
|
|
|
log=logging.getLogger(DownloadAPKs.__module__))
|
2021-08-12 16:21:21 +00:00
|
|
|
if serial:
|
|
|
|
download.serial = serial
|
2021-07-16 06:05:01 +00:00
|
|
|
download.run()
|
|
|
|
|
|
|
|
packages = download.packages
|
|
|
|
|
|
|
|
if len(packages) == 0:
|
|
|
|
return
|
|
|
|
|
|
|
|
if virustotal or all_checks:
|
|
|
|
virustotal_lookup(packages)
|
|
|
|
|
|
|
|
if koodous or all_checks:
|
|
|
|
koodous_lookup(packages)
|
|
|
|
except KeyboardInterrupt:
|
|
|
|
print("")
|
2021-08-17 11:06:31 +00:00
|
|
|
ctx.exit(1)
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
|
|
|
|
#==============================================================================
|
2022-02-01 23:09:53 +00:00
|
|
|
# Command: check-adb
|
2021-07-16 06:05:01 +00:00
|
|
|
#==============================================================================
|
|
|
|
@cli.command("check-adb", help="Check an Android device over adb")
|
2021-08-21 13:48:52 +00:00
|
|
|
@click.option("--serial", "-s", type=str, help=HELP_MSG_SERIAL)
|
2021-08-18 11:19:34 +00:00
|
|
|
@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
|
2021-08-21 13:48:52 +00:00
|
|
|
default=[], help=HELP_MSG_IOC)
|
2021-07-20 01:09:53 +00:00
|
|
|
@click.option("--output", "-o", type=click.Path(exists=False),
|
2021-08-21 13:48:52 +00:00
|
|
|
help=HELP_MSG_OUTPUT)
|
2021-12-16 18:16:24 +00:00
|
|
|
@click.option("--fast", "-f", is_flag=True, help=HELP_MSG_FAST)
|
2021-08-21 13:48:52 +00:00
|
|
|
@click.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
|
|
|
|
@click.option("--module", "-m", help=HELP_MSG_MODULE)
|
2021-08-17 11:06:31 +00:00
|
|
|
@click.pass_context
|
2021-12-16 18:16:24 +00:00
|
|
|
def check_adb(ctx, iocs, output, fast, list_modules, module, serial):
|
2021-07-16 06:05:01 +00:00
|
|
|
if list_modules:
|
|
|
|
log.info("Following is the list of available check-adb modules:")
|
|
|
|
for adb_module in ADB_MODULES:
|
|
|
|
log.info(" - %s", adb_module.__name__)
|
|
|
|
|
|
|
|
return
|
|
|
|
|
|
|
|
log.info("Checking Android through adb bridge")
|
|
|
|
|
2021-07-30 09:08:32 +00:00
|
|
|
if output and not os.path.exists(output):
|
|
|
|
try:
|
|
|
|
os.makedirs(output)
|
|
|
|
except Exception as e:
|
|
|
|
log.critical("Unable to create output folder %s: %s", output, e)
|
2021-08-17 11:06:31 +00:00
|
|
|
ctx.exit(1)
|
2021-07-30 09:08:32 +00:00
|
|
|
|
2021-08-18 11:19:34 +00:00
|
|
|
indicators = Indicators(log=log)
|
2022-01-07 15:11:01 +00:00
|
|
|
indicators.load_indicators_files(iocs)
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
timeline = []
|
|
|
|
timeline_detected = []
|
|
|
|
for adb_module in ADB_MODULES:
|
|
|
|
if module and adb_module.__name__ != module:
|
|
|
|
continue
|
|
|
|
|
2021-12-16 18:16:24 +00:00
|
|
|
m = adb_module(output_folder=output, fast_mode=fast,
|
|
|
|
log=logging.getLogger(adb_module.__module__))
|
2022-01-21 15:26:58 +00:00
|
|
|
if indicators.total_ioc_count:
|
2022-01-07 15:11:01 +00:00
|
|
|
m.indicators = indicators
|
|
|
|
m.indicators.log = m.log
|
2021-08-12 16:21:21 +00:00
|
|
|
if serial:
|
|
|
|
m.serial = serial
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
run_module(m)
|
|
|
|
timeline.extend(m.timeline)
|
|
|
|
timeline_detected.extend(m.timeline_detected)
|
|
|
|
|
|
|
|
if output:
|
|
|
|
if len(timeline) > 0:
|
|
|
|
save_timeline(timeline, os.path.join(output, "timeline.csv"))
|
|
|
|
if len(timeline_detected) > 0:
|
|
|
|
save_timeline(timeline_detected, os.path.join(output, "timeline_detected.csv"))
|
|
|
|
|
2021-08-17 20:54:33 +00:00
|
|
|
|
2021-07-16 06:05:01 +00:00
|
|
|
#==============================================================================
|
2022-02-01 23:09:53 +00:00
|
|
|
# Command: check-bugreport
|
|
|
|
#==============================================================================
|
|
|
|
@cli.command("check-bugreport", help="Check an Android Bug Report")
|
|
|
|
@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
|
|
|
|
default=[], help=HELP_MSG_IOC)
|
|
|
|
@click.option("--output", "-o", type=click.Path(exists=False), help=HELP_MSG_OUTPUT)
|
|
|
|
@click.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
|
|
|
|
@click.option("--module", "-m", help=HELP_MSG_MODULE)
|
|
|
|
@click.argument("BUGREPORT_PATH", type=click.Path(exists=True))
|
|
|
|
@click.pass_context
|
|
|
|
def check_bugreport(ctx, iocs, output, list_modules, module, bugreport_path):
|
|
|
|
if list_modules:
|
|
|
|
log.info("Following is the list of available check-bugreport modules:")
|
|
|
|
for adb_module in BUGREPORT_MODULES:
|
|
|
|
log.info(" - %s", adb_module.__name__)
|
|
|
|
|
|
|
|
return
|
|
|
|
|
|
|
|
log.info("Checking an Android Bug Report located at: %s", bugreport_path)
|
|
|
|
|
|
|
|
if output and not os.path.exists(output):
|
|
|
|
try:
|
|
|
|
os.makedirs(output)
|
|
|
|
except Exception as e:
|
|
|
|
log.critical("Unable to create output folder %s: %s", output, e)
|
|
|
|
ctx.exit(1)
|
|
|
|
|
|
|
|
indicators = Indicators(log=log)
|
|
|
|
indicators.load_indicators_files(iocs)
|
|
|
|
|
2022-02-02 15:10:12 +00:00
|
|
|
if os.path.isfile(bugreport_path):
|
|
|
|
bugreport_format = "zip"
|
|
|
|
zip_archive = ZipFile(bugreport_path)
|
|
|
|
zip_files = []
|
|
|
|
for file_name in zip_archive.namelist():
|
|
|
|
zip_files.append(file_name)
|
|
|
|
elif os.path.isdir(bugreport_path):
|
|
|
|
bugreport_format = "dir"
|
|
|
|
folder_files = []
|
|
|
|
parent_path = Path(bugreport_path).absolute().as_posix()
|
|
|
|
for root, subdirs, subfiles in os.walk(os.path.abspath(bugreport_path)):
|
|
|
|
for file_name in subfiles:
|
|
|
|
folder_files.append(os.path.relpath(os.path.join(root, file_name), parent_path))
|
2022-02-01 23:09:53 +00:00
|
|
|
|
|
|
|
timeline = []
|
|
|
|
timeline_detected = []
|
|
|
|
for bugreport_module in BUGREPORT_MODULES:
|
|
|
|
if module and bugreport_module.__name__ != module:
|
|
|
|
continue
|
|
|
|
|
|
|
|
m = bugreport_module(base_folder=bugreport_path, output_folder=output,
|
|
|
|
log=logging.getLogger(bugreport_module.__module__))
|
|
|
|
|
2022-02-02 15:10:12 +00:00
|
|
|
if bugreport_format == "zip":
|
|
|
|
m.from_zip(zip_archive, zip_files)
|
|
|
|
else:
|
|
|
|
m.from_folder(bugreport_path, folder_files)
|
2022-02-01 23:09:53 +00:00
|
|
|
|
|
|
|
if indicators.total_ioc_count:
|
|
|
|
m.indicators = indicators
|
|
|
|
m.indicators.log = m.log
|
|
|
|
|
|
|
|
run_module(m)
|
|
|
|
timeline.extend(m.timeline)
|
|
|
|
timeline_detected.extend(m.timeline_detected)
|
|
|
|
|
|
|
|
if output:
|
|
|
|
if len(timeline) > 0:
|
|
|
|
save_timeline(timeline, os.path.join(output, "timeline.csv"))
|
|
|
|
if len(timeline_detected) > 0:
|
|
|
|
save_timeline(timeline_detected, os.path.join(output, "timeline_detected.csv"))
|
|
|
|
|
|
|
|
|
|
|
|
#==============================================================================
|
|
|
|
# Command: check-backup
|
2021-07-16 06:05:01 +00:00
|
|
|
#==============================================================================
|
|
|
|
@cli.command("check-backup", help="Check an Android Backup")
|
2021-08-21 13:48:52 +00:00
|
|
|
@click.option("--serial", "-s", type=str, help=HELP_MSG_SERIAL)
|
2021-08-18 11:19:34 +00:00
|
|
|
@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
|
2021-08-21 13:48:52 +00:00
|
|
|
default=[], help=HELP_MSG_IOC)
|
|
|
|
@click.option("--output", "-o", type=click.Path(exists=False), help=HELP_MSG_OUTPUT)
|
2021-07-16 06:05:01 +00:00
|
|
|
@click.argument("BACKUP_PATH", type=click.Path(exists=True))
|
2021-08-17 11:06:31 +00:00
|
|
|
@click.pass_context
|
|
|
|
def check_backup(ctx, iocs, output, backup_path, serial):
|
2021-07-16 06:05:01 +00:00
|
|
|
log.info("Checking ADB backup located at: %s", backup_path)
|
|
|
|
|
2021-07-30 09:08:32 +00:00
|
|
|
if output and not os.path.exists(output):
|
|
|
|
try:
|
|
|
|
os.makedirs(output)
|
|
|
|
except Exception as e:
|
|
|
|
log.critical("Unable to create output folder %s: %s", output, e)
|
2021-08-17 11:06:31 +00:00
|
|
|
ctx.exit(1)
|
2021-07-20 01:09:53 +00:00
|
|
|
|
2021-08-18 11:19:34 +00:00
|
|
|
indicators = Indicators(log=log)
|
2022-01-07 15:11:01 +00:00
|
|
|
indicators.load_indicators_files(iocs)
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
if os.path.isfile(backup_path):
|
|
|
|
log.critical("The path you specified is a not a folder!")
|
|
|
|
|
|
|
|
if os.path.basename(backup_path) == "backup.ab":
|
2021-11-19 14:27:51 +00:00
|
|
|
log.info("You can use ABE (https://github.com/nelenkov/android-backup-extractor) "
|
2021-07-16 06:05:01 +00:00
|
|
|
"to extract 'backup.ab' files!")
|
2021-08-17 11:06:31 +00:00
|
|
|
ctx.exit(1)
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
for module in BACKUP_MODULES:
|
|
|
|
m = module(base_folder=backup_path, output_folder=output,
|
2021-08-12 16:21:21 +00:00
|
|
|
log=logging.getLogger(module.__module__))
|
2022-01-21 15:26:58 +00:00
|
|
|
if indicators.total_ioc_count:
|
2022-01-07 15:11:01 +00:00
|
|
|
m.indicators = indicators
|
|
|
|
m.indicators.log = m.log
|
2021-08-12 16:21:21 +00:00
|
|
|
if serial:
|
|
|
|
m.serial = serial
|
2021-07-16 06:05:01 +00:00
|
|
|
|
|
|
|
run_module(m)
|
2022-01-07 15:11:01 +00:00
|
|
|
|
2022-01-11 15:02:01 +00:00
|
|
|
|
2022-01-27 17:23:19 +00:00
|
|
|
#==============================================================================
|
|
|
|
# Command: check-iocs
|
|
|
|
#==============================================================================
|
|
|
|
@cli.command("check-iocs", help="Compare stored JSON results to provided indicators")
|
|
|
|
@click.option("--iocs", "-i", type=click.Path(exists=True), multiple=True,
|
|
|
|
default=[], help=HELP_MSG_IOC)
|
|
|
|
@click.option("--list-modules", "-l", is_flag=True, help=HELP_MSG_LIST_MODULES)
|
|
|
|
@click.option("--module", "-m", help=HELP_MSG_MODULE)
|
|
|
|
@click.argument("FOLDER", type=click.Path(exists=True))
|
|
|
|
@click.pass_context
|
|
|
|
def check_iocs(ctx, iocs, list_modules, module, folder):
|
|
|
|
all_modules = []
|
|
|
|
for entry in BACKUP_MODULES + ADB_MODULES:
|
|
|
|
if entry not in all_modules:
|
|
|
|
all_modules.append(entry)
|
|
|
|
|
|
|
|
if list_modules:
|
|
|
|
log.info("Following is the list of available check-iocs modules:")
|
|
|
|
for iocs_module in all_modules:
|
|
|
|
log.info(" - %s", iocs_module.__name__)
|
|
|
|
|
|
|
|
return
|
|
|
|
|
|
|
|
log.info("Checking stored results against provided indicators...")
|
|
|
|
|
|
|
|
indicators = Indicators(log=log)
|
|
|
|
indicators.load_indicators_files(iocs)
|
|
|
|
|
|
|
|
total_detections = 0
|
|
|
|
for file_name in os.listdir(folder):
|
|
|
|
name_only, ext = os.path.splitext(file_name)
|
|
|
|
file_path = os.path.join(folder, file_name)
|
|
|
|
|
|
|
|
# TODO: Skipping processing of result files that are not json.
|
|
|
|
# We might want to revisit this eventually.
|
|
|
|
if ext != ".json":
|
|
|
|
continue
|
|
|
|
|
|
|
|
for iocs_module in all_modules:
|
|
|
|
if module and iocs_module.__name__ != module:
|
|
|
|
continue
|
|
|
|
|
|
|
|
if iocs_module().get_slug() != name_only:
|
|
|
|
continue
|
|
|
|
|
|
|
|
log.info("Loading results from \"%s\" with module %s", file_name,
|
|
|
|
iocs_module.__name__)
|
|
|
|
|
|
|
|
m = iocs_module.from_json(file_path,
|
|
|
|
log=logging.getLogger(iocs_module.__module__))
|
|
|
|
if indicators.total_ioc_count > 0:
|
|
|
|
m.indicators = indicators
|
|
|
|
m.indicators.log = m.log
|
|
|
|
|
|
|
|
try:
|
|
|
|
m.check_indicators()
|
|
|
|
except NotImplementedError:
|
|
|
|
continue
|
|
|
|
else:
|
|
|
|
total_detections += len(m.detected)
|
|
|
|
|
|
|
|
if total_detections > 0:
|
|
|
|
log.warning("The check of the results produced %d detections!",
|
|
|
|
total_detections)
|
|
|
|
|
|
|
|
|
2022-01-07 15:11:01 +00:00
|
|
|
#==============================================================================
|
2022-01-11 14:59:01 +00:00
|
|
|
# Command: download-iocs
|
2022-01-07 15:11:01 +00:00
|
|
|
#==============================================================================
|
2022-01-11 14:59:01 +00:00
|
|
|
@cli.command("download-iocs", help="Download public STIX2 indicators")
|
2022-01-07 15:11:01 +00:00
|
|
|
def download_indicators():
|
|
|
|
download_indicators_files(log)
|